Windows native backend C reference
Windows contracts use a separate Doxygen XML project so identical backend function and structure names cannot merge with the X11 implementation. Parameter descriptions identify retained DC/batch state, caller-owned clip payloads, and temporary drawables. Return values that select fallback are not interchangeable with drawing-success reports; see Native renderer internals.
For a retained polygon batch, pair rbcNativeWindows.Rbc_NativeBeginPolygonBatch() with
rbcNativeWindows.Rbc_NativeEndPolygonBatch(). For direct clipping,
rbcNativeWindows.Rbc_NativePlatformUnclip() must unwind even partial setup from
rbcNativeWindows.Rbc_NativePlatformClip().
- group Windows native backend
Private Windows implementation; extracted separately from X11 namesakes.
Functions
-
Tcl_Size Rbc_NativePolygonPointLimit(Graph *graphPtr)
Return the Windows component-level polygon allowance.
Returns TCL_SIZE_MAX, without an X11 request-size bound. Actual drawing still validates the count against INT_MAX and available workspace.
- Parameters:
graphPtr – [in] Unused on Windows; no display request limit is queried.
-
void Rbc_NativePolyline(Rbc_NativeTrace *ctx, const Point2D *screenPts, Tcl_Size nPoints)
Stroke connected mapped points through a retained Windows DC.
Borrows the trace context and input. NULL context/points or fewer than two points is a no-op. Converts coordinates to int and repeats the previous endpoint in continuation chunks. Uses preallocated POINT workspace; Polyline return values are not propagated.
- Parameters:
ctx – [inout] Live native trace context returned by Rbc_NativeBeginTrace; NULL is accepted.
screenPts – [in] Borrowed mapped polyline vertices with nPoints entries; NULL suppresses drawing.
nPoints – [in] Number of polyline vertices; fewer than two draws nothing.
-
void Rbc_NativeStrips(Graph *graphPtr, Drawable drawable, GC gc, const Segment2D *segments, Tcl_Size nSegments)
Draw independent two-point strips with one DC acquisition.
Owns bounded POINT and DWORD count buffers. Narrow strokes use up to 8192 segments per PolyPolyline call; wide strokes use 680. Converts endpoints to LONG, selects a GC-derived pen and raster operation, restores/deletes the selected pen and releases DC state. Allocation failure skips output; GDI drawing failures are not reported through this void interface.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
gc – [in] Borrowed configured drawing GC, including raster operation, clip and style.
segments – [in] Borrowed mapped endpoint pairs; readable for the supplied segment count.
nSegments – [in] Number of Segment2D records, not endpoints.
-
Rbc_NativeTrace *Rbc_NativeBeginTrace(Graph *graphPtr, Drawable drawable, GC gc)
Allocate a Windows trace context and acquire its drawing state.
Borrows graph, target and GC; owns trailing POINT workspace, acquired DC state and selected pen/brush. Wide strokes use base capacity 100; narrow strokes use request-derived capacity, with one extra continuation slot. Returns NULL for capacity/allocation failure. DC and GDI object acquisition failures are not separately validated here. EndTrace must release the context.
- Parameters:
graphPtr – [in] Borrowed owning graph, kept alive until the returned context is released.
drawable – [in] Borrowed target, kept valid until the returned context is released.
gc – [in] Borrowed configured GC, kept valid until the returned batch is released.
-
void Rbc_NativeEndTrace(Rbc_NativeTrace *ctx)
Restore and release a Windows trace batch.
Accepts NULL. Reselects the saved pen/brush, deletes the displaced batch objects, releases acquired DC state and frees the combined context buffer. Does not free the borrowed graph, drawable or GC.
- Parameters:
ctx – [in] Owned trace context consumed by this call; NULL is accepted.
-
static int GetCirclePathTemplate(HDC dc, int radius, POINT **pointsPtrPtr, BYTE **typesPtrPtr, int *nPointsPtr)
Obtain reusable ellipse geometry generated by GDI itself.
Initializes outputs to NULL/zero. Builds an Ellipse path in the borrowed DC using diameter 2*radius+1 and copies GetPath points/types to owned arrays. Aborts the temporary path after extraction. Returns FALSE on invalid radius, path failure or allocation failure, releasing partial arrays. On success the caller owns both arrays; radius arithmetic must be representable.
- Parameters:
dc – [inout] Borrowed compatible DC with no path the caller needs to preserve; a temporary GDI ellipse path is created and aborted.
radius – [in] Positive circle radius; twice the radius plus one and translated coordinates must remain representable.
pointsPtrPtr – [out] Required output initialized to NULL; successful point-array ownership transfers to the caller for ckfree.
typesPtrPtr – [out] Required output initialized to NULL; successful GDI type-array ownership transfers to the caller for ckfree.
nPointsPtr – [out] Required output initialized to zero; number of entries in both arrays on TRUE.
-
static void LoadCirclePath(POINT *dstPoints, BYTE *dstTypes, const POINT *templatePoints, const BYTE *templateTypes, int nTemplatePoints, LONG x, LONG y, int radius)
Translate one ellipse template into caller-owned batch storage.
Borrows template arrays and copies point types unchanged. Translates points by center minus radius. Caller provides capacity for nTemplatePoints and representable LONG coordinates; no allocation or validation occurs.
- Parameters:
dstPoints – [out] Writable destination with capacity for nTemplatePoints POINT entries, separate from the template.
dstTypes – [out] Writable parallel destination with capacity for nTemplatePoints BYTE entries.
templatePoints – [in] Borrowed origin-based ellipse template containing nTemplatePoints entries.
templateTypes – [in] Borrowed matching GDI path-type bytes, copied unchanged.
nTemplatePoints – [in] Nonnegative template entry count; source bounds and destination capacity are caller-validated.
x – [in] Horizontal circle center in DC coordinates; translated POINT values must fit LONG.
y – [in] Vertical circle center in DC coordinates; translated POINT values must fit LONG.
radius – [in] Positive circle radius; twice the radius plus one and translated coordinates must remain representable.
-
static void DrawCircleCentersDirect(HDC dc, const POINT *centers, int nCenters, int radius)
Draw buffered circles individually using Ellipse.
Borrows DC and centers and preserves the existing radius-plus-one far edge. Used to replay a failed copy-compatible batch. Does not own GDI state or report individual drawing failures.
- Parameters:
dc – [inout] Borrowed destination DC with suitable mapping and selected pen/brush; not acquired or released here.
centers – [in] Borrowed array of nCenters circle centers in DC coordinates.
nCenters – [in] Nonnegative center count; no array bounds checks are performed.
radius – [in] Positive circle radius; twice the radius plus one and translated coordinates must remain representable.
-
static int DrawCirclePathBatch(HDC dc, const POINT *points, const BYTE *types, int nPoints, int doFill, int doOutline)
Render a combined circle path or outline batch.
Outline-only calls PolyDraw directly. Filled batches bracket PolyDraw in BeginPath/EndPath, then use FillPath or StrokeAndFillPath. Returns the GDI success result; aborts failed construction paths. Caller owns DC, arrays and selected pen/brush and decides whether replay is safe.
- Parameters:
dc – [inout] Borrowed destination DC with suitable mapping and selected pen/brush; not acquired or released here.
points – [in] Borrowed array of nPoints translated GDI path points.
types – [in] Borrowed parallel array of nPoints GDI path types.
nPoints – [in] Positive number of initialized point entries; caller validates array bounds.
doFill – [in] Nonzero builds and fills a path; zero submits outline geometry directly.
doOutline – [in] Nonzero adds a stroke when filling; the outline-only path always uses PolyDraw.
-
void Rbc_NativeCircles(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, Tcl_Size nSymbolPts, const Point2D *symbolPts, int radius)
Draw Windows circle symbols with guarded path batching.
Borrows style/centers and advances interval counters for examined centers. Owns template/batch arrays, DC acquisition and non-stock pen/brush objects. Batching requires GXcopy for participating GCs and equal fill/outline colors when both are used. Filled batches contain at most 32 circles; outlines use 512, or 64 for wide pens. Setup failure selects individual Ellipse drawing; failed copy batches replay their buffered centers. Restores fill mode and selected objects and frees temporary resources. No Tcl error is produced.
- Parameters:
display – [in] Borrowed display owning the drawable and GC resources.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
style – [inout] Borrowed symbol style; interval-aware branches advance its counter for examined centers.
nSymbolPts – [in] Nonnegative number of mapped symbol centers.
symbolPts – [in] Borrowed mapped center array with nSymbolPts entries.
radius – [in] Circle radius in pixels; caller supplies representable center/radius arithmetic.
-
void Rbc_NativeSquares(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, Tcl_Size nSymbolPts, const Point2D *symbolPts, int r)
Convert selected squares to closed polygon symbols.
Allocates five XPoints per input center, including a repeated first vertex. Subtracts radius before short conversion. Positive intervals update the style counter even for skipped centers. Delegates selected squares to Rbc_NativePolygonSymbols and frees storage; invalid/empty output or allocation failure is ignored.
- Parameters:
display – [in] Borrowed display owning the drawable and GC resources.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
style – [inout] Borrowed symbol style; interval-aware branches advance its counter for examined centers.
nSymbolPts – [in] Nonnegative number of mapped symbol centers.
symbolPts – [in] Borrowed mapped center array with nSymbolPts entries.
r – [in] Square half-size in pixels; caller supplies representable center/radius arithmetic.
-
static void LoadPolygonBatch(POINT *points, const XPoint *polygons, Tcl_Size first, Tcl_Size count, int stride, int nPoints)
Pack selected XPoint polygons into Windows POINT storage.
Borrows source and destination arrays. Source stride includes closure; nPoints chooses fill vertices without closure or the complete outline. Copies count polygons starting at first, widening existing short values to LONG. Caller ensures all bounds and destination capacity.
- Parameters:
points – [out] Writable POINT buffer with capacity for count times nPoints entries.
polygons – [in] Borrowed packed XPoint polygons; stride includes each polygon closure.
first – [in] Zero-based first polygon offset, not a vertex offset.
count – [in] Nonnegative number of polygons to copy; source bounds and products are caller-validated.
stride – [in] Positive XPoint entries per complete source polygon, including closure.
nPoints – [in] Vertices copied per polygon, no greater than stride; omit closure for fills or include it for outlines.
-
void Rbc_NativePolygonSymbols(Display *display, Drawable drawable, Rbc_RenderNativeSymbolStyle *style, const XPoint *polygons, Tcl_Size nPolygons, int stride, int nVertices)
Fill polygon symbols, then draw their closed outlines.
Owns bounded point/count arrays and one acquired DC. Copy fills use WINDING and small PolyPolygon batches; non-copy fills preserve per-polygon effects. Outlines use larger PolyPolyline batches only for GXcopy, otherwise each outline is drawn separately. Failed copy batches replay individual shapes. Restores fill mode and selected GDI objects, deletes owned brushes/pens and releases all buffers. Interval selection is the shared caller’s responsibility.
- Parameters:
display – [in] Borrowed display owning the drawable and GC resources.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
style – [in] Borrowed symbol style and GCs; caller has already selected the symbol intervals.
polygons – [in] Borrowed packed XPoint polygons, with stride points per polygon.
nPolygons – [in] Nonnegative number of packed polygon records.
stride – [in] Points per polygon record, including its repeated closing vertex.
nVertices – [in] Distinct vertices per polygon; excludes the repeated closing point.
-
int Rbc_NativePolygonPointCount(Display *display, Tcl_Size nPoints)
Validate a polygon count for the GDI int interface.
Returns zero for fewer than three vertices or counts above INT_MAX; otherwise returns the int count. Does not enforce an X11 request limit or inspect coordinate geometry.
- Parameters:
display – [in] Unused on Windows; only the count range is checked.
nPoints – [in] Number of polygon vertices, including any repeated closing point.
-
static void DrawWin3DRectangle1(HDC dc, const Rbc_Win3DBorderColors *colorsPtr, int x, int y, int width, int height, int relief)
Reproduce a one-pixel Tk raised or sunken rectangle bevel.
Borrows DC and extracted colors. Clamps the bevel for tiny rectangles. Draws left, right, top and bottom strips in Tk order; unsupported relief draws nothing. Does not acquire a DC or retain color resources.
- Parameters:
dc – [inout] Borrowed destination DC with suitable mapping and selected pen/brush; not acquired or released here.
colorsPtr – [in] Borrowed extracted flat/light/dark border colors, valid throughout drawing.
x – [in] Left destination coordinate in pixels; coordinate arithmetic must remain representable.
y – [in] Top destination coordinate in pixels; coordinate arithmetic must remain representable.
width – [in] Positive rectangle width in pixels; endpoint arithmetic must remain representable.
height – [in] Positive rectangle height in pixels; endpoint arithmetic must remain representable.
relief – [in] Tk relief selector; only TK_RELIEF_RAISED and TK_RELIEF_SUNKEN draw in this helper.
-
static void DrawWinRbcOuter3DBorder(HDC dc, const Rbc_Win3DBorderColors *colorsPtr, int x, int y, int width, int height, int relief)
Draw the RBC-specific outer layer of a two-pixel bevel.
Requires dimensions greater than two; supports raised/sunken relief only. Uses the historical flat/light/dark color selection and right, top, bottom, left drawing order. Borrows DC and colors without allocating state.
- Parameters:
dc – [inout] Borrowed destination DC with suitable mapping and selected pen/brush; not acquired or released here.
colorsPtr – [in] Borrowed extracted flat/light/dark border colors, valid throughout drawing.
x – [in] Left destination coordinate in pixels; coordinate arithmetic must remain representable.
y – [in] Top destination coordinate in pixels; coordinate arithmetic must remain representable.
width – [in] Positive rectangle width in pixels; endpoint arithmetic must remain representable.
height – [in] Positive rectangle height in pixels; endpoint arithmetic must remain representable.
relief – [in] Tk relief selector; only TK_RELIEF_RAISED and TK_RELIEF_SUNKEN draw in this helper.
-
static int Clamp3DBorderWidth(int width, int height, int borderWidth)
Clamp a requested bevel to half each rectangle dimension.
Returns the effective width using the same sequential width/height checks as Tk. Callers supply positive bounded dimensions and border widths.
- Parameters:
width – [in] Positive bounded rectangle width in pixels.
height – [in] Positive bounded rectangle height in pixels.
borderWidth – [in] Positive requested border width; result is limited by half each dimension.
-
int Rbc_NativeBarBorders(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *penPtr, const Rbc_RenderRectangle *rectangles, Tcl_Size nRects)
Batch supported Windows bar bevels through one DC.
Handles raised/sunken border widths one and two; returns FALSE for other configurations so the shared caller can use ordinary relief drawing. Skips nonpositive rectangles and reproduces tiny-rectangle width clamping. Borrows border/colors and releases the acquired DC. TRUE means configuration handled, not verified success of every GDI drawing operation.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
penPtr – [in] Borrowed bar style and its live color, border and GC resources.
rectangles – [in] Borrowed mapped rectangle array with the supplied rectangle count.
nRects – [in] Number of rectangle records, not bytes.
-
void Rbc_NativeBarRectangles(Graph *graphPtr, Drawable drawable, const Rbc_RenderBarStyle *penPtr, XRectangle *rectangles, int nRects)
Try optimized opaque-stipple bar fills before Xlib fallback.
Borrows prepacked rectangles and style GC. If the Windows stipple helper declines, sends the same batch to XFillRectangles. Caller bounds the request.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
penPtr – [in] Borrowed bar style and its live color, border and GC resources.
rectangles – [in] Borrowed prepacked XRectangle array; caller has bounded count for the platform request.
nRects – [in] Number of rectangle records, not bytes.
-
Rbc_NativePolygonBatch *Rbc_NativeBeginPolygonBatch(Graph *graphPtr, Drawable drawable, GC gc, Tcl_Size maxPoints)
Acquire a reusable fill-only Windows polygon context.
Validates positive workspace capacity and allocation size. Owns point workspace, solid brush and DC state; selects a stock null pen and the GC fill rule. Returns NULL for invalid capacity, workspace or brush failure. Later DC/selection failures are not separately checked. Borrows graph/GC; a successful context requires Rbc_NativeEndPolygonBatch.
- Parameters:
graphPtr – [in] Borrowed owning graph, kept alive until the returned context is released.
drawable – [in] Borrowed target, kept valid until the returned context is released.
gc – [in] Borrowed configured GC, kept valid until the returned batch is released.
maxPoints – [in] Maximum number of vertices in any polygon submitted to the returned batch.
-
void Rbc_NativeBatchPolygon(Rbc_NativePolygonBatch *batch, const Point2D *points, Tcl_Size count)
Fill one polygon using retained Windows batch state.
Requires a live context and valid point array. Rejects unsupported count or count exceeding workspace capacity. Deliberately converts through short before LONG to preserve the original polygon path. Does not propagate Polygon failure or retain input points.
- Parameters:
batch – [inout] Live owned polygon batch returned by Rbc_NativeBeginPolygonBatch.
points – [in] Borrowed mapped polygon vertices with count entries.
count – [in] Number of input records, not bytes.
-
void Rbc_NativeEndPolygonBatch(Rbc_NativePolygonBatch *batch)
Restore and free a live Windows polygon batch.
Requires non-NULL context. Restores fill mode and stock/previous selections, deletes the owned brush, releases DC state and frees workspace/context.
- Parameters:
batch – [in] Owned polygon batch consumed by this call; Windows requires non-NULL.
-
size_t Rbc_NativeClipStateSize(void)
Return extra Windows state size for a shared clip frame.
The common allocator reserves this payload immediately after its frame. Ownership remains with the shared clip stack.
-
int Rbc_NativePlatformClip(Graph *graphPtr, Drawable parent, int left, int top, int right, int bottom, void *clientData, Drawable *drawablePtr)
Install a Windows meta-region clip on an acquired parent DC.
Initializes caller-owned state, acquires DC, saves it and intersects bounds. Promotes the clip to a meta region so bitmap mask changes cannot bypass it. Caller must initialize the output drawable to None. Returns TRUE even on setup failure; a missing output means skip drawing, not scratch fallback. Every call requires PlatformUnclip, including partial setup failures.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
parent – [in] Borrowed parent drawable whose clipping and pixels must remain live through unclip.
left – [in] Inclusive left clip edge in absolute pixels.
top – [in] Inclusive top clip edge in absolute pixels.
right – [in] Exclusive right clip edge in absolute pixels.
bottom – [in] Exclusive bottom clip edge in absolute pixels.
clientData – [inout] Caller-owned NativeDCClip payload, sized by Rbc_NativeClipStateSize; not a Tcl command client-data record.
drawablePtr – [inout] Required output initialized to None; success installs a temporary drawable valid until unclip.
-
void Rbc_NativePlatformUnclip(void *clientData, Drawable drawable)
Unwind complete or partial Windows clip setup.
Frees a non-None borrowed-DC wrapper, restores saved DC state when present and releases the acquisition record. Does not free the enclosing shared frame or own the parent drawable.
- Parameters:
clientData – [inout] Caller-owned NativeDCClip payload, sized by Rbc_NativeClipStateSize; not a Tcl command client-data record.
drawable – [in] Temporary platform wrapper to release, or None after partial setup; ignored on X11.
-
void Rbc_NativeRun(Graph *graphPtr, Drawable drawable, void *data, Tcl_Size count, Rbc_RenderRunProc *proc)
Run a callback through one temporary Windows drawable wrapper.
Ignores NULL data or nonpositive count. Acquires a DC and wraps it for one synchronous callback; acquisition/wrapping failure invokes the callback on the original drawable instead. Releases wrapper and DC after the call. Callback must be valid, preserve borrowed resource lifetime and not retain the temporary target. This is not a Tcl evaluation boundary.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
data – [in] Borrowed callback-specific run data; NULL suppresses the run.
count – [in] Number of run items; nonpositive counts suppress drawing.
proc – [in] Required synchronous callback for a nonempty run; must not retain the target or destroy drawing resources.
-
int Rbc_NativeOpaqueBitmapRun(Graph *graphPtr, Drawable drawable, Pixmap bitmap, GC gc, int width, int height, const Rbc_RenderPosition *positions, Tcl_Size count)
Delegate opaque bitmap batching to the Windows compatibility layer.
Returns Rbc_WinCopyOpaqueBitmapBatch’s handled/fallback result unchanged. Borrows target, bitmap, GC and positions; the shared caller owns replay policy and requires copy-compatible input.
- Parameters:
graphPtr – [in] Borrowed owning graph; its display and drawing resources must remain live during the call.
drawable – [in] Borrowed destination drawable in mapped pixel coordinates.
bitmap – [in] Borrowed one-bit source bitmap, readable over width by height pixels.
gc – [in] Borrowed opaque GXcopy-compatible GC; masked or XOR copies are outside this interface contract.
width – [in] Positive source bitmap width in pixels.
height – [in] Positive source bitmap height in pixels.
positions – [in] Borrowed array of count integer destination origins.
count – [in] Number of run items; nonpositive counts suppress drawing.
-
Tcl_Size Rbc_NativePolygonPointLimit(Graph *graphPtr)
-
struct Rbc_NativeTrace
Windows trace allocation with trailing POINT workspace.
Borrows graph/GC/target, owns DC acquisition and selected pen/brush, and retains prior selections for restoration by EndTrace.
Public Members
-
Drawable nativeDrawable
Borrowed destination drawable.
-
GC nativeGC
Borrowed configured graphics context.
-
void *nativePoints
Point workspace stored after this record in the same allocation.
-
int nativeMaxPoints
Maximum vertices per chunk, excluding the continuation slot.
-
Rbc_WinDrawableDC *nativeDCState
Owned DC acquisition record.
-
HDC nativeDC
DC borrowed from the acquisition record.
-
HPEN nativeOldPen
Previous selected pen, restored when ending the batch.
-
HBRUSH nativeOldBrush
Previous selected brush, restored when ending the batch.
-
Drawable nativeDrawable
-
struct Rbc_NativePolygonBatch
Fill-only polygon context owning point workspace, brush and DC state.
Retains prior brush, pen and fill mode for restoration. Component callers remain responsible for style grouping and painter order.
Public Members
-
Rbc_WinDrawableDC *dcState
Owned DC acquisition record.
-
HDC dc
DC borrowed from dcState.
-
HBRUSH oldBrush
Previous brush restored before deleting the batch brush.
-
HPEN oldPen
Previous pen restored on release.
-
POINT *points
Owned point workspace with capacity entries.
-
int oldFillMode
Previous GDI polygon fill rule restored on release.
-
Tcl_Size capacity
Allocated workspace capacity in POINT entries.
-
Display *display
Borrowed Tk display used by native services.
-
Rbc_WinDrawableDC *dcState
-
struct NativeDCClip
Windows clip payload stored after the shared clip frame.
Owns the acquisition record and tracks a SaveDC token. The parent drawable remains borrowed; PlatformUnclip handles partial initialization.
Tk Windows resource boundary
These compatibility services confine private Tk drawable/DC representations to rbcWinDraw.c. Components use the
renderer interface rather than these helpers.
- group Windows drawing resource helpers
Drawable wrappers, acquisition records, raster fast paths and GC conversion.
Functions
-
Drawable Rbc_WinCreateDrawableFromDC(HDC dc)
Wrap a borrowed HDC as a Tk-compatible drawable.
Returns None for NULL DC; otherwise allocates a TkWinDC wrapper. Caller releases only this wrapper with Rbc_WinFreeDrawableFromDC. Underlying DC ownership and restoration stay with the caller.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
-
void Rbc_WinFreeDrawableFromDC(Drawable drawable)
Free an owned HDC drawable wrapper.
Accepts None. The argument must come from Rbc_WinCreateDrawableFromDC; this does not release or destroy the underlying HDC.
- Parameters:
drawable – [in] Owned wrapper from Rbc_WinCreateDrawableFromDC, consumed here; None is harmless.
-
Window Rbc_WinWindowFromHWND(HWND hWnd)
Wrap an HWND in static Tk window storage.
Returns a borrowed Window valid only until the next call. Does not create a Tk window, own the HWND or allocate a persistent wrapper. The static record is overwritten on each call and is not independent per thread.
- Parameters:
hWnd – [in] Borrowed native HWND wrapped without acquiring ownership.
-
HDC Rbc_WinAcquireDrawableDC(Display *display, Drawable drawable, Rbc_WinDrawableDC **statePtrPtr)
Acquire a drawable DC and allocate its release record.
Requires valid output storage. Always returns an owned state record through statePtrPtr, including when the returned DC is NULL. Release that record with Rbc_WinReleaseDrawableDC. The record contains private Tk DC state; callers separately restore GDI objects/state they explicitly change.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
statePtrPtr – [out] Required output receiving an owned release record even when DC acquisition fails.
-
void Rbc_WinReleaseDrawableDC(Rbc_WinDrawableDC *statePtr)
Release Tk drawable state and its RBC acquisition record.
Accepts NULL. Calls TkWinReleaseDrawableDC only for a non-NULL acquired DC, then frees the record even after failed acquisition. Must be called once for each acquisition record; does not destroy the drawable.
- Parameters:
statePtr – [in] Owned acquisition record consumed here, or NULL.
-
void Rbc_WinSetROP2(HDC dc, int function)
Select the DC raster operation from the compatibility table.
Requires an X graphics-function index in the table range. Changes the borrowed DC without saving its prior ROP2 value; no range check or GDI error result is provided.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
function – [in] X graphics-function index within the compatibility table range.
-
Pixmap Rbc_WinCreatePixmapFromBitmap(HBITMAP hBitmap, int depth, Colormap colormap)
Wrap a native bitmap in Tk pixmap representation.
Returns None for NULL HBITMAP; otherwise allocates a TkWinBitmap record with the supplied depth and colormap. The result participates in normal Tk pixmap destruction, including bitmap deletion. Do not independently delete the bitmap while the wrapper remains live.
- Parameters:
hBitmap – [in] Native bitmap transferred to the Tk pixmap wrapper on success; NULL returns None.
depth – [in] Pixel depth recorded in the new Tk pixmap wrapper.
colormap – [in] Colormap recorded in the wrapper; no independent reference is acquired.
-
HBITMAP Rbc_WinGetPixmapHandle(Pixmap pixmap)
Return the borrowed native bitmap handle of a Tk pixmap.
Returns NULL for None or a non-bitmap drawable. The returned handle remains owned by the pixmap; no reference or copy is acquired.
- Parameters:
pixmap – [in] Borrowed Tk pixmap to inspect, or None.
-
HPALETTE Rbc_GetSystemPalette(void)
Copy the system palette when the display is palette-based.
Acquires and releases a screen DC. For RC_PALETTE devices, allocates a temporary 256-entry LOGPALETTE and creates an owned HPALETTE. Caller deletes the returned palette with DeleteObject. Returns NULL on unsupported devices or acquisition/allocation/creation failure; temporary storage is released.
-
unsigned char *Rbc_GetBitmapData(Display *display, Pixmap bitmap, int width, int height, int *pitchPtr)
Read monochrome DIB data into a caller-owned byte buffer.
Requires pitchPtr, initializes it to zero and rejects invalid dimensions or overflowing storage sizes. Requests a positive-height one-bit BI_RGB DIB with DWORD-aligned rows; returned rows retain native bottom-up order. Uses at least the calculated stride times height even if biSizeImage is zero. Releases temporary global memory and each DC acquisition. Returns NULL on failure, or ckalloc storage to free with ckfree and the row pitch. A nonzero GetDIBits result is accepted; exact scanline count is not checked.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
bitmap – [in] Borrowed source monochrome Tk pixmap.
width – [in] Rectangle or bitmap width in pixels; validity requirements are described above.
height – [in] Rectangle or bitmap height in pixels; validity requirements are described above.
pitchPtr – [out] Required output, initialized to zero, then set to the returned row stride in bytes.
-
void Rbc_WinGet3DBorderColors(Tk_Window tkwin, Tk_3DBorder border, Rbc_Win3DBorderColors *colorsPtr)
Read Tk Windows bevel pixels into caller storage.
Borrows window and border; fills flat, light, dark, light2 and dark2 through TkWinGetBorderPixels. Does not allocate or transfer color resources.
- Parameters:
tkwin – [in] Borrowed live Tk window supplying the display context.
border – [in] Borrowed Tk border whose native bevel colors are queried.
colorsPtr – [out] Required caller-owned output record for the five bevel colors.
-
void Rbc_WinFillRect(HDC dc, int x, int y, int width, int height, COLORREF color)
Fill a positive rectangle through Tk Windows drawing.
Borrows DC and ignores nonpositive dimensions. Uses TkWinFillRect so bevel strips match Tk geometry. Does not acquire a DC or report drawing failure.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
x – [in] Horizontal drawable coordinate in pixels.
y – [in] Vertical drawable coordinate in pixels.
width – [in] Rectangle or bitmap width in pixels; validity requirements are described above.
height – [in] Rectangle or bitmap height in pixels; validity requirements are described above.
color – [in] Fill color passed by value as a Windows COLORREF.
-
int Rbc_WinFillOpaqueStippledRectangles(Display *display, Drawable drawable, GC gc, const XRectangle *rectangles, int nRectangles)
Try a pattern-brush fast path for opaque stipple rectangles.
Requires GXcopy, FillOpaqueStippled and a bitmap stipple. Borrows GC/rectangles and owns the pattern brush and DC acquisition. Sets text/background colors in reverse GC order for monochrome stipple expansion and uses the GC origin. Restores colors, brush and origin after painting. FALSE requests ordinary fallback and can follow partial output; copy semantics permit replay. Failed DC acquisition releases its allocated record and the pattern brush before returning FALSE.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
rectangles – [in] Borrowed array of nRectangles native-coordinate rectangles.
nRectangles – [in] Number of rectangles supplied in the array.
-
int Rbc_WinCopyOpaqueBitmapBatch(Display *display, Drawable drawable, Pixmap bitmap, GC gc, int width, int height, const int (*positions)[2], Tcl_Size nPositions)
Copy a monochrome bitmap at multiple positions using shared DCs.
Borrows bitmap, GC and positions. Caller restricts this to the unmasked copy-compatible case; the helper does not validate raster-operation or clip-mask eligibility. Saves destination background mode/colors, sets the opaque expansion colors and uses SRCCOPY. Restores destination state and releases both DC acquisitions. FALSE can follow partial output; shared caller may replay only because this path has copy semantics.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
bitmap – [in] Borrowed source monochrome Tk pixmap.
gc – [in] Borrowed graphics context supplying native drawing attributes.
width – [in] Rectangle or bitmap width in pixels; validity requirements are described above.
height – [in] Rectangle or bitmap height in pixels; validity requirements are described above.
positions – [in] Borrowed nPositions by 2 array of integer destination x/y pairs.
nPositions – [in] Number of accessible destination pairs.
-
long Rbc_EmulateXMaxRequestSize(Display *display)
Return the legacy Windows X request-size surrogate.
Returns SHRT_MAX divided by four, independent of display. This is a compatibility sizing value, not a query of a live GDI device limit.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
-
void Rbc_EmulateXLowerWindow(Display *display, Window window)
Move the native window to the bottom of its stacking order.
Borrows the Tk-compatible Window, obtains its HWND and calls SetWindowPos without moving or resizing. Does not report failure or increment an X request counter; the flags do not explicitly suppress activation.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
window – [in] Borrowed Tk-compatible native window identifier.
-
static int GetGCDashValues(GC gc, DWORD *dashArr)
Copy the bounded zero-terminated GC dash sequence.
Borrows the GC and writes at most RBC_MAX_DASH_VALUES DWORDs into caller storage. Reads unsigned bytes starting at gc->dashes using the established Windows GC dash layout. Returns the number copied, without allocation.
- Parameters:
gc – [in] Borrowed graphics context supplying native drawing attributes.
dashArr – [out] Required output array with capacity for RBC_MAX_DASH_VALUES DWORD entries.
-
HPEN Rbc_GCToPen(HDC dc, GC gc)
Create an owned GDI pen from configured GC line attributes.
Clamps line width to at least one, maps caps/joins and duplicates a single dash value for a repeating user style. Both dash line styles use the same user-style pen representation. Sets the borrowed DC background mode to TRANSPARENT without restoring it. Uses a geometric pen for width above one and a cosmetic pen otherwise; asserts creation success. Caller selects and later deletes the pen after restoring its previous selection.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
-
Drawable Rbc_WinCreateDrawableFromDC(HDC dc)
-
struct Rbc_WinDrawableDC
Owned release record for a borrowed Tk drawable DC.
Retains the drawable and private Tk state until release. A NULL dc still leaves this allocated record owned by the acquiring caller.
Compatibility drawing primitives
These entries implement the Windows Xlib-shaped drawing boundary. They consume mapped integer geometry and configured GCs, with the historical conversions and fallback policies described in Native renderer internals.
- group Windows compatibility primitives
Xlib-shaped drawing entry points implemented with native Windows operations.
Functions
-
void Rbc_EmulateXDrawRectangles(Display *display, Drawable drawable, GC gc, XRectangle *rectArr, int nRects)
Draw rectangle outlines through one acquired Windows DC.
Ignores None target, NULL array and nonpositive count. Borrows GC/rectangles; selects an owned GC-derived pen and stock null brush, then draws rectangles in input order. Adds one to each far edge for the Windows pixel convention. Restores selections, deletes the displaced objects and releases DC state. Requires valid GC and usable DC; GDI results are not propagated.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
rectArr – [in] Borrowed array of nRects native-coordinate rectangles.
nRects – [in] Number of accessible rectangles; nonpositive counts draw nothing.
-
static void DrawArc(HDC dc, int arcMode, XArc *arcPtr, HPEN pen, HBRUSH brush)
Translate XArc angle units and closure into a GDI arc operation.
Borrows an already configured DC and XArc. Sweeps of at least one full turn in magnitude use Ellipse. Other sweeps normalize angles in 1/64 degrees and swap endpoints for negative extent. Converts radial endpoints with the historical add-one-half then int conversion, accounting for inverted Y. Adds one to bounding-box far edges. A zero brush argument selects open Arc; a nonzero brush selects Chord or Pie from arcMode. Pen/brush selection is the caller’s responsibility; the pen argument is not otherwise used. Does not explicitly reject zero sweep or change the DC arc direction.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
arcMode – [in] X arc closure selector used when brush is nonzero.
arcPtr – [in] Borrowed native arc record; angles are in 1/64 degree units.
pen – [in] Caller-selected pen; this argument is otherwise unused.
brush – [in] Zero selects an open arc; nonzero selects closure without selecting the brush here.
-
void Rbc_EmulateXDrawArcs(Display *display, Drawable drawable, GC gc, XArc *arcArr, int nArcs)
Draw open arcs with a retained pen and null brush.
Ignores None target, NULL input and nonpositive count. Acquires one DC, sets the GC raster operation and selects a GC-derived pen and stock null brush. Calls DrawArc for each item in order, then restores selections, deletes displaced objects and releases state. GC and array remain borrowed.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
arcArr – [in] Borrowed array of nArcs native arc records.
nArcs – [in] Number of accessible arc entries; nonpositive counts draw nothing.
-
void Rbc_EmulateXFillArcs(Display *display, Drawable drawable, GC gc, XArc *arcArr, int nArcs)
Draw filled arc figures with a solid foreground brush.
Acquires one DC and selects both a GC-derived pen and an owned solid brush. DrawArc chooses chord/pieslice closure or a full ellipse. Thus this path retains a drawing pen rather than selecting a null pen for fill-only output. Ignores empty input; restores selections, deletes owned objects and releases DC state. Does not report individual GDI failures.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
arcArr – [in] Borrowed array of nArcs native arc records.
nArcs – [in] Number of accessible arc entries; nonpositive counts draw nothing.
-
static int DrawXorSegments(HDC dc, GC gc, const XSegment *segments, int count)
Compose independent XOR segments offscreen and present once.
Requires nonempty valid segments, GC and DC. Intersects expanded segment bounds with GetClipBox and returns TRUE for empty coverage. Owns a compatible DC, bitmap and GC-derived pen. Clears black (XOR identity), translates the viewport and draws each segment as its own Polyline. Only successful composition triggers one SRCINVERT copy to the destination. Restores selected objects and frees temporary resources on handled failure paths. FALSE asks the caller to retry directly; no destination rollback is implemented.
- Parameters:
dc – [in] Borrowed valid device context; state changes and restoration are described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
segments – [in] Borrowed nonempty array of independent segments.
count – [in] Positive number of accessible segments.
-
void Rbc_EmulateXDrawSegments(Display *display, Drawable drawable, GC gc, XSegment *segArr, int nSegments)
Draw independent segments with XOR-specific presentation.
Rejects missing target/GC/segments and nonpositive count. GXxor first tries DrawXorSegments and stops if handled. Otherwise owns bounded POINT/count arrays and an acquired DC/pen: batches contain 8192 segments, or 680 for wide lines. XOR fallback uses individual Polyline calls to retain dash phase and overlap cancellation. Other operations use PolyPolyline, with per-segment MoveToEx/LineTo fallback on failure. Frees arrays and restores/releases pen and DC state. Void return does not report partial output or GDI failures.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
segArr – [in] Borrowed array of nSegments independent native-coordinate segments.
nSegments – [in] Number of accessible segments; nonpositive counts draw nothing.
-
void Rbc_EmulateXDrawPoints(Display *display, Drawable drawable, GC gc, XPoint *pointArr, int nPoints, int mode)
Write foreground pixels at absolute or accumulated positions.
Ignores None target, NULL array and nonpositive count. Acquires one DC and sets its raster operation, then calls SetPixelV with GC foreground for each point. CoordModeOrigin uses absolute positions; any other mode accumulates LONG offsets from the first point. Releases DC state. No explicit pixel read/modify/write composition or overflow check is performed here.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
pointArr – [in] Borrowed array of nPoints native-coordinate points.
nPoints – [in] Number of accessible point entries; nonpositive counts draw nothing.
mode – [in] CoordModeOrigin for absolute points; other values accumulate relative offsets.
-
void Rbc_EmulateXDrawString(Display *display, Drawable drawable, GC gc, int x, int y, const char *string, int length)
Draw a counted string using the Tk font in the GC.
Ignores None target, NULL string and nonpositive byte length. Delegates to Tk_DrawChars with gc->font cast to Tk_Font and baseline coordinates. Borrows all arguments and does not create a DC, font or converted string itself.
- Parameters:
display – [in] Borrowed display associated with the native drawable.
drawable – [in] Borrowed compatible destination drawable; None handling is described above.
gc – [in] Borrowed graphics context supplying native drawing attributes.
x – [in] Horizontal drawable coordinate in pixels.
y – [in] Vertical drawable coordinate in pixels.
string – [in] Borrowed counted string; NULL draws nothing.
length – [in] String byte count; nonpositive values draw nothing.
-
void Rbc_EmulateXDrawRectangles(Display *display, Drawable drawable, GC gc, XRectangle *rectArr, int nRects)
Bitmap capture and transforms
Windows-specific image contracts are extracted without the same-named shared header declarations. See Image storage and tile clients for common image ownership and Native renderer internals for platform representations and limits.
- group Windows bitmap and capture services
Platform implementation, extracted separately from shared image declarations.
Functions
-
static int GetMonoBitmapStride(int width)
Calculate a DWORD-aligned monochrome row stride.
Returns zero for nonpositive width or width too large for the alignment addition. Otherwise returns ((width + 31) & ~31) / 8 bytes. Height and total allocation-size validation remain with the caller.
- Parameters:
width – [in] Requested monochrome width in pixels; nonpositive or alignment-overflowing values return zero.
-
Rbc_ColorImage Rbc_DrawableToColorImage(Tk_Window tkwin, Drawable drawable, int x, int y, int width, int height, double inputGamma)
Capture a Windows drawable rectangle into an owned color image.
Rejects nonpositive dimensions and nonfinite/nonpositive gamma. Borrows window/target, creates a 32-bit DIB and memory DC, then copies the rectangle with SRCCOPY. Converts bottom-up BGR rows using the bitmap row stride and a pow(channel/255, inputGamma) lookup; output alpha is fully opaque. Releases temporary bitmap/DC resources and any copied system palette. Returns NULL on checked capture failures; caller frees a successful image with Rbc_FreeColorImage. Not every GDI acquisition/selection is validated.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
drawable – [in] Borrowed source drawable compatible with tkwin; copied without ownership transfer.
x – [in] Source rectangle left coordinate in pixels.
y – [in] Source rectangle top coordinate in pixels.
width – [in] Positive rectangle width in pixels; endpoint arithmetic must remain representable.
height – [in] Positive rectangle height in pixels; endpoint arithmetic must remain representable.
inputGamma – [in] Finite positive exponent applied to normalized RGB channels; invalid values return NULL.
-
Pixmap Rbc_PhotoImageMask(Tk_Window tkwin, Tk_PhotoImageBlock src)
Create a Windows one-bit transparency mask from a Tk photo block.
Borrows photo storage and honors pitch, pixelSize and alpha offset. Requires a valid block with accessible alpha bytes. Sets bits only for exactly zero alpha; partial alpha is treated as opaque. Uses aligned temporary rows and the existing photo-specific row traversal before CreateBitmapIndirect. Returns an owned Tk pixmap, or None for all-opaque input, invalid dimensions or bitmap creation failure. Releases temporary bits; caller frees the pixmap.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
src – [in] Photo-block descriptor copied by value; pixel storage is borrowed and must expose valid pitch, pixelSize and alpha offset.
-
Pixmap Rbc_ColorImageMask(Tk_Window tkwin, Rbc_ColorImage image)
Create a one-bit transparency mask from RBC color pixels.
Borrows a valid image and sets bits only where alpha equals zero. Uses aligned rows and the SetBit bottom-up addressing convention while traversing source pixels in logical row order. Returns None for all-opaque input or checked failure, otherwise an owned Tk pixmap to free with Tk_FreePixmap. Temporary bit storage is released after wrapping the native bitmap.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
image – [in] Borrowed valid RBC color image; source pixels and alpha remain unchanged.
-
Pixmap Rbc_RotateBitmap(Tk_Window tkwin, Pixmap srcBitmap, int srcWidth, int srcHeight, double theta, int *destWidthPtr, int *destHeightPtr)
Create a rotated Windows monochrome pixmap.
Borrows source/window. Rejects invalid sizes, nonfinite angle or missing output pointers before initializing outputs. After initial validation, outputs are zero until success. Normalizes angle to [0,360), rounds bounding dimensions upward and checks stride, size_t and DWORD image-size limits. Uses exact quadrant mappings or inverse mapping with ROUND and source bounds checks. Frees readback bits and temporary storage; failed upload frees the destination. Returns None on checked failure, otherwise owned pixmap and dimensions. Caller releases the pixmap with Tk_FreePixmap.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
srcBitmap – [in] Borrowed monochrome source pixmap on the window display, readable at the supplied source dimensions.
srcWidth – [in] Positive source bitmap width in pixels.
srcHeight – [in] Positive source bitmap height in pixels.
theta – [in] Finite rotation angle in degrees, normalized to a full turn internally.
destWidthPtr – [out] Required width output, separate from destHeightPtr; zeroed after initial validation and assigned on success.
destHeightPtr – [out] Required height output, separate from destWidthPtr; initial validation failure leaves it untouched.
-
Pixmap Rbc_ScaleBitmap(Tk_Window tkwin, Pixmap srcBitmap, int srcWidth, int srcHeight, int destWidth, int destHeight)
Scale a monochrome bitmap through Windows StretchBlt.
Borrows source/window and allocates an owned destination pixmap. Acquires source and destination DC records and releases both after SRCCOPY scaling. Returns None if pixmap allocation fails. This path does not validate sizes or test DC acquisition and StretchBlt success separately; callers must supply valid dimensions. A returned pixmap is not proof of successful copy.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
srcBitmap – [in] Borrowed monochrome source pixmap on the window display, readable at the supplied source dimensions.
srcWidth – [in] Positive source bitmap width in pixels.
srcHeight – [in] Positive source bitmap height in pixels.
destWidth – [in] Positive destination bitmap width in pixels; caller validates native allocation limits.
destHeight – [in] Positive destination bitmap height in pixels; caller validates native allocation limits.
-
Pixmap Rbc_ScaleRotateBitmapRegion(Tk_Window tkwin, Pixmap srcBitmap, int srcWidth, int srcHeight, int regionX, int regionY, int regionWidth, int regionHeight, int virtWidth, int virtHeight, double theta)
Construct only a region of a virtual scaled/rotated bitmap.
Validates positive source, region and virtual sizes plus finite angle. Borrows source/window; owns destination pixmap and readback/output buffers. Normalizes rotation and inverse-maps region coordinates through virtual scaling into source bits. Exact quadrant paths assume an in-bounds region and directly sample; arbitrary angles bounds-check source coordinates. Callers must keep region offsets and coordinate arithmetic representable and within the virtual image. Checks stride/storage limits and frees the destination on checked readback/upload failure. Caller owns successful pixmap.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
srcBitmap – [in] Borrowed monochrome source pixmap on the window display, readable at the supplied source dimensions.
srcWidth – [in] Positive source bitmap width in pixels.
srcHeight – [in] Positive source bitmap height in pixels.
regionX – [in] Left offset inside the virtual scaled/rotated image; the complete region must fit and arithmetic must be representable.
regionY – [in] Top offset inside the virtual scaled/rotated image; the complete region must fit and arithmetic must be representable.
regionWidth – [in] Positive width of the requested destination region in pixels.
regionHeight – [in] Positive height of the requested destination region in pixels.
virtWidth – [in] Positive width of the complete virtual image, not the allocated region.
virtHeight – [in] Positive height of the complete virtual image, not the allocated region.
theta – [in] Finite rotation angle in degrees, normalized to a full turn internally.
-
char *Rbc_LastError(void)
Format the current Windows error in borrowed static storage.
Captures GetLastError before formatting. Uses FormatMessageA with the system default language and removes trailing CR/LF. Falls back to a numeric error string if formatting fails. The returned 1024-byte buffer is overwritten by later calls, is not thread-local, and must not be freed. Text is in the Windows ANSI encoding rather than guaranteed UTF-8; copy/convert if retained or exposed through a Tcl API expecting UTF-8.
-
static int GetMonoBitmapStride(int width)
Native window handle lookup
- group Windows native handle lookup
Functions
-
static HWND GetWindowHandle(Tk_Window tkwin)
Return the client HWND or its immediate parent for a toplevel.
Realizes the Tk window if needed, then converts its drawable with Tk_GetHWND. Toplevels use GetParent; a NULL result is returned unchanged. Does not walk ancestors, map the window, retain the handle or install destruction hooks. Requires a live Tk window on its owning thread.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread; may be realized to obtain a native ID, but is not retained.
-
Window Rbc_GetRealWindowId(Tk_Window tkwin)
Return a native client or toplevel-wrapper identifier.
May realize the borrowed Tk window. X11 queries the toplevel parent; Windows returns a raw HWND cast to Window. It is not a portable Tk drawable token. No ownership transfers. X11 keeps the realized client if parent lookup fails; callers must still distinguish native wrapper IDs from Tk drawable tokens.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread; may be realized to obtain a native ID, but is not retained.
-
static HWND GetWindowHandle(Tk_Window tkwin)
DC and handle ownership
rbcWindowsResources.Rbc_WinAcquireDrawableDC() returns a release record even when acquisition fails. Pass that
record to rbcWindowsResources.Rbc_WinReleaseDrawableDC(); restoring explicitly selected GDI objects remains the
caller’s responsibility. In contrast, rbcWindowsResources.Rbc_WinCreateDrawableFromDC() wraps an already
borrowed DC: rbcWindowsResources.Rbc_WinFreeDrawableFromDC() releases only the wrapper.
rbcWindowsResources.Rbc_WinCreatePixmapFromBitmap() transfers a native bitmap into Tk pixmap ownership. A handle
returned by rbcWindowsResources.Rbc_WinGetPixmapHandle() is borrowed and must not be independently
deleted. These ownership rules differ from the transient static window wrapper returned by
rbcWindowsResources.Rbc_WinWindowFromHWND().
Tiled shapes
These contracts describe the Windows DC implementation, separately from the same-named X11 helpers in Image and tile C reference. Origins and mask/color source offsets must agree across cropped copies; see Image storage and tile clients.
- group Windows tiled shape drawing
Functions
-
static void TileRegion(HDC srcDC, HDC destDC, HDC maskDC, TileClient *clientPtr, int x, int y, int width, int height)
Blit a Windows tile repeatedly across a rectangular region.
Requires positive cached tile dimensions and borrowed source/destination DCs. Aligns the first repetition to the client origin, then clips edge copies to the requested rectangle. Opaque copies use SRCCOPY. Transparent copies combine SRCAND and SRCPAINT with matching mask/color source offsets at cropped tile boundaries. Does not acquire/release DCs or report BitBlt failure.
- Parameters:
srcDC – [in] Borrowed memory DC with the cached tile color bitmap selected.
destDC – [inout] Borrowed destination DC receiving repeated clipped copies; clipping/mapping state is established by the caller.
maskDC – [in] Borrowed matching monochrome-mask DC, or NULL for opaque SRCCOPY.
clientPtr – [in] Borrowed live tile client with current cached pixmap, positive tile dimensions and destination-relative origin.
x – [in] Left destination coordinate in pixels; coordinate arithmetic must remain representable.
y – [in] Top destination coordinate in pixels; coordinate arithmetic must remain representable.
width – [in] Positive rectangle width in pixels; endpoint arithmetic must remain representable.
height – [in] Positive rectangle height in pixels; endpoint arithmetic must remain representable.
-
void Rbc_TilePolygon(Tk_Window tkwin, Drawable drawable, TileClient *clientPtr, XPoint pointArr[], int nPoints)
Fill a Windows polygon by clipping tiled bounding-box copies.
Requires a nonempty point array and live cached tile; None drawable is ignored. Copies points relative to the inclusive bounding box, converts them to device coordinates, installs a polygon region using the GC fill rule and tiles the bounds. Restores bitmap selection, deletes temporary DC/region and releases acquired DCs. Explicitly clears the polygon clip before release; does not report allocation or native drawing failures.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
drawable – [in] Borrowed destination drawable compatible with the window/display; no ownership is transferred.
clientPtr – [in] Borrowed live tile client with current cached pixmap, positive tile dimensions and destination-relative origin.
pointArr – [in] Borrowed nonempty array of nPoints absolute XPoint coordinates; not modified.
nPoints – [in] Positive number of initialized point entries; caller validates array bounds.
-
void Rbc_TileRectangle(Tk_Window tkwin, Drawable drawable, TileClient *clientPtr, int x, int y, int width, int height)
Draw one tiled rectangle through Windows DCs.
Ignores None drawables and nonpositive dimensions. Requires a live client with usable cached pixmap and positive tile size. Acquires the destination DC, selects the source bitmap into a temporary memory DC, and optionally acquires the mask DC for TileRegion. Restores the selected bitmap, deletes the memory DC and releases acquired DCs. Native API failures are not propagated; no tile refresh or window ownership is acquired.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
drawable – [in] Borrowed compatible destination drawable; None causes no drawing.
clientPtr – [in] Borrowed live tile client with current cached pixmap, positive tile dimensions and destination-relative origin.
x – [in] Left destination coordinate in pixels; coordinate arithmetic must remain representable.
y – [in] Top destination coordinate in pixels; coordinate arithmetic must remain representable.
width – [in] Destination width in pixels; nonpositive values cause no drawing.
height – [in] Destination height in pixels; nonpositive values cause no drawing.
-
void Rbc_TileRectangles(Tk_Window tkwin, Drawable drawable, TileClient *clientPtr, XRectangle rectArr[], Tcl_Size nRectangles)
Draw a rectangle batch while retaining Windows drawing contexts.
Ignores None drawables, NULL arrays and nonpositive counts. Acquires and selects source/destination resources once, optionally acquires one mask DC, and calls TileRegion for each rectangle. Restores bitmap selection and releases DCs after the batch. Borrows the array; uses client-stored origin and requires usable cached tile resources.
- Parameters:
tkwin – [in] Borrowed live Tk window on its owning thread, supplying the interpreter/display and native resource context.
drawable – [in] Borrowed compatible destination drawable; None causes no drawing.
clientPtr – [in] Borrowed live tile client with current cached pixmap, positive tile dimensions and destination-relative origin.
rectArr – [in] Borrowed array of nRectangles absolute rectangles; NULL causes no drawing.
nRectangles – [in] Rectangle count; nonpositive counts cause no drawing.
-
static void TileRegion(HDC srcDC, HDC destDC, HDC maskDC, TileClient *clientPtr, int x, int y, int width, int height)
Windows header records
The packed file headers retain their on-disk layout. Border colors are resolved values, not retained Tk resources.
-
struct DOSEPSHEADER
Packed DOS EPS wrapper header; offsets and lengths are byte counts.
Public Members
-
BYTE magic[4]
Magic number for a DOS EPS file C5,D0,D3,C6.
-
DWORD psStart
Offset of PostScript section.
-
DWORD psLength
Length of the PostScript section.
-
DWORD wmfStart
Offset of Windows Meta File section.
-
DWORD wmfLength
Length of Meta file section.
-
DWORD tiffStart
Offset of TIFF section.
-
DWORD tiffLength
Length of TIFF section.
-
WORD checksum
Checksum of header.
If FFFF, ignore.
-
BYTE magic[4]
-
struct APMHEADER
Packed Aldus placeable-metafile header.
-
struct Rbc_Win3DBorderColors
Resolved Windows colors for flat and bevelled Tk borders.
Platform-specific record extensions
These views include Windows-only handles omitted from the normal-platform Text and font C reference and EPS canvas C reference records.
-
struct FontSource
Temporary native font source; cleanup releases bytes and platform handles.
Public Members
-
unsigned char *bytes
Owned retrieved font-program bytes.
-
size_t length
Number of retrieved bytes.
-
size_t offset
Face offset within a font collection.
-
HDC dc
Temporary Windows device context, released by font-source cleanup.
-
HFONT font
Selected native font handle.
-
HFONT oldFont
Previous DC font restored before releasing the DC.
-
unsigned char *bytes
-
struct EpsItem
Canvas EPS item owning parsed PostScript and preview resources.
Public Members
-
Tk_Item header
Generic stuff that’s the same for all types.
MUST BE FIRST IN STRUCTURE.
-
Tk_Canvas canvas
Canvas containing the EPS item.
-
int canvasX
Translated (by the anchor) canvas coordinates of the EPS item.
-
int canvasY
Translated (by the anchor) canvas coordinates of the EPS item.
-
int lastWidth
Last known dimensions of the EPS item.
This is used to know if the color image preview needs to be resized.
-
int lastHeight
Last known dimensions of the EPS item.
This is used to know if the color image preview needs to be resized.
-
Tcl_Interp *interp
Borrowed canvas interpreter.
-
FILE *psFile
File pointer to Encapsulated PostScript file.
We’ll hold this as long as the EPS item is using this file.
-
size_t psStart
File offset of PostScript code.
-
size_t psLength
Length of PostScript code.
If zero, indicates to read to EOF.
-
size_t wmfStart
File offset of Windows Metafile preview.
-
size_t wmfLength
Length of WMF portion in bytes.
If zero, indicates there is no WMF preview.
-
size_t tiffStart
File offset of TIFF preview.
-
size_t tiffLength
Length of TIFF portion in bytes.
If zero, indicates there is no TIFF preview.
-
char *previewName
Configured preview image name.
-
int previewFormat
Preview format selector.
-
Tk_Image preview
A Tk photo image provided as a preview of the EPS contents.
This image supersedes any EPS preview embedded PostScript preview (EPSI).
-
Tk_Image tmpImage
Used to display the resized preview image.
Created and deleted internally.
-
Pixmap pixmap
Pixmap representing scaled preview.
This isn’t currently used. For now we’re overwriting the Tk image everytime the EPS item is resized. In the future we’ll use our own image routines.
-
Rbc_ColorImage colorImage
The original photo or PostScript preview image converted to a color image.
This is kept around for resampling or resizing the image.
-
int firstLine
First and last line numbers of the PostScript preview.
They are used to skip over the preview when encapsulating PostScript for the canvas item.
-
int lastLine
First and last line numbers of the PostScript preview.
They are used to skip over the preview when encapsulating PostScript for the canvas item.
-
GC fillGC
Graphics context to fill background of image outline if no preview image was present.
-
int llx
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int lly
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int urx
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
int ury
Lower left and upper right coordinates of PostScript bounding box, retrieved from file’s “BoundingBox:” field.
-
char *title
Title, retrieved from the file’s “Title:” field, to be displayed over the top of the EPS preview (allocated).
-
Tcl_DString dString
Contains the encapsulate PostScript.
-
double x
Canvas coordinates of the item.
-
double y
Canvas coordinates of the item.
-
Tk_Anchor anchor
Tk anchor locating the item relative to x/y.
-
char *fileName
Name of the encapsulated PostScript file.
If NULL, indicates that no EPS file has be successfully loaded yet.
-
char *reqTitle
Title to be displayed in the EPS item.
Supersedes the title found in the EPS file. If NULL, indicates that the title found in the EPS file should be used.
-
int width
Dimensions of EPS item.
If set to zero, the dimension found in the “%%BoundingBox:” specification from the EPS file are used.
-
int height
Dimensions of EPS item.
If set to zero, the dimension found in the “%%BoundingBox:” specification from the EPS file are used.
-
int showImage
Indicates if the image or the outline rectangle should be displayed.
-
int quick
Nonzero requests quick preview resampling.
-
XColor *fillColor
Fill color of the image outline.
-
Tk_3DBorder border
Outline color.
-
int borderWidth
Preview border thickness in pixels.
-
int relief
Tk preview border relief.
-
Pixmap stipple
Stipple for image fill.
-
ClientData tiffPtr
TIFF decoder handle when TIFF preview support is compiled in.
-
HENHMETAFILE *hMetaFile
Optional Windows metafile state retained by the EPS item.
-
Tk_Item header