Expand description
§knipsa-ffi
knipsa-ffi exposes the polygon API through a small C-compatible ABI for
applications and language bindings that can load a C shared or static
library.
Inputs are borrowed for the duration of each call. Results are allocated by
knipsa and must be released with the matching knipsa_free_paths64 or
knipsa_free_paths_d function. Initialize result slots with
KNIPSA_PATHS64_INIT or KNIPSA_PATHS_D_INIT; release a live result before
reusing its slot.
Offset calls use KnipsaOffsetOptions, normally initialized with
KNIPSA_OFFSET_OPTIONS_INIT. Status codes are returned for invalid pointers,
bad geometry, invalid options, arithmetic failures, and topology failures.
Offset input and generated contours use Knipsa’s fixed default complexity
budget.
The C ABI also exposes knipsa_simplify64, knipsa_simplify_d,
knipsa_clip_to_rect64, and knipsa_clip_to_rect_d for common cleanup and
viewport-clipping workflows.
§Minimal C client
#include "knipsa.h"
#include <stdio.h>
int main(void) {
const KnipsaPoint64 points[] = {
{0, 0}, {10, 0}, {10, 10}, {0, 10},
};
const KnipsaPath64 subject = {points, 4};
KnipsaPaths64 result = KNIPSA_PATHS64_INIT;
const KnipsaStatus status = knipsa_boolean64(
&subject, 1, NULL, 0,
KNIPSA_CLIP_UNION, KNIPSA_FILL_EVEN_ODD,
&result
);
if (status != KNIPSA_STATUS_OK) {
fprintf(stderr, "knipsa failed: %s\n", knipsa_status_message(status));
return 1;
}
printf("rings: %zu\n", result.path_count);
knipsa_free_paths64(&result);
return 0;
}The repository contains a complete C11 tour in examples/quickstart.c and a
contract reference in docs/ffi.md.
Structs§
- Knipsa
Offset Options - Options shared by the integer and floating-point offset entry points.
- Knipsa
Path64 - A borrowed integer point slice.
- Knipsa
PathD - A borrowed floating-point point slice.
- Knipsa
Paths64 - An owned integer result returned by a Rust operation.
- Knipsa
PathsD - An owned floating-point result returned by a Rust operation.
- Knipsa
Point64 - A fixed-layout integer point for FFI callers.
- Knipsa
PointD - A fixed-layout floating-point point for FFI callers.
- Knipsa
Rect64 - An axis-aligned integer clipping rectangle.
- Knipsa
RectD - An axis-aligned floating-point clipping rectangle.
Enums§
- Knipsa
Clip Type - Boolean operation values used by the C ABI.
- Knipsa
EndType - The endpoint style accepted by offset operations.
- Knipsa
Fill Rule - Fill-rule values used by the C ABI.
- Knipsa
Join Type - The corner style accepted by offset operations.
- Knipsa
Location - Point classification returned by
knipsa_point_in_polygon64. - Knipsa
Path Kind - Whether an FFI path is closed or open.
- Knipsa
Status - Stable status codes returned by exported functions.
Functions§
- knipsa_
boolean64 ⚠ - Executes an integer boolean operation and allocates the result for the
caller. The operation and fill-rule arguments use the values from
KnipsaClipTypeandKnipsaFillRule. - knipsa_
boolean_ ⚠d - Executes a floating-point boolean operation and allocates the result for
the caller. Coordinates are accepted as IEEE-754
doublevalues and are checked for finiteness by the Rust API. - knipsa_
clip_ ⚠to_ rect64 - Clips integer paths to an axis-aligned rectangle.
- knipsa_
clip_ ⚠to_ rect_ d - Clips floating-point paths to an axis-aligned rectangle.
- knipsa_
free_ ⚠paths64 - Releases a result returned by
knipsa_boolean64orknipsa_triangulate64. It is safe to pass a null pointer or to call this function again after it zeroes the result. - knipsa_
free_ ⚠paths_ d - Releases a result returned by
knipsa_boolean_d,knipsa_offset64,knipsa_offset_d, orknipsa_triangulate_d. It is safe to pass a null pointer or to call this function again after it zeroes the result. - knipsa_
offset64 ⚠ - Offsets integer-coordinate paths and returns the floating-point outline.
Integer input coordinates are converted exactly when they fit in the
exact
f64integer range; joins and round caps are not rounded to integers by this entry point. - knipsa_
offset_ ⚠d - Offsets floating-point paths and returns floating-point polygon outlines.
- knipsa_
point_ ⚠in_ polygon64 - Classifies one point against a borrowed closed path using the even-odd rule.
- knipsa_
simplify64 ⚠ - Simplifies integer paths with a union using the selected fill rule.
- knipsa_
simplify_ ⚠d - Simplifies floating-point paths with a union using the selected fill rule.
- knipsa_
status_ message - Returns a static NUL-terminated description for a status code.
- knipsa_
triangulate64 ⚠ - Triangulates integer-coordinate rings. Each returned triangle is exposed
as a three-point path in
KnipsaPaths64. - knipsa_
triangulate_ ⚠d - Triangulates floating-point rings. Each returned triangle is exposed as a
three-point path in
KnipsaPathsD. - knipsa_
validate_ ⚠paths64 - Validates a borrowed array of paths.
- knipsa_
validate_ ⚠paths_ d - Validates a borrowed array of floating-point paths.
- knipsa_
version - Returns the knipsa FFI version as a static NUL-terminated string.