﻿---
title: Scene
description: "The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs."
url: https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/
---

# Scene – C API Reference – Deformable v0.3.1

A [`DeformableScene`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene) holds a set of objects and steps them through time. Its calls come first, then the values they take and return, in the order a host meets them: materials and material regions, objects, glue, driven vertices, steps and the outputs of a step.

## DeformableScene

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableScene DeformableScene;
```

One scene a host drives frame by frame: its materials and objects, the glue, driven vertices and forces between
steps, the frame step and the outputs a host reads back.

[`deformable_scene_create`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_create) creates an empty scene and [`deformable_scene_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_destroy) frees it. Materials and objects
are `uint32_t` handles counting up from 0 in creation order.

Lengths cross in host units (multiplied by the scale on the way in, divided by it on the way out); time, forces,
gravity, masses and material values pass in simulation units. A scene may move between threads, but calls on
one scene must not overlap; [`deformable_scene_step`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_step) runs the scene's own worker threads, and its results do
not depend on their count.

Each array a per-frame output call lends is owned by the scene and stays valid until the next call of the same
function on it or its destruction, so a frame's outputs can be read side by side without a copy.

**Example**

```c
DeformableScene *scene = NULL;
CHECK(deformable_scene_create(&scene));
DeformableVector3 z_up = {0.0, 0.0, -9.81};
CHECK(deformable_scene_set_gravity(scene, z_up));
DeformableStepReport report;
CHECK(deformable_scene_step(scene, 0.0, 10, NULL, &report));
CHECK(deformable_scene_step(scene, 1.0 / 24, 10, NULL, &report));
deformable_scene_destroy(scene);
```

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Rust `Scene`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene) · [Python `Scene`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene)

### deformable_scene_create

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_create(DeformableScene **scene);
```

Creates an empty scene: gravity (0, -9.81, 0), scale 1, and as many worker threads as the machine runs in
parallel, at most 16.

**Parameters**

- `scene` ([`DeformableScene **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): Out. Receives the new scene; free it with [`deformable_scene_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_destroy).

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Rust `Scene::new`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-new)

### deformable_scene_destroy

**Function** · `deformable.h`

```c
void deformable_scene_destroy(DeformableScene *scene);
```

Destroys a scene with everything it holds; `NULL` is ignored. The arrays it lent become invalid, and it must
not be used again.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to destroy, or `NULL`. No other call may be using it.

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Python `Scene.close`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-close)

### deformable_scene_set_scale

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_scale(
    DeformableScene *scene,
    double scale);
```

Sets the factor from the host length unit to the simulation unit, from 0.001 to 1,000.

A new scene has scale 1: a host unit is a simulation unit, which reads as a metre under the default gravity,
and a scene modelled in centimetres sets 0.01. Positions, driven targets and glue plane offsets are multiplied by
the scale on the way in, and positions and velocities divided by it on the way out; time, forces, gravity, node
masses and material values pass unscaled. The scale applies to later calls: stored state is not rescaled.

The scene lives in a world box that reaches 1,000 simulation units from the origin along each axis. An awake island
that leaves it in a step becomes static for good: its nodes stop where they are. Choose the scale so that the scene
stays inside.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to change.
- `scale` (`double`): The length of one host unit in simulation units, from 0.001 to 1,000.

**Errors**

- [`DEFORMABLE_STATUS_SCALE_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_scale_out_of_range): `scale` is below 0.001, above 1,000, or NaN.

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Rust `Scene::set_scale`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_scale) · [Python `Scene.set_scale`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_scale)

### deformable_scene_set_gravity

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_gravity(
    DeformableScene *scene,
    DeformableVector3 gravity);
```

Sets the gravity acceleration, in simulation units: the scale does not apply to it.

A new scene has (0, -9.81, 0): y points up, and a simulation unit reads as a metre. A z-up scene sets
(0, 0, -9.81).

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to change.
- `gravity` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): The acceleration, in simulation units per second squared.

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A component of `gravity` is NaN or infinite.

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Rust `Scene::set_gravity`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_gravity) · [Python `Scene.set_gravity`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_gravity)

### deformable_scene_set_worker_count

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_worker_count(
    DeformableScene *scene,
    size_t count);
```

Sets the number of threads a step uses, the calling thread included; results do not depend on it.

A new scene has as many as the machine runs in parallel, at most 16. Any count from 1 up is accepted, but a
step never runs more threads than the machine runs in parallel.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to change.
- `count` (`size_t`): The thread count, at least 1.

**Errors**

- [`DEFORMABLE_STATUS_INVALID_WORKER_COUNT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_invalid_worker_count): `count` is 0.

