Image compatibility C reference

These functions are defined by RBC in rbcImage.c and declared privately in rbcImage.h. See Temporary images and private Tk adapters for lifetime and private-layout requirements.

int Rbc_ImageIsDeleted(Tk_Image tkImage)

Inspect whether a retained image instance has lost its image manager.

Require a non-NULL, unfreed Tk_Image. Return true for a NULL master pointer or NULL master type. This RBC-defined helper reads copied private Tk layout; it cannot validate an arbitrary or already-freed pointer.

Parameters:
  • tkImage – [in] Borrowed retained image instance; master validity requirements are described above.

Tk_ImageMaster Rbc_ImageGetMaster(Tk_Image tkImage)

Return the borrowed master pointer from a retained, non-NULL Tk image.

No reference is acquired. The result may be NULL; callers must establish validity before passing it to further Tk or RBC operations. This helper is implemented by RBC using copied private Tk structure layout.

Parameters:
  • tkImage – [in] Borrowed retained image instance; master validity requirements are described above.

Tk_ImageType *Rbc_ImageGetType(Tk_Image tkImage)

Return a borrowed image-type pointer using RBC’s private-layout adapter.

Require a retained non-NULL instance with a non-NULL master. A deleted master’s type may be NULL. Do not free or modify the returned descriptor.

Parameters:
  • tkImage – [in] Borrowed retained image instance; master validity requirements are described above.

Pixmap Rbc_ImageGetPhotoPixmap(Tk_Image photoImage)

Borrow the native display pixmap of a live photo instance, or return None for a different live image type.

Require non-NULL instance, master and type. This is RBC’s private-layout accessor, not a retained pixel snapshot. Do not free the pixmap or retain it across image changes.

Parameters:
  • photoImage – [in] Borrowed live instance with a valid master and image type.

GC Rbc_ImageGetPhotoGC(Tk_Image photoImage)

Borrow the display GC of a live photo instance, or return NULL for another live type.

Require non-NULL instance, master and type. Do not free or mutate the returned Tk-owned GC. This RBC helper relies on private photo layout.

Parameters:
  • photoImage – [in] Borrowed live instance with a valid master and image type.

const char *Rbc_NameOfImage(Tk_Image tkImage)

Return the borrowed Tk name of an image with a valid master.

No name copy or lifetime reference is acquired. Do not free the result; copy it before an operation that can invalidate the image or master.

Parameters:
  • tkImage – [in] Borrowed retained image instance; master validity requirements are described above.

Tk_Image Rbc_CreateTemporaryImage(Tcl_Interp *interp, Tk_Window tkwin, ClientData clientData)

Create a named photo through Tcl and acquire an image instance for tkwin.

Borrow interp, tkwin and clientData; the installed change callback is a no-op. Return a caller-owned token paired with Rbc_DestroyTemporaryImage(), or NULL on failure. The Tcl result object is retained while Tk_GetImage consumes its name. If instance acquisition fails, the named image is deleted through Tk’s C API while preserving the acquisition error. Evaluates the image command in the current context and does not preserve caller lifetime or interpreter result across callbacks.

Parameters:
  • interp – [inout] Interpreter in which the image command is evaluated; receives the result or error.

  • tkwin – [in] Borrowed live window providing the native display and drawable context.

  • clientData – [in] Borrowed opaque data supplied to the no-op image-change callback.

int Rbc_DestroyTemporaryImage(Tcl_Interp *interp, Tk_Image tkImage)

Delete a temporary image through Tk’s C API and consume its instance.

NULL is a successful no-op. Otherwise require a retained token. Already deleted images still have their instance released. Always returns TCL_OK; cleanup preserves interpreter state and does not evaluate the image command. Tk deletion may notify other image clients. Callers must detach the token from owner fields before calling and provide their own owner lifetime guard.

Parameters:
  • interp – [inout] Interpreter owning the temporary image; result state is preserved.

  • tkImage – [in] Owned temporary image instance consumed by this call, or NULL.

Data records and member contracts

These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.

struct TkImageMasterStruct

Compatibility view of Tk image master internals; RBC does not own these fields.

Public Members

Tk_ImageType *typePtr

Information about image type.

NULL means that no image manager owns this image: the image was deleted.

ClientData masterData

One-word argument to pass to image mgr when dealing with the master, as opposed to instances.

int width

Last known dimensions for image.

int height

Last known dimensions for image.

Tcl_HashTable *tablePtr

Pointer to hash table containing image (the imageTable field in some TkMainInfo structure).

Tcl_HashEntry *hPtr

Hash entry in mainPtr->imageTable for this structure (used to delete the hash entry).

TkImage *instancePtr

Pointer to first in list of instances derived from this name.

struct TkImageStruct

Compatibility view of Tk image instance internals; layout must match the supported Tk version.

Public Members

Tk_Window tkwin

Window passed to Tk_GetImage (needed to “re-get” the image later if the manager changes).

Display *display

Display for tkwin.

Needed because when the image is eventually freed tkwin may not exist anymore.

struct TkImageMasterStruct *masterPtr

Borrowed Tk image master.

ClientData instanceData

Tk image-type instance payload.

Tk_ImageChangedProc *changeProc

Tk image-change callback.

ClientData widgetClientData

Borrowed callback data supplied by the image consumer.

struct Image *nextPtr

Next in list of all image instances associated with the same name.

struct TkPhotoInstanceStruct

Compatibility view of Tk photo instance internals; RBC does not own these fields.

Public Members

TkPhotoMaster *masterPtr

Pointer to master for image.

Display *display

Display for windows using this instance.

Colormap colormap

The image may only be used in windows with this particular colormap.

struct TkPhotoInstanceStruct *nextPtr

Next Tk-managed instance of the same photo master.

int refCount

Number of instances using this structure.

Tk_Uid palette

Palette for these particular instances.

double outputGamma

Gamma value for these instances.

Tk_Uid defaultPalette

Default palette to use if a palette is not specified for the master.

TkColorTable *colorTablePtr

Pointer to information about colors allocated for image display in windows like this one.

Pixmap pixels

X pixmap containing dithered image.

int width

Dimensions of the pixmap.

int height

Dimensions of the pixmap.

char *error

Error image, used in dithering.

XImage *imagePtr

Image structure for converted pixels.

XVisualInfo visualInfo

Information about the visual that these windows are using.

GC gc

Graphics context for writing images to the pixmap.