Image transform C reference

These private declarations are in rbcImage.h. Color rotation is implemented in rbcImage.c; bitmap transforms have Windows and X11 implementations in rbcWinImage.c and rbcUnixImage.c. See Color-image rotation and bitmap transforms.

Rbc_ColorImage Rbc_RotateColorImage(Rbc_ColorImage src, double angle)

Return a newly owned color image rotated counterclockwise in display space.

Borrow image and accept a finite angle in degrees, normalized modulo 360. Non-finite angles panic. Empty input is copied without swapping dimensions. Right angles copy pixels exactly; other angles use three filtered shears after a quadrant rotation, with transparent white background. The result never aliases image, even at zero degrees; free with Rbc_FreeColorImage().

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

  • angle – [in] Finite counterclockwise angle in degrees; normalized modulo 360.

Pixmap Rbc_RotateBitmap(Tk_Window tkwin, Pixmap bitmap, int width, int height, double theta, int *widthPtr, int *heightPtr)

Create an owned one-bit pixmap containing the rotated source bitmap.

Borrow the Tk window and source bitmap, whose positive dimensions must match the supplied sizes. Require a finite angle in degrees and non-NULL dimension output pointers. On success assign output sizes and return a new pixmap for Tk_FreePixmap(). None reports a detected failure; do not rely on output dimensions after failure, since Windows and X11 initialize them differently. Rotation uses discrete sampling, not the color-image shear filter.

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

  • bitmap – [in] Borrowed one-bit source pixmap matching width and height.

  • width – [in] Positive source width in pixels.

  • height – [in] Positive source height in pixels.

  • theta – [in] Finite rotation angle in degrees.

  • widthPtr – [out] Required output for the new width; unspecified on failure.

  • heightPtr – [out] Required output for the new height; unspecified on failure.

Pixmap Rbc_ScaleBitmap(Tk_Window tkwin, Pixmap srcBitmap, int srcWidth, int srcHeight, int scaledWidth, int scaledHeight)

Create an owned one-bit pixmap scaled to the requested dimensions.

Borrow the window and source bitmap. Require positive source and destination sizes and a source bitmap matching its declared dimensions. Release a returned pixmap with Tk_FreePixmap(). X11 copies nearest-neighbour samples; Windows uses StretchBlt and does not propagate its status. A non-None return is not a portable guarantee that every native drawing operation succeeded.

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

  • srcBitmap – [in] Borrowed one-bit source pixmap matching its declared dimensions.

  • srcWidth – [in] Positive source horizontal dimension in pixels.

  • srcHeight – [in] Positive source vertical dimension in pixels.

  • scaledWidth – [in] Positive destination horizontal dimension in pixels.

  • scaledHeight – [in] Positive destination vertical dimension in pixels.

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)

Create only a region of a virtually scaled, rotated one-bit bitmap.

Borrow window and source bitmap. The region coordinates refer to the virtual rotated destination, whose dimensions are virtWidth and virtHeight. Require positive dimensions, a finite degree angle and a region contained in that virtual image, with representable coordinate sums. Right-angle paths assume these bounds rather than checking each source sample. Return an owned pixmap of regionWidth by regionHeight, or None for a detected failure. Free with Tk_FreePixmap(); no source or window ownership is transferred.

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

  • srcBitmap – [in] Borrowed one-bit source pixmap matching its declared dimensions.

  • srcWidth – [in] Positive source width in pixels.

  • srcHeight – [in] Positive source height in pixels.

  • regionX – [in] Left coordinate of the requested region in the virtual rotated image.

  • regionY – [in] Top coordinate of the requested region in the virtual rotated image.

  • regionWidth – [in] Positive output width; region must fit within the virtual image.

  • regionHeight – [in] Positive output height; region must fit within the virtual image.

  • virtWidth – [in] Positive width of the complete virtual rotated destination.

  • virtHeight – [in] Positive height of the complete virtual rotated destination.

  • theta – [in] Finite rotation angle in degrees.

Color rotation implementation

These CPU-side helpers implement exact quadrant copies and the residual three-shear path. Native bitmap transforms use separate implementations.

