﻿---
title: Scene
description: Build a scene from C, with materials, objects, driven vertices, forces and glue, then step it and read the outputs every frame.
url: https://help.tangerina.io/deformable/v0.5.0/user-guides/c/scene/
---

# Scene – C SDK – Deformable v0.5.0

A `DeformableScene` holds materials and objects and steps them through time. You add them to it, then call
`deformable_scene_step` once per frame and read the outputs. What each setting, material value and output means, the
same in the plugins and every SDK, is in the Engine guide:
[Simulation settings](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/simulation-settings/),
[Materials](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/materials/) and
[Kinematic objects and regions](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/kinematic-and-regions/). This page shows each task with a
short example. For the full signature and documentation of every function and struct, see the
[C API Reference](https://help.tangerina.io/deformable/v0.5.0/api-references/c/scene/).

## The frame loop

This program drops a glass cube onto a stone slab that stays in place. The glass breaks on impact. The function
`solid_box` triangulates the six faces of a box, then fills it with tetrahedrons; [Tools](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/tools/)
explains both steps. The `CHECK` macro stops the program with the last error when a call fails.

```c
#include <stdio.h>
#include <stdlib.h>

#include "deformable.h"

/* Stops the program with the last error when a call fails. */
#define CHECK(call)                                                                                \
    do {                                                                                           \
        if ((call) != DEFORMABLE_STATUS_OK) {                                                      \
            fprintf(stderr, "%s:%d: %s\n", __FILE__, __LINE__, deformable_last_error_message());   \
            exit(1);                                                                               \
        }                                                                                          \
    } while (0)

/* Fills the box from minimum to maximum with tetrahedrons: six outward quads, triangulated, then tetrahedralized. */
static DeformableTetrahedralization *solid_box(DeformableVector3 minimum, DeformableVector3 maximum,
                                               double maximum_area, double maximum_edge_length) {
    DeformableVector3 positions[8];
    for (int corner = 0; corner < 8; ++corner) {
        positions[corner].x = corner & 1 ? maximum.x : minimum.x;
        positions[corner].y = corner & 2 ? maximum.y : minimum.y;
        positions[corner].z = corner & 4 ? maximum.z : minimum.z;
    }
    const uint32_t sizes[6] = {4, 4, 4, 4, 4, 4};
    const uint32_t corners[24] = {0, 2, 3, 1, 4, 5, 7, 6, 0, 1, 5, 4, 2, 6, 7, 3, 0, 4, 6, 2, 1, 3, 7, 5};
    DeformablePolygonMeshView box = {positions, 8, sizes, 6, corners, 24};

    DeformableTriangulateParameters triangulate_parameters;
    CHECK(deformable_triangulate_parameters_default(&triangulate_parameters));
    triangulate_parameters.maximum_area = maximum_area;
    DeformableTriangulation *triangulation = NULL;
    CHECK(deformable_triangulate(&box, NULL, 0, &triangulate_parameters, NULL, &triangulation));
    DeformableTriangulationView cage;
    CHECK(deformable_triangulation_view(triangulation, &cage));

    DeformableTetrahedralizeParameters parameters = {0};
    parameters.maximum_edge_length = maximum_edge_length;
    CHECK(deformable_anisotropy_default(&parameters.anisotropy[0]));
    CHECK(deformable_anisotropy_default(&parameters.anisotropy[1]));
    DeformableTetrahedralization *solid = NULL;
    CHECK(deformable_tetrahedralize(&cage.mesh, &parameters, NULL, &solid));
    deformable_triangulation_destroy(triangulation);
    return solid;
}

int main(void) {
    DeformableTetrahedralization *ground_solid = solid_box((DeformableVector3){-3, -0.5, -3},
                                                          (DeformableVector3){3, 0, 3}, 1.0, 1.0);
    DeformableTetrahedralization *cube_solid = solid_box((DeformableVector3){-0.5, 2, -0.5},
                                                         (DeformableVector3){0.5, 3, 0.5}, 0.05, 0.3);
    DeformableTetrahedralizationView ground_view, cube_view;
    CHECK(deformable_tetrahedralization_view(ground_solid, &ground_view));
    CHECK(deformable_tetrahedralization_view(cube_solid, &cube_view));

    DeformableScene *scene = NULL;
    CHECK(deformable_scene_create(&scene));

    DeformableMaterialParameters parameters;
    uint32_t stone = 0, glass = 0;
    CHECK(deformable_material_preset_find("stone", &parameters));
    CHECK(deformable_scene_add_material(scene, &parameters, &stone));
    CHECK(deformable_material_preset_find("glass", &parameters));
    CHECK(deformable_scene_add_material(scene, &parameters, &glass));

    DeformableObjectOptions options;
    CHECK(deformable_object_options_default(&options));
    DeformableTetrahedronMaterials ground_materials = {DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM, stone, NULL, 0};
    DeformableTetrahedronMaterials cube_materials = {DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM, glass, NULL, 0};
    uint32_t ground = 0, cube = 0;
    CHECK(deformable_scene_add_object(scene, &ground_view.mesh, &ground_materials, &options, &ground));
    CHECK(deformable_scene_add_object(scene, &cube_view.mesh, &cube_materials, &options, &cube));

    /* The ground is driven: each node is held at its rest position. */
    size_t ground_node_count = ground_view.mesh.position_count;
    DeformableDrivenVertex *held = malloc(ground_node_count * sizeof *held);
    for (size_t node = 0; node < ground_node_count; ++node) {
        held[node].vertex = (uint32_t)node;
        held[node].target = ground_view.mesh.positions[node];
    }
    CHECK(deformable_scene_drive(scene, ground, held, ground_node_count));
    free(held);

    /* Two seconds at 24 frames per second, 10 substeps per frame. */
    size_t fractured = 0;
    for (int frame = 0; frame <= 48; ++frame) {
        DeformableStepReport report;
        CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL, &report));

        const DeformableFaceEvent *events = NULL;
        size_t event_count = 0;
        CHECK(deformable_scene_face_events(scene, cube, &events, &event_count));
        fractured += event_count;
    }

    const DeformableVector3 *positions = NULL;
    size_t node_count = 0;
    CHECK(deformable_scene_node_positions(scene, cube, &positions, &node_count));
    printf("rest nodes: %zu\n", cube_view.mesh.position_count);
    printf("nodes now: %zu\n", node_count);
    printf("face events: %zu\n", fractured);

    deformable_scene_destroy(scene);
    /* The scene copied the meshes; the snippets below still read cube_view, so free them last. */
    deformable_tetrahedralization_destroy(ground_solid);
    deformable_tetrahedralization_destroy(cube_solid);
    return 0;
}
```

```text
rest nodes: 145
nodes now: 342
face events: 462
```

The cube has more nodes at the end than at rest: each fracture clones the nodes along the crack. Each face event
reports a tetrahedron whose faces a fracture exposed in the last step.

The snippets on the rest of this page go into `main` of this program and use its names: `scene`, `ground`,
`cube`, `cube_view`, `options` and `CHECK`. Put a snippet that sets up the scene before the frame loop, and a snippet
that reads outputs inside the loop, after `deformable_scene_step`.

## Set up the scene

`deformable_scene_create` creates an empty scene with gravity (0, -9.81, 0), scale 1, and as many worker threads
as the CPU offers, up to 16. `deformable_scene_destroy` frees the scene and every array it lent. Three
functions change the scene settings:

```c
CHECK(deformable_scene_set_scale(scene, 0.01));                         /* positions in centimetres */
CHECK(deformable_scene_set_gravity(scene, (DeformableVector3){0, 0, -9.81})); /* a Z-up host */
CHECK(deformable_scene_set_worker_count(scene, 4));
```

- **Scale** converts your length unit to the simulation unit, which reads as a metre; see
  [Scale](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/simulation-settings/#scale). It must be from 0.001 to 1,000, or the call
  returns `DEFORMABLE_STATUS_SCALE_OUT_OF_RANGE`. Set it before you add objects: it applies only to later conversions.
- **Gravity** is in simulation units. The scale does not change it.
- **Worker count** is the number of threads a step uses, the calling thread included. It must be at least 1. The
  results are the same for every count.

Positions, driven targets and glue plane offsets are in your units. Time, forces, gravity, masses and material
values are in simulation units.

## Materials

### Material values

A `DeformableMaterialParameters` holds the ten values of
[Materials](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/materials/#the-ten-values), which says what each one does and how to make a
material elastic, plastic or breakable. `deformable_material_parameters_default` writes the defaults, and the scene
clamps each value to its range:

| Field | Default | Range | What it does |
|---|---|---|---|
| `youngs_modulus` | 800000 | [1000, 1e10] | Stiffness, in pascals. |
| `poissons_ratio` | 0 | [-0.90001, 0.490001] | How much the material bulges sideways when you squeeze it. |
| `density` | 2500 | [0, 10000] | Mass per unit volume. |
| `toughness` | 200000 | [0, 1e8] | The stress at which the material breaks. 0 or less never breaks. |
| `youngs_damping` | 0 | [0, 1e9] | Damping. The solver uses `youngs_damping / youngs_modulus`. |
| `yield_strain` | 0 | [0, 1] | The strain above which plastic flow starts. |
| `maximum_yield` | 0 | [0, 1] | The largest plastic strain. 0 resets the plastic strain at every solve. |
| `creep_fraction` | 0 | [0, 1] | The fraction of the elastic strain that becomes plastic at each solve. 0 turns plasticity off. |
| `wake_up_radius` | 1.2 | [1, 1000] | How far an impact wakes a sleeping, glued object, in simulation units. |
| `friction` | 0.6 | [0, 1] | The friction coefficient. A contact uses the smaller of the two materials' values. |

### Use a preset

The library ships the 43 presets of [Materials](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/materials/#the-presets), which lists them
with their values. `deformable_material_preset_find` looks a name up exactly, case included; a name no preset has gives
`DEFORMABLE_STATUS_INVALID_ARGUMENT`. To list them all, count with `deformable_material_preset_count` and read each with
`deformable_material_preset`. The names are static strings; you never free them.

```c
size_t preset_count = deformable_material_preset_count();
for (size_t index = 0; index < preset_count; ++index) {
    const char *name = NULL;
    DeformableMaterialParameters preset;
    CHECK(deformable_material_preset(index, &name, &preset));
    printf("%s: E = %g Pa, density = %g\n", name, preset.youngs_modulus, preset.density);
}
```

```text
sponge: E = 12000 Pa, density = 40
foam: E = 13000 Pa, density = 60
snow: E = 100000 Pa, density = 300
...
```

### Add and change a material

`deformable_scene_add_material` writes a material handle: 0 for the first material, 1 for the next, and so on.
A NaN or infinite value gives `DEFORMABLE_STATUS_NON_FINITE_VALUE`. `deformable_scene_set_material` rewrites a
material; the objects that use it take the new values before the next step. A new density changes the lumped node
masses then too, and the velocities stay as they were.

```c
DeformableMaterialParameters rubber;
CHECK(deformable_material_parameters_default(&rubber));
rubber.youngs_modulus = 1e5;
rubber.poissons_ratio = 0.45;
rubber.density = 1100;
rubber.toughness = 0; /* unbreakable */
uint32_t rubber_material = 0;
CHECK(deformable_scene_add_material(scene, &rubber, &rubber_material));

rubber.friction = 0.9;
CHECK(deformable_scene_set_material(scene, rubber_material, &rubber));
```

## Objects

### Add an object

`deformable_scene_add_object` takes a `DeformableTetrahedralMeshView` in world space and in your units, a
`DeformableTetrahedronMaterials` and a `DeformableObjectOptions`. It copies the mesh, so you can free the mesh after
the call. It writes an object handle: 0 for the first object, 1 for the next, and so on.

The materials come in one of two forms:

- `DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM` gives every tetrahedron `material`, as in the frame loop.
- `DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON` gives tetrahedron i `materials[i]`. `material_count` must equal the
  tetrahedron count, or the call returns `DEFORMABLE_STATUS_LENGTH_MISMATCH`.

`deformable_object_options_default` writes the default options: self collision on, and the object enabled.

### Tetrahedron orientation

Each tetrahedron lists four node indices. Its corners must be *left-handed*: with eᵢ = Xᵢ - X0, the value
-e1 · (e2 × e3) must be positive. The tools make them so, though a thick `deformable_extrude` shell can invert some
where the mesh curves sharply. The call checks each tetrahedron, and it creates nothing when one fails:

| Status | Cause |
|---|---|
| `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_INVERTED` | The corners are right-handed. Swap two of them. |
| `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_FLAT` | The four corners lie in one plane. |
| `DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_TOO_SMALL` | The volume is too small to simulate. |
| `DEFORMABLE_STATUS_NON_MANIFOLD_FACE` | Three or more tetrahedrons share one face. |

The last error's `first_index` names the tetrahedron. [Memory and errors](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/memory-and-errors/#status-codes-and-the-last-error)
shows how to read it.

### Give part of an object another material

A [material region](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/kinematic-and-regions/#material-regions) gives part of an object its
own material. The region is a closed convex polygon mesh, such as a unit cube, with a `DeformableAffineTransform` into
the object mesh's space. A transform maps a point p, as a row vector, to p · `linear` + `translation`.

`deformable_material_region_indices` tells which region holds the centroid of each tetrahedron: 0 for a tetrahedron
outside every region, or k + 1 for region k. When regions overlap, the region whose mesh has the smaller volume
before its transform wins.

This snippet makes the lower half of the cube steel, and adds the cube with one material per tetrahedron. Put it in
place of the line of the frame loop that adds the cube:

```c
uint32_t steel = 0;
CHECK(deformable_material_preset_find("steel", &parameters));
CHECK(deformable_scene_add_material(scene, &parameters, &steel));

/* The unit cube from (0, 0, 0) to (1, 1, 1), squashed and moved to cover the lower half of the cube object. */
DeformableVector3 unit_positions[8];
for (int corner = 0; corner < 8; ++corner) {
    unit_positions[corner] = (DeformableVector3){corner & 1, (corner >> 1) & 1, corner >> 2};
}
const uint32_t unit_sizes[6] = {4, 4, 4, 4, 4, 4};
const uint32_t unit_corners[24] = {0, 2, 3, 1, 4, 5, 7, 6, 0, 1, 5, 4, 2, 6, 7, 3, 0, 4, 6, 2, 1, 3, 7, 5};
DeformableMaterialRegion region = {
    {unit_positions, 8, unit_sizes, 6, unit_corners, 24},
    {{{{1, 0, 0}, {0, 0.5, 0}, {0, 0, 1}}}, {-0.5, 2, -0.5}},
};

DeformableMaterialRegionIndices *indices = NULL;
CHECK(deformable_material_region_indices(&cube_view.mesh, &region, 1, &indices));
const uint32_t *values = NULL;
size_t value_count = 0;
CHECK(deformable_material_region_indices_values(indices, &values, &value_count));

uint32_t *per_tetrahedron = malloc(value_count * sizeof *per_tetrahedron);
size_t steel_count = 0;
for (size_t tetrahedron = 0; tetrahedron < value_count; ++tetrahedron) {
    per_tetrahedron[tetrahedron] = values[tetrahedron] == 0 ? glass : steel;
    steel_count += values[tetrahedron] != 0;
}
deformable_material_region_indices_destroy(indices);
printf("%zu of %zu tetrahedrons are steel\n", steel_count, value_count);

DeformableTetrahedronMaterials mixed = {DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON, 0, per_tetrahedron, value_count};
CHECK(deformable_scene_add_object(scene, &cube_view.mesh, &mixed, &options, &cube));
free(per_tetrahedron);
```

```text
220 of 463 tetrahedrons are steel
```

A region polygon with fewer than 3 corners or no normal gives `DEFORMABLE_STATUS_DEGENERATE_REGION`, with the region
and the polygon in the last error's indices.

### Change an object

| Function | What it does |
|---|---|
| `deformable_scene_set_object_material` | Gives the object new materials before the next step. It wakes nothing. |
| `deformable_scene_remove_object` | Deletes the object and its contacts and glue. Its handle then gives `DEFORMABLE_STATUS_UNKNOWN_OBJECT`. |
| `deformable_scene_set_object_disabled` | Takes the object out of the scene (not 0) or puts it back (0). A disabled object keeps its outputs and ignores forces; its driving waits until it is enabled. |
| `deformable_scene_set_self_collision` | Turns collision of the object with itself on or off. |
| `deformable_scene_set_never_sleep` | Keeps the part of the object around one node awake. |

```c
CHECK(deformable_scene_set_self_collision(scene, cube, 0));
CHECK(deformable_scene_set_never_sleep(scene, cube, 0, 1));
```

## Drive vertices

A driven vertex follows a path you give instead of the simulation; see
[Driven vertices and forces](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/kinematic-and-regions/#driven-vertices-and-forces). A
`DeformableDrivenVertex` names a node of an object and a target in your units. `deformable_scene_drive` moves each
listed node to its target by the end of the next step, whatever the forces on it. The list stays in force until the next
`deformable_scene_drive` call for the same object. The nodes you then leave out are released with their last velocity,
so you can throw an object. An empty list releases them all:

```c
CHECK(deformable_scene_drive(scene, ground, NULL, 0));
```

![A cube moves in equal steps while its nodes are driven to their targets, then keeps the same speed after it is released.](../../images/sdk-drive-then-release.svg "A released node keeps its last driven velocity, so you can throw an object.")

To pin an object in place, drive every node to its rest position, as the slab in the frame loop does. To animate an
object, call `deformable_scene_drive` before each step with the new targets. This snippet, inside the frame
loop before the step, lifts the slab 1 unit per second:

```c
size_t slab_node_count = ground_view.mesh.position_count;
DeformableDrivenVertex *lifted = malloc(slab_node_count * sizeof *lifted);
for (size_t node = 0; node < slab_node_count; ++node) {
    lifted[node].vertex = (uint32_t)node;
    lifted[node].target = ground_view.mesh.positions[node];
    lifted[node].target.y += frame / 24.0;
}
CHECK(deformable_scene_drive(scene, ground, lifted, slab_node_count));
free(lifted);
```

## Add forces

`deformable_scene_add_force` adds a force, in simulation units, to one node of an object. The force acts in
every substep of the next step only, so call it before each step for as long as the force lasts. Every
`deformable_scene_step` call that succeeds takes the queued forces, even one that runs no substep, such as the
first call, and `deformable_scene_skip_to` drops them: a force added before the first step call never acts.
Calls on one node add up. This snippet pushes the cube along x with an acceleration of 5 units/s² for one step:

```c
const double *masses = NULL;
size_t mass_count = 0;
CHECK(deformable_scene_node_masses(scene, cube, &masses, &mass_count));
for (size_t node = 0; node < mass_count; ++node) {
    DeformableVector3 push = {5.0 * masses[node], 0, 0};
    CHECK(deformable_scene_add_force(scene, cube, (uint32_t)node, push));
}
```

## Glue objects together

Glue holds objects together where their tetrahedrons overlap, as a stiff spring with a damper; see
[Glue regions](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/kinematic-and-regions/#glue-regions). The damper resists
only motion relative to the other object, so an object glued to a driven one rides along with it. Glue is made by the
first step after an object is added that advances the time with at least one substep, so set it up before that step.
The first step call only records the time, so it makes no glue.

- `deformable_scene_set_glue_all` glues each new object to every other enabled object. `NULL` parameters turn
  it off again, as in a new scene.
- `deformable_scene_add_glue_region` glues the member objects to each other, only through tetrahedrons with a
  vertex inside the region.

A `DeformableGlueParameters` holds a spring constant and a damping coefficient. A spring constant of 0 takes the
default 4,905, and a damping coefficient of 0 takes 2,452.5.

A `DeformableConvexRegion` is a list of planes. A point p is inside when normal · p + offset ≤ 0 for every plane.
Offsets are in your units. `deformable_convex_region_contains` runs the same test on one point.

```c
DeformableGlueParameters glue = {0, 0}; /* the defaults */
const DeformablePlane planes[1] = {{{0, 1, 0}, -0.1}}; /* y <= 0.1 */
DeformableConvexRegion below = {planes, 1};
const uint32_t members[2] = {ground, cube};
CHECK(deformable_scene_add_glue_region(scene, &below, members, 2, &glue));

uint8_t inside = 0;
CHECK(deformable_convex_region_contains(&below, (DeformableVector3){0, -0.25, 0}, &inside));
printf("inside: %u\n", (unsigned)inside);
```

```text
inside: 1
```

## Step

`deformable_scene_step` advances the scene to a time, in seconds, in a number of equal substeps. Call it once per frame
with the frame's time. The first call only records the time, so call it at your start frame first. A substep must not be
longer than 0.04 s ([Substeps](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/simulation-settings/#substeps)); 10 substeps per frame at
24 frames per second is a good start. A time before the last one gives `DEFORMABLE_STATUS_TIME_WENT_BACKWARDS`: to go
back, destroy the scene and build it again.

![A time line of three frames: the first call at frame 0 only records the time, and each later step runs 10 equal substeps up to its frame.](../../images/sdk-frames-and-substeps.svg "Step once per frame. The first call only records the time, and each later step runs its substeps.")

The step writes a `DeformableStepReport`: the substeps it ran and an outcome.

| Outcome | Meaning |
|---|---|
| `DEFORMABLE_STEP_OUTCOME_STEPPED` | The substeps ran. |
| `DEFORMABLE_STEP_OUTCOME_FIRST_CALL` | The first call only recorded the time. |
| `DEFORMABLE_STEP_OUTCOME_NO_TIME_ELAPSED` | The time equals the last time; nothing was stepped, and the queued forces are used up. |
| `DEFORMABLE_STEP_OUTCOME_NO_SUBSTEPS` | The substep count was 0; the time advanced without a step. |
| `DEFORMABLE_STEP_OUTCOME_SUBSTEP_TOO_LARGE` | A substep would be longer than 0.04 s; the time advanced without a step. |
| `DEFORMABLE_STEP_OUTCOME_CANCELLED` | The cancel flag stopped the step after `substeps_run` substeps. |

This snippet replaces the step call of the frame loop:

```c
DeformableStepReport report;
CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL, &report));
switch (report.outcome) {
case DEFORMABLE_STEP_OUTCOME_STEPPED:
    break;
case DEFORMABLE_STEP_OUTCOME_FIRST_CALL:
    printf("frame %d: first call, time recorded\n", frame);
    break;
case DEFORMABLE_STEP_OUTCOME_CANCELLED:
    printf("frame %d: cancelled after %u substeps\n", frame, (unsigned)report.substeps_run);
    break;
default:
    printf("frame %d: outcome %d, nothing stepped\n", frame, (int)report.outcome);
    break;
}
```

```text
frame 0: first call, time recorded
```

### Cancel a step

Pass a `DeformableCancelFlag` in place of `NULL`, and set it from another thread. The step stops between two
substeps, after at least one, and returns `DEFORMABLE_STATUS_OK` with the outcome `DEFORMABLE_STEP_OUTCOME_CANCELLED`.
The time advances only by the substeps that ran, so the next step goes on from there.
[Memory and errors](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/memory-and-errors/#cancel-a-long-call) shows a cancel flag in use.

### Pause

`deformable_scene_skip_to` records a time as the last time without stepping, gluing or driving, and it drops
the forces you added. Call it in place of the step while the scene is paused or disabled. Before the first step it
records nothing.

## Read the outputs

These functions lend the state of one object after a step:

| Function | What it lends |
|---|---|
| `deformable_scene_node_positions` | The node positions, in your units. |
| `deformable_scene_node_velocities` | The node velocities, in your units per second. |
| `deformable_scene_node_masses` | The node masses, in simulation units. |
| `deformable_scene_tetrahedron_nodes` | The four current nodes of each tetrahedron. |
| `deformable_scene_tetrahedron_states` | One `DeformableTetrahedronState` per tetrahedron. |
| `deformable_scene_face_events` | The tetrahedrons whose faces a fracture exposed in the last step. |

Each array belongs to the scene and stays valid until the next call of the same function on the same scene; see
[Memory and errors](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/memory-and-errors/#arrays-the-library-lends). Copy what you keep.

Fracture never deletes or reorders tetrahedrons: tetrahedron i of the outputs is tetrahedron i of the mesh you
added. It clones nodes instead, so the node count grows as the object breaks.

![Two tetrahedrons that share a face and 5 nodes break apart along that face; they are still 2 tetrahedrons, now with 8 nodes, and the opened face shows.](../../images/sdk-fracture-splits-nodes.svg "Fracture clones nodes but never deletes or reorders tetrahedrons, so only the node count grows.")

A `DeformableTetrahedronState` holds:

- `corners`: the current corner positions, in your units.
- `island`: the id of the group of tetrahedrons solved together, or 0.
- `strain_measure`: the squared norm of the total strain.
- `flags`: bits 0 to 3 are set for each face that has been exposed so far, face k being the face opposite corner k.
  The bits stay set. `DEFORMABLE_NODE_REPLACED` (0x10) is set while a fracture has moved one of the tetrahedron's
  nodes to a clone.

### Find the faces a crack opened

A `DeformableFaceEvent` names a tetrahedron, and bit k of its `exposed_faces` is set when face k no longer touches
another tetrahedron. Faces on the object's surface at rest count as exposed too. A tetrahedron gets a new event each
time fracture changes it, and `exposed_faces` holds every face exposed so far. To get only the faces a crack just
opened, remove two masks: the rest mask that `deformable_boundary_faces` gives, and the faces already reported. Then
`deformable_tetrahedron_state_face_centroid` and `deformable_tetrahedron_state_face_normal` place each opened face, for
example to emit dust particles as the plugins'
[fracture points](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/fracture-and-splinters/#fracture-points) do.

Before the frame loop, read the rest masks of the cube, and start the reported masks from them:

```c
DeformableBoundaryFaces *boundary = NULL;
CHECK(deformable_boundary_faces(&cube_view.mesh, &boundary));
const uint8_t *rest_masks = NULL;
size_t mask_count = 0;
CHECK(deformable_boundary_faces_masks(boundary, &rest_masks, &mask_count));
uint8_t *reported = malloc(mask_count);
for (size_t tetrahedron = 0; tetrahedron < mask_count; ++tetrahedron) {
    reported[tetrahedron] = rest_masks[tetrahedron];
}
size_t opened_faces = 0;
```

Inside the loop, after the step:

```c
const DeformableTetrahedronState *states = NULL;
size_t state_count = 0;
CHECK(deformable_scene_tetrahedron_states(scene, cube, &states, &state_count));
const DeformableFaceEvent *opened = NULL;
size_t opened_count = 0;
CHECK(deformable_scene_face_events(scene, cube, &opened, &opened_count));
for (size_t index = 0; index < opened_count; ++index) {
    uint32_t tetrahedron = opened[index].tetrahedron;
    uint8_t new_faces = opened[index].exposed_faces & (uint8_t)~reported[tetrahedron];
    reported[tetrahedron] |= opened[index].exposed_faces;
    for (uint32_t face = 0; face < 4; ++face) {
        if (new_faces & (1u << face)) {
            DeformableVector3 centroid, normal;
            CHECK(deformable_tetrahedron_state_face_centroid(&states[tetrahedron], face, &centroid));
            CHECK(deformable_tetrahedron_state_face_normal(&states[tetrahedron], face, &normal));
            ++opened_faces; /* Emit particles at centroid along normal. */
        }
    }
}
```

After the loop, `opened_faces` holds the count. `free(reported)` and `deformable_boundary_faces_destroy(boundary)`
free the masks.

### Measure a scene

Objects at rest on a support go to sleep; see [Sleep](https://help.tangerina.io/deformable/v0.5.0/user-guides/engine/simulation-settings/#sleep).
`deformable_scene_awake_tetrahedron_count` counts the tetrahedrons still awake. `deformable_scene_statistics` gives the
solver, contact and island counters. After the loop:

```c
size_t awake = 0;
DeformableSceneStatistics statistics;
CHECK(deformable_scene_awake_tetrahedron_count(scene, &awake));
CHECK(deformable_scene_statistics(scene, &statistics));
printf("awake: %zu, contacts: %zu, islands: %zu\n", awake, statistics.contacts, statistics.islands);
```

## Next steps

- [Tools](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/tools/): build the tetrahedral meshes you add as objects.
- [Render surfaces](https://help.tangerina.io/deformable/v0.5.0/user-guides/c/render-surfaces/): skin a detailed render mesh on the simulated cube.
- [C API Reference](https://help.tangerina.io/deformable/v0.5.0/api-references/c/scene/): every scene function and struct of `deformable.h`.
