You are viewing the documentation for Deformable v0.3.0, an older version. Read the latest, v0.9.0

C SDK

Getting started with C

Download the C SDK, compile against deformable.h with a compiler, make or CMake, and run your first simulation from C.

On this page

The C SDK brings the Tangerina Deformable engine into your own C or C++ tools. It is libdeformable, a shared and a static library, and one header, deformable.h. The header is plain C99, and it wraps its declarations in extern "C", so C++ code can include it too. The library has the same scene, mesh tools and render surfaces as the Rust and Python SDKs. What they do, and why, is in the Engine guide, starting with How the engine works. This guide shows how to use them from C; the C API Reference documents every type, constant and function.

Requirements

  • A C99 compiler, such as Clang, GCC or MSVC.
  • Optional: make, or CMake 3.18 or later.
  • macOS on Apple silicon, Linux x64 or Windows x64.

Download the C SDK

Download the C SDK zip for your platform from the download page, for example deformable-c-v0.1.0-macos-arm64.zip, and unzip it. It holds one folder, named like the zip:

Path What it is
include/deformable.h The header. Every type, constant and function of the C SDK.
lib/ The shared and the static library. See the table below.
lib/cmake/deformable/ The CMake package. find_package(deformable) gives the targets deformable::deformable and deformable::static.
README.txt A short guide to the SDK.
LICENSE.md The license.
THIRD_PARTY_NOTICES.txt The notice and the license text of the third-party code in the library. See Licensing.

The lib/ folder holds these files:

Platform Shared library Static library
macOS libdeformable.dylib libdeformable.a
Linux libdeformable.so libdeformable.a
Windows deformable.dll, with the import library deformable.dll.lib deformable.lib

The commands on this page name the unzipped folder $DEFORMABLE. Set it once in your shell:

sh
export DEFORMABLE=/path/to/deformable-c-v0.1.0-macos-arm64

On macOS, clear the download mark from the folder once. A browser marks a downloaded zip, unzipping copies the mark onto each file, and macOS will not load a marked library that is not notarized, so without this step a program linked with libdeformable.dylib never starts:

sh
xattr -dr com.apple.quarantine "$DEFORMABLE"

Your first simulation

This program builds a closed unit cube, fills it with tetrahedrons, and lets it fall under gravity for one second. Save it as falling_cube.c.

c
#include <stdio.h>

#include "deformable.h"

/* Prints the last error of this thread and returns 1, for main to return. */
static int fail(const char *call) {
    fprintf(stderr, "%s failed: %s\n", call, deformable_last_error_message());
    return 1;
}

int main(void) {
    /* A closed unit cube: 8 corners and 12 outward triangles. */
    DeformableVector3 corners[8];
    for (int corner = 0; corner < 8; ++corner) {
        corners[corner].x = (double)(corner & 1);
        corners[corner].y = (double)((corner >> 1) & 1);
        corners[corner].z = (double)(corner >> 2);
    }
    const uint32_t triangles[12][3] = {
        {0, 2, 3}, {0, 3, 1}, {4, 5, 7}, {4, 7, 6}, {0, 1, 5}, {0, 5, 4},
        {2, 6, 7}, {2, 7, 3}, {0, 4, 6}, {0, 6, 2}, {1, 3, 7}, {1, 7, 5},
    };
    DeformableTriangleMeshView cage = {corners, 8, triangles, 12};

    /* Fill the cage with tetrahedrons. */
    DeformableTetrahedralizeParameters parameters = {0};
    parameters.maximum_edge_length = 0.5;
    deformable_anisotropy_default(&parameters.anisotropy[0]);
    deformable_anisotropy_default(&parameters.anisotropy[1]);

    DeformableTetrahedralization *tetrahedralization = NULL;
    if (deformable_tetrahedralize(&cage, &parameters, NULL, &tetrahedralization) != DEFORMABLE_STATUS_OK) {
        return fail("deformable_tetrahedralize");
    }
    DeformableTetrahedralizationView result;
    deformable_tetrahedralization_view(tetrahedralization, &result);

    DeformableScene *scene = NULL;
    if (deformable_scene_create(&scene) != DEFORMABLE_STATUS_OK) {
        deformable_tetrahedralization_destroy(tetrahedralization);
        return fail("deformable_scene_create");
    }

    DeformableMaterialParameters material_parameters;
    DeformableObjectOptions options;
    DeformableTetrahedronMaterials materials = {0};
    uint32_t cube = 0;
    deformable_material_parameters_default(&material_parameters);
    deformable_object_options_default(&options);
    materials.assignment = DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM;
    if (deformable_scene_add_material(scene, &material_parameters, &materials.material) !=
            DEFORMABLE_STATUS_OK ||
        deformable_scene_add_object(scene, &result.mesh, &materials, &options, &cube) !=
            DEFORMABLE_STATUS_OK) {
        int code = fail("adding the cube");
        deformable_scene_destroy(scene);
        deformable_tetrahedralization_destroy(tetrahedralization);
        return code;
    }
    /* The scene copied the mesh, so the tetrahedralization can go. */
    deformable_tetrahedralization_destroy(tetrahedralization);

    /* 24 frames per second, 10 substeps per frame. The first call only records the time. */
    for (int frame = 0; frame <= 24; ++frame) {
        DeformableStepReport report;
        if (deformable_scene_step(scene, frame / 24.0, 10, NULL, &report) != DEFORMABLE_STATUS_OK) {
            int code = fail("deformable_scene_step");
            deformable_scene_destroy(scene);
            return code;
        }
    }

    const DeformableVector3 *positions = NULL;
    size_t count = 0;
    deformable_scene_node_positions(scene, cube, &positions, &count);
    printf("deformable %s: %zu nodes, first node at y = %.3f\n", deformable_version(), count, positions[0].y);

    deformable_scene_destroy(scene);
    return 0;
}