group Color-image rotation internals

Functions

static void ShearY(Rbc_ColorImage src, Rbc_ColorImage dest, int y, int offset, double frac, Pix32 bgColor)

Shift and filter one source row into a destination row.

Despite its name, this helper moves pixels horizontally at fixed row y. Borrows distinct images; y must exist in both. Initializes the entire destination row to bgColor, then processes all source pixels, including clipped ones, to retain the preceding fractional contribution. offset supplies the integer displacement and frac must lie in [0,1). Writes only in-range destination pixels and a final residual pixel when visible. Uses 14-bit fixed-point straight RGBA arithmetic with byte clamping. Caller ensures offset plus source width remains representable as int. Does not allocate, resize, or validate the row index or fraction.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

  • dest – [inout] Borrowed writable destination image with the required matching dimensions.

  • y – [in] Row index valid in both images.

  • offset – [in] Integer horizontal displacement; offset plus source width must fit int.

  • frac – [in] Fractional horizontal displacement in [0,1).

  • bgColor – [in] RGBA padding color copied by value.

static void ShearX(Rbc_ColorImage src, Rbc_ColorImage dest, int x, int offset, double frac, Pix32 bgColor)

Shift and filter one source column into a destination column.

Despite its name, this helper moves pixels vertically at fixed column x. Borrows distinct images; x must exist in both. Initializes the complete destination column to bgColor. offset is the integer displacement and frac must lie in [0,1). Accumulates the preceding fractional contribution even while destination coordinates are clipped, and emits the final residual pixel if visible. Filters straight RGBA with 14-bit fixed-point weights and clamps channels. Requires representable offset plus source height. Does not allocate or validate the column index or fraction.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

  • dest – [inout] Borrowed writable destination image with the required matching dimensions.

  • x – [in] Column index valid in both images.

  • offset – [in] Integer vertical displacement; offset plus source height must fit int.

  • frac – [in] Fractional vertical displacement in [0,1).

  • bgColor – [in] RGBA padding color copied by value.

static int GetRotationDimension(double value)

Validate and truncate a nonnegative rotation extent.

Returns int truncation of a finite value in [0, INT_MAX]. Invalid or unrepresentable values panic. Does not round upward or add padding; callers include any extra space in their dimension formula.

Parameters:
  • value – [in] Finite nonnegative extent no greater than INT_MAX.

static int GetShearOffset(double value)

Floor a fractional displacement before checked integer conversion.

Returns floor(value) as an int, including for negative displacements. Non-finite or out-of-range results panic. The caller derives the fractional remainder by subtracting this result from the original value.

Parameters:
  • value – [in] Finite displacement whose floor must fit int.

static Rbc_ColorImage Rotate45(Rbc_ColorImage src, double theta, Pix32 bgColor)

Rotate a borrowed image by a residual angle using three filtered shears.

theta is in radians and must lie in [-pi/4, pi/4]; this helper does not normalize or validate that interval. Uses horizontal, vertical, horizontal passes based on tan(theta/2) and sin(theta). Allocates two intermediates and the final image, releasing each intermediate after its last use. bgColor supplies padding and boundary contributions for every pass. Returns independent owned storage released with Rbc_FreeColorImage. Dimension/offset conversion panics on unrepresentable geometry. The construction follows Alan W. Paeth, A Fast Algorithm for General Raster Rotation, Graphics Gems, pp. 179-195. It is not a single-pass inverse-mapped rotation; intermediate clamping affects pixel results.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

  • theta – [in] Residual angle in radians within [-pi/4,pi/4].

  • bgColor – [in] RGBA padding color copied by value.

static Rbc_ColorImage CopyColorImage(Rbc_ColorImage src)

Duplicate an entire RGBA image into independent storage.

Borrows a valid source, checks its pixel count, allocates an equal-size image and copies complete Pix32 values including alpha. Empty dimensions are retained. Returns ownership to the caller, which frees the result with Rbc_FreeColorImage. Does not modify or share source pixel storage.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

