﻿---
title: Overview
description: "The reference of the deformable.h C header: its conventions, and the pages that list every public item."
url: https://help.tangerina.io/deformable/v0.5.0/api-references/c/overview/
---

# Overview – C API Reference – Deformable v0.5.0

The C SDK is the `deformable.h` header and the library it declares. These pages list every public declaration of the header with its signature and documentation, generated from the header. They group the declarations by topic rather than in the order of the header: the functions that act on an opaque handle or a struct sit under it.

For tasks and worked examples, start with the [getting-started guide](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/getting-started/).

## Pages

- [Scene](https://help.tangerina.io/deformable/v0.5.0/api-references/c/scene/): The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
- [Tools](https://help.tangerina.io/deformable/v0.5.0/api-references/c/tools/): Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
- [Mesh checks](https://help.tangerina.io/deformable/v0.5.0/api-references/c/mesh-checks/): Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
- [Meshes](https://help.tangerina.io/deformable/v0.5.0/api-references/c/meshes/): The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
- [Render surfaces](https://help.tangerina.io/deformable/v0.5.0/api-references/c/render-surfaces/): Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
- [Math](https://help.tangerina.io/deformable/v0.5.0/api-references/c/math/): The points, vectors, transforms, planes and convex regions the other pages take and return.
- [Errors](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/): Errors and status codes, the library version, and the cancel flag that stops a long call.
- [License](https://help.tangerina.io/deformable/v0.5.0/api-references/c/license/): The license state of this device, or of this program under an Application license, and the calls that refresh, activate and deactivate it.

## Conventions

- **Status.** A fallible call returns a [`DeformableStatus`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus): [`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_ok) (0) on success, a positive code otherwise. The calling thread's last error then holds the code, up to two element indices and a message ([`deformable_last_error_message`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformable_last_error_message), [`deformable_last_error_details`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformable_last_error_details)); a call that returns a status clears it on success, except `deformable_last_error_details`, which leaves it. Nothing is written to an out-pointer on failure, except the license status that [`deformable_license_refresh`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/license/#deformable_license_refresh), [`deformable_license_activate`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/license/#deformable_license_activate) and [`deformable_license_deactivate`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/license/#deformable_license_deactivate) fill on a license failure.
- **Handles.** Library objects are opaque pointers made by a `_create` function or a tool and freed by the matching `_destroy` function, which accepts `NULL`. Object and material handles are `uint32_t` values counting up from 0.
- **Values.** Parameters and records are plain structs; booleans are `uint8_t` (0 false, anything else true); enumerations are `int32_t` codes, and an undefined code gives [`DEFORMABLE_STATUS_INVALID_ARGUMENT`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_invalid_argument).
- **Arrays in.** A pointer and a count, borrowed for the call only. A count of 0 accepts any pointer; otherwise a `NULL` pointer gives [`DEFORMABLE_STATUS_NULL_POINTER`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_null_pointer), and a count whose array would not fit in the address space [`DEFORMABLE_STATUS_INVALID_ARGUMENT`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_invalid_argument).
- **Arrays out.** Library-owned: a `_view` function (or a pointer and count pair) lends the arrays of a handle, valid until the handle is destroyed or, for a scene's per-frame outputs and a deformed surface, until the next call that refills them. The host copies what it keeps and never frees a lent pointer.
- **Safety.** Every pointer a call that returns a status reads or writes is checked for `NULL` and alignment before use (a misaligned one gives [`DEFORMABLE_STATUS_INVALID_ARGUMENT`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_invalid_argument)); a `_destroy` function only skips `NULL`. No failure inside the library unwinds into the host (a caught panic gives [`DEFORMABLE_STATUS_PANICKED`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_panicked)). The rest of each contract, live handles and counts that match the memory, is the host's.
- **Units.** Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The scene's scale converts host lengths to simulation lengths.
- **Threads.** A scene may move between threads but takes one call at a time; tools, embeddings and cancel flags may be used from several threads at once. The last error is per thread. The license functions may be called from any thread; one contact with the licensing service runs per process at a time.
- **License.** Nothing ever refuses to run. Without a license, the Free license runs: a scene simulates at most 2,500 tetrahedrons, [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/scene/#deformable_scene_add_object) gives [`DEFORMABLE_STATUS_TETRAHEDRON_LIMIT_EXCEEDED`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/errors/#deformablestatus-deformable_status_tetrahedron_limit_exceeded) for an object that would take it past the limit, and [`deformable_scene_step`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/scene/#deformable_scene_step) holds back the objects that do not fit, so the rest runs. The tools and the render surface calls have no limit. Two licenses lift it, both activated with [`deformable_license_activate`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/license/#deformable_license_activate). A Standalone license runs on 1 device per seat: its key and the lease the licensing service signs for this device are stored for this device and user, every program loading the library shares them, and the lease renews in the background while the engine runs; a device may stay offline up to 7 days. An Application license is a company's, for one app it ships: the app activates its key at every start, as its first Deformable call, before status and refresh; the key is checked offline, licenses that process on any device and is never stored or sent, so the app's users need nothing. The plugins refuse an Application key. Creating, setting, reading and destroying never check, so a host can always tear down.
- **Examples.** The examples share a few values set up out of view: `cage`, the unit cube as a closed triangle mesh with outward normals (a [`DeformableTriangleMeshView`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/meshes/#deformabletrianglemeshview)); `polygons`, the same cube as six quads (a [`DeformablePolygonMeshView`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/meshes/#deformablepolygonmeshview)); `mesh`, the cage filled with tetrahedrons (a [`DeformableTetrahedralMeshView`](https://help.tangerina.io/deformable/v0.5.0/api-references/c/meshes/#deformabletetrahedralmeshview)); `scene`, a scene holding one object made of `mesh` with one default material; and `material` and `object`, the `uint32_t` handles of that material and object. CHECK stops an example when a call fails.

## The header

`deformable.h`: the C interface of libdeformable, the library of the Deformable C SDK.

Finite element deformation and fracture of tetrahedral meshes: a scene a host drives frame by frame, the render
surfaces embedded in its objects, and the mesh tools that prepare its inputs. The C SDK ships the library in its lib
folder as `libdeformable.dylib` (`.so` on Linux, `deformable.dll` with its import library `deformable.dll.lib` on Windows)
and `libdeformable.a` (`deformable.lib` on Windows).

The host flow below fills a closed cage with tetrahedrons, makes the mesh an object of a new scene, steps it for one
second and reads where its nodes are.

```c
// Fill the cage with tetrahedrons; zeroed anisotropy stretches nothing.
DeformableTetrahedralizeParameters parameters = {0};
parameters.maximum_edge_length = 0.5;
DeformableTetrahedralization *filled = NULL;
CHECK(deformable_tetrahedralize(&cage, &parameters, NULL, &filled));
DeformableTetrahedralizationView result;
CHECK(deformable_tetrahedralization_view(filled, &result));
// Make the mesh an object of a new scene, with the default material.
DeformableScene *scene = NULL;
CHECK(deformable_scene_create(&scene));
DeformableMaterialParameters defaults;
CHECK(deformable_material_parameters_default(&defaults));
DeformableTetrahedronMaterials uniform = {0};
CHECK(deformable_scene_add_material(scene, &defaults,
                                    &uniform.material));
DeformableObjectOptions options;
CHECK(deformable_object_options_default(&options));
uint32_t cube;
CHECK(deformable_scene_add_object(scene, &result.mesh, &uniform,
                                  &options, &cube));
// Step one second at 24 frames a second, 10 substeps a frame.
for (int frame = 0; frame <= 24; frame++) {
    DeformableStepReport report;
    CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL,
                                &report));
}
// Read where the nodes are, then free what the flow made.
const DeformableVector3 *positions = NULL;
size_t count = 0;
CHECK(deformable_scene_node_positions(scene, cube, &positions,
                                      &count));
deformable_scene_destroy(scene);
deformable_tetrahedralization_destroy(filled);
```
