﻿---
title: Getting started with C
description: Download the C SDK, compile against deformable.h with a compiler, make or CMake, and run your first simulation from C.
url: https://help.tangerina.io/deformable/v0.8.0/user-guides/c/getting-started/
---

# Getting started with C – C SDK – Deformable v0.8.0

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](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/how-the-engine-works/). This guide shows how to use them from C;
the [C API Reference](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/) 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](https://tangerina.io/deformable#download-c), 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.md` | A short guide to the SDK. |
| `LICENSE.md` | The license. |

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.

A Standalone subscription or license belongs to each device that runs the program. On a colleague's device, a server
or a render farm node, the program runs as Free, 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 an Application license: your app then activates its
key at every start, offline, and its users need no activation, network or seat. See
[Application license](https://help.tangerina.io/deformable/v0.8.0/licensing/#application-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.

![A tetrahedral cube is added as an object, then falls further each frame, and its node positions are read after every step.](../../images/sdk-first-simulation-loop.svg "Add the mesh as an object once, then step the scene each frame and read the node positions.")

The cube falls about 4.9 units in one second. Nothing stops it, because the scene has no floor.
[Scene](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/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](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/) shows how to triangulate the cage
first for a finer mesh.

## License

The C SDK works with Free, the Standalone subscription, and the Standalone and Application licenses. Without a sign-in
or a key, it runs as Free, forever: every feature, up to 2,500 tetrahedrons per scene, with no account and no internet,
and nothing is sent. A Standalone subscription or a Standalone license lifts the limit on your device. Sign in to the
subscription once, in the browser, and the library checks it in by itself while the program runs online, at least once a
day. Or activate a Standalone license key once, online, and the library renews it by itself, at least once every 7 days.
Either one is shared with the plugins and the other SDKs on the same device. An app you ship to others uses an
Application license instead: it activates the Application key at every start, offline, as its first Deformable call,
before any engine call. [Licensing](https://help.tangerina.io/deformable/v0.8.0/licensing/) has the whole story.

Nine functions read and change the license state. This program renews the Standalone subscription or 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: up to 2,500 tetrahedrons per scene
```

| Function | What it does |
|---|---|
| `deformable_license_status` | Fills a `DeformableLicenseStatus`: the `state`, `days_left` (of an Application trial), `tetrahedron_limit` (2,500 on Free, 0 without a limit), `has_license_key`, `signed_in` (1 while a Standalone subscription is signed in on this device), the status line `message` and the signed-in `account`'s email. It never goes online. |
| `deformable_license_refresh` | Renews the Standalone license, or checks in the Standalone subscription, when that is due. Call it when your program starts. On Free, and under an Application license, it contacts nothing. |
| `deformable_license_start_sign_in` | Starts a sign-in with a Standalone subscription. Fills a `DeformableSignIn`: the `user_code` to approve, the `verification_url` of the page that approves it, and `expires_in_seconds`, how long the code lasts. Show both to the user, or open the address in the browser. |
| `deformable_license_wait_for_sign_in` | Waits for the approval, for at most the timeout. Sets `approved` to 1 once the account approved it, with the status after it tries to take a seat: `DEFORMABLE_LICENSE_STATE_STANDALONE_SUBSCRIPTION` when a seat was free, otherwise the state that says why there is none (for example `DEFORMABLE_LICENSE_STATE_SUBSCRIPTION_NO_SEAT`, where `deformable_license_take_over` can be offered). Sets it to 0 while not yet: call it again. It can return up to 25 seconds after its timeout, so call it off your interface thread. |
| `deformable_license_take_over` | Moves the subscription's seat to this device from the device that uses it. |
| `deformable_license_sign_out` | Forgets the sign-in on this device at once, even offline, and frees its seat when the device is online. |
| `deformable_license_activate` | Turns a license key on. A Standalone key, such as `"tgdfp-xxxxx-xxxxx-xxxxx-xxxxx"`, is activated on this device and needs internet. An Application 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 Standalone 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 a subscription or a Standalone 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`,
`_STANDALONE_SUBSCRIPTION`, `_STANDALONE_LICENSE` or `_APPLICATION_LICENSE`. `_SUBSCRIPTION_NEEDS_ONLINE`,
`_SUBSCRIPTION_NO_SEAT` (another device uses the seat, or this one was removed), `_NO_SUBSCRIPTION`, `_SIGN_IN_ENDED`,
`_LICENSE_NEEDS_ONLINE` (a Standalone license that needs a renewal) and `_APPLICATION_TRIAL_ENDED` run as Free, with
its limit.

A sign-in shows a code and waits until the user approves it in the browser:

```c
#include <stdio.h>

#include "deformable.h"

int main(void) {
    DeformableSignIn sign_in;
    if (deformable_license_start_sign_in(15000, &sign_in) != DEFORMABLE_STATUS_OK) {
        fprintf(stderr, "%s\n", deformable_last_error_message());
        return 1;
    }
    printf("Open %s and approve the code %s\n", sign_in.verification_url, sign_in.user_code);
    DeformableLicenseStatus status;
    uint8_t approved = 0;
    while (!approved) {
        if (deformable_license_wait_for_sign_in(5000, &approved, &status) != DEFORMABLE_STATUS_OK) {
            fprintf(stderr, "%s\n", deformable_last_error_message());
            return 1;
        }
    }
    printf("%s\n", status.message);
    return 0;
}
```

```text
Open https://platform.tangerina.io/device?user_code=ABCDEFGH and approve the code ABCD-EFGH
Standalone subscription
```

When the code ends or the user denies it, the wait returns `DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILED`, and the loop
ends with its message.

The timeouts are in milliseconds: one above 60,000 counts as 60,000, and 0 gives `DEFORMABLE_STATUS_INVALID_ARGUMENT`.
On Free, `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: this would simulate
3,120 tetrahedrons; the limit is 2,500 per scene**. See
[Memory and errors](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/memory-and-errors/#license-statuses).

## Conventions

These rules hold for every function. [Memory and errors](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/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](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/how-the-engine-works/#units-and-axes).
- **License.** On Free, 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](https://help.tangerina.io/deformable/v0.8.0/user-guides/engine/how-the-engine-works/): the ideas the plugins and every SDK
  share, explained once in the Engine guide.
- [Scene](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/scene/): materials, objects, stepping and outputs.
- [Tools](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/tools/): the mesh tools that prepare a scene's inputs.
- [Render surfaces](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/render-surfaces/): skin a render mesh on a simulated object.
- [Memory and errors](https://help.tangerina.io/deformable/v0.8.0/user-guides/c/memory-and-errors/): ownership, handles, status codes and threads.
- [C API Reference](https://help.tangerina.io/deformable/v0.8.0/api-references/c/overview/): every type, constant and function of `deformable.h`.
