Geometry C reference

These declarations remain in rbcInt.h. See Geometry, clipping and simplification for conventions.

double Rbc_GetClosestPointOnSegment(const Point2D *samplePtr, const Point2D *p, const Point2D *q, Point2D *closestPtr)

Find the clamped nearest point on a finite segment and return distance.

Inputs and closestPtr are borrowed; closestPtr must be non-NULL. Segments of length at most DBL_EPSILON use p. Invalid inputs or rejected intermediate arithmetic return DBL_MAX without writing the result. The final hypot may still overflow for extreme finite coordinates; this is not a Tcl error API.

Parameters:
  • samplePtr – [in] Borrowed finite query point in the same coordinate system as the segment.

  • p – [in] Borrowed finite first endpoint.

  • q – [in] Borrowed finite second endpoint.

  • closestPtr – [out] Required caller-owned nearest-point output; rejected inputs/intermediates leave it unchanged.

int Rbc_LineRectClip(const Extents2D *extsPtr, const Point2D *p, const Point2D *q, Segment2D *clippedPtr)

Clip a segment to inclusive extents using Liang-Barsky parameters.

Requires finite, ordered extents and finite endpoints. Returns false for invalid/disjoint input, leaving output untouched. On success, writes the clipped segment if clippedPtr is non-NULL; NULL requests visibility only. Input endpoints are not modified when output storage is separate.

Parameters:
  • extsPtr – [in] Borrowed finite ordered clipping bounds; zero width or height is allowed.

  • p – [in] Borrowed finite first endpoint.

  • q – [in] Borrowed finite second endpoint.

  • clippedPtr – [out] Optional clipped segment; NULL requests a visibility test. Rejection leaves separate output untouched.

Tcl_Size Rbc_PolyRectClip(const Extents2D *extsPtr, const Point2D *inputPts, Tcl_Size nInputPts, Point2D *outputPts, Tcl_Size outputCapacity)

Clip a polygon into a separate caller-owned output array.

Input contains exactly nInputPts vertices; the closing edge is implicit. Uses left/top and historical right+1/bottom+1 clipping boundaries. Output is explicitly closed by repeating its first vertex. outputCapacity counts all available Point2D entries, including closure. Returns the output count, or zero for empty/invalid input or insufficient capacity. Capacity failure can leave partial output; discard it. Input and output must not overlap.

Parameters:
  • extsPtr – [in] Borrowed finite ordered bounds; right and bottom are expanded by one coordinate unit internally.

  • inputPts – [in] Borrowed source vertices, disjoint from output; no repeated closing vertex is required.

  • nInputPts – [in] Number of accessible source vertices, positive for nonempty output.

  • outputPts – [out] Caller-owned output buffer; failure may leave a prefix that must be discarded.

  • outputCapacity – [in] Number of available Point2D slots including the repeated closing vertex.

int Rbc_PointInPolygon(const Point2D *samplePtr, const Point2D *points, Tcl_Size nPoints)

Test polygon membership by an even-odd horizontal ray crossing.

Requires at least three finite vertices and a finite sample; invalid input returns false. The closing edge is implicit. Half-open crossing comparisons do not promise that every point on an edge is inside. Does not modify input.

Parameters:
  • samplePtr – [in] Borrowed finite query point in the polygon coordinate system.

  • points – [in] Borrowed finite polygon vertices; the closing edge is implicit.

  • nPoints – [in] Number of accessible vertices, at least three for membership/enclosure tests.

int Rbc_RegionInPolygon(const Extents2D *extsPtr, const Point2D *points, Tcl_Size nPoints, int enclosed)

Test polygon enclosure by, or overlap with, a rectangle.

With enclosed nonzero, every polygon vertex must be inside inclusive extents; this means the rectangle encloses the polygon, not the reverse. Otherwise test edge intersection and then rectangle-inside-polygon containment. Invalid extents or fewer than three finite vertices return false.

Parameters:
  • extsPtr – [in] Borrowed finite ordered query rectangle.

  • points – [in] Borrowed finite polygon vertices; the closing edge is implicit.

  • nPoints – [in] Number of accessible vertices, at least three for membership/enclosure tests.

  • enclosed – [in] Nonzero tests whether the rectangle encloses the polygon; zero tests overlap or containment.

int Rbc_PointInSegments(const Point2D *samplePtr, const Segment2D *segments, Tcl_Size nSegments, double halo)

Return true if any segment is strictly closer than halo to the sample.

Requires a finite positive halo; zero or invalid halo, no segments or an invalid sample returns false. Uses clamped segment distance, including degenerate segments. Does not acquire or modify the borrowed arrays.

Parameters:
  • samplePtr – [in] Borrowed finite query point.

  • segments – [in] Borrowed array of accessible segment records.

  • nSegments – [in] Number of segment records; zero or negative counts return false.

  • halo – [in] Finite positive strict distance threshold in the input coordinate units; zero never matches.

Tcl_Size Rbc_SimplifyLine(const Point2D *origPts, Tcl_Size low, Tcl_Size high, double tolerance, Tcl_Size indices[])

Return retained original indices for an inclusive input interval.

Caller supplies valid finite points through high and space for high-low+1 indices; no array lengths are supplied or checked here. Use a finite, nonnegative tolerance in the same coordinate units as input. The algorithm measures distance to the infinite endpoint line, or to the endpoint when endpoints coincide. Retains interval endpoints in input order, splitting only when squared distance exceeds squared tolerance. Returns zero on rejected bounds/allocation failure; discard any partial output. Input is borrowed and unchanged; temporary stack storage is released before return.