Compile and run

Run these commands in the folder that holds falling_cube.c.

Shared library. Point the compiler at the header and the linker at the library. The run path lets the program find the library in the SDK folder when it starts:

sh
cc -std=c99 -I "$DEFORMABLE/include" falling_cube.c -L "$DEFORMABLE/lib" -ldeformable -Wl,-rpath,"$DEFORMABLE/lib" -o falling_cube
./falling_cube
text
deformable 0.1.0: 9 nodes, first node at y = -4.925

On Windows, with MSVC, link the import library and put deformable.dll next to the program:

text
cl /I %DEFORMABLE%\include falling_cube.c %DEFORMABLE%\lib\deformable.dll.lib

Static library. Pass the archive itself. The library is written in Rust, so the program also needs the system libraries that Rust’s standard library uses. On macOS this is only the math library:

sh
cc -std=c99 -I "$DEFORMABLE/include" falling_cube.c "$DEFORMABLE/lib/libdeformable.a" -lm -o falling_cube

The CMake target deformable::static lists the system libraries for its platform, so with CMake you need not know them. The static library needs nothing at run time: the program carries the library inside it.

Build with make

This Makefile builds the same program with the built-in rules of make. Set DEFORMABLE to the unzipped SDK folder:

text
DEFORMABLE = /path/to/deformable-c-v0.1.0-macos-arm64

CFLAGS = -std=c99 -Wall -Wextra -I $(DEFORMABLE)/include
LDFLAGS = -L $(DEFORMABLE)/lib -Wl,-rpath,$(DEFORMABLE)/lib
LDLIBS = -ldeformable

falling_cube: falling_cube.c
sh
make
./falling_cube

Build with CMake

The SDK holds a CMake package with two imported targets. deformable::deformable links the shared library, and deformable::static links the static library with the system libraries it needs. Both add the header folder to the include path. Find the package and link a target:

text
cmake_minimum_required(VERSION 3.18)
project(falling_cube LANGUAGES C)

find_package(deformable 0.1 CONFIG REQUIRED)

add_executable(falling_cube falling_cube.c)
target_link_libraries(falling_cube PRIVATE deformable::deformable)

Add the SDK folder to CMAKE_PREFIX_PATH so CMake finds the package:

sh
cmake -S . -B build -DCMAKE_PREFIX_PATH="$DEFORMABLE"
cmake --build build
./build/falling_cube

find_package refuses an SDK whose version does not match the one you ask for.

Ship the shared library

A program you give to others needs the shared library next to it. Copy the library next to the program, and give the program a run path that points there:

Platform File Link with
macOS libdeformable.dylib -Wl,-rpath,@executable_path. The library’s install name is @rpath/libdeformable.dylib.
Linux libdeformable.so -Wl,-rpath,'$ORIGIN'
Windows deformable.dll Nothing: Windows looks in the executable’s folder first.

On macOS:

sh
mkdir -p app
cp "$DEFORMABLE/lib/libdeformable.dylib" app/
cc -std=c99 -I "$DEFORMABLE/include" falling_cube.c -L "$DEFORMABLE/lib" -ldeformable -Wl,-rpath,@executable_path -o app/falling_cube
./app/falling_cube

The static library needs none of this: the program carries the library inside it.

The Standard license belongs to each device that runs the program. On a colleague’s device, a server or a render farm node, the program runs under the Free license, up to 2,500 tetrahedrons per scene, unless that device has its own seat. To ship the engine inside an app you give to others, you need a Developer license: your app then activates its key at every start, offline, and its users need no activation, network or seat. See Developer license.