static Rbc_ColorImage Rotate90(Rbc_ColorImage src)

Copy pixels into a counterclockwise quarter-turn image.

Borrows source storage and allocates a destination with exchanged width and height. Maps (x,y) to (y,sourceWidth-x-1), copying all RGBA bytes exactly. No interpolation or background blending occurs. Caller owns the result and releases it with Rbc_FreeColorImage.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

static Rbc_ColorImage Rotate180(Rbc_ColorImage src)

Copy pixels into a half-turn image with unchanged dimensions.

Borrows source storage and maps (x,y) to (width-x-1,height-y-1) in a newly allocated image. Copies complete RGBA values with no interpolation. Caller owns the independent result and frees it with Rbc_FreeColorImage.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

static Rbc_ColorImage Rotate270(Rbc_ColorImage src)

Copy pixels into a clockwise quarter-turn image.

Borrows source storage and allocates a destination with exchanged width and height. Maps (x,y) to (sourceHeight-y-1,x), copying complete pixels. No interpolation occurs. Caller owns the independent result and frees it with Rbc_FreeColorImage.

Parameters:
  • src – [in] Borrowed valid source image; ownership remains with the caller.

X11 image and bitmap helpers

group X11 image sizing and capture helpers

Checked dimensions, visual channel masks and asynchronous capture errors.

Functions

static size_t GetUnixImagePixelCount(int width, int height)

Compute a nonnegative image pixel count without size_t overflow.

Returns width times height, including zero for an empty dimension. Negative dimensions or overflow panic rather than returning a recoverable Tcl error. Does not check a later pixel-byte multiplication or allocate storage.

Parameters:
  • width – [in] Nonnegative image width; a negative value causes Tcl_Panic.

  • height – [in] Nonnegative image height; a negative value or product overflow causes Tcl_Panic.

static size_t GetPackedBitmapRowBytes(int width)

Compute bytes per tightly packed one-bit bitmap row.

Returns ceiling(width/8) using size_t arithmetic, including zero for width zero. Negative width panics. This is byte packing, not the Windows DWORD-aligned bitmap stride.

Parameters:
  • width – [in] Nonnegative width in bits/pixels; zero returns zero bytes and a negative width panics.

static int GetBitmapDimension(double value)

Round a geometric extent upward to a usable native dimension.

Applies ceil and accepts only finite results from 1 through INT_MAX. Returns zero for invalid, nonpositive or unrepresentable rounded dimensions. Does not allocate or set an interpreter diagnostic.

Parameters:
  • value – [in] Geometric pixel extent to round upward; invalid or unrepresentable rounded dimensions return zero.

static int ShiftCount(unsigned int mask)

Find the lowest set bit in a 32-bit visual component mask.

Examines at most 32 positions and returns 32 when none is set. Caller supplies a nonzero valid TrueColor mask before using the result as a shift. Does not allocate or inspect a display.

Parameters:
  • mask – [in] Visual component mask within the low 32 bits; no display resource ownership is involved.

static int CountBits(unsigned long mask)

Count set bits in a 32-bit visual mask.

Uses parallel masked tallies over the low 32 bits, returning zero for a zero mask. The caller supplies a visual component mask within that range. Runs during mask preparation, not once per captured pixel.

Parameters:
  • mask – [in] Visual component mask within the low 32 bits; no display resource ownership is involved.

static void ComputeMasks(const Visual *visualPtr, TrueColorMasks *masks)

Prepare per-capture TrueColor shifts for eight-bit gamma indices.

Borrows a Visual with valid nonzero contiguous RGB masks in its 32-bit pixel layout and fills caller-owned shift metadata. Components narrower than eight bits retain the legacy left shift without low-bit replication. Wider components discard low bits by increasing the extraction shift, so ten-bit channels cannot index beyond the 256-entry gamma table. Eight-bit extraction is unchanged. No display calls, shared mutable state or allocation occur.

Parameters:
  • visualPtr – [in] Borrowed TrueColor visual with valid nonzero contiguous RGB masks in a 32-bit pixel layout.

  • masks – [out] Required caller-owned shift metadata; all extraction shifts and eight-bit adjustments are assigned.

