Image and tile C reference
These interfaces are private. See Image storage and tile clients for resource lifetimes.
-
int Rbc_GetTile(Tcl_Interp *interp, Tk_Window tkwin, const char *imageName, Rbc_Tile *tilePtr)
Acquire a new client token for a named Tk image.
Requires a live window. The interpreter-local server is shared by display, depth and image name, but each successful call returns its own client. On TCL_OK, the caller owns the token and must call Rbc_FreeTile before its window/client data disappear. On TCL_ERROR, the output is not assigned.
- Parameters:
interp – [inout] Interpreter owning the registry and receiving acquisition diagnostics.
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
imageName – [in] Name of an existing Tk image; copied by a new server.
tilePtr – [out] Required output receiving an owned client token only on success.
-
void Rbc_FreeTile(Rbc_Tile tile)
Release one client token and destroy the server if it was the last.
NULL is harmless. A released token is invalid; the magic check does not make stale pointers or repeated frees safe. Server teardown cancels pending idle notification. Active notification snapshots defer record reclamation.
- Parameters:
tile – [in] Client token to release, or NULL; ownership ends at this call.
-
void Rbc_SetTileChangedProc(Rbc_Tile tile, Rbc_TileChangedProc *changeProc, ClientData clientData)
Install or replace one client’s borrowed notification callback and data.
A NULL callback disables notification. No immediate callback is made. Notifications run after an idle pixmap update over preserved client records. Callbacks may release clients or process nested updates. Removed clients are skipped; newly added clients wait for a later update. Interpreter deletion stops the current pass. Callback data remains owned by the caller.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
changeProc – [in] Borrowed callback, or NULL to disable delivery.
clientData – [in] Opaque caller-owned callback data, passed unchanged at delivery.
-
Pixmap Rbc_PixmapOfTile(Rbc_Tile tile)
Return a borrowed cached pixmap, or None for no tile.
Do not free it or retain it across a tile update/release. Image changes are processed at idle, so this is a cache query, not a forced refresh.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
-
Tk_Image Rbc_ImageOfTile(Rbc_Tile tile)
Borrow the tile’s Tk image without acquiring another image reference.
Returns NULL for no tile or a deleted image. Do not call Tk_FreeImage on the result; use it only while the tile and current image state remain valid.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
-
int Rbc_GetTilePhoto(Rbc_Tile tile, Tk_PhotoImageBlock *blockPtr)
Borrow photo pixel storage into a caller-owned block record.
Clears the record first. Returns false for no tile or a non-photo image; a deleted image returns true with an empty block. The pixel pointer remains Tk-owned and is invalidated by image changes or deletion. No copy is made.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
blockPtr – [out] Required caller-owned descriptor; cleared before querying borrowed photo pixels.
-
Rbc_ColorImage Rbc_CreateColorImage(int width, int height)
Allocate an owned row-major RGBA pixel buffer and image record.
Dimensions must be nonnegative; invalid or overflowing sizes panic. Pixels start zeroed, including alpha. Release with Rbc_FreeColorImage. The returned image has no Tk image identity, reference count or change notification.
- Parameters:
width – [in] Nonnegative horizontal pixel count; source or destination role is specified above.
height – [in] Nonnegative vertical pixel count; source or destination role is specified above.
-
void Rbc_FreeColorImage(struct ColorImage *imagePtr)
Release both the pixel array and its owning image record.
Requires a valid non-NULL owned image. All borrowed pixel pointers become invalid. This does not delete or modify any Tk photo used to create it.
- Parameters:
imagePtr – [in] Owned non-NULL image consumed here, including its pixel allocation.
-
Rbc_ColorImage Rbc_PhotoToColorImage(Tk_PhotoHandle photo)
Copy a valid Tk photo into a newly owned RBC color image.
Copies pixels using the photo block’s pitch and channel offsets. The result is independent of later photo changes; release it with Rbc_FreeColorImage.
- Parameters:
photo – [in] Borrowed live Tk photo handle.
-
Rbc_ColorImage Rbc_PhotoRegionToColorImage(Tk_PhotoHandle photo, int x, int y, int width, int height)
Copy a clamped photo origin and limited spans into an owned image.
Requires a valid photo handle. An empty effective region returns an empty image, not NULL. Negative origins clamp without reducing positive spans. Non-RGB/RGBA layouts replicate offset[0] into RGB and supply opaque alpha, matching whole-photo conversion. The result owns its pixels and must be freed with Rbc_FreeColorImage.
- Parameters:
photo – [in] Borrowed live Tk photo handle.
x – [in] Horizontal source origin in pixels; clamped as described above.
y – [in] Vertical source origin in pixels; clamped as described above.
width – [in] Requested source horizontal span; negative or excessive spans extend to the edge.
height – [in] Requested source vertical span; negative or excessive spans extend to the edge.
-
void Rbc_ColorImageToPhoto(Tcl_Interp *interp, Rbc_ColorImage src, Tk_PhotoHandle photo)
Replace a borrowed Tk photo’s size and pixels from an RBC image.
Source ownership stays with the caller; Tk copies the block synchronously. Uses TK_PHOTO_COMPOSITE_SET, including alpha. This legacy void helper ignores return codes from Tk_PhotoSetSize and Tk_PhotoPutBlock; it does not provide a reliable success/failure status to its caller.
- Parameters:
interp – [inout] Interpreter receiving Tcl diagnostics; no ownership is transferred.
src – [in] Borrowed valid source image; ownership remains with the caller.
photo – [in] Borrowed live Tk photo handle.
Tile queries and origins
-
char *Rbc_NameOfTile(Rbc_Tile tile)
Return the borrowed image name; NULL yields an empty string.
An invalid magic value yields “not a tile”. Neither result validates a stale pointer. The server owns a live name; callers must not modify or free it.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
-
void Rbc_SizeOfTile(Rbc_Tile tile, int *widthPtr, int *heightPtr)
Read cached tile dimensions without forcing an idle refresh.
Both output pointers are required. NULL or invalid tokens yield zero sizes; deleted images may retain their last cached dimensions.
- Parameters:
tile – [in] Borrowed client token; validity and NULL policy are described above.
widthPtr – [out] Required output for cached width in pixels.
heightPtr – [out] Required output for cached height in pixels.
-
void Rbc_SetTileOrigin(Tk_Window tkwin, Rbc_Tile tile, int x, int y)
Align a client pattern origin through its window ancestry.
Requires a live client and window. Adds position and border offsets up to the toplevel, negates the result and updates both client origin and shared server GC. Does not retain windows or change other clients stored origins.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
tile – [in] Borrowed client token; validity and NULL policy are described above.
x – [in] Horizontal offset before ancestry translation, in pixels.
y – [in] Vertical offset before ancestry translation, in pixels.
-
void Rbc_SetTSOrigin(Tk_Window tkwin, Rbc_Tile tile, int x, int y)
Set a client origin directly in drawable coordinates.
Requires a live client and compatible window. Updates its stored origin and the shared server GC; callers must establish origins for each draw.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
tile – [in] Borrowed client token; validity and NULL policy are described above.
x – [in] Horizontal tile origin in drawable pixels.
y – [in] Vertical tile origin in drawable pixels.
Tile lifecycle implementation
-
static void RedrawTile(Tk_Window tkwin, Tile *tilePtr)
Refresh a live tile server using a client window.
Requires a live Tk image and compatible window. Allocates a replacement pixmap before freeing the old one when size changes, redraws the image, replaces the tiled GC, records dimensions and rebuilds the photo alpha mask. Releases masks with their platform-specific allocator. The image display procedure is an external callback boundary; this helper provides no lifetime barrier around it and has no error return.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
tilePtr – [inout] Live server whose native cache is rebuilt; Tk image must remain valid.
-
static void FreeTileRecord(DestroyData memory)
Reclaim a detached tile or client record after preservation ends.
Receives storage transferred through Tcl_EventuallyFree. Frees only the record: links, image and native resources must already have been released.
- Parameters:
memory – [in] Detached heap record transferred by Tcl_EventuallyFree; freed here.
-
static void UpdateTile(ClientData clientData)
Refresh the cache and notify a preserved snapshot of clients.
Preserves server and interpreter, clears the pending bit, and redraws using the first client window. A deleted image instead releases only the cached pixmap. Snapshots and preserves client membership after refresh, but reads callback pointers at delivery time. Removed clients are skipped, new clients wait for another pass, and callback replacement takes effect immediately. Stops delivery if the server is destroying or interpreter is deleted. Releases every snapshot reference even after early termination. Does not save or restore interpreter result state, and refresh precedes the client snapshot.
- Parameters:
clientData – [in] Live Tile server queued by the image-change callback.
-
static void ImageChangedProc(ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight)
Coalesce Tk image changes into a deferred cache update.
Ignores the changed rectangle and image dimensions. Schedules UpdateTile only when TILE_NOTIFY_PENDING is clear. Does not redraw synchronously or invoke client callbacks; server teardown must cancel the queued idle call.
- Parameters:
clientData – [in] Live Tile server registered with Tk_GetImage.
x – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
y – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
width – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
height – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
imageWidth – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
imageHeight – [in] Tk image-change metadata; ignored because refresh rebuilds the whole cache.
-
static void DestroyTile(Tile *tilePtr)
Detach a server and release all owned resources.
Marks destruction and cancels pending idle work. Invalidates remaining client tokens, clears their links and callbacks, and defers record frees. Destroys the client chain, removes a still-linked hash entry, releases pixmap, mask, Tk image, GC and copied name, then defers the server record free. Active notification preserves storage only, not these resources. Requires a live server and is not an idempotent operation.
- Parameters:
tilePtr – [in] Live owned server to detach and destroy; invalid after this call.
-
static Tile *CreateTile(Tcl_Interp *interp, Tk_Window tkwin, const char *imageName)
Acquire a Tk image and construct an unregistered tile server.
Allocates a zeroed record and acquires the image with ImageChangedProc. Acquisition failure frees the record and returns NULL with the Tk error. Success owns the copied name, image and client chain, and immediately builds native cache resources before returning. Hash registration and first-client attachment belong to CreateClient. Tk image acquisition and drawing can call image-provider code before that attachment exists.
- Parameters:
interp – [inout] Interpreter owning the registry and receiving acquisition diagnostics.
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
imageName – [in] Borrowed existing image name; copied on successful acquisition.
-
static void DestroyClient(TileClient *clientPtr)
Detach one live client and destroy an unused server.
Removes its chain link first. If no clients remain, destroys the server; then clears client validity, server/link pointers and callback and defers record reclamation. Requires a valid attached client. The removed record is no longer in the server chain when last-client teardown occurs.
- Parameters:
clientPtr – [in] Attached client to detach and release; invalid after this call.
-
static TileClient *CreateClient(Tcl_Interp *interp, Tk_Window tkwin, const char *name)
Acquire an interpreter-local server and append a new client token.
Zeroes the complete display/depth/interned-name key, including padding. Creates a hash entry and server if absent, removing the entry on acquisition failure. Every success allocates a distinct zeroed client with a borrowed window and no callback, appends it to the server chain and returns ownership to the caller. Existing server resources are shared, not copied.
- Parameters:
interp – [inout] Interpreter owning the registry and receiving acquisition diagnostics.
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
name – [in] Borrowed Tk image name used in the display/depth/name registry key.
-
static void TileInterpDeleteProc(ClientData clientData, Tcl_Interp *interp)
Destroy all tile servers when interpreter associated data is removed.
The clientData argument is interpreter-owned TileInterpData, not thread local storage. Clears each server hash pointer before destroying it so hash iteration remains valid, then deletes the table and associated-data entry and frees the registry. Invalidates outstanding client tokens.
- Parameters:
clientData – [in] Owned TileInterpData registry supplied as interpreter associated data.
interp – [inout] Interpreter whose tile registry is being removed.
-
static TileInterpData *GetTileInterpData(Tcl_Interp *interp)
Find or create the interpreter-owned tile registry.
Lazily allocates associated data and installs TileInterpDeleteProc. Uses a fixed-size multiword key for TileKey. Returns borrowed registry storage valid until associated-data teardown; no global or cross-interpreter sharing.
- Parameters:
interp – [inout] Live interpreter owning the lazily allocated associated-data registry.
-
struct TileInterpData
Interpreter-owned registry of shared tile servers.
Owns tileTable and its servers; interp is borrowed. The associated-data deletion callback destroys all registered servers before freeing this record.
-
struct Tile
Shared image cache and notification state for one tile key.
Owns name, Tk image, pixmap, mask, GC and client chain. Registry links are borrowed. Destruction releases resources immediately; Tcl preservation can defer only final record reclamation.
Public Members
-
char *name
Name of image used to generate the pixmap.
-
Display *display
Display where pixmap was created.
-
int flags
See definitions below.
-
int destroying
Resources released; record may be preserved by notification.
-
Tcl_Interp *interp
Borrowed owning interpreter.
-
Tcl_HashEntry *hashPtr
Pointer to hash table location.
-
Tcl_HashTable *tablePtr
Borrowed owning tile-cache table.
-
Pixmap pixmap
Pixmap generated from image.
-
Pixmap mask
Monochrome pixmap used as transparency mask.
-
GC gc
GC.
-
Tk_Image tkImage
Tk image token.
-
int width
Cached image width in pixels.
-
int height
Cached image height in pixels.
-
char *name
-
struct Rbc_TileClientStruct
Individual tile token with borrowed window and callback data.
The server chain owns membership. Origin is client-local, while native resources are shared. A detached preserved token has its magic, server, link and callback cleared before eventual reclamation.
Public Members
-
unsigned int magic
Validation marker for a live tile client token.
-
Tk_Window tkwin
Client window.
-
int xOrigin
Tiling origin in relation to the client window.
-
int yOrigin
Tiling origin in relation to the client window.
-
Rbc_TileChangedProc *notifyProc
If non-NULL, routine to call to when tile image changes.
-
ClientData clientData
Data to pass to when calling the above routine.
-
Rbc_ChainLink *linkPtr
Pointer to client entry in the server’s client list.
Used to delete the client
-
unsigned int magic
-
struct TileKey
Composite key for interpreter-local tile sharing.
Borrows the display and interned image-name UID and records screen depth. The whole structure is zeroed before hashing because padding participates in the fixed-size multiword key.
Native tiled shapes
-
void Rbc_TileRectangle(Tk_Window tkwin, Drawable drawable, Rbc_Tile tile, int x, int y, int width, int height)
Draw one rectangle using borrowed native tile resources.
Requires a live client/window and a usable cached pixmap with positive tile dimensions. None drawables or nonpositive dimensions are ignored. Does not refresh pending image changes; native failures have no status return. Transparency uses platform masks rather than continuous alpha blending.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
drawable – [in] Compatible destination drawable, or None to draw nothing.
tile – [in] Borrowed client token; validity and NULL policy are described above.
x – [in] Left destination coordinate in pixels.
y – [in] Top destination coordinate in pixels.
width – [in] Rectangle width in pixels; nonpositive values draw nothing.
height – [in] Rectangle height in pixels; nonpositive values draw nothing.
-
void Rbc_TileRectangles(Tk_Window tkwin, Drawable drawable, Rbc_Tile tile, XRectangle *rectArr, Tcl_Size nRects)
Draw a borrowed rectangle array with one shared tile.
None drawables, NULL arrays and nonpositive counts are ignored. Other lifetime requirements match Rbc_TileRectangle. Windows retains DCs across the batch; X11 batches opaque requests but draws masked rectangles singly.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
drawable – [in] Compatible destination drawable, or None to draw nothing.
tile – [in] Borrowed client token; validity and NULL policy are described above.
rectArr – [in] Borrowed native-coordinate rectangle array, or NULL to draw nothing.
nRects – [in] Number of array entries; nonpositive counts draw nothing.
-
void Rbc_TilePolygon(Tk_Window tkwin, Drawable drawable, Rbc_Tile tile, XPoint *pointArr, int nPoints)
Draw a borrowed nonempty polygon with a shared tile.
Requires a valid drawable, live client and usable cache. Callers must reject empty arrays; unlike rectangle helpers, polygon guards differ by platform. Uses native fill rules and temporary clipping resources for transparency. Does not force image refresh or propagate native drawing errors.
- Parameters:
tkwin – [in] Borrowed live window supplying display, depth and coordinate context.
drawable – [in] Valid compatible destination drawable.
tile – [in] Borrowed client token; validity and NULL policy are described above.
pointArr – [in] Borrowed nonempty array of native-coordinate polygon vertices.
nPoints – [in] Positive number of accessible vertices.
-
static Pixmap RectangleMask(Display *display, Drawable drawable, int x, int y, int width, int height, Pixmap mask, int xOrigin, int yOrigin)
Build an X11 rectangle-sized repeating transparency mask.
Requires positive dimensions and a valid one-bit stipple. Allocates a depth-one pixmap, fills it using FillOpaqueStippled at the client origin translated into mask-local coordinates, and releases the temporary private GC. Returns an owned pixmap for Tk_FreePixmap; does not modify the source mask or return an error status.
- Parameters:
display – [in] Borrowed live X display owning the supplied drawable and resources.
drawable – [in] Borrowed destination drawable compatible with the window/display; no ownership is transferred.
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.
mask – [in] Borrowed valid depth-one repeating stipple; not consumed or modified.
xOrigin – [in] Horizontal tile origin in destination coordinates, translated into mask-local coordinates here.
yOrigin – [in] Vertical tile origin in destination coordinates, translated into mask-local coordinates here.
-
static Pixmap PolygonMask(Display *display, XPoint *pointArr, int nPoints, Region2D *regionPtr, Pixmap mask, int xOrigin, int yOrigin)
Build an X11 polygon-shaped repeating transparency mask.
Uses the supplied inclusive bounding box to allocate a depth-one pixmap. Copies and translates XPoint coordinates, clears the mask with the default GC foreground, then draws a Complex polygon using FillStippled and the translated client origin. Frees temporary points and GC; returns an owned pixmap for Tk_FreePixmap. Requires a valid nonempty point array and bounds; translated coordinates are still stored as XPoint shorts.
- Parameters:
display – [in] Borrowed live X display owning the supplied drawable and resources.
pointArr – [in] Borrowed nonempty array of nPoints absolute XPoint coordinates; not modified.
nPoints – [in] Positive number of initialized point entries; caller validates array bounds.
regionPtr – [in] Borrowed inclusive nonempty polygon bounds; translated coordinates must fit XPoint shorts.
mask – [in] Borrowed valid depth-one repeating stipple; not consumed or modified.
xOrigin – [in] Horizontal tile origin in destination coordinates, translated into mask-local coordinates here.
yOrigin – [in] Vertical tile origin in destination coordinates, translated into mask-local coordinates here.
The mask helper reference above describes X11. Windows tiled shapes and rbcWindowsTiles.TileRegion() are
extracted separately in Windows native backend C reference; see Image storage and tile clients for origin and DC batching rules.
Storage and coordinate implementation
- group Image storage and coordinate helpers
Functions
-
static size_t GetColorImagePixelCount(int width, int height)
Validate dimensions and calculate their size_t pixel product.
Requires nonnegative dimensions; zero is valid. Panics for negative input or multiplication overflow. Returns a pixel count, not a byte count. Does not allocate storage; the allocator separately checks element size.
- Parameters:
width – [in] Nonnegative horizontal pixel count; source or destination role is specified above.
height – [in] Nonnegative vertical pixel count; source or destination role is specified above.
-
static ptrdiff_t GetPhotoByteOffset(const Tk_PhotoImageBlock *blockPtr, int x, int y)
Calculate a photo-block byte displacement with wide arithmetic.
Borrows a valid Tk block. Computes y*pitch + x*pixelSize in Tcl_WideInt and checks the ptrdiff_t range before conversion. Does not validate x/y against image bounds, channel offsets, or accessible storage; callers establish those conditions before adding the result to pixelPtr.
- Parameters:
blockPtr – [in] Borrowed valid photo block; pitch and pixelSize determine byte displacement.
x – [in] In-bounds column index; not validated here.
y – [in] In-bounds row index; not validated here.
-
static int ClipImageRegion(int imageWidth, int imageHeight, int *xPtr, int *yPtr, int *widthPtr, int *heightPtr)
Clamp a source origin and limit its spans to the remaining image.
Reads and rewrites all four coordinate outputs. Negative image dimensions panic. Origins clamp to inclusive bounds [0,imageSize]; negative or excessive spans become the remaining distance to the edge. A negative origin does not subtract from a positive span: this is not geometric rectangle intersection. Returns true only when both resulting spans are positive. Performs no allocation or image access.
- Parameters:
imageWidth – [in] Nonnegative source width in pixels.
imageHeight – [in] Nonnegative source height in pixels.
xPtr – [inout] Required input/output for horizontal origin; rewritten to the effective region.
yPtr – [inout] Required input/output for vertical origin; rewritten to the effective region.
widthPtr – [inout] Required input/output for horizontal span; rewritten to the effective region.
heightPtr – [inout] Required input/output for vertical span; rewritten to the effective region.
-
static int MapNearestCoordinate(int origin, int span, int position, int destSpan)
Map an in-range destination position into a source interval.
Requires positive span/destSpan and position in [0,destSpan). Computes position*span/destSpan in double, truncates, caps at span-1 and adds origin. Caller ensures that sum lies within the source and int range. Has no half-pixel offset, interpolation or allocation.
- Parameters:
origin – [in] Source interval origin; origin plus span must be representable.
span – [in] Positive source interval length.
position – [in] Destination index in [0,destSpan).
destSpan – [in] Positive destination interval length.
-
static int MapVirtualCoordinate(int srcSize, double virtualPosition, int virtualSize)
Map a virtual destination position to a clamped source index.
Requires positive source and virtual sizes and a finite virtualPosition. Scales in double, clamps at either source edge, and truncates interior values. Allows positions outside the virtual image; those repeat edge pixels rather than producing transparent padding. Does not allocate.
- Parameters:
srcSize – [in] Positive source dimension.
virtualPosition – [in] Finite coordinate in the virtual destination; outlying values repeat edge samples.
virtualSize – [in] Positive virtual destination dimension.
-
void Rbc_GammaCorrectColorImage(Rbc_ColorImage src, double newGamma)
Apply a gamma lookup table to RGB bytes in place, preserving alpha.
Borrows a writable valid image. newGamma must be finite and positive; invalid gamma panics. Builds a stack table with 255*pow(i/255,1/gamma), clamping and truncating each entry to a byte. Replaces RGB independently for every pixel without changing alpha, dimensions or ownership. No Tk change notification is issued for this CPU-side mutation.
- Parameters:
src – [inout] Borrowed writable image modified in place.
newGamma – [in] Finite positive gamma used as the reciprocal exponent.
-
Region2D *Rbc_SetRegion(int x, int y, int width, int height, Region2D *regionPtr)
Set inclusive integer bounds from an origin and size.
Computes endpoints in wide arithmetic and panics if either cannot fit int. Does not normalize nonpositive sizes or allocate a region.
- Parameters:
x – [in] Left coordinate in pixels.
y – [in] Top coordinate in pixels.
width – [in] Pixel width; right is x+width-1. Positive sizes describe a nonempty region.
height – [in] Pixel height; bottom is y+height-1.
regionPtr – [out] Required caller-owned region record, also returned by the function.
-
static void TempImageChangedProc(ClientData clientData, int x, int y, int width, int height, int imageWidth, int imageHeight)
Ignore notifications from the internally managed temporary photo.
This callback does not schedule redraw, retain data or release the image token.
- Parameters:
clientData – [in] Caller-supplied callback data; unused and not dereferenced.
x – [in] Changed image rectangle X origin; unused.
y – [in] Changed image rectangle Y origin; unused.
width – [in] Changed rectangle width; unused.
height – [in] Changed rectangle height; unused.
imageWidth – [in] Current complete image width; unused.
imageHeight – [in] Current complete image height; unused.
-
static size_t GetColorImagePixelCount(int width, int height)
Drawable snapshot to photo
-
int Rbc_SnapPhoto(Tcl_Interp *interp, Tk_Window tkwin, Drawable drawable, int x, int y, int width, int height, int destWidth, int destHeight, const char *photoName, double inputGamma)
Capture a drawable and optionally box-resample it into an existing photo.
Borrows window, drawable, interpreter and photo name. Requires positive capture dimensions, nonnegative destination dimensions and finite positive gamma; reports TCL_ERROR for invalid arguments, missing photo or failed native capture. Owns and releases captured/resampled RBC images. If sizes differ, uses the box filter on both axes. Zero destination sizes are not a request to retain the source size. Replaces the photo through the legacy void writer, whose Tk errors are not propagated; TCL_OK therefore covers capture/processing, not a checked photo-write result. Native capture and Tk photo operations must run with valid objects on their owning thread.
- Parameters:
interp – [inout] Interpreter receiving Tcl diagnostics; no ownership is transferred.
tkwin – [in] Borrowed live window supplying the native display context.
drawable – [in] Borrowed compatible drawable to capture.
x – [in] Capture left coordinate in drawable pixels.
y – [in] Capture top coordinate in drawable pixels.
width – [in] Positive capture width in pixels.
height – [in] Positive capture height in pixels.
destWidth – [in] Nonnegative destination width in pixels.
destHeight – [in] Nonnegative destination height in pixels.
photoName – [in] Borrowed name of an existing destination photo.
inputGamma – [in] Finite positive gamma for native capture.