iShape-ffi

A C ABI bridge to the Rust iOverlay and iTriangle geometry libraries, built as libi_shape_ffi.a. Use it to bring polygon geometry into Swift, C, C++, or another language that can call C functions.

It exposes opaque handles and flat coordinate buffers so callers can use the Rust algorithms without depending on Rust types or memory layouts. Reusable output buffers retain capacity between calls. For Apple apps, iShapeKit provides Swift wrappers and a prebuilt XCFramework.

What it does

• Polygon union, intersection, difference, and XOR with integer or f64 coordinates, including holes and fill rules.
• Floating-point outlines and strokes, with configurable joins, caps, and per-vertex stroke widths.
• Triangulation and convex decomposition for mesh and collision geometry.
• Floating-point Boolean results with nesting links between shapes.

Use it for vector editing, clipping map regions, expanding boundaries, or preparing geometry for rendering and physics.

Build and integrate

With a Rust toolchain supporting edition 2024, run:

cargo build --release

Link target/release/libi_shape_ffi.a into your application and include the matching iShapeFFI.h. Build for your application's target architecture and keep the header and library versions in sync. The current crate version is 0.2.7.

For Apple platforms, keep both repositories as sibling directories and run ./build_ffi.sh from iShape-swift to build the macOS/iOS XCFramework.

Quick start (C)

Combine two rectangles and read the number of result shapes:

#include "iShapeFFI.h"
#include <stdio.h>

int main(void) {
    const double subject[] = {0, 0, 4, 0, 4, 4, 0, 4};
    const double clip[] = {2, 0, 6, 0, 6, 4, 2, 4};
    Float64OverlayOptions options = {0};
    options.output_direction = IntContourDirectionCounterClockwise;

    F64OverlayOpaque *overlay = ishape_overlay_f64_create(2, options);
    FlatF64ShapesBufferOpaque *output = ishape_flat_f64_shapes_create();

    bool ok = ishape_overlay_f64_add_contour(
        overlay, subject, 8, IntShapeTypeSubject);
    ok = ok && ishape_overlay_f64_add_contour(
        overlay, clip, 8, IntShapeTypeClip);
    ok = ok && ishape_overlay_f64_overlay_into_flat(
        overlay, IntOverlayRuleUnion, IntFillRuleEvenOdd, output);

    if (ok) {
        printf("%zu merged shape(s)\n", ishape_flat_f64_shapes_shapes_len(output));
    }

    ishape_flat_f64_shapes_free(output);
    ishape_overlay_f64_free(overlay);
    return ok ? 0 : 1;
}

Buffer and handle conventions

• Coordinates are packed as [x0, y0, x1, y1, ...]. Coordinate counts and contour ranges refer to scalar elements, not point pairs; RangeFFI uses an exclusive end. Shape ranges index the contour array.
• Free each owned handle with its matching *_free function. Pointers returned by buffer accessors are borrowed; read them before the buffer is mutated or freed.
• Use distinct input and output buffers for offsets and convex decomposition. Check Boolean return values before reading results; a successful operation may produce an empty result.
• Stroke widths are full widths. Outline distances may be positive or negative; join and cap angle values are in radians.

Run cargo test when changing the Rust bridge. The exported functions live in src/ffi_*.rs; the C declarations are maintained in the Swift repository.