Cairo backend C reference
These static helpers belong to rbcRenderCairo.c. They are not component APIs. The documentation preprocessor
enables RBC_HAVE_CAIRO to extract this group; it does not change the configured library build or require Cairo to
build docs. See Cairo surfaces and drawing contexts for platform-specific target lifetime, path consumption and pattern
ownership. The parameter contracts describe backend state, not permission to call a helper on an arbitrary renderer
context. In particular, fill callbacks require initialized fill style, and cleanup consumes its context.
Start with BeginRenderTarget() for setup, StrokeRenderPath() for stroke composition, and
CreateRenderPhoto() for copied pixel storage. Component code should use the interface in Renderer C reference
instead of calling these static functions.
- group Cairo backend internals
Private context and image-conversion services, compiled with Cairo enabled.
Functions
-
static void CairoClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)
Save graphics state and intersect with a rectangular clip.
Nonpositive dimensions become an empty rectangle. Coordinates use the current transform; the common dispatcher owns clip depth. Cairo clipping consumes the current path, so callers must finish pending geometry before pushing a clip.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
x – [in] Destination X coordinate in display units.
y – [in] Destination Y coordinate in display units.
width – [in] Rectangle width in pixels; nonpositive clip dimensions select an empty rectangle.
height – [in] Rectangle height in pixels; nonpositive clip dimensions select an empty rectangle.
-
static void CairoClipEnd(Rbc_RenderContext *ctx)
Restore the state saved by one clip push.
Requires a matching CairoClipBegin through common dispatch. This does not decrement common clip depth itself and cannot restore a consumed path.
- Parameters:
ctx – [inout] Live Cairo context with one matching saved clip state; common dispatch owns depth bookkeeping.
-
static void FreeRenderContext(Rbc_RenderContext *ctx)
Release a fully or partially initialized Cairo context.
Destroys owned pattern, cairo_t and surface reference, then restores saved Windows DC state and releases its acquisition record. Finally frees the context. Does not flush/report drawing errors; CairoEnd provides that normal-completion behavior. Borrowed graph and component resources survive.
- Parameters:
ctx – [in] Owned non-NULL Cairo context with zero-initialized optional fields; consumed even after partial setup.
-
static cairo_antialias_t GetAntialias(int mode)
Translate an RBC antialias mode to Cairo.
Known modes map directly; unrecognized values select Cairo default. This is a mapping helper, not option validation.
- Parameters:
mode – [in] RBC_ANTIALIAS_* value; an unknown value selects Cairo default.
- Returns:
Mapped Cairo antialias constant.
-
static void SetStrokeColor(cairo_t *cr, const XColor *colorPtr)
Set an opaque RGB source from a borrowed Tk color.
Requires a non-NULL color. Channels are normalized from 16-bit values; Cairo copies the numeric source, so the color pointer is not retained.
- Parameters:
cr – [inout] Borrowed live cairo_t receiving an opaque RGB source.
colorPtr – [in] Required borrowed Tk color; channel values are copied.
-
static void StrokeRenderPath(Rbc_RenderContext *ctx)
Stroke and consume the current path using the context’s dash policy.
Double-dash mode first paints a solid off-color stroke while preserving the path, then applies foreground dashes and consumes the path. Owns no additional resources. This is not an XOR/raster-operation adapter.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
-
static Rbc_RenderContext *BeginRenderTarget(Graph *graphPtr, Drawable drawable, const XColor *colorPtr, double width, const Rbc_Dashes *dashesPtr, const XColor *offColorPtr, int targetWidth, int targetHeight, int left, int top, int right, int bottom)
Create a Cairo context for an explicitly sized native target and clip.
Borrows graph/drawable, copies stroke colors and dash values, and owns the resulting surface reference and cairo_t. The four final integers are inclusive clip edges; target dimensions describe the underlying drawable. Establishes the clip before the half-pixel translation. Windows can reference the current marker-pass image, otherwise it acquires/saves a display DC; X11 creates an Xlib surface wrapper. Printing/metafile Windows targets decline Cairo. Finish successful contexts with Rbc_RenderEnd while borrowed resources and any enclosing marker pass remain alive. No native retry occurs here.
- Returns:
Owned context, or NULL after cleanup if input or setup is unsupported.
- Parameters:
graphPtr – [in] Borrowed owning graph, kept alive until context release; must select Cairo.
drawable – [in] Borrowed non-None destination kept valid until context release and within any enclosing marker pass.
colorPtr – [in] Required borrowed Tk color; channel values are copied.
width – [in] Finite positive stroke width in display units, not destination width.
dashesPtr – [in] Optional borrowed dash specification copied into the context; NULL selects solid.
offColorPtr – [in] Optional borrowed off-dash color copied into the context when used.
targetWidth – [in] Positive destination width in pixels.
targetHeight – [in] Positive destination height in pixels.
left – [in] Inclusive left target clip edge in pixels.
top – [in] Inclusive top target clip edge in pixels.
right – [in] Inclusive right target clip edge in pixels.
bottom – [in] Inclusive bottom target clip edge in pixels.
-
static void CairoPolyline(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)
Build and stroke a connected trace.
Counts below two do nothing. Borrows mapped points and preserves joins within the trace. StrokeRenderPath consumes the path, including its optional off-color pass; callers must not leave unrelated pending geometry.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
points – [in] Borrowed mapped point array, readable for count entries.
count – [in] Number of geometry records, not bytes.
-
static void CairoArcPath(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)
Replace the path with a normalized mapped ellipse arc.
Builds the arc under a temporary translate/scale, then restores the transform before painting. Full sweeps close without a radial edge; partial sectors add the center and chords close directly. The caller supplies common-dispatch-validated geometry.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
arc – [in] Borrowed finite ellipse geometry already normalized by common dispatch; radii are positive.
-
static void CairoArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)
Stroke the normalized arc with current dash policy.
Replaces and consumes the current path. The temporary ellipse transform affects geometry only, preserving screen-space line widths and dash lengths.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
arc – [in] Borrowed finite ellipse geometry already normalized by common dispatch; radii are positive.
-
static void CairoFillArc(Rbc_RenderContext *ctx, const Rbc_RenderArcGeometry *arc)
Fill a normalized closed arc with the configured style.
Temporarily cancels the half-pixel center translation and selects even-odd fill. A retained bitmap pattern takes precedence over solid opacity. Common dispatch excludes open arcs; a solid style requires its borrowed foreground to remain live.
- Parameters:
ctx – [inout] Live Cairo fill context with initialized fillStyle and optional owned bitmapPattern.
arc – [in] Borrowed finite ellipse geometry already normalized by common dispatch; radii are positive.
-
static void CairoLineStyle(Rbc_RenderContext *ctx, int capStyle, int joinStyle)
Translate native cap and join constants to Cairo state.
Round and projecting caps map to round and square; other caps use butt. Round and bevel joins map directly, with miter as the fallback. Does not change dash state or pending geometry.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
capStyle – [in] X/Tk cap constant: round and projecting have dedicated mappings; other values select butt.
joinStyle – [in] X/Tk join constant: round and bevel have dedicated mappings; other values select miter.
-
static void CairoDashBackground(Rbc_RenderContext *ctx, const XColor *color)
Update the off-color underlay without changing dashes.
Enables double-dash only when dashes exist and a color is supplied, copying that color by value. NULL disables the underlay; unlike initial construction, this helper does not collapse equal colors to a solid stroke.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
color – [in] Optional borrowed off-dash color copied by value; NULL disables the underlay.
-
static void CairoSegments(Rbc_RenderContext *ctx, const Segment2D *segments, Tcl_Size count)
Stroke independent segment subpaths in bounded batches.
Ordinary strokes flush every 8192 segments and at completion. Double-dash strokes flush after each segment to preserve painter order at intersections. Input geometry is borrowed, and each flush consumes the path.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
segments – [in] Borrowed mapped endpoint pairs, readable for count Segment2D records.
count – [in] Number of geometry records, not bytes.
-
static void AppendRenderSymbol(cairo_t *cr, const Rbc_RenderShape *shape, const Point2D *center)
Append one independent symbol without painting it.
Borrows shape and center. Circles start a new subpath; segment shapes use pairs and ignore an unmatched final point; other nonempty shapes close a polygon. Does not clear existing shapes, set paint or allocate caller-owned storage.
- Parameters:
cr – [inout] Borrowed live cairo_t; the symbol is appended to its current path without painting.
shape – [in] Borrowed screen-space template; nPoints must fit its fixed point array.
center – [in] Borrowed mapped symbol center added to template coordinates.
-
static uint32_t RenderAreaPixel(const XColor *color)
Convert a borrowed Tk color to an opaque ARGB32 pixel.
NULL becomes transparent zero. Color channels use rounded division by 257, not truncation; opaque channels require no additional premultiplication.
- Parameters:
color – [in] Optional borrowed color; NULL selects transparent pixels.
- Returns:
Opaque ARGB32 pixel, or transparent zero for NULL.
-
static cairo_pattern_t *CreateRenderStipple(Graph *graphPtr, Pixmap stipple, const XColor *foreground, const XColor *background)
Copy a named bitmap into an owned repeating pattern.
Reads XYPixmap bits before destination-context acquisition and maps them to foreground/background ARGB pixels. Releases the temporary XImage and local surface reference. Returns a nearest-filtered pattern owned by the caller, or NULL after cleanup on failure; NULL colors create transparent pixels.
- Parameters:
graphPtr – [in] Borrowed owning graph with live display, window and interpreter resources.
stipple – [in] Borrowed named Tk bitmap, readable through the graph display.
foreground – [in] Optional borrowed foreground color; NULL converts set bits to transparent pixels.
background – [in] Optional borrowed background color; NULL converts clear bits to transparent pixels.
- Returns:
Owned repeating nearest-filtered pattern, or NULL after cleanup on failure.
-
static void CairoFillRectangles(Rbc_RenderContext *ctx, const Rbc_RenderRectangle *rectangles, Tcl_Size count)
Fill rectangle batches with optional group opacity.
Temporarily cancels pixel-center translation and uses winding fill. Nonpositive rectangles are skipped and paths flush every 8192 input entries. Opacity applies once to the composed group, including stipple paint, rather than separately at every overlap. Restores graphics state after consuming the path.
- Parameters:
ctx – [inout] Live Cairo fill context with initialized fillStyle and optional owned bitmapPattern.
rectangles – [in] Borrowed mapped rectangle array, readable for count entries.
count – [in] Number of geometry records, not bytes.
-
static void FillRenderArea(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count, cairo_pattern_t *pattern)
Fill a borrowed polygon in pixel-boundary coordinates.
Requires at least three readable points and no unrelated pending geometry. Cancels the half-pixel translation, selects even-odd fill and optionally sets a borrowed pattern. This helper does not save or restore graphics state: callers must bracket it or end the context afterward.
- Parameters:
ctx – [inout] Live Cairo-backed context with initialized graphics state; no ownership transfer.
points – [in] Borrowed mapped point array, readable for count entries.
count – [in] Number of vertices; caller must supply at least three.
pattern – [in] Optional borrowed fill pattern; NULL retains the current Cairo source.
-
static cairo_pattern_t *CreateRenderBitmap(Graph *graphPtr, Pixmap bitmap, Pixmap mask, int width, int height, const XColor *foreground, const XColor *background)
Copy mapped bitmap and optional mask into an owned pattern.
Caller supplies positive dimensions and pixmaps readable over that rectangle. When mask equals bitmap, one XImage serves both roles and is freed once. Distinct readbacks and the local surface are cleaned up on failure. Returns a nearest-filtered, nonrepeating pattern or NULL; source pixmaps remain borrowed.
- Parameters:
graphPtr – [in] Borrowed owning graph with live display, window and interpreter resources.
bitmap – [in] Borrowed one-bit source pixmap readable over width by height pixels.
mask – [in] Optional one-bit visibility mask, or None; may equal bitmap. Zero mask bits become transparent.
width – [in] Positive source bitmap and mask width in pixels.
height – [in] Positive source bitmap and mask height in pixels.
foreground – [in] Optional borrowed foreground color; NULL converts set bits to transparent pixels.
background – [in] Optional borrowed background color; NULL converts clear bits to transparent pixels.
- Returns:
Owned nonrepeating nearest-filtered pattern, or NULL after cleanup on failure.
-
static void CairoFillPolygon(Rbc_RenderContext *ctx, const Point2D *points, Tcl_Size count)
Fill a polygon using retained solid or stipple style.
Common dispatch guarantees at least three points. Solid opacity is applied only without a stipple; the retained pattern already owns its pixel alpha. Saves and restores state around FillRenderArea, but consumes the path.
- Parameters:
ctx – [inout] Live Cairo fill context with initialized fillStyle and optional owned bitmapPattern.
points – [in] Borrowed mapped point array, readable for count entries.
count – [in] Number of geometry records, not bytes.
-
static cairo_pattern_t *CreateRenderPhoto(const Tk_PhotoImageBlock *block)
Copy a Tk photo block into an owned repeating Cairo pattern.
Validates RGB offsets. A distinct valid alpha offset selects alpha; otherwise pixels are opaque. Premultiplies RGB with rounded division by 255. The pattern retains its copied surface; no source pixel pointer escapes. Does not validate the caller’s allocation size or retain the Tk photo itself.
- Returns:
Owned nearest-filtered ARGB32 pattern, or NULL on invalid channel layout or failed surface/pattern creation. Caller destroys a returned pattern.
- Parameters:
block – [in] Borrowed photo block with readable pixels, dimensions, pitch and channel layout.
-
static void CairoEnd(Rbc_RenderContext *ctx)
Flush, release and report completion errors.
Requires a live context and interpreter after common clip unwinding. Captures context status, then surface status if needed, frees owned resources, and reports a background Tcl exception with interpreter state restored. This is terminal cleanup, not a request to replay native drawing.
- Parameters:
ctx – [in] Owned live Cairo context after common clip unwinding; consumed by this call.
-
static void CairoClipBegin(Rbc_RenderContext *ctx, int x, int y, int width, int height)
Context storage
-
struct CairoRenderContext
Cairo paint context owning graphics resources; input graph and style resources remain borrowed.
Public Members
-
Rbc_RenderContext core
Common dispatch prefix; must remain first.
-
Rbc_RenderFillStyle fillStyle
Copied fill policy with borrowed color and stipple resources.
-
cairo_surface_t *surface
Owned surface reference released during context cleanup.
-
cairo_t *cr
Owned Cairo drawing state, destroyed before the surface.
-
cairo_pattern_t *bitmapPattern
Owned optional bitmap/stipple pattern.
-
int bitmapWidth
Bitmap/pattern width in pixels.
-
int bitmapHeight
Bitmap/pattern height in pixels.
-
XColor foreground
Copied stroke foreground.
-
XColor offColor
Copied off-dash underlay color.
-
int doubleDash
Nonzero enables the off-dash underlay.
-
int nDashes
Number of initialized entries in dashes.
-
double dashes[RBC_MAX_DASH_VALUES]
Copied dash lengths in Cairo user-space units.
-
double dashOffset
Dash phase in Cairo user-space units.
-
Rbc_RenderContext core
Windows context and marker-pass target
The target owns the shared DIB and borrows the graph and destination. Its image surface and DC are views of that DIB, not independently owned objects.
-
struct CairoRenderContext
Cairo paint context owning graphics resources; input graph and style resources remain borrowed.
Public Members
-
Rbc_RenderContext core
Common dispatch prefix; must remain first.
-
Rbc_RenderFillStyle fillStyle
Copied fill policy with borrowed color and stipple resources.
-
cairo_surface_t *surface
Owned surface reference released during context cleanup.
-
cairo_t *cr
Owned Cairo drawing state, destroyed before the surface.
-
cairo_pattern_t *bitmapPattern
Owned optional bitmap/stipple pattern.
-
int bitmapWidth
Bitmap/pattern width in pixels.
-
int bitmapHeight
Bitmap/pattern height in pixels.
-
XColor foreground
Copied stroke foreground.
-
XColor offColor
Copied off-dash underlay color.
-
int doubleDash
Nonzero enables the off-dash underlay.
-
int nDashes
Number of initialized entries in dashes.
-
double dashes[RBC_MAX_DASH_VALUES]
Copied dash lengths in Cairo user-space units.
-
double dashOffset
Dash phase in Cairo user-space units.
-
Rbc_WinDrawableDC *dcState
Owned Windows DC acquisition record, or NULL.
-
HDC dc
DC borrowed from dcState while the context is live.
-
int savedDC
SaveDC restoration token; zero means no saved state.
-
Rbc_RenderContext core
-
struct Rbc_RenderTarget
Windows Cairo marker-pass target; EndMarkerPass copies back and releases owned resources.
Public Members
-
cairo_surface_t *surface
Owned Windows DIB surface for the complete marker pass.
-
cairo_surface_t *image
Borrowed image surface obtained from surface; not destroyed separately.
-
Rbc_WinDrawableDC *destinationState
Owned acquisition record for the original destination.
-
HDC destinationDC
Original destination DC borrowed from destinationState.
-
HDC dc
DIB DC borrowed from surface.
-
Drawable drawable
Owned Tk-compatible wrapper around the DIB DC.
-
cairo_surface_t *surface