What the program does

  1. deformable_tetrahedralize fills the closed triangle cage with tetrahedrons. It writes a new handle, a DeformableTetrahedralization *. deformable_tetrahedralization_view lends its arrays.
  2. deformable_scene_create creates an empty scene with gravity (0, -9.81, 0).
  3. deformable_scene_add_material and deformable_scene_add_object write a material handle and an object handle. Both are uint32_t values that count up from 0.
  4. The scene copies the mesh, so the program destroys the tetrahedralization right after deformable_scene_add_object.
  5. deformable_scene_step advances the scene to a time in seconds. The first call only records the start time.
  6. deformable_scene_node_positions lends the current node positions. The scene owns the array.
  7. deformable_scene_destroy frees the scene and every array it lent.
tetrahedral mesh add object each frame: step, then read node positions

The cube falls about 4.9 units in one second. Nothing stops it, because the scene has no floor. Scene adds one.

The cage has only 12 triangles, and deformable_tetrahedralize keeps the cage triangles as the boundary of the mesh, so the cube gets only 12 tetrahedrons. Tools shows how to triangulate the cage first for a finer mesh.

License

The C SDK works with all three licenses. Without a key, it runs under the Free license, forever: every feature, up to 2,500 tetrahedrons per scene, with no account and no internet, and nothing is sent. A Standard license lifts the limit on your device: activate its key once, online, and the library renews it by itself while the program runs online, at least once every 14 days. It is shared with the plugins and the other SDKs on the same device. An app you ship to others uses a Developer license instead: it activates the Developer key at every start, offline, as its first Deformable call, before any engine call. Licensing has the whole story.

Five functions read and change the license state. This program renews the Standard license when that is due, and prints the status line:

c
#include <stdio.h>

#include "deformable.h"

int main(void) {
    DeformableLicenseStatus status;
    if (deformable_license_refresh(15000, &status) != DEFORMABLE_STATUS_OK) {
        fprintf(stderr, "%s\n", deformable_last_error_message());
        return 1;
    }
    printf("%s\n", status.message);
    return 0;
}
text
Free license: up to 2,500 tetrahedrons per scene — Buy license
Function What it does
deformable_license_status Fills a DeformableLicenseStatus: the state, days_left (of a Developer trial), tetrahedron_limit (2,500 under the Free license, 0 without a limit), has_license_key and the status line message. It never goes online.
deformable_license_refresh Renews the Standard license when that is due. On a Standard license, call it when your program starts. Without a key, and under a Developer license, it contacts nothing.
deformable_license_activate Turns a license key on. A Standard key, such as "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx", is activated on this device and needs internet. A Developer key, "tgdfp-<payload hex>-<signature hex>", is checked offline and holds for this run of the program, so call it at every start.
deformable_license_deactivate Forgets the Standard license on this device at once, even offline, and frees its seat when the device is online.
deformable_license_set_online_access With 0, keeps the program off the network: nothing is sent, and the Standard license runs only as long as it runs offline.

The state is one of the DEFORMABLE_LICENSE_STATE_ constants, such as DEFORMABLE_LICENSE_STATE_FREE_LICENSE, _STANDARD_LICENSE or _DEVELOPER_LICENSE. _NEEDS_ONLINE (a Standard license that needs a renewal) and _DEVELOPER_TRIAL_ENDED run under the Free license, with its limit.

The timeouts are in milliseconds: one above 60,000 counts as 60,000, and 0 gives DEFORMABLE_STATUS_INVALID_ARGUMENT. Under the Free license, deformable_scene_add_object returns DEFORMABLE_STATUS_TETRAHEDRON_LIMIT_EXCEEDED for an object that would take the scene past the limit, and deformable_last_error_message says so, such as Free license: this would simulate 3,120 tetrahedrons; the limit is 2,500 per scene. See Memory and errors.

Conventions

These rules hold for every function. Memory and errors covers them in full.

  • Status. A function that can fail returns a DeformableStatus: DEFORMABLE_STATUS_OK (0) on success, a positive code otherwise. deformable_last_error_message then describes the failure.
  • Handles. A _create function or a tool makes a handle; the matching _destroy function frees it.
  • Arrays. You pass arrays as a pointer and a count, borrowed for the call. The library lends its own arrays; you never free them.
  • Booleans and enumerations. Booleans are uint8_t, 0 for false and anything else for true. Enumerations are int32_t codes with DEFORMABLE_ constants.
  • Units. Lengths are in your units. Time, forces, gravity, masses and material values are in simulation units. The scene’s scale converts your lengths to simulation lengths. See Units and axes.
  • License. Under the Free license, a scene simulates up to 2,500 tetrahedrons, and deformable_scene_add_object returns a license status for an object past the limit. The deformable_license_ functions read and change the license.
  • Threads. A scene takes one call at a time. Tools, embeddings and cancel flags work from several threads at once. The last error is per thread.

Next steps

  • How the engine works: the ideas the plugins and every SDK share, explained once in the Engine guide.
  • Scene: materials, objects, stepping and outputs.
  • Tools: the mesh tools that prepare a scene’s inputs.
  • Render surfaces: skin a render mesh on a simulated object.
  • Memory and errors: ownership, handles, status codes and threads.
  • C API Reference: every type, constant and function of deformable.h.