Image resampling C reference
These private services are declared in rbcImage.h and implemented in rbcImage.c. See Image resizing and resampling for
coordinate conventions and Image storage and tile clients for image storage ownership.
-
int Rbc_GetResampleFilterFromObj(Tcl_Interp *interp, Tcl_Obj *filterObj, ResampleFilter **filterPtrPtr)
Resolve a filter name or unambiguous abbreviation to borrowed static state.
Return TCL_OK and a filter-table pointer, or NULL for the name none. On lookup failure return TCL_ERROR without assigning the output pointer. Do not free or modify a returned filter. NULL selects policy in callers; it is not a valid filter argument to Rbc_ResampleColorImage().
- Parameters:
interp – [inout] Interpreter receiving Tcl diagnostics; no ownership is transferred.
filterObj – [in] Borrowed Tcl object naming a filter or unambiguous abbreviation.
filterPtrPtr – [out] Required output; receives borrowed static filter or NULL for none only on success.
-
Rbc_ColorImage Rbc_ResampleColorImage(Rbc_ColorImage src, int width, int height, ResampleFilter *horzFilterPtr, ResampleFilter *vertFilterPtr)
Return a newly owned image filtered horizontally and then vertically.
Borrow the source and two valid, non-NULL filters; leave the source intact. Release the result with Rbc_FreeColorImage(). Negative destination dimensions or missing filters panic. Zero dimensions are allowed; empty input leaves zero-initialized output. Each pass filters straight RGBA channels separately, with fixed-point weights and clamping, without gamma conversion.
- Parameters:
src – [in] Borrowed valid source image; ownership remains with the caller.
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.
horzFilterPtr – [in] Borrowed non-NULL horizontal reconstruction filter.
vertFilterPtr – [in] Borrowed non-NULL vertical reconstruction filter.
-
Rbc_ColorImage Rbc_ResizeColorImage(Rbc_ColorImage src, int x, int y, int width, int height, int destWidth, int destHeight)
Copy a source region into a newly owned image using nearest-neighbour mapping.
Borrow src. Clamp the origin to source bounds; negative or excessive spans extend to the remaining edge. Scale that effective region to destWidth by destHeight. Empty regions leave zero-initialized output. Negative destination dimensions panic; zero dimensions are allowed. Free the independent result with Rbc_FreeColorImage(). All four channels are copied unchanged.
- Parameters:
src – [in] Borrowed valid source image; ownership remains with the caller.
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.
destWidth – [in] Nonnegative destination width in pixels.
destHeight – [in] Nonnegative destination height in pixels.
-
Rbc_ColorImage Rbc_ResizeColorSubimage(Rbc_ColorImage src, int regionX, int regionY, int regionWidth, int regionHeight, int destWidth, int destHeight)
Sample a region of a virtually resized source without allocating the full resize.
Here x and y are virtual destination coordinates, width and height are the returned region size, and destWidth/destHeight are the virtual full size. Nearest-neighbour coordinates clamp to source edges, including regions beyond the virtual image. Borrow src and free the result with Rbc_FreeColorImage(). Negative region dimensions panic; empty regions return immediately. A nonempty region requires positive virtual dimensions. Empty source images leave zero-initialized output.
- Parameters:
src – [in] Borrowed valid source image; ownership remains with the caller.
regionX – [in] Horizontal origin in the virtual destination, not the source.
regionY – [in] Vertical origin in the virtual destination, not the source.
regionWidth – [in] Nonnegative width of the returned region.
regionHeight – [in] Nonnegative height of the returned region.
destWidth – [in] Virtual full-image width; positive for a nonempty region.
destHeight – [in] Virtual full-image height; positive for a nonempty region.
-
void Rbc_ResamplePhoto(Tcl_Interp *interp, Tk_PhotoHandle srcPhoto, int x, int y, int width, int height, Tk_PhotoHandle destPhoto, ResampleFilter *horzFilterPtr, ResampleFilter *vertFilterPtr)
Filter a source photo region into the destination photo’s existing dimensions.
Snapshot the source region before writing, allowing identical photo handles. Borrow both handles and valid non-NULL filters. Temporary RBC images are released internally. The void photo-write wrapper does not propagate Tk’s write status; callers must not interpret return as a success code.
- Parameters:
interp – [inout] Interpreter receiving Tcl diagnostics; no ownership is transferred.
srcPhoto – [in] Borrowed live source photo, snapshotted before destination writes.
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.
destPhoto – [inout] Borrowed live destination photo whose existing dimensions determine output size.
horzFilterPtr – [in] Borrowed non-NULL horizontal reconstruction filter.
vertFilterPtr – [in] Borrowed non-NULL vertical reconstruction filter.
-
void Rbc_ResizePhoto(Tcl_Interp *interp, Tk_PhotoHandle srcPhoto, int x, int y, int width, int height, Tk_PhotoHandle destPhoto)
Resize a source photo region to the destination’s existing size without filtering.
Borrow both handles. Snapshot before writing so source and destination may be the same photo. Release temporary RBC images internally. As with Rbc_ResamplePhoto(), this void wrapper does not return the Tk write status.
- Parameters:
interp – [inout] Interpreter receiving Tcl diagnostics; no ownership is transferred.
srcPhoto – [in] Borrowed live source photo, snapshotted before destination writes.
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.
destPhoto – [inout] Borrowed live destination photo whose existing dimensions determine output size.
Filter kernels and contribution records
These helpers implement the filtered path in rbcImage.c. See Image resizing and resampling for kernel support, coordinate
conventions and fixed-point arithmetic.
- group Image resampling kernels and contributions
Functions
-
static double DefaultFilter(double x)
Evaluate the compact cubic default kernel.
For t = abs(x) below one returns (2t - 3)t squared + 1, otherwise zero. Uses no mutable state or allocation. The table support is one pixel.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double DummyFilter(double x)
Evaluate the historical diagnostic kernel abs(x).
Has no intrinsic cutoff, normalization or image access. Its table support is 0.5; contribution construction supplies the sampling interval. This test kernel is not an identity or nearest-neighbour operation.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double BoxFilter(double x)
Return unit weight inside the closed interval [-0.5, 0.5].
Returns zero outside the interval, including neither endpoint in that rejection. Stateless; the table support is 0.5 pixels.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double TriangleFilter(double x)
Evaluate the linear tent kernel.
Returns 1 - abs(x) for abs(x) below one, otherwise zero. Stateless with table support one pixel; performs no contribution normalization itself.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double BellFilter(double x)
Evaluate the piecewise quadratic bell kernel.
For t = abs(x), returns 0.75 - t squared below 0.5 and half of (t - 1.5) squared below 1.5; otherwise zero. Stateless; support is 1.5.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double BSplineFilter(double x)
Evaluate the compact cubic B-spline kernel.
Uses even cubic pieces on abs(x) below one and below two, and returns zero outside. Stateless; table support is two pixels. The kernel value at zero is 2/3, so this is not an interpolating cardinal kernel.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double SincFilter(double x)
Evaluate sin(pi*x)/(pi*x), with its removable singularity filled.
Returns one at zero. No intrinsic cutoff; the table limits sampling to support four. Stateless; signed lobes are preserved for normalization.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double BesselFilter(double x)
Evaluate the legacy Bessel reconstruction kernel.
Returns pi/4 at zero and j1(pi*x)/(2*x) otherwise. The table support is 3.2383; there is no cutoff in this function. The legacy Borland branch returns zero for all inputs. Requires the platform j1 implementation on other builds. Owns no state and performs no normalization.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double GaussianFilter(double x)
Evaluate exp(-2*x*x) times sqrt(2/pi).
Stateless with no intrinsic cutoff. The gaussian and gauss8 table entries share this procedure but use support radii 1.25 and 8 respectively.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double Lanczos3Filter(double x)
Evaluate a sinc kernel with a three-lobe sinc window.
For abs(x) below three returns SincFilter(x) times SincFilter(x/3), otherwise zero. Stateless; the table support is three pixels.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double MitchellFilter(double x)
Evaluate the compact Mitchell cubic with B = C = 1/3.
Uses even polynomial pieces below absolute distances one and two, then returns zero. Stateless; support is two. Negative lobes are retained here and may produce values later clamped by the image passes.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double CatRomFilter(double x)
Evaluate the piecewise Catmull-Rom cubic kernel.
Uses four polynomial intervals spanning [-2, 2] and is zero outside. Returns one at zero. Stateless; signed lobes are not clipped here and the table support is two pixels.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static double GiFilter(double x)
Evaluate the historical Gaussian-tail integral approximation.
Returns one below -1.5 and zero above 1.5, with three polynomial pieces between. This is an asymmetric cumulative function, not the even Gaussian kernel. The table support is 1.25. Owns no mutable state.
- Parameters:
x – [in] Signed distance from the reconstruction center in sample units.
-
static size_t GetSampleRecordSize(int nWeights)
Compute storage for one variable-sized contribution record.
Requires a positive weight count. Includes the first ResampleWeight already in Sample and checks extra storage against SIZE_MAX before multiplying. Returns a byte stride; invalid count or representational overflow panics. Does not allocate or initialize a record.
- Parameters:
nWeights – [in] Positive capacity of one contribution record, including its inline first weight.
-
static int GetFilterSize(int srcWidth, double radius)
Bound contribution capacity by the source pixel count.
Requires positive srcWidth and finite nonnegative radius; invalid input panics. Computes 2*radius + 2, caps at srcWidth before integer conversion (also for an overflowed sum), and returns at least one. This capacity bounds the clipped interval, not the count of nonzero weights.
- Parameters:
srcWidth – [in] Positive number of source samples along the filtered axis.
radius – [in] Finite nonnegative support radius in source-sample units.
-
static void GetFilterBounds(int srcWidth, double center, double radius, int *leftPtr, int *rightPtr)
Round and clip an inclusive source contribution interval.
Borrows output pointers. Requires positive srcWidth, finite center/radius and nonnegative radius; invalid geometry panics. Rounds center +/- radius using +0.5 then positive integer truncation, with clipping before casts. Writes ordered bounds in [0, srcWidth-1]; outlying centers clamp to an edge sample rather than yielding an empty interval.
- Parameters:
srcWidth – [in] Positive number of source samples along the filtered axis.
center – [in] Finite center coordinate of the source contribution interval.
radius – [in] Finite nonnegative support radius in source-sample units.
leftPtr – [out] Required output for inclusive first source sample.
rightPtr – [out] Required output for inclusive last source sample.
-
static size_t ComputeWeights(int srcWidth, int destWidth, ResampleFilter *filterPtr, Sample **samplePtrPtr)
Allocate normalized fixed-point contributions for one output axis.
Requires positive dimensions and a non-NULL filter with a valid procedure and finite nonnegative support. Invalid geometry panics. Returns the byte stride between records and writes an owned zero-allocated array to samplePtrPtr; caller frees it with ckfree. One record per destination coordinate stores the clipped source start/count. Downsampling expands support by inverse scale; weights use a half-pixel offset. Float weights are summed in double, normalized unless the sum is zero, then overwritten in the union by fixed-point ints using a scale of 16384 and +0.5 before truncation. Custom kernels must yield finite, representable normalized weights; there is no general validation of callback results.
- Parameters:
srcWidth – [in] Positive number of source samples along the filtered axis.
destWidth – [in] Positive number of destination samples.
filterPtr – [in] Borrowed filter descriptor with a valid procedure and support.
samplePtrPtr – [out] Required output receiving owned contribution storage; release with ckfree.
-
static void ZoomImageVertically(Rbc_ColorImage src, Rbc_ColorImage dest, ResampleFilter *filterPtr)
Filter source columns into an equally wide destination image.
Borrows distinct source/destination images and a valid non-NULL filter. Requires equal widths; empty dimensions return without writing. Computes one owned contribution array for all columns, accumulates straight RGBA independently and clamps to bytes. Frees weights before returning. Does not allocate image storage or perform gamma conversion; in-place filtering is unsupported.
- Parameters:
src – [in] Borrowed valid source image; ownership remains with the caller.
dest – [inout] Borrowed writable destination image with the required matching dimensions.
filterPtr – [in] Borrowed filter descriptor with a valid procedure and support.
-
static void ZoomImageHorizontally(Rbc_ColorImage src, Rbc_ColorImage dest, ResampleFilter *filterPtr)
Filter source rows into an equally tall destination image.
Borrows distinct source/destination images and a valid non-NULL filter. Requires equal heights; returns without writing if either image has an empty dimension. Computes one owned contribution array for all rows, accumulates straight RGBA independently and clamps each channel to a byte. Releases weights before returning. Does not resize either image or perform gamma conversion; in-place filtering is unsupported.
- Parameters:
src – [in] Borrowed valid source image; ownership remains with the caller.
dest – [inout] Borrowed writable destination image with the required matching dimensions.
filterPtr – [in] Borrowed filter descriptor with a valid procedure and support.
-
static double DefaultFilter(double x)
Contribution workspace records
These image-local records are distinct from the element palette Weight interval in Pen and palette C reference.
-
union ResampleWeight
One image-resampling coefficient, in floating or fixed-point form.
The resampling phase selects the representation; the two members share storage.
-
struct Sample
Contribution record for one destination image sample.
Stored in an owned resampling workspace with extra trailing coefficient storage; ComputeSampleSize determines the byte stride between records.
Public Members
-
int count
Number of source samples contributing to this destination.
-
int start
First contributing source sample index.
-
ResampleWeight weights[1]
Inline first coefficient; allocated storage contains count entries.
-
int count