Parameters:
  • origPts – [in] Borrowed finite point array accessible through high; no length argument validates that capacity.

  • low – [in] Inclusive first original index, nonnegative.

  • high – [in] Inclusive final original index, at least low.

  • tolerance – [in] Finite nonnegative distance tolerance in the same units as the points.

  • indices – [out] Caller-owned room for high-low+1 original indices; discard partial output when the returned count is zero.

Parameter directions follow C calling conventions. Inputs remain borrowed; output buffers belong to the caller. Counts, distances and booleans have distinct completion conventions, summarized in Geometry, clipping and simplification.

Implementation helpers

group Geometry validation and subdivision

Private helpers; callers retain storage and lifetime responsibilities.

Functions

static int IsFinitePoint(const Point2D *pointPtr)

Test a point pointer and both coordinates.

Returns FALSE for NULL or either non-finite coordinate; otherwise TRUE. No allocation, mutation or coordinate transformation.

Parameters:
  • pointPtr – [in] Borrowed point to test; NULL is accepted as an invalid input.

static int IsValidExtents(const Extents2D *extsPtr)

Test finite ordered rectangular extents.

Requires left <= right and top <= bottom after checking all coordinates. NULL or non-finite bounds return FALSE; zero width/height is accepted. Does not normalize reversed bounds or apply pixel-area expansion.

Parameters:
  • extsPtr – [in] Borrowed rectangle to test; NULL, reversed or nonfinite bounds are rejected.

static int ClipTest(double ds, double dr, double *t1, double *t2)

Intersect a Liang-Barsky parameter interval with one boundary.

Caller supplies initialized t1/t2, normally 0/1. Negative ds can raise the entry parameter; positive ds can lower the exit parameter. A parallel edge (ds zero) rejects only when dr is negative. Returns boolean; this call leaves parameters untouched when it rejects, but earlier successful boundary calls may already have narrowed them. No allocation or independent finite checks.

Parameters:
  • ds – [in] Signed segment-direction coefficient for one clipping boundary.

  • dr – [in] Signed boundary distance in the same coordinate units as ds.

  • t1 – [inout] Required initialized entry fraction, normally zero before the first boundary.

  • t2 – [inout] Required initialized exit fraction, normally one; this call changes neither fraction on rejection.

static int AppendClipVertex(Point2D *points, Tcl_Size capacity, Tcl_Size *countPtr, double x, double y)

Append one vertex when the caller-provided buffer has room.

Requires a valid countPtr; rejects NULL points, negative count or count at or above capacity without changing storage/count. On success writes X/Y and increments count. Does not test coordinate finiteness or suppress duplicates. The clipper must discard the whole polygon on a failed append.

Parameters:
  • points – [out] Caller-owned output buffer; only the entry at the old count is written on success.

  • capacity – [in] Number of available Point2D slots, not bytes.

  • countPtr – [inout] Required current vertex count; incremented once on success and retained on failure.

  • x – [in] X coordinate to append without finite validation.

  • y – [in] Y coordinate to append without finite validation.

static double FindSplit(const Point2D points[], Tcl_Size i, Tcl_Size j, Tcl_Size *split)

Find the first farthest interior point for line simplification.

Requires valid source indices and caller storage for split. Returns maximum squared distance and writes its original source index; ties keep the first. Uses distance to the infinite endpoint line, not the bounded segment. If the endpoint distance is at most DBL_EPSILON, measures from the first endpoint.

NULL split returns -1. Otherwise initializes split to -1, also returning -1 for invalid pointers/ranges or no interior point. Does not know array capacity or validate every coordinate; extreme intermediate arithmetic may overflow. No allocation or input mutation.

Parameters:
  • points – [in] Borrowed source array accessible through j; caller validates finite coordinates and capacity.

  • i – [in] Original index of the left endpoint, nonnegative.

  • j – [in] Original index of the right endpoint; a split requires at least one interior point.

  • split – [out] Original index of the first farthest interior point; initialized to -1. NULL causes a -1 distance result.

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 Dim2D

Integer dimensions in pixels.

Public Members

int width

Horizontal extent.

int height

Vertical extent.

struct Extents2D

Coordinate bounds; units and axis direction follow the caller.

Public Members

double left

Left boundary.

double right

Right boundary.

double top

Top boundary.

double bottom

Bottom boundary.

struct Extents3D

Coordinate bounds; units and axis direction follow the caller.

Public Members

double left

Left boundary.

double right

Right boundary.

double top

Top boundary.

double bottom

Bottom boundary.

double front

Front boundary.

double back

Back boundary.

struct Point2D

Coordinate value; the containing operation determines units.

Public Members

double x

X coordinate.

double y

Y coordinate.

struct Point3D

Coordinate value; the containing operation determines units.

Public Members

double x

X coordinate.

double y

Y coordinate.

double z

Z coordinate.

struct Rbc_Dashes

Native dash pattern with a zero terminator and phase.

Public Members

unsigned char values[RBC_MAX_DASH_VALUES + 1]

Dash lengths in pixels followed by zero; first zero selects a solid line.

int offset

Dash phase offset in pixels.

struct Rbc_Pad

Opposite-side padding in pixels.

Public Members

int side1

Left padding for X, top padding for Y.

int side2

Right padding for X, bottom padding for Y.

struct Region2D

Rectangle with inclusive integer pixel edges.

Public Members

int left

Left boundary.

int right

Right boundary.

int top

Top boundary.

int bottom

Bottom boundary.

struct Segment2D

Two endpoints of a line segment in the caller coordinate system.

Public Members

Point2D p

The two end points of the segment.

Point2D q

The two end points of the segment.