static int XGetImageErrorProc(ClientData clientData, XErrorEvent *errEventPtr)

Record an X capture error in a caller-owned status slot.

Sets the retained integer slot to TCL_ERROR and returns zero to mark the error handled. Does not inspect error fields, report Tcl diagnostics or release resources. The caller keeps the slot alive until XSync has delivered errors and the temporary Tk handler is removed.

Parameters:
  • clientData – [inout] Borrowed int status slot kept alive until XSync and handler removal; set to TCL_ERROR.

  • errEventPtr – [in] Unused borrowed X error event; its fields are not inspected.

Rbc_ColorImage Rbc_DrawableToColorImage(Tk_Window tkwin, Drawable drawable, int x, int y, int width, int height, double inputGamma)

Capture a compatible X drawable into owned RGBA pixels.

Returns an owned color image released with Rbc_FreeColorImage, or NULL when capture fails. Output alpha is opaque. Does not own or alter the drawable.

Parameters:
  • tkwin – [in] Borrowed Tk window supplying display, visual and colormap compatible with drawable.

  • drawable – [in] Borrowed readable X drawable containing the entire requested rectangle.

  • x – [in] Source rectangle left coordinate in drawable pixels.

  • y – [in] Source rectangle top coordinate in drawable pixels.

  • width – [in] Positive source width in pixels; nonpositive values return NULL.

  • height – [in] Positive source height in pixels; nonpositive values return NULL.

  • inputGamma – [in] Finite positive input gamma used for channel conversion; invalid values return NULL.

Pixmap Rbc_PhotoImageMask(Tk_Window tkwin, Tk_PhotoImageBlock src)

Build an X11 one-bit opacity mask when transparent pixels exist.

Returns an owned pixmap released with Tk_FreePixmap, or None for fully opaque input. Alpha zero clears a mask bit; any nonzero alpha sets it. Source pixels are read without modification.

Parameters:
  • tkwin – [in] Borrowed Tk window supplying the bitmap display; realized only when a mask is needed.

  • src – [in] Borrowed photo block with positive dimensions, valid pixel storage, pitch, pixelSize and a readable alpha offset.

Pixmap Rbc_ColorImageMask(Tk_Window tkwin, Rbc_ColorImage image)

Build an X11 one-bit opacity mask when transparent pixels exist.

Returns an owned pixmap released with Tk_FreePixmap, or None for fully opaque input. Alpha zero clears a mask bit; any nonzero alpha sets it. Source pixels are read without modification.

Parameters:
  • tkwin – [in] Borrowed Tk window supplying the bitmap display; realized only when a mask is needed.

  • image – [in] Borrowed color image with valid dimensions and RGBA storage.

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 ColorImage

Owned packed pixel array and its dimensions.

Public Members

int width

Dimensions of the image.

int height

Dimensions of the image.

Pix32 *bits

Array of pixels representing the image.

struct Filter2D

Two-dimensional convolution kernel and normalization state.

Public Members

double support

Radius of filter.

double sum

Sum of kernel.

double scale

Sum of kernel.

double *kernel

Array of values (allocated) representing the discrete 2-D filter.

union Pix32
#include <rbcImage.h>

Four-channel pixel with packed and byte-array views.

Public Members

unsigned int value

Packed pixel word; byte interpretation is shared with rgba.

struct Pix32.RGBA rgba

Named channel view of this pixel.

unsigned char channel[4]

Channel-byte array sharing storage with rgba and value; byte order follows RGBA member order.

struct RGBA
#include <rbcImage.h>

Pixel channel bytes; alpha represents opacity.

Public Members

unsigned char red

Red intensity 0..255.

unsigned char green

Green intensity 0..255.

unsigned char blue

Blue intensity 0..255.

unsigned char alpha

Alpha-channel for compositing.

0..255

struct ResampleFilter

Named separable reconstruction filter and support radius.

Public Members

const char *name

Name of the filter.

ResampleFilterProc *proc

1-D filter procedure.

double support

Width of 1-D filter.