**See also** [Guide: Set up the scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#set-up-the-scene) · [Rust `Scene::set_worker_count`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_worker_count) · [Python `Scene.set_worker_count`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_worker_count)

### deformable_scene_add_material

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_add_material(
    DeformableScene *scene,
    const DeformableMaterialParameters *parameters,
    uint32_t *material);
```

Creates a material and writes its handle to `material`; handles count up from 0 in creation order.

Each value is clamped to its range (see [`DeformableMaterialParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)), a toughness of 0 or below makes the material
unbreakable, and the damping coefficient alpha is `youngs_damping / youngs_modulus` of the clamped values, at full
double precision.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that receives the material.
- `parameters` ([`const DeformableMaterialParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)): The material's values, such as the defaults of [`deformable_material_parameters_default`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_parameters_default) or a preset.
- `material` (`uint32_t *`): Out. Receives the new material's handle.

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A value of `parameters` is NaN or infinite.

**See also** [Guide: Add and change a material](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-and-change-a-material) · [Rust `Scene::add_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-add_material) · [Python `Scene.add_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-add_material)

### deformable_scene_set_material

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_material(
    DeformableScene *scene,
    uint32_t material,
    const DeformableMaterialParameters *parameters);
```

Rewrites the values of `material` as [`deformable_scene_add_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_material) makes them.

The objects using the material get their materials again at the next step that advances the time with at least
one substep, before its substeps: their nodes take the new toughness and the masses of a new density, with their
velocities kept (see [`deformable_scene_node_masses`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_node_masses)), their islands rebuild and nothing wakes.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the material.
- `material` (`uint32_t`): The material to rewrite.
- `parameters` ([`const DeformableMaterialParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)): Its new values.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_MATERIAL`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_material): `material` names no material of this scene.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A value of `parameters` is NaN or infinite.

**See also** [Guide: Add and change a material](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-and-change-a-material) · [Rust `Scene::set_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_material) · [Python `Scene.set_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_material)

### deformable_scene_add_object

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_add_object(
    DeformableScene *scene,
    const DeformableTetrahedralMeshView *mesh,
    const DeformableTetrahedronMaterials *materials,
    const DeformableObjectOptions *options,
    uint32_t *object);
```

Creates an object from a tetrahedral mesh and writes its handle to `object`; handles count up from 0 in creation
order.

The mesh is in world space and host units, and its positions are the object's rest shape: one node per vertex, and
one tetrahedron for each of its tetrahedrons, with its material. Every tetrahedron must be positively oriented, as
the tools make them; the check runs in simulation units, after the scale. Nothing is created when a check fails or
the Free license's limit refuses the object; the limit counts the tetrahedrons the scene simulates with this one's,
none when it is created disabled, so a smaller `object` may still fit. The object is glued at the next step that
advances the time with at least one substep.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that receives the object.
- `mesh` ([`const DeformableTetrahedralMeshView *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmeshview)): The object's tetrahedral mesh, in world space and host units.
- `materials` ([`const DeformableTetrahedronMaterials *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronmaterials)): One material for every tetrahedron, or one per tetrahedron in mesh order.
- `options` ([`const DeformableObjectOptions *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformableobjectoptions)): Self-collision, and whether the object starts disabled; usually the defaults of [`deformable_object_options_default`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_object_options_default).
- `object` (`uint32_t *`): Out. Receives the new object's handle.

**Errors**

- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): `materials` gives one material per tetrahedron, and not as many as the mesh has tetrahedrons.
- [`DEFORMABLE_STATUS_EMPTY_MESH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_empty_mesh): The mesh has no tetrahedron.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A tetrahedron uses a node index past the positions.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A position is NaN or infinite, or becomes infinite once multiplied by the scale.
- [`DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_TOO_SMALL`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_degenerate_tetrahedron_too_small): A tetrahedron's orientation determinant is above 1e-15 but at most 1e-9 in simulation units, or NaN: it is positively oriented but too small. The first index of the last error names the first one.
- [`DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_FLAT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_degenerate_tetrahedron_flat): A tetrahedron is flat: its orientation determinant is within 1e-15 of 0. The first index of the last error names the first one.
- [`DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_INVERTED`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_degenerate_tetrahedron_inverted): A tetrahedron is inverted: its corners are ordered right-handed. The first index of the last error names the first one.
- [`DEFORMABLE_STATUS_UNKNOWN_MATERIAL`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_material): A handle of `materials` names no material of this scene.
- [`DEFORMABLE_STATUS_NON_MANIFOLD_FACE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_manifold_face): Three or more tetrahedrons share one face.
- Under the Free license, `TETRAHEDRON_LIMIT_EXCEEDED` when the scene would simulate more than 2,500 tetrahedrons with the object (see the [license statuses](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/memory-and-errors/#license-statuses)).

**See also** [Guide: Add an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-an-object) · [Rust `Scene::add_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-add_object) · [Python `Scene.add_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-add_object)

### deformable_scene_set_object_material

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_object_material(
    DeformableScene *scene,
    uint32_t object,
    const DeformableTetrahedronMaterials *materials);
```

Gives the tetrahedrons of `object` new materials at the next step that advances the time with at least one substep,
before its substeps.

Their nodes then take the new toughness and the masses of the new densities, with their velocities kept (see
[`deformable_scene_node_masses`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_node_masses)), the object's islands rebuild and nothing wakes. A later call before that step
replaces this one.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to change.
- `materials` ([`const DeformableTetrahedronMaterials *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronmaterials)): One material for every tetrahedron, or one per tetrahedron in mesh order.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.
- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): `materials` gives one material per tetrahedron, and not as many as the object has tetrahedrons.
- [`DEFORMABLE_STATUS_UNKNOWN_MATERIAL`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_material): A handle of `materials` names no material of this scene.

**See also** [Guide: Change an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#change-an-object) · [Rust `Scene::set_object_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_object_material) · [Python `Scene.set_object_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_object_material)

### deformable_scene_remove_object

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_remove_object(
    DeformableScene *scene,
    uint32_t object);
```

Deletes `object` at once, with its contacts, glue, driven vertices, queued forces and pending material change.

Its handle becomes unknown to every call and is never given to another object, so the other objects keep theirs.
Its tetrahedrons stop counting toward the Free license's limit.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to delete.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or one already removed.

**See also** [Guide: Change an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#change-an-object) · [Rust `Scene::remove_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-remove_object) · [Python `Scene.remove_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-remove_object)

### deformable_scene_set_object_disabled

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_object_disabled(
    DeformableScene *scene,
    uint32_t object,
    uint8_t disabled);
```

Disables `object` or enables it again.

Disabling frees the object's contacts and glue at once, and takes it out of its islands at the next step that runs a
substep; its nodes keep their state, it keeps its outputs, and forces on it are ignored while it is disabled. Its
driving waits too: its driven vertices hold still, and the [`deformable_scene_drive`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_drive) calls made for it take effect
at the first step after it is enabled, where a vertex they release leaves with its last driven velocity. Enabling it
again returns its nodes with their stored state, but not its glue: an object that is disabled when the next step
glues new objects gets no glue either. Setting the state the object already has does nothing. A disabled object
does not count toward the Free license's limit; enabled again, it takes part from the next step if it fits under
the limit, and is held back as a disabled object is while it does not.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to disable or enable.
- `disabled` (`uint8_t`): Not 0 disables the object, 0 enables it.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**See also** [Guide: Change an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#change-an-object) · [Rust `Scene::set_object_disabled`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_object_disabled) · [Python `Scene.set_object_disabled`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_object_disabled)

### deformable_scene_set_self_collision

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_self_collision(
    DeformableScene *scene,
    uint32_t object,
    uint8_t enabled);
```

Sets or clears the self-collision of `object`: whether its colliders test its own faces against each other.

Each island of the object takes the change when it is next rebuilt. The `self_collision` field of
[`DeformableObjectOptions`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformableobjectoptions) gives the setting an object starts with.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to change.
- `enabled` (`uint8_t`): Not 0 turns self-collision on, 0 off.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**See also** [Guide: Change an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#change-an-object) · [Rust `Scene::set_self_collision`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_self_collision) · [Python `Scene.set_self_collision`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_self_collision)

### deformable_scene_set_never_sleep

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_never_sleep(
    DeformableScene *scene,
    uint32_t object,
    uint32_t node,
    uint8_t enabled);
```

Sets or clears the never-sleep flag of node `node` of `object`: an island that holds a tetrahedron of a never-sleep
node never sleeps.

Setting the flag on a frozen node wakes the node: its island and the islands around it rebuild at the next step. On
an awake node the flag takes effect when its island is next rebuilt, and clearing it does nothing else.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object that holds the node.
- `node` (`uint32_t`): The node, an index into the object's nodes.
- `enabled` (`uint8_t`): Not 0 sets the flag, 0 clears it.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `node` is past the object's nodes.

**See also** [Guide: Change an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#change-an-object) · [Rust `Scene::set_never_sleep`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_never_sleep) · [Python `Scene.set_never_sleep`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_never_sleep)

### deformable_scene_set_glue_all

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_set_glue_all(
    DeformableScene *scene,
    const DeformableGlueParameters *parameters);
```

Turns glue all on with `parameters`, or off with `NULL`, the setting of a new scene.

With glue all on, each new object is glued to every other enabled object where their tetrahedrons overlap. The glue
is made by the next step that advances the time with at least one substep, from the positions the objects have then;
the new objects are those added since the last such step. Objects that only touch are not glued, and glue made before
stays when glue all is turned off. A spring constant of 0 means 4,905, and a damping coefficient of 0 means 2,452.5.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to change.
- `parameters` ([`const DeformableGlueParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformableglueparameters)): The spring and damping of the glue, or `NULL` to turn glue all off.

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A value of `parameters` is NaN or infinite.

**See also** [Guide: Glue objects together](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#glue-objects-together) · [Rust `Scene::set_glue_all`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-set_glue_all) · [Python `Scene.set_glue_all`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-set_glue_all)

### deformable_scene_add_glue_region

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_add_glue_region(
    DeformableScene *scene,
    const DeformableConvexRegion *region,
    const uint32_t *members,
    size_t member_count,
    const DeformableGlueParameters *parameters);
```

Adds a glue region: each new member is glued to every other enabled member through their tetrahedrons with a
vertex inside `region`.

The glue is made by the next step that advances the time with at least one substep, from the positions the objects
have then; the new members are those added since the last such step, and the region stays for every later such step.
The planes are in host units: their offsets are multiplied by the scale when the region is added, their normals are
not. A region with no plane holds every point. A spring constant of 0 means 4,905, and a damping coefficient of 0
means 2,452.5.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to change.
- `region` ([`const DeformableConvexRegion *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformableconvexregion)): The convex region, in world space and host units.
- `members` (`const uint32_t *`): The handles of the objects the region glues to each other.
- `member_count` (`size_t`): The number of handles in `members`.
- `parameters` ([`const DeformableGlueParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformableglueparameters)): The spring and damping of the glue.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): A handle of `members` names no object of this scene, or a removed one.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A plane, or a value of `parameters`, is NaN or infinite.

**See also** [Guide: Glue objects together](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#glue-objects-together) · [Rust `Scene::add_glue_region`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-add_glue_region) · [Python `Scene.add_glue_region`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-add_glue_region)

### deformable_scene_drive

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_drive(
    DeformableScene *scene,
    uint32_t object,
    const DeformableDrivenVertex *vertices,
    size_t vertex_count);
```

Drives the listed vertices of `object` to their targets from the next step on, in place of the vertices it drove
before.

Each listed vertex moves in equal substeps to reach its target, to within rounding, at the end of the next step,
whatever the forces on it, then holds the target until a later call for the object. Vertices driven before but not
listed are released with their last driven velocity, so a host can throw them; an empty list releases them all. A
vertex released by a step that ends with [`DEFORMABLE_STEP_OUTCOME_SUBSTEP_TOO_LARGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_substep_too_large) gets that velocity too, and the
next step that runs a substep starts from it. On a disabled object the call waits until the object is enabled, and
takes effect at the first step after that (see [`deformable_scene_set_object_disabled`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_object_disabled)). A call that fails changes
nothing.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object whose vertices to drive.
- `vertices` ([`const DeformableDrivenVertex *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabledrivenvertex)): Each vertex to drive, with its target in host units. May be `NULL` when `vertex_count` is 0.
- `vertex_count` (`size_t`): The number of `vertices`; 0 releases every driven vertex of the object.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A vertex is past the object's nodes.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A target is NaN or infinite.

**Example**

```c
DeformableStepReport report;
for (int frame = 0; frame <= 24; frame++) {
    DeformableDrivenVertex lifted = {0, mesh.positions[0]};
    lifted.target.y += 0.01 * frame;
    CHECK(deformable_scene_drive(scene, object, &lifted, 1));
    CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL,
                                &report));
}
```

**See also** [Guide: Drive vertices](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#drive-vertices) · [Rust `Scene::drive`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-drive) · [Python `Scene.drive`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-drive)

### deformable_scene_add_force

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_add_force(
    DeformableScene *scene,
    uint32_t object,
    uint32_t node,
    DeformableVector3 force);
```

Queues `force` on node `node` of `object` for the substeps of the next step call; calls on one node add up.

The next step call that returns a report uses up the queue, whether it runs substeps or not, and
[`deformable_scene_skip_to`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_skip_to) drops it, so a lasting force is queued again before each step. When a substep applies
it, a force on a frozen node wakes the node's connected piece, or for an object with glue the nodes within the
material's `wake_up_radius` of it, even a zero force; on a node that is not solved, such as a driven one, the force is
kept and acts at once on the node's first solve. Forces on a disabled object are ignored.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object that holds the node.
- `node` (`uint32_t`): The node, an index into the object's nodes.
- `force` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): The force, in simulation units: the scale does not apply to it.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `node` is past the object's nodes.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A component of `force` is NaN or infinite.

**Example**

```c
// A push along x on every node, for the next step.
DeformableVector3 push = {5.0, 0.0, 0.0};
for (uint32_t node = 0; node < mesh.position_count; node++) {
    CHECK(deformable_scene_add_force(scene, object, node,
                                     push));
}
```

**See also** [Guide: Add forces](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-forces) · [Rust `Scene::add_force`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-add_force) · [Python `Scene.add_force`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-add_force)

### deformable_scene_step

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_step(
    DeformableScene *scene,
    double time,
    uint32_t substeps,
    const DeformableCancelFlag *cancel,
    DeformableStepReport *report);
```

Advances the scene to `time`, in seconds, in `substeps` equally long substeps, and writes what it did to `report`.

A host calls it once per frame with the frame's time. The first call only records the time, so make it at the start
frame. A later call runs its substeps when time has passed, `substeps` is not 0 and a substep is at most 0.04 s;
otherwise the outcome says which of these stopped it. A `cancel` flag set from another thread stops the step between
two substeps, after at least one, with the outcome [`DEFORMABLE_STEP_OUTCOME_CANCELLED`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_cancelled): the time then stands at the
last substep run, so the next call goes on from there.

Every call that succeeds uses up the forces [`deformable_scene_add_force`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_force) queued. The license is checked at every
call: under the Free license the step simulates the objects that fit under its 2,500 tetrahedrons, in the order they
were added, and holds the rest back as disabled objects are until the scene runs under a license again, which glues
them again where they stand.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to step.
- `time` (`double`): The frame's time, in seconds. It may not be before the last time a step or [`deformable_scene_skip_to`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_skip_to) recorded.
- `substeps` (`uint32_t`): How many substeps to run, all of one length; at 24 frames per second, 10 is a good start.
- `cancel` ([`const DeformableCancelFlag *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablecancelflag)): Stops the step between two substeps when another thread sets it. May be `NULL`.
- `report` ([`DeformableStepReport *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepreport)): Out. Receives how many substeps ran, and what the call did: whether they ran, and if not, why.

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): `time` is NaN or infinite.
- [`DEFORMABLE_STATUS_TIME_WENT_BACKWARDS`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_time_went_backwards): `time` is before the last time recorded. To go back, destroy the scene and create a new one.

**Example**

```c
DeformableStepReport report;
for (int frame = 0; frame < 3; frame++) {
    CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL,
                                &report));
    unsigned substeps = report.substeps_run;
    printf("%d %u\n", (int)report.outcome, substeps);
}
// 1 0 (the first call), then 0 10 (stepped) twice.
```

**See also** [Guide: Step](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#step) · [Rust `Scene::step`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-step) · [Python `Scene.step`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-step)

### deformable_scene_skip_to

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_skip_to(
    DeformableScene *scene,
    double time);
```

Records `time` as the last time without creating glue, applying driven vertices or stepping, and drops the forces
[`deformable_scene_add_force`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_force) queued.

A host calls it in place of [`deformable_scene_step`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_step) while its scene is paused or disabled: the next step goes on
from `time` as if no time had passed. Before the first step it records nothing, so the next step is still a first
call.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene whose time to record.
- `time` (`double`): The time to record, in seconds. It may not be before the last time recorded.

**Errors**

- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): `time` is NaN or infinite.
- [`DEFORMABLE_STATUS_TIME_WENT_BACKWARDS`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_time_went_backwards): `time` is before the last time recorded.

**See also** [Guide: Pause](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#pause) · [Rust `Scene::skip_to`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-skip_to) · [Python `Scene.skip_to`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-skip_to)

### deformable_scene_node_positions

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_node_positions(
    DeformableScene *scene,
    uint32_t object,
    const DeformableVector3 **positions,
    size_t *count);
```

Lends the current node positions of `object`, in host units.

The first nodes are the vertices of the mesh the object was made from, in order. Fracture clones nodes and adds
them after, so the node count grows as the object breaks. The array is owned by the scene and stays valid
until the next call of this function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `positions` ([`const DeformableVector3 **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): Out. Receives a pointer to `count` positions, one per node.
- `count` (`size_t *`): Out. Receives the number of nodes.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**Example**

```c
const DeformableVector3 *positions;
size_t count;
CHECK(deformable_scene_node_positions(scene, object,
                                      &positions, &count));
// Before any fracture, one node per mesh vertex.
printf("%zu nodes, %zu vertices\n", count, mesh.position_count);
```

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `Scene::node_positions`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-node_positions) · [Python `Scene.node_positions`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-node_positions)

### deformable_scene_node_velocities

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_node_velocities(
    DeformableScene *scene,
    uint32_t object,
    const DeformableVector3 **velocities,
    size_t *count);
```

Lends the current node velocities of `object`, in host units per second (divided by the scale), in the order of
[`deformable_scene_node_positions`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_node_positions). The array is owned by the scene and stays valid until the next call of
this function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `velocities` ([`const DeformableVector3 **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): Out. Receives a pointer to `count` velocities, one per node.
- `count` (`size_t *`): Out. Receives the number of nodes.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `Scene::node_velocities`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-node_velocities) · [Python `Scene.node_velocities`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-node_velocities)

### deformable_scene_node_masses

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_node_masses(
    DeformableScene *scene,
    uint32_t object,
    const double **masses,
    size_t *count);
```

Lends the lumped node masses of `object`, in simulation units, in the order of [`deformable_scene_node_positions`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_node_positions).

Each node, driven or not, takes a quarter of the mass (density times volume) of every tetrahedron it belongs to.
A density that [`deformable_scene_set_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_material) or [`deformable_scene_set_object_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_object_material) changes reaches the
masses at the next step that advances the time with at least one substep: each of its tetrahedrons gives its nodes
the quarter of the new mass in place of the old one, and the velocities stay as they were, so the momentum changes
with the mass. Fracture moves a tetrahedron's quarter to the clone that takes it. The array is owned by the
scene and stays valid until the next call of this function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `masses` (`const double **`): Out. Receives a pointer to `count` masses, one per node.
- `count` (`size_t *`): Out. Receives the number of nodes.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `Scene::node_masses`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-node_masses) · [Python `Scene.node_masses`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-node_masses)

### deformable_scene_tetrahedron_nodes

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_tetrahedron_nodes(
    DeformableScene *scene,
    uint32_t object,
    const uint32_t (**tetrahedrons)[4],
    size_t *count);
```

Lends the current four nodes of each tetrahedron of `object`, as indices into its nodes (the order of
[`deformable_scene_node_positions`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_node_positions)), in mesh order.

Fracture never deletes or reorders tetrahedrons: tetrahedron i stays tetrahedron i of the mesh. It moves
tetrahedrons onto cloned nodes instead, which these indices follow. The array is owned by the scene and stays
valid until the next call of this function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `tetrahedrons` (`const uint32_t (**)[4]`): Out. Receives a pointer to `count` groups of four node indices, one per tetrahedron.
- `count` (`size_t *`): Out. Receives the tetrahedron count.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**Example**

```c
const uint32_t (*tetrahedrons)[4];
size_t count;
CHECK(deformable_scene_tetrahedron_nodes(scene, object,
                                         &tetrahedrons, &count));
// Before any fracture, the nodes are those of the mesh.
printf("%zu tetrahedrons, %zu in the mesh\n", count,
       mesh.tetrahedron_count);
```

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `Scene::tetrahedron_nodes`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-tetrahedron_nodes) · [Python `Scene.tetrahedron_nodes`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-tetrahedron_nodes)

### deformable_scene_tetrahedron_states

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_tetrahedron_states(
    DeformableScene *scene,
    uint32_t object,
    const DeformableTetrahedronState **states,
    size_t *count);
```

Lends the output record of each tetrahedron of `object`, in mesh order: its corners in host units, its island id or
0, its strain measure and its flags. The array is owned by the scene and stays valid until the next call of this
function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `states` ([`const DeformableTetrahedronState **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronstate)): Out. Receives a pointer to `count` records, one per tetrahedron.
- `count` (`size_t *`): Out. Receives the number of tetrahedrons.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**Example**

```c
const DeformableTetrahedronState *states;
size_t count, index, broken = 0;
CHECK(deformable_scene_tetrahedron_states(scene, object,
                                          &states, &count));
for (index = 0; index < count; index++) {
    if (states[index].flags & DEFORMABLE_NODE_REPLACED) broken++;
}
printf("%zu tetrahedrons sit on a cloned node\n", broken);
```

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `Scene::tetrahedron_states`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-tetrahedron_states) · [Python `Scene.tetrahedron_states`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-tetrahedron_states)

### deformable_scene_face_events

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_face_events(
    DeformableScene *scene,
    uint32_t object,
    const DeformableFaceEvent **events,
    size_t *count);
```

Lends the exposed-face events of `object` from the last step: one for each tetrahedron that fracture changed in it.

Every step that succeeds replaces them, so a step without fracture leaves none. The array is owned by the scene
and stays valid until the next call of this function on it or its destruction.

**Parameters**

- `scene` ([`DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene that holds the object.
- `object` (`uint32_t`): The object to read.
- `events` ([`const DeformableFaceEvent **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablefaceevent)): Out. Receives a pointer to `count` events.
- `count` (`size_t *`): Out. Receives the event count.

**Errors**

- [`DEFORMABLE_STATUS_UNKNOWN_OBJECT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_object): `object` names no object of this scene, or a removed one.

**Example**

```c
const DeformableFaceEvent *events;
size_t count, index;
CHECK(deformable_scene_face_events(scene, object, &events,
                                   &count));
for (index = 0; index < count; index++) {
    printf("tetrahedron %zu\n", (size_t)events[index].tetrahedron);
}
```

**See also** [Guide: Find the faces a crack opened](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#find-the-faces-a-crack-opened) · [Rust `Scene::face_events`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-face_events) · [Python `Scene.face_events`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-face_events)

### deformable_scene_awake_tetrahedron_count

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_awake_tetrahedron_count(
    const DeformableScene *scene,
    size_t *count);
```

Writes the number of tetrahedrons in awake islands, over the whole scene, counted at each call, to `count`.

Sleeping tetrahedrons do not count, nor do static ones: those whose four nodes are all driven, and those of an
island that left the world box (see [`deformable_scene_set_scale`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_scale)). Nor do those of islands waiting to be rebuilt
at the next step that runs a substep, as after a material change, a disable or a fracture. A tetrahedron counts once
a step has put it in an island, so a new object counts from the next step that runs substeps.

**Parameters**

- `scene` ([`const DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene whose tetrahedrons are counted.
- `count` (`size_t *`): Out. Receives the number of awake tetrahedrons.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

**See also** [Guide: Measure a scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#measure-a-scene) · [Rust `Scene::awake_tetrahedron_count`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-awake_tetrahedron_count) · [Python `Scene.awake_tetrahedron_count`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-awake_tetrahedron_count)

### deformable_scene_statistics

**Function** · `deformable.h`

```c
DeformableStatus deformable_scene_statistics(
    const DeformableScene *scene,
    DeformableSceneStatistics *statistics);
```

Writes the solver, contact and island counters of the scene, for measuring it, to `statistics`: the solves since the
scene was created, and the live contacts and the islands it holds now.

**Parameters**

- `scene` ([`const DeformableScene *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescene)): The scene to measure.
- `statistics` ([`DeformableSceneStatistics *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablescenestatistics)): Out. Receives the counters.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

**See also** [Guide: Measure a scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#measure-a-scene) · [Rust `Scene::statistics`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scene-statistics) · [Python `Scene.statistics`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scene-statistics)

## DeformableMaterialParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableMaterialParameters {
    double youngs_modulus;
    double poissons_ratio;
    double density;
    double toughness;
    double youngs_damping;
    double yield_strain;
    double maximum_yield;
    double creep_fraction;
    double wake_up_radius;
    double friction;
} DeformableMaterialParameters;
```

The values of a material, as a host gives them to [`deformable_scene_add_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_material) and
[`deformable_scene_set_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_material), which clamp each one to its range and refuse a NaN or infinite one.

[`deformable_material_parameters_default`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_parameters_default) writes the defaults below, and [`deformable_material_preset_find`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_preset_find) the values
of a named material such as `"steel"`.

**Fields**

- `youngs_modulus` (`double`): Young's modulus, in pascals in simulation units: the higher, the stiffer.
  Default `8e5`, clamped to `[1e3, 1e10]`.
- `poissons_ratio` (`double`): Poisson's ratio, unitless: how much the material bulges sideways when it is squeezed.
  Default `0`, clamped to `[-0.90001, 0.490001]`.
- `density` (`double`): Mass per unit volume, in simulation units: a tetrahedron weighs its density times its volume.
  Default `2500`, clamped to `[0, 1e4]`.
- `toughness` (`double`): The fracture threshold: a node can split once half the largest eigenvalue of its separation tensor exceeds
  the lowest toughness among its tetrahedrons. 0 or less makes the material unbreakable.
  Default `2e5`, clamped to `[0, 1e8]`.
- `youngs_damping` (`double`): Stiffness-proportional damping; the engine's damping coefficient is `youngs_damping / youngs_modulus`.
  Default `0`, clamped to `[0, 1e9]`.
- `yield_strain` (`double`): The elastic strain norm above which plastic flow starts.
  Default `0`, clamped to `[0, 1]`.
- `maximum_yield` (`double`): The bound on the plastic strain norm; 0 resets the plastic strain every solve.
  Default `0`, clamped to `[0, 1]`.
- `creep_fraction` (`double`): The share of the elastic strain added to the plastic strain once per solve, not per second, while the elastic
  strain norm exceeds `yield_strain`; 0 turns plasticity off.
  Default `0`, clamped to `[0, 1]`.
- `wake_up_radius` (`double`): How far, in simulation units, an impact on this material wakes the sleeping nodes of an object that has glue;
  an object without glue wakes its whole connected piece instead.
  Default `1.2`, clamped to `[1, 1000]`.
- `friction` (`double`): The Coulomb friction coefficient; a contact uses the lower of its two materials' coefficients.
  Default `0.6`, clamped to `[0, 1]`.

**Example**

```c
DeformableMaterialParameters rubber;
CHECK(deformable_material_parameters_default(&rubber));
rubber.youngs_modulus = 1e6;
rubber.poissons_ratio = 0.45;
uint32_t handle;
CHECK(deformable_scene_add_material(scene, &rubber, &handle));
```

**See also** [Guide: Materials](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#materials) · [Rust `MaterialParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#materialparameters) · [Python `MaterialParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialparameters)

### deformable_material_parameters_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_material_parameters_default(
    DeformableMaterialParameters *parameters);
```

Writes the values a new material starts from, the defaults [`DeformableMaterialParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters) lists, to `parameters`.

**Parameters**

- `parameters` ([`DeformableMaterialParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

**See also** [Guide: Material values](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#material-values) · [Python `MaterialParameters.default`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialparameters-default)

### deformable_material_preset_count

**Function** · `deformable.h`

```c
size_t deformable_material_preset_count(void);
```

The number of material presets the library ships: [`deformable_material_preset`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_preset) reads each one by its index, in the
library's order, by family from the softest solids to the metals.

Density is in kilograms per cubic metre, with one simulation unit a metre. The values are chosen for each material
and checked on a cube about one unit across, dropped onto a floor, and on a cantilever: whether the preset shatters,
breaks from a fall or survives both, whether it bounces or keeps a dent, and how far it sags. An `unbreakable_`
preset is its namesake with toughness 0, and a few other presets are unbreakable too. Every value lies inside its
clamp range, and every preset keeps the default `wake_up_radius`.

The names of the presets, by family:

- Soft solids: `sponge`, `foam`, `snow`, `jelly`, `rubber`, `unbreakable_rubber`, `hard_rubber`.
- Living and wooden: `flesh`, `bone`, `plant`, `straw`, `cork`, `tree`, `wood`, `plywood`, `cardboard`.
- Building materials and stone: `drywall`, `plaster`, `asphalt`, `clay`, `brick`, `concrete`, `reinforced_concrete`, `sandstone`, `stone`, `granite`.
- Glass and ceramics: `glass`, `safety_glass`, `ceramic`, `diamond`.
- Plastics and carbon: `plastic`, `rigid_foam`, `carbon_fiber`, `graphite`.
- Metals: `wire`, `stiff_wire`, `steel`, `sheet_metal`, `foil`, `rebar`, `unbreakable_rebar`, `lead`, `iron`.

**See also** [Guide: Use a preset](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#use-a-preset) · [Rust `MaterialParameters::presets`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#materialparameters-presets) · [Python `MaterialParameters.presets`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialparameters-presets)

### deformable_material_preset

**Function** · `deformable.h`

```c
DeformableStatus deformable_material_preset(
    size_t index,
    const char **name,
    DeformableMaterialParameters *parameters);
```

Writes the name and values of material preset `index`, in the library's order, to `name` and `parameters`.

**Parameters**

- `index` (`size_t`): The preset's index, counted from 0 and below the count [`deformable_material_preset_count`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_preset_count) gives.
- `name` (`const char **`): Out. Receives the preset's name, in lowercase with underscores between words, such as `"unbreakable_rubber"`: a static NUL-terminated string the host never frees.
- `parameters` ([`DeformableMaterialParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)): Out. Receives the preset's values.

**Errors**

- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `index` is the count `deformable_material_preset_count` gives, or more.

**Example**

```c
size_t count = deformable_material_preset_count();
for (size_t index = 0; index < count; index++) {
    const char *name;
    DeformableMaterialParameters parameters;
    CHECK(deformable_material_preset(index, &name, &parameters));
    puts(name);
}
```

**See also** [Guide: Use a preset](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#use-a-preset) · [Rust `MaterialParameters::presets`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#materialparameters-presets) · [Python `MaterialParameters.presets`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialparameters-presets)

### deformable_material_preset_find

**Function** · `deformable.h`

```c
DeformableStatus deformable_material_preset_find(
    const char *name,
    DeformableMaterialParameters *parameters);
```

Looks a material preset up by its name and writes its values to `parameters`.

The `name` must match a preset's exactly, case included: `"steel"` is a preset, `"Steel"` is not.

**Parameters**

- `name` (`const char *`): The preset's name, a NUL-terminated string such as `"concrete"` or `"unbreakable_rubber"`.
- `parameters` ([`DeformableMaterialParameters *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialparameters)): Out. Receives the preset's values.

**Errors**

- [`DEFORMABLE_STATUS_INVALID_ARGUMENT`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_invalid_argument): No preset has this name.

**Example**

```c
DeformableMaterialParameters steel;
CHECK(deformable_material_preset_find("steel", &steel));
uint32_t handle;
CHECK(deformable_scene_add_material(scene, &steel, &handle));
```

**See also** [Guide: Use a preset](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#use-a-preset) · [Rust `MaterialParameters::preset`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#materialparameters-preset) · [Python `MaterialParameters.preset`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialparameters-preset)

## DeformableMaterialRegion

**Struct** · `deformable.h`

```c
typedef struct DeformableMaterialRegion {
    DeformablePolygonMeshView mesh;
    DeformableAffineTransform to_mesh_space;
} DeformableMaterialRegion;
```

A material region: a polygon mesh in its own object space, and its map into the object space of a tetrahedral
mesh, for [`deformable_material_region_indices`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices).

A region with no polygons holds every tetrahedron.

**Fields**

- `mesh` ([`DeformablePolygonMeshView`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmeshview)): The region's mesh, normally a closed convex polyhedron with outward faces, such as a unit cube: the region is
  what lies behind all of its face planes. Borrowed for the call only.
- `to_mesh_space` ([`DeformableAffineTransform`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformableaffinetransform)): Maps the region's points into the tetrahedral mesh's object space: the region's world matrix times the inverse
  of the object's.

**Example**

```c
// The unit cube moved 0.5 along x: it holds the right half of mesh.
DeformableMaterialRegion region = {0};
region.mesh = polygons;
region.to_mesh_space = (DeformableAffineTransform){
    {{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0.5, 0, 0}};
DeformableMaterialRegionIndices *indices = NULL;
CHECK(deformable_material_region_indices(&mesh, &region, 1, &indices));
deformable_material_region_indices_destroy(indices);
```

**See also** [Guide: Give part of an object another material](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#give-part-of-an-object-another-material) · [Rust `MaterialRegion`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#materialregion) · [Python `MaterialRegion`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#materialregion)

## DeformableMaterialRegionIndices

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableMaterialRegionIndices
    DeformableMaterialRegionIndices;
```

The material-region indices [`deformable_material_region_indices`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices) makes, one per tetrahedron: read them with
[`deformable_material_region_indices_values`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices_values) and free them with [`deformable_material_region_indices_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices_destroy).

**See also** [Guide: Give part of an object another material](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#give-part-of-an-object-another-material)

### deformable_material_region_indices_values

**Function** · `deformable.h`

```c
DeformableStatus deformable_material_region_indices_values(
    const DeformableMaterialRegionIndices *indices,
    const uint32_t **values,
    size_t *count);
```

Lends the indices of `indices`: one per tetrahedron of the mesh, in mesh order, valid until `indices` is destroyed.

**Parameters**

- `indices` ([`const DeformableMaterialRegionIndices *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialregionindices)): The indices [`deformable_material_region_indices`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices) made.
- `values` (`const uint32_t **`): Out. Receives a pointer to the first index, owned by `indices`.
- `count` (`size_t *`): Out. Receives how many indices it lends: the mesh's tetrahedron count.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

### deformable_material_region_indices_destroy

**Function** · `deformable.h`

```c
void deformable_material_region_indices_destroy(
    DeformableMaterialRegionIndices *indices);
```

Destroys material-region indices; `NULL` is ignored. The values they lent become invalid.

**Parameters**

- `indices` ([`DeformableMaterialRegionIndices *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialregionindices)): The indices to destroy, or `NULL`.

## deformable_material_region_indices

**Function** · `deformable.h`

```c
DeformableStatus deformable_material_region_indices(
    const DeformableTetrahedralMeshView *mesh,
    const DeformableMaterialRegion *regions,
    size_t region_count,
    DeformableMaterialRegionIndices **indices);
```

Finds which material region holds each tetrahedron of `mesh`: 0 when none does, or 1 plus the index in `regions` of the
region that does.

A region holds a tetrahedron when the tetrahedron's centroid lies behind or on every face plane of the region's
mesh, mapped by `to_mesh_space`. Where regions overlap, the one whose mesh has the smallest signed volume before the
map wins, whatever their order in `regions`; regions of equal volume may be tried in another order than theirs. A
region with no polygons holds every tetrahedron. Each face plane is taken from the mapped polygon, so any
invertible map, a non-uniform scale or a zero diagonal included, keeps the region exactly where the map puts it.

The host turns the indices into the [`DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialassignment-deformable_material_assignment_per_tetrahedron) materials of
[`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_object) or [`deformable_scene_set_object_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_object_material): 0 is the object's material, and each
other index the material of the region one below it in `regions`.

**Parameters**

- `mesh` ([`const DeformableTetrahedralMeshView *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmeshview)): The tetrahedral mesh, in the object space the regions map into.
- `regions` ([`const DeformableMaterialRegion *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialregion)): The regions, each a polygon mesh and its map into the object space of `mesh`.
- `region_count` (`size_t`): The number of `regions`.
- `indices` ([`DeformableMaterialRegionIndices **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialregionindices)): Out. Receives a new handle; free it with [`deformable_material_region_indices_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `indices`: read the indices, one per tetrahedron in mesh order, with [`deformable_material_region_indices_values`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_material_region_indices_values).

**Errors**

- [`DEFORMABLE_STATUS_EMPTY_MESH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_empty_mesh): `mesh` has no tetrahedron.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A tetrahedron of `mesh`, or a polygon of a region, uses a vertex past the end of its positions.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A position of `mesh` or of a region's mesh, or a value of a region's map, is NaN or infinite.
- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): The polygon sizes of a region's mesh do not add up to its `corner_count`.
- [`DEFORMABLE_STATUS_DEGENERATE_REGION`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_degenerate_region): A polygon of a region has fewer than 3 corners, or a zero normal once mapped; the last error's first index names the region, its second the polygon.

**Example**

```c
// The unit cube with x halved: it holds the left half of mesh.
DeformableMaterialRegion region = {0};
region.mesh = polygons;
region.to_mesh_space = (DeformableAffineTransform){
    {{{0.5, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0, 0, 0}};
DeformableMaterialRegionIndices *indices = NULL;
CHECK(deformable_material_region_indices(&mesh, &region, 1, &indices));
deformable_material_region_indices_destroy(indices);
```

**See also** [Guide: Give part of an object another material](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#give-part-of-an-object-another-material) · [Rust `material_region_indices`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#material_region_indices) · [Python `material_region_indices`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#material_region_indices)

## DeformableTetrahedronMaterials

**Struct** · `deformable.h`

```c
typedef struct DeformableTetrahedronMaterials {
    DeformableMaterialAssignment assignment;
    uint32_t material;
    const uint32_t *materials;
    size_t material_count;
} DeformableTetrahedronMaterials;
```

The materials of an object's tetrahedrons, for [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_object) and
[`deformable_scene_set_object_material`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_object_material): one material for all of them, or one per tetrahedron.

A list of another count than the mesh's tetrahedron count gives [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch), and a handle
that names no material of the scene gives [`DEFORMABLE_STATUS_UNKNOWN_MATERIAL`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_unknown_material).

**Fields**

- `assignment` ([`DeformableMaterialAssignment`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialassignment)): Which of the two forms applies: [`DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialassignment-deformable_material_assignment_uniform) or
  [`DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablematerialassignment-deformable_material_assignment_per_tetrahedron).
- `material` (`uint32_t`): The material of every tetrahedron, with `DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM`.
- `materials` (`const uint32_t *`): One material per tetrahedron, in mesh order, with `DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON`; borrowed
  for the call only.
- `material_count` (`size_t`): The number of entries of `materials`, which must be the mesh's tetrahedron count.

**Example**

```c
DeformableTetrahedronMaterials uniform = {0};
uniform.assignment = DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM;
uniform.material = material;
CHECK(deformable_scene_set_object_material(scene, object,
                                           &uniform));
```

**See also** [Guide: Add an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-an-object) · [Rust `TetrahedronMaterials`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#tetrahedronmaterials)

## DeformableMaterialAssignment

**Enum** · `deformable.h`

```c
typedef int32_t DeformableMaterialAssignment;
```

How [`DeformableTetrahedronMaterials`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronmaterials) gives the tetrahedrons their materials.

**Values**

- `DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM` (`0`): The struct's `material` for every tetrahedron; `materials` is not read.
- `DEFORMABLE_MATERIAL_ASSIGNMENT_PER_TETRAHEDRON` (`1`): `materials[i]` for tetrahedron i, in mesh order: the form material regions take; `material` is not read.

**See also** [Guide: Add an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-an-object)

## DeformableObjectOptions

**Struct** · `deformable.h`

```c
typedef struct DeformableObjectOptions {
    uint8_t self_collision;
    uint8_t disabled;
} DeformableObjectOptions;
```

The per-object settings a host gives when it creates an object with [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_object); booleans are
0 or not 0.

[`deformable_object_options_default`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_object_options_default) writes the defaults: self-collision on and the object enabled.
[`deformable_scene_set_self_collision`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_self_collision) and [`deformable_scene_set_object_disabled`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_object_disabled) change them later.

**Fields**

- `self_collision` (`uint8_t`): The object's colliders test its own faces against each other. Default `1`.
- `disabled` (`uint8_t`): The object is created disabled: it takes no part in the scene until `deformable_scene_set_object_disabled`
  enables it, and it gets no glue if it is still disabled when the next step glues new objects. Default `0`.

**Example**

```c
DeformableObjectOptions options;
CHECK(deformable_object_options_default(&options));
options.self_collision = 0;
DeformableTetrahedronMaterials uniform = {0};
uniform.material = material;
uint32_t cube;
CHECK(deformable_scene_add_object(scene, &mesh, &uniform,
                                  &options, &cube));
```

**See also** [Guide: Add an object](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#add-an-object) · [Rust `ObjectOptions`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#objectoptions) · [Python `ObjectOptions`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#objectoptions)

### deformable_object_options_default

**Function** · `deformable.h`

```c
DeformableStatus deformable_object_options_default(
    DeformableObjectOptions *options);
```

Writes the object defaults to `options`: self-collision on (`self_collision` 1) and the object enabled (`disabled` 0).

**Parameters**

- `options` ([`DeformableObjectOptions *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformableobjectoptions)): Out. Receives the defaults.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#conventions) describe.

**See also** [Python `ObjectOptions.default`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#objectoptions-default)

## DeformableGlueParameters

**Struct** · `deformable.h`

```c
typedef struct DeformableGlueParameters {
    double spring_constant;
    double damping_coefficient;
} DeformableGlueParameters;
```

The spring and damping of glue, for [`deformable_scene_set_glue_all`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_set_glue_all) and [`deformable_scene_add_glue_region`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_add_glue_region).

Glue holds two overlapping tetrahedrons at the overlap volume they had when it was made, as a spring with a damper;
the library scales the spring by the mass of the lighter of the two glued islands. A spring constant of 0 means
4,905, and a damping coefficient of 0 means 2,452.5.

**Fields**

- `spring_constant` (`double`): The spring constant; 0 means 4,905.
- `damping_coefficient` (`double`): The damping coefficient; 0 means 2,452.5.

**Example**

```c
// A stiffer spring than the default, with the default damping.
DeformableGlueParameters glue = {2e4, 0.0};
CHECK(deformable_scene_set_glue_all(scene, &glue));
```

**See also** [Guide: Glue objects together](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#glue-objects-together) · [Rust `GlueParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#glueparameters) · [Python `GlueParameters`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#glueparameters)

## DeformableDrivenVertex

**Struct** · `deformable.h`

```c
typedef struct DeformableDrivenVertex {
    uint32_t vertex;
    DeformableVector3 target;
} DeformableDrivenVertex;
```

A vertex of an object driven to a target, in host units, for [`deformable_scene_drive`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_drive).

**Fields**

- `vertex` (`uint32_t`): The vertex, an index into the object's nodes.
- `target` ([`DeformableVector3`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): Where the vertex is at the end of the next step, in host units. It holds the target until a later
  `deformable_scene_drive` call for the object moves or releases it.

**Example**

```c
// Vertex 0, lifted 0.1 above where the mesh has it.
DeformableDrivenVertex lifted = {0, mesh.positions[0]};
lifted.target.y += 0.1;
CHECK(deformable_scene_drive(scene, object, &lifted, 1));
```

**See also** [Guide: Drive vertices](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#drive-vertices) · [Rust `DrivenVertex`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#drivenvertex) · [Python `DrivenVertex`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#drivenvertex)

## DeformableStepReport

**Struct** · `deformable.h`

```c
typedef struct DeformableStepReport {
    uint32_t substeps_run;
    DeformableStepOutcome outcome;
} DeformableStepReport;
```

The result of a [`deformable_scene_step`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_step) call: how many substeps ran, and what the call did.

**Fields**

- `substeps_run` (`uint32_t`): The number of substeps simulated: all of them for [`DEFORMABLE_STEP_OUTCOME_STEPPED`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_stepped), fewer for
  [`DEFORMABLE_STEP_OUTCOME_CANCELLED`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepoutcome-deformable_step_outcome_cancelled), 0 for the other outcomes.
- `outcome` ([`DeformableStepOutcome`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablestepoutcome)): What the call did.

**See also** [Guide: Step](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#step) · [Rust `StepReport`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#stepreport) · [Python `StepReport`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#stepreport)

## DeformableStepOutcome

**Enum** · `deformable.h`

```c
typedef int32_t DeformableStepOutcome;
```

What a [`deformable_scene_step`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_step) call did.

**Values**

- `DEFORMABLE_STEP_OUTCOME_STEPPED` (`0`): The substeps ran.
- `DEFORMABLE_STEP_OUTCOME_FIRST_CALL` (`1`): The first call only records the time.
- `DEFORMABLE_STEP_OUTCOME_NO_TIME_ELAPSED` (`2`): The time equals the last time; nothing is stepped.
- `DEFORMABLE_STEP_OUTCOME_NO_SUBSTEPS` (`3`): Zero substeps were asked for; the time advances without a step.
- `DEFORMABLE_STEP_OUTCOME_SUBSTEP_TOO_LARGE` (`4`): A substep would be longer than 0.04 s. The time advances, and the step's new glue, material changes and
  driven-vertex changes are made, but no substep runs; a vertex released now gets its last driven velocity, and the
  next step that runs a substep starts from it.
- `DEFORMABLE_STEP_OUTCOME_CANCELLED` (`5`): The cancel flag stopped the step after `substeps_run` substeps; the time advances by as many substeps, so the next
  step goes on from there. The queued forces are used up and do not reach the substeps that remain.

**See also** [Guide: Step](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#step) · [Rust `StepOutcome`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#stepoutcome) · [Python `StepOutcome`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#stepoutcome)

## DeformableSceneStatistics

**Struct** · `deformable.h`

```c
typedef struct DeformableSceneStatistics {
    uint64_t systems;
    uint64_t conjugate_gradient_updates;
    size_t contacts;
    size_t islands;
} DeformableSceneStatistics;
```

The solver, contact and island counters of a scene, for measuring it, as [`deformable_scene_statistics`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_statistics) writes
them; nothing in the scene uses them.

**Fields**

- `systems` (`uint64_t`): The linear systems solved since the scene was created: one per contact island, and one per awake island
  outside every contact island, in each substep.
- `conjugate_gradient_updates` (`uint64_t`): The conjugate gradient solution updates, summed over every solve since the scene was created.
- `contacts` (`size_t`): The live contacts, glue contacts included.
- `islands` (`size_t`): The islands it holds: awake, asleep and static (driven, or out of the world box), those waiting to be rebuilt
  at the next step included.

**See also** [Guide: Measure a scene](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#measure-a-scene) · [Rust `SceneStatistics`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#scenestatistics) · [Python `SceneStatistics`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#scenestatistics)

## DeformableTetrahedronState

**Struct** · `deformable.h`

```c
typedef struct DeformableTetrahedronState {
    DeformableVector3 corners[4];
    uint32_t island;
    double strain_measure;
    uint32_t flags;
} DeformableTetrahedronState;
```

The output record of one tetrahedron, as [`deformable_scene_tetrahedron_states`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_scene_tetrahedron_states) lends it.

**Fields**

- `corners` ([`DeformableVector3[4]`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): The current corner positions in host units, in the order of the tetrahedron's nodes.
- `island` (`uint32_t`): The id of the tetrahedron's island, the group of tetrahedrons solved together, or 0 while it has none.
- `strain_measure` (`double`): The squared norm of the total co-rotated strain, plastic part included, measured with the tetrahedron's stored
  rotation: `ε_xx² + ε_yy² + ε_zz² + 2(γ_yz² + γ_xz² + γ_xy²)`, with no square root taken.
- `flags` (`uint32_t`): Bit k (0 to 3) is set once face k, opposite corner k, has been reported exposed, and stays set; bit
  [`DEFORMABLE_NODE_REPLACED`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformable_node_replaced) is set while a fracture has moved the tetrahedron onto a cloned node.

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `TetrahedronState`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#tetrahedronstate) · [Python `TetrahedronState`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#tetrahedronstate)

### deformable_tetrahedron_state_face_centroid

**Function** · `deformable.h`

```c
DeformableStatus deformable_tetrahedron_state_face_centroid(
    const DeformableTetrahedronState *state,
    uint32_t face,
    DeformableVector3 *centroid);
```

Writes the centroid of the face `face`, the one opposite corner `face`, of `state` to `centroid`, in the unit of the corners.

**Parameters**

- `state` ([`const DeformableTetrahedronState *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronstate)): The output record of the tetrahedron.
- `face` (`uint32_t`): The face, 0 to 3.
- `centroid` ([`DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): Out. Receives the centroid.

**Errors**

- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `face` is above 3.

**See also** [Guide: Find the faces a crack opened](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#find-the-faces-a-crack-opened) · [Rust `TetrahedronState::face_centroid`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#tetrahedronstate-face_centroid) · [Python `TetrahedronState.face_centroid`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#tetrahedronstate-face_centroid)

### deformable_tetrahedron_state_face_normal

**Function** · `deformable.h`

```c
DeformableStatus deformable_tetrahedron_state_face_normal(
    const DeformableTetrahedronState *state,
    uint32_t face,
    DeformableVector3 *normal);
```

Writes the outward unit normal of the face `face`, the one opposite corner `face`, of `state` to `normal`, for a positively
oriented tetrahedron; a face of zero area gives the zero vector.

**Parameters**

- `state` ([`const DeformableTetrahedronState *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronstate)): The output record of the tetrahedron.
- `face` (`uint32_t`): The face, 0 to 3.
- `normal` ([`DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): Out. Receives the normal.

**Errors**

- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `face` is above 3.

**See also** [Guide: Find the faces a crack opened](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#find-the-faces-a-crack-opened) · [Rust `TetrahedronState::face_normal`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#tetrahedronstate-face_normal) · [Python `TetrahedronState.face_normal`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#tetrahedronstate-face_normal)

## DeformableFaceEvent

**Struct** · `deformable.h`

```c
typedef struct DeformableFaceEvent {
    uint32_t tetrahedron;
    uint8_t exposed_faces;
} DeformableFaceEvent;
```

An exposed-face event: a tetrahedron fracture changed in the last step and the faces it now shares with no other
tetrahedron.

The mask holds every exposed face of the tetrahedron, not only those the step opened: the faces on the surface of
the rest mesh, which [`deformable_boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces) gives, count too. A tetrahedron that a later fracture changes again
gets a new event, with the faces reported before still set.

**Fields**

- `tetrahedron` (`uint32_t`): The tetrahedron's index in its object's mesh.
- `exposed_faces` (`uint8_t`): Bit k is set when face k, opposite corner k, is shared with no other tetrahedron.

**See also** [Guide: Find the faces a crack opened](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#find-the-faces-a-crack-opened) · [Rust `FaceEvent`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#faceevent) · [Python `FaceEvent`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#faceevent)

## DEFORMABLE_NODE_REPLACED

**Constant** · `deformable.h`

```c
#define DEFORMABLE_NODE_REPLACED 0x10u
```

The bit of the flags of a [`DeformableTetrahedronState`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformabletetrahedronstate) set while one of the tetrahedron's nodes is no longer the node
it was created with: a fracture moved the tetrahedron onto a clone of that node. It is worked out again for every
read, not kept like the face bits.

**See also** [Guide: Read the outputs](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/scene/#read-the-outputs) · [Rust `NODE_REPLACED`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/scene/#node_replaced) · [Python `NODE_REPLACED`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/scene/#node_replaced)
