Skip to main content

Crate knipsa_ffi

Crate knipsa_ffi 

Source
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§

KnipsaOffsetOptions
Options shared by the integer and floating-point offset entry points.
KnipsaPath64
A borrowed integer point slice.
KnipsaPathD
A borrowed floating-point point slice.
KnipsaPaths64
An owned integer result returned by a Rust operation.
KnipsaPathsD
An owned floating-point result returned by a Rust operation.
KnipsaPoint64
A fixed-layout integer point for FFI callers.
KnipsaPointD
A fixed-layout floating-point point for FFI callers.
KnipsaRect64
An axis-aligned integer clipping rectangle.
KnipsaRectD
An axis-aligned floating-point clipping rectangle.

Enums§

KnipsaClipType
Boolean operation values used by the C ABI.
KnipsaEndType
The endpoint style accepted by offset operations.
KnipsaFillRule
Fill-rule values used by the C ABI.
KnipsaJoinType
The corner style accepted by offset operations.
KnipsaLocation
Point classification returned by knipsa_point_in_polygon64.
KnipsaPathKind
Whether an FFI path is closed or open.
KnipsaStatus
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 KnipsaClipType and KnipsaFillRule.
knipsa_boolean_d⚠
Executes a floating-point boolean operation and allocates the result for the caller. Coordinates are accepted as IEEE-754 double values 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_boolean64 or knipsa_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, or knipsa_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 f64 integer 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.