﻿---
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.2.0/api-references/rust/scene/
---

# Scene – Rust API Reference – Deformable v0.2.0

A [`Scene`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene) 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.

## Scene

**Struct** · `deformable::scene::Scene`

```rust
pub struct Scene { /* private fields */ }
```

One scene a host drives frame by frame: its materials and objects, the glue, driven vertices and forces between
steps, the frame [`step`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-step) and the outputs a host reads back.

[`Scene::new`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-new), or `Scene::default()`, creates an empty scene, and dropping the scene frees it in
the library. Materials and objects are named by the [`MaterialHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialhandle) and [`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle) that their calls
return, counting up from 0 in creation order.

Lengths cross the boundary 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 through in simulation units. A scene may move to
another thread but takes one call at a time, so it is `Send` and not `Sync`; `step` runs the scene's own worker
threads, and its results do not depend on their count.

**Implements** `Debug` · `Default` · `Drop` · `Send` · not `Sync`

**Example**

```rust
let mut scene = Scene::new();
scene.set_gravity(Vector3::new(0.0, 0.0, -9.81))?;
// The first step only records the time.
scene.step(0.0, 10, None)?;
let report = scene.step(1.0 / 24.0, 10, None)?;
assert_eq!(report.outcome, StepOutcome::Stepped);
```

**See also** [Guide: Create a scene](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#create-a-scene) · [C `DeformableScene`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformablescene) · [Python `Scene`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene)

### Scene::new

**Associated function** · `deformable::scene::Scene::new`

```rust
pub fn new() -> Self
```

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.

Panics when the library reports a failure, which only a defect in the library can cause.

**See also** [Guide: Create a scene](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#create-a-scene) · [C `deformable_scene_create`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_create)

### Scene::set_scale

**Method** · `deformable::scene::Scene::set_scale`

```rust
pub fn set_scale(&mut self, scale: f64) -> Result<(), Error>
```

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**

- `scale` (`f64`): The length of one host unit in simulation units, from 0.001 to 1,000.

**Errors**

- [`ScaleOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-scaleoutofrange): `scale` is below 0.001, above 1,000, or
  NaN.

**See also** [Guide: Create a scene](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#create-a-scene) · [C `deformable_scene_set_scale`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_set_scale) · [Python `Scene.set_scale`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene-set_scale)

### Scene::set_gravity

**Method** · `deformable::scene::Scene::set_gravity`

```rust
pub fn set_gravity(&mut self, gravity: Vector3) -> Result<(), Error>
```

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**

- `gravity` ([`Vector3`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): The acceleration, in simulation units per second squared.

**Errors**

- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A component of `gravity` is NaN or
  infinite.

**See also** [Guide: Create a scene](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#create-a-scene) · [C `deformable_scene_set_gravity`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_set_gravity) · [Python `Scene.set_gravity`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene-set_gravity)

### Scene::set_worker_count

**Method** · `deformable::scene::Scene::set_worker_count`

```rust
pub fn set_worker_count(&mut self, count: usize) -> Result<(), Error>
```

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**

- `count` (`usize`): The thread count, at least 1.

**Errors**

- [`InvalidWorkerCount`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-invalidworkercount): `count` is 0.

**See also** [Guide: Create a scene](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#create-a-scene) · [C `deformable_scene_set_worker_count`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_set_worker_count) · [Python `Scene.set_worker_count`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene-set_worker_count)

### Scene::add_material

**Method** · `deformable::scene::Scene::add_material`

```rust
pub fn add_material(
    &mut self,
    parameters: &MaterialParameters,
) -> Result<MaterialHandle, Error>
```

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

Each value is clamped to its range (see [`MaterialParameters`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters)), 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 f64 precision.

**Parameters**

- `parameters` ([`&MaterialParameters`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters)): The material's values, such as `MaterialParameters::default()` or a
  [preset](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters-preset).

**Errors**

- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A value of `parameters` is NaN or
  infinite.

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

### Scene::set_material

**Method** · `deformable::scene::Scene::set_material`

```rust
pub fn set_material(
    &mut self,
    material: MaterialHandle,
    parameters: &MaterialParameters,
) -> Result<(), Error>
```

Rewrites the values of `material` as [`add_material`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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 [`node_masses`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-node_masses)), their islands rebuild and nothing wakes.

**Parameters**

- `material` ([`MaterialHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialhandle)): The material to rewrite.
- `parameters` ([`&MaterialParameters`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters)): Its new values.

**Errors**

- [`UnknownMaterial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownmaterial): `material` names no material of this
  scene.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A value of `parameters` is NaN or
  infinite.

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

### Scene::add_object

**Method** · `deformable::scene::Scene::add_object`

```rust
pub fn add_object(
    &mut self,
    mesh: &TetrahedralMesh,
    materials: TetrahedronMaterials<'_>,
    options: ObjectOptions,
) -> Result<ObjectHandle, Error>
```

Creates an object from a tetrahedral mesh and returns its handle; 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 license refuses the call; the trial counts the tetrahedrons of the enabled
objects with this one's, none when it is created disabled. The object is glued at the next step that advances
the time with at least one substep.

**Parameters**

- `mesh` ([`&TetrahedralMesh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/meshes/#tetrahedralmesh)): The object's tetrahedral mesh, in world space and host units.
- `materials` ([`TetrahedronMaterials<'_>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#tetrahedronmaterials)): One material for every tetrahedron, or one per tetrahedron in mesh order.
- `options` ([`ObjectOptions`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objectoptions)): Self-collision, and whether the object starts disabled; usually `ObjectOptions::default()`.

**Errors**

- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-lengthmismatch): `materials` gives one material per
  tetrahedron, and not as many as the mesh has tetrahedrons.
- [`EmptyMesh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-emptymesh): The mesh has no tetrahedron.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-indexoutofrange): A tetrahedron uses a node index past the
  positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A position is NaN or infinite, or becomes
  infinite once multiplied by the scale.
- [`DegenerateTetrahedron`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-degeneratetetrahedron): The orientation determinant
  of a tetrahedron is not above 1e-9 in simulation units: the tetrahedron is too small, flat or inverted, as
  its [`DegenerateKind`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/mesh-checks/#degeneratekind) says. The error's first index names the first such
  tetrahedron.
- [`UnknownMaterial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownmaterial): A handle of `materials` names no material
  of this scene.
- [`NonManifoldFace`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonmanifoldface): Three or more tetrahedrons share one
  face.
- The [license kinds](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/errors/#license-errors) every engine call can return.

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

### Scene::set_object_material

**Method** · `deformable::scene::Scene::set_object_material`

```rust
pub fn set_object_material(
    &mut self,
    object: ObjectHandle,
    materials: TetrahedronMaterials<'_>,
) -> Result<(), Error>
```

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
[`node_masses`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-node_masses)), the object's islands rebuild and nothing wakes. A later call before that
step replaces this one.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to change.
- `materials` ([`TetrahedronMaterials<'_>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#tetrahedronmaterials)): One material for every tetrahedron, or one per tetrahedron in mesh order.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.
- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-lengthmismatch): `materials` gives one material per
  tetrahedron, and not as many as the object has tetrahedrons.
- [`UnknownMaterial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownmaterial): A handle of `materials` names no material
  of this scene.

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

### Scene::remove_object

**Method** · `deformable::scene::Scene::remove_object`

```rust
pub fn remove_object(
    &mut self,
    object: ObjectHandle,
) -> Result<(), Error>
```

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 trial limit.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to delete.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or one already removed.

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

### Scene::set_object_disabled

**Method** · `deformable::scene::Scene::set_object_disabled`

```rust
pub fn set_object_disabled(
    &mut self,
    object: ObjectHandle,
    disabled: bool,
) -> Result<(), Error>
```

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 [`drive`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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 trial's limit; enabled again, it counts from the next
step, which fails with [`ErrorKind::TrialLimitExceeded`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-triallimitexceeded) while the
enabled objects pass the limit.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to disable or enable.
- `disabled` (`bool`): `true` disables the object, `false` enables it.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

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

### Scene::set_self_collision

**Method** · `deformable::scene::Scene::set_self_collision`

```rust
pub fn set_self_collision(
    &mut self,
    object: ObjectHandle,
    enabled: bool,
) -> Result<(), Error>
```

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. [`ObjectOptions::self_collision`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objectoptions) gives
the setting an object starts with.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to change.
- `enabled` (`bool`): `true` turns self-collision on, `false` off.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

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

### Scene::set_never_sleep

**Method** · `deformable::scene::Scene::set_never_sleep`

```rust
pub fn set_never_sleep(
    &mut self,
    object: ObjectHandle,
    node: u32,
    enabled: bool,
) -> Result<(), Error>
```

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**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object that holds the node.
- `node` (`u32`): The node, an index into the object's nodes.
- `enabled` (`bool`): `true` sets the flag, `false` clears it.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-indexoutofrange): `node` is past the object's nodes.

**See also** [Guide: Sleep](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#sleep) · [C `deformable_scene_set_never_sleep`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_set_never_sleep) · [Python `Scene.set_never_sleep`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene-set_never_sleep)

### Scene::set_glue_all

**Method** · `deformable::scene::Scene::set_glue_all`

```rust
pub fn set_glue_all(
    &mut self,
    parameters: Option<GlueParameters>,
) -> Result<(), Error>
```

Turns glue all on with `parameters`, or off with `None`, 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**

- `parameters` ([`Option<GlueParameters>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#glueparameters)): The spring and damping of the glue, or `None` to turn glue all off.

**Errors**

- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A value of `parameters` is NaN or
  infinite.

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

### Scene::add_glue_region

**Method** · `deformable::scene::Scene::add_glue_region`

```rust
pub fn add_glue_region(
    &mut self,
    region: ConvexRegion,
    members: &[ObjectHandle],
    parameters: GlueParameters,
) -> Result<(), Error>
```

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**

- `region` ([`ConvexRegion`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#convexregion)): The convex region, in world space and host units.
- `members` ([`&[ObjectHandle]`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The objects the region glues to each other.
- `parameters` ([`GlueParameters`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#glueparameters)): The spring and damping of the glue.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): A handle of `members` names no object of this
  scene, or a removed one.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A plane, or a value of `parameters`, is NaN
  or infinite.

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

### Scene::drive

**Method** · `deformable::scene::Scene::drive`

```rust
pub fn drive(
    &mut self,
    object: ObjectHandle,
    vertices: &[DrivenVertex],
) -> Result<(), Error>
```

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 [`StepOutcome::SubstepTooLarge`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepoutcome-substeptoolarge) 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 [`set_object_disabled`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_object_disabled)). A call
that fails changes nothing.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object whose vertices to drive.
- `vertices` ([`&[DrivenVertex]`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#drivenvertex)): Each vertex to drive, with its target in host units.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-indexoutofrange): A vertex is past the object's nodes.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A target is NaN or infinite.

**Example**

```rust
// Each frame, vertex 0 rises 0.01 further before the step.
for frame in 0..=24 {
    let rise = Vector3::Y * (0.01 * f64::from(frame));
    let target = mesh.positions[0] + rise;
    scene.drive(object, &[DrivenVertex { vertex: 0, target }])?;
    scene.step(f64::from(frame) / 24.0, 10, None)?;
}
```

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

### Scene::add_force

**Method** · `deformable::scene::Scene::add_force`

```rust
pub fn add_force(
    &mut self,
    object: ObjectHandle,
    node: u32,
    force: Vector3,
) -> Result<(), Error>
```

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
[`skip_to`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object that holds the node.
- `node` (`u32`): The node, an index into the object's nodes.
- `force` ([`Vector3`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): The force, in simulation units: the scale does not apply to it.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-indexoutofrange): `node` is past the object's nodes.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A component of `force` is NaN or infinite.

**Example**

```rust
// A push along x on every node, for the next step.
let push = Vector3::new(5.0, 0.0, 0.0);
for node in 0..mesh.positions.len() as u32 {
    scene.add_force(object, node, push)?;
}
```

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

### Scene::step

**Method** · `deformable::scene::Scene::step`

```rust
pub fn step(
    &mut self,
    time: f64,
    substeps: u32,
    cancel: Option<&CancelFlag>,
) -> Result<StepReport, Error>
```

Advances the scene to `time`, in seconds, in `substeps` equally long substeps.

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 [`StepOutcome::Cancelled`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepoutcome-cancelled): the time then stands
at the last substep run, so the next call goes on from there.

Every call that returns a report uses up the forces [`add_force`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-add_force) queued. The license is
checked at every call, so a scene larger than the trial allows steps only while a license is active.

**Parameters**

- `time` (`f64`): The frame's time, in seconds. It may not be before the last time a step or
  [`skip_to`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-skip_to) recorded.
- `substeps` (`u32`): How many substeps to run, all of one length; at 24 frames per second, 10 is a good start.
- `cancel` ([`Option<&CancelFlag>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#cancelflag)): Stops the step between two substeps when another thread sets it.

**Returns**

[`StepReport`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepreport): How many substeps ran, and what the call did: whether they ran, and if not, why.

**Errors**

- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): `time` is NaN or infinite.
- [`TimeWentBackwards`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-timewentbackwards): `time` is before the last time
  recorded. To go back, create a new scene.
- [`Unrecognized`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unrecognized): The library reports an outcome this crate does
  not know, which only a newer library does; the step has run.
- The [license kinds](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/errors/#license-errors) every engine call can return.

**Example**

```rust
for frame in 0..3 {
    let report = scene.step(f64::from(frame) / 24.0, 10, None)?;
    println!("{:?}, {} substeps", report.outcome, report.substeps_run);
}
```

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

### Scene::skip_to

**Method** · `deformable::scene::Scene::skip_to`

```rust
pub fn skip_to(&mut self, time: f64) -> Result<(), Error>
```

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

A host calls it in place of [`step`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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**

- `time` (`f64`): The time to record, in seconds. It may not be before the last time recorded.

**Errors**

- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): `time` is NaN or infinite.
- [`TimeWentBackwards`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-timewentbackwards): `time` is before the last time
  recorded.
- The [license kinds](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/errors/#license-errors) every engine call can return.

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

### Scene::node_positions

**Method** · `deformable::scene::Scene::node_positions`

```rust
pub fn node_positions(
    &self,
    object: ObjectHandle,
    output: &mut Vec<Vector3>,
) -> Result<(), Error>
```

Fills `output` with 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.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.
- `output` ([`&mut Vec<Vector3>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): Cleared, then filled with one position per node. Reuse it every frame.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

**Example**

```rust
let mut positions = Vec::new();
scene.node_positions(object, &mut positions)?;
// Before any fracture, one node per mesh vertex.
assert_eq!(positions.len(), mesh.positions.len());
```

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

### Scene::node_velocities

**Method** · `deformable::scene::Scene::node_velocities`

```rust
pub fn node_velocities(
    &self,
    object: ObjectHandle,
    output: &mut Vec<Vector3>,
) -> Result<(), Error>
```

Fills `output` with the current node velocities of `object`, in host units per second (divided by the scale),
in the order of [`node_positions`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-node_positions).

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.
- `output` ([`&mut Vec<Vector3>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): Cleared, then filled with one velocity per node.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

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

### Scene::node_masses

**Method** · `deformable::scene::Scene::node_masses`

```rust
pub fn node_masses(
    &self,
    object: ObjectHandle,
    output: &mut Vec<f64>,
) -> Result<(), Error>
```

Fills `output` with the lumped node masses of `object`, in simulation units, in the order of
[`node_positions`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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 [`set_material`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_material) or [`set_object_material`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.
- `output` (`&mut Vec<f64>`): Cleared, then filled with one mass per node.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

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

### Scene::tetrahedron_nodes

**Method** · `deformable::scene::Scene::tetrahedron_nodes`

```rust
pub fn tetrahedron_nodes(
    &self,
    object: ObjectHandle,
    output: &mut Vec<[u32; 4]>,
) -> Result<(), Error>
```

Fills `output` with the current four nodes of each tetrahedron of `object`, as indices into its nodes (the
order of [`node_positions`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.
- `output` (`&mut Vec<[u32; 4]>`): Cleared, then filled with the four nodes of each tetrahedron.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

**Example**

```rust
let mut tetrahedrons = Vec::new();
scene.tetrahedron_nodes(object, &mut tetrahedrons)?;
// Before any fracture, the nodes are those of the mesh.
assert_eq!(tetrahedrons, mesh.tetrahedrons);
```

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

### Scene::tetrahedron_states

**Method** · `deformable::scene::Scene::tetrahedron_states`

```rust
pub fn tetrahedron_states(
    &self,
    object: ObjectHandle,
    output: &mut Vec<TetrahedronState>,
) -> Result<(), Error>
```

Fills `output` with 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.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.
- `output` ([`&mut Vec<TetrahedronState>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#tetrahedronstate)): Cleared, then filled with one record per tetrahedron.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

**Example**

```rust
let mut states = Vec::new();
scene.tetrahedron_states(object, &mut states)?;
let broken = states
    .iter()
    .filter(|state| state.flags & NODE_REPLACED != 0)
    .count();
println!("{broken} tetrahedrons sit on a cloned node");
```

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

### Scene::face_events

**Method** · `deformable::scene::Scene::face_events`

```rust
pub fn face_events(
    &mut self,
    object: ObjectHandle,
) -> Result<&[FaceEvent], Error>
```

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

Every step that returns a report replaces them, so a step without fracture leaves none. The slice is the
library's own buffer, so it borrows the scene mutably until it is dropped.

**Parameters**

- `object` ([`ObjectHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#objecthandle)): The object to read.

**Errors**

- [`UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject): `object` names no object of this scene,
  or a removed one.

**Example**

```rust
let boundary = boundary_faces(&mesh)?;
for event in scene.face_events(object)? {
    let index = event.tetrahedron as usize;
    // The faces a crack opened, without the rest surface.
    let opened = event.exposed_faces & !boundary[index];
    println!("tetrahedron {index}: faces {opened:04b}");
}
```

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

### Scene::awake_tetrahedron_count

**Method** · `deformable::scene::Scene::awake_tetrahedron_count`

```rust
pub fn awake_tetrahedron_count(&self) -> usize
```

The number of tetrahedrons in awake islands, over the whole scene, counted at each call.

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 [`set_scale`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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.

**See also** [Guide: Sleep](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#sleep) · [C `deformable_scene_awake_tetrahedron_count`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_scene_awake_tetrahedron_count) · [Python `Scene.awake_tetrahedron_count`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#scene-awake_tetrahedron_count)

### Scene::statistics

**Method** · `deformable::scene::Scene::statistics`

```rust
pub fn statistics(&self) -> SceneStatistics
```

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

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

## MaterialParameters

**Struct** · `deformable::scene::MaterialParameters`

```rust
pub struct MaterialParameters {
    pub youngs_modulus: f64,
    pub poissons_ratio: f64,
    pub density: f64,
    pub toughness: f64,
    pub youngs_damping: f64,
    pub yield_strain: f64,
    pub maximum_yield: f64,
    pub creep_fraction: f64,
    pub wake_up_radius: f64,
    pub friction: f64,
}
```

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

`MaterialParameters::default()` gives the defaults below, and [`MaterialParameters::preset`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters-preset) the values of a named
material such as `"steel"`.

**Fields**

- `youngs_modulus` (`f64`): Young's modulus, in pascals in simulation units: the higher, the stiffer.
  Default `8e5`, clamped to `[1e3, 1e10]`.
- `poissons_ratio` (`f64`): Poisson's ratio, unitless: how much the material bulges sideways when it is squeezed.
  Default `0`, clamped to `[-0.90001, 0.490001]`.
- `density` (`f64`): Mass per unit volume, in simulation units: a tetrahedron weighs its density times its volume.
  Default `2500`, clamped to `[0, 1e4]`.
- `toughness` (`f64`): 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` (`f64`): Stiffness-proportional damping; the engine's damping coefficient is `youngs_damping / youngs_modulus`.
  Default `0`, clamped to `[0, 1e9]`.
- `yield_strain` (`f64`): The elastic strain norm above which plastic flow starts.
  Default `0`, clamped to `[0, 1]`.
- `maximum_yield` (`f64`): The bound on the plastic strain norm; 0 resets the plastic strain every solve.
  Default `0`, clamped to `[0, 1]`.
- `creep_fraction` (`f64`): 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` (`f64`): 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` (`f64`): The Coulomb friction coefficient; a contact uses the lower of its two materials' coefficients.
  Default `0.6`, clamped to `[0, 1]`.

**Implements** `Clone` · `Copy` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
let rubber = MaterialParameters {
    youngs_modulus: 1e6,
    poissons_ratio: 0.45,
    ..MaterialParameters::default()
};
let material = scene.add_material(&rubber)?;
```

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

### MaterialParameters::presets

**Associated function** · `deformable::scene::MaterialParameters::presets`

```rust
pub fn presets() -> &'static [MaterialPreset]
```

The presets the library ships, in its order: named starting points for a material, 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`.

**Example**

```rust
for preset in MaterialParameters::presets() {
    println!("{}", preset.name);
}
```

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

### MaterialParameters::preset

**Associated function** · `deformable::scene::MaterialParameters::preset`

```rust
pub fn preset(name: &str) -> Option<MaterialParameters>
```

Looks a preset up by its name.

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

**Parameters**

- `name` (`&str`): The preset's name, such as `"concrete"` or `"unbreakable_rubber"`.

**Returns**

[`Option<MaterialParameters>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters): The preset's values, or `None` when no preset has this name.

**Example**

```rust
let steel = MaterialParameters::preset("steel").expect("a preset");
let material = scene.add_material(&steel)?;
assert_eq!(MaterialParameters::preset("Steel"), None);
```

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

## MaterialPreset

**Struct** · `deformable::scene::MaterialPreset`

```rust
pub struct MaterialPreset {
    pub name: &'static str,
    pub parameters: MaterialParameters,
}
```

A material preset: its name and its values, as [`MaterialParameters::presets`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters-presets) lists them.

**Fields**

- `name` (`&'static str`): The preset's name, in lowercase with underscores between words, such as `"concrete"` or
  `"unbreakable_rubber"`.
- `parameters` ([`MaterialParameters`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialparameters)): The values, each inside its clamp range, so [`Scene::add_material`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-add_material)
  keeps them as they are.

**Implements** `Clone` · `Copy` · `Debug` · `PartialEq` · `Send` · `Sync`

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

## MaterialHandle

**Struct** · `deformable::scene::MaterialHandle`

```rust
pub struct MaterialHandle(pub u32);
```

The handle of a material of a [`Scene`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene): its number in creation order, counting up from 0. Use it only with
the scene that returned it.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `Hash` · `Ord` · `PartialEq` · `PartialOrd` · `Send` · `Sync`

**See also** [Guide: Add and change a material](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#add-and-change-a-material)

## MaterialRegion

**Struct** · `deformable::scene::MaterialRegion`

```rust
pub struct MaterialRegion {
    pub mesh: PolygonMesh,
    pub to_mesh_space: AffineTransform,
}
```

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

A region with no polygons holds every tetrahedron.

**Fields**

- `mesh` ([`PolygonMesh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/meshes/#polygonmesh)): 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.
- `to_mesh_space` ([`AffineTransform`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#affinetransform)): Maps the region's points into the tetrahedral mesh's object space: the region's world matrix times the inverse
  of the object's.

**Implements** `Clone` · `Debug` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// The unit cube moved 0.5 along x: it holds the right half of `mesh`.
let right_half = MaterialRegion {
    mesh: polygons,
    to_mesh_space: AffineTransform {
        translation: Vector3::new(0.5, 0.0, 0.0),
        ..AffineTransform::IDENTITY
    },
};
```

**See also** [Guide: Material regions](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#material-regions) · [C `DeformableMaterialRegion`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformablematerialregion) · [Python `MaterialRegion`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#materialregion)

## material_region_indices

**Function** · `deformable::scene::material_region_indices`

```rust
pub fn material_region_indices(
    mesh: &TetrahedralMesh,
    regions: &[MaterialRegion],
) -> Result<Vec<u32>, Error>
```

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 materials for [`TetrahedronMaterials::PerTetrahedron`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#tetrahedronmaterials-pertetrahedron): 0 is the object's
material, and each other index the material of the region one below it in `regions`.

**Parameters**

- `mesh` ([`&TetrahedralMesh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/meshes/#tetrahedralmesh)): The tetrahedral mesh, in the object space the regions map into.
- `regions` ([`&[MaterialRegion]`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialregion)): The regions, each a polygon mesh and its map into the object space of `mesh`.

**Returns**

`Vec<u32>`: One index per tetrahedron, in mesh order.

**Errors**

- [`EmptyMesh`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-emptymesh): `mesh` has no tetrahedron.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-indexoutofrange): A tetrahedron of `mesh`, or a polygon of a
  region, uses a vertex past the end of its positions.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-nonfinitevalue): A position of `mesh` or of a region's mesh,
  or a value of a region's map, is NaN or infinite.
- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-lengthmismatch): The polygon sizes of a region's mesh do not
  add up to its number of polygon vertices.
- [`DegenerateRegion`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-degenerateregion): A polygon of a region has fewer than 3
  corners, or a zero normal once mapped; the error's first index names the region, its second the polygon.
- The [license kinds](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/errors/#license-errors) every engine call can return.

**Example**

```rust
let left_half = MaterialRegion {
    mesh: polygons,
    to_mesh_space: AffineTransform {
        linear: Matrix3::from_diagonal(Vector3::new(0.5, 1.0, 1.0)),
        ..AffineTransform::IDENTITY
    },
};
let indices = material_region_indices(&mesh, &[left_half])?;
```

**See also** [Guide: Material regions](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#material-regions) · [C `deformable_material_region_indices`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_material_region_indices) · [Python `material_region_indices`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#material_region_indices)

## TetrahedronMaterials

**Enum** · `deformable::scene::TetrahedronMaterials`

```rust
pub enum TetrahedronMaterials<'a> {
    Uniform(MaterialHandle),
    PerTetrahedron(&'a [MaterialHandle]),
}
```

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

A list of another length than the mesh's tetrahedron count gives
[`ErrorKind::LengthMismatch`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-lengthmismatch), and a handle that names no material of the
scene gives [`ErrorKind::UnknownMaterial`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownmaterial).

**Values**

- `Uniform` ([`MaterialHandle`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialhandle)): One material for every tetrahedron.
- `PerTetrahedron` ([`&'a [MaterialHandle]`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#materialhandle)): One material per tetrahedron, in mesh order: the form material regions take, with the indices of
  [`material_region_indices`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#material_region_indices).

**Implements** `Clone` · `Copy` · `Debug` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
let uniform = TetrahedronMaterials::Uniform(material);
scene.set_object_material(object, uniform)?;
// The same materials, as one per tetrahedron in mesh order.
let materials = vec![material; mesh.tetrahedrons.len()];
let per_tetrahedron = TetrahedronMaterials::PerTetrahedron(&materials);
scene.set_object_material(object, per_tetrahedron)?;
```

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

## ObjectOptions

**Struct** · `deformable::scene::ObjectOptions`

```rust
pub struct ObjectOptions {
    pub self_collision: bool,
    pub disabled: bool,
}
```

The per-object settings a host gives when it creates an object with [`Scene::add_object`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-add_object).

`ObjectOptions::default()` turns self-collision on and leaves the object enabled.
[`Scene::set_self_collision`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_self_collision) and [`Scene::set_object_disabled`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_object_disabled) change them later.

**Fields**

- `self_collision` (`bool`): The object's colliders test its own faces against each other. Default `true`.
- `disabled` (`bool`): The object is created disabled: it takes no part in the scene until [`Scene::set_object_disabled`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_object_disabled)
  enables it, and it gets no glue if it is still disabled when the next step glues new objects. Default `false`.

**Implements** `Clone` · `Copy` · `Debug` · `Default` · `Eq` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
let options = ObjectOptions {
    self_collision: false,
    ..ObjectOptions::default()
};
let materials = TetrahedronMaterials::Uniform(material);
let cube = scene.add_object(&mesh, materials, options)?;
```

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

## ObjectHandle

**Struct** · `deformable::scene::ObjectHandle`

```rust
pub struct ObjectHandle(pub u32);
```

The handle of an object of a [`Scene`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene): its number in creation order, counting up from 0.

Use it only with the scene that returned it. A removed object's handle is never given to another object:
later calls with it give [`ErrorKind::UnknownObject`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/errors/#errorkind-unknownobject).

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `Hash` · `Ord` · `PartialEq` · `PartialOrd` · `Send` · `Sync`

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

## GlueParameters

**Struct** · `deformable::scene::GlueParameters`

```rust
pub struct GlueParameters {
    pub spring_constant: f64,
    pub damping_coefficient: f64,
}
```

The spring and damping of glue, for [`Scene::set_glue_all`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-set_glue_all) and
[`Scene::add_glue_region`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#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` (`f64`): The spring constant; 0 means 4,905.
- `damping_coefficient` (`f64`): The damping coefficient; 0 means 2,452.5.

**Implements** `Clone` · `Copy` · `Debug` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// A stiffer spring than the default, with the default damping.
let glue = GlueParameters {
    spring_constant: 2e4,
    damping_coefficient: 0.0,
};
scene.set_glue_all(Some(glue))?;
```

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

## DrivenVertex

**Struct** · `deformable::scene::DrivenVertex`

```rust
pub struct DrivenVertex {
    pub vertex: u32,
    pub target: Vector3,
}
```

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

**Fields**

- `vertex` (`u32`): The vertex, an index into the object's nodes.
- `target` ([`Vector3`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): Where the vertex is at the end of the next step, in host units. It holds the target until a later
  [`Scene::drive`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-drive) call for the object moves or releases it.

**Implements** `Clone` · `Copy` · `Debug` · `PartialEq` · `Send` · `Sync`

**Example**

```rust
// Vertex 0, lifted 0.1 above where the mesh has it.
let lifted = DrivenVertex {
    vertex: 0,
    target: mesh.positions[0] + Vector3::Y * 0.1,
};
scene.drive(object, &[lifted])?;
```

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

## StepReport

**Struct** · `deformable::scene::StepReport`

```rust
pub struct StepReport {
    pub substeps_run: u32,
    pub outcome: StepOutcome,
}
```

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

**Fields**

- `substeps_run` (`u32`): The number of substeps simulated: all of them for [`StepOutcome::Stepped`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepoutcome-stepped), fewer for
  [`StepOutcome::Cancelled`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepoutcome-cancelled), 0 for the other outcomes.
- `outcome` ([`StepOutcome`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#stepoutcome)): What the call did.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `PartialEq` · `Send` · `Sync`

**See also** [Guide: Read the step's outcome](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#read-the-steps-outcome) · [C `DeformableStepReport`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformablestepreport) · [Python `StepReport`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#stepreport)

## StepOutcome

**Enum** · `deformable::scene::StepOutcome`

```rust
pub enum StepOutcome {
    Stepped,
    FirstCall,
    NoTimeElapsed,
    NoSubsteps,
    SubstepTooLarge,
    Cancelled,
}
```

What a [`Scene::step`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-step) call did.

**Values**

- `Stepped`: The substeps ran.
- `FirstCall`: The first call only records the time.
- `NoTimeElapsed`: The time equals the last time; nothing is stepped.
- `NoSubsteps`: Zero substeps were asked for; the time advances without a step.
- `SubstepTooLarge`: 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.
- `Cancelled`: 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.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `PartialEq` · `Send` · `Sync`

**See also** [Guide: Read the step's outcome](https://help.tangerina.io/deformable/v0.2.0/user-guides/rust/scene/#read-the-steps-outcome) · [C `DeformableStepOutcome`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformablestepoutcome) · [Python `StepOutcome`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#stepoutcome)

## SceneStatistics

**Struct** · `deformable::scene::SceneStatistics`

```rust
pub struct SceneStatistics {
    pub systems: u64,
    pub conjugate_gradient_updates: u64,
    pub contacts: usize,
    pub islands: usize,
}
```

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

**Fields**

- `systems` (`u64`): 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` (`u64`): The conjugate gradient solution updates, summed over every solve since the scene was created.
- `contacts` (`usize`): The live contacts, glue contacts included.
- `islands` (`usize`): 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.

**Implements** `Clone` · `Copy` · `Debug` · `Default` · `Eq` · `PartialEq` · `Send` · `Sync`

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

## TetrahedronState

**Struct** · `deformable::scene::TetrahedronState`

```rust
pub struct TetrahedronState {
    pub corners: [Vector3; 4],
    pub island: u32,
    pub strain_measure: f64,
    pub flags: u32,
}
```

The output record of one tetrahedron, as [`Scene::tetrahedron_states`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#scene-tetrahedron_states)
reads it.

**Fields**

- `corners` ([`[Vector3; 4]`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3)): The current corner positions in host units, in the order of the tetrahedron's nodes.
- `island` (`u32`): The id of the tetrahedron's island, the group of tetrahedrons solved together, or 0 while it has none.
- `strain_measure` (`f64`): 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` (`u32`): Bit k (0 to 3) is set once face k, opposite corner k, has been reported exposed, and stays set; bit
  [`NODE_REPLACED`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#node_replaced) is set while a fracture has moved the tetrahedron onto a cloned node.

**Implements** `Clone` · `Copy` · `Debug` · `Default` · `PartialEq` · `Send` · `Sync`

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

### TetrahedronState::face_centroid

**Method** · `deformable::scene::TetrahedronState::face_centroid`

```rust
pub fn face_centroid(&self, face: usize) -> Option<Vector3>
```

The centroid of the face `face`, the one opposite corner `face`, in the unit of the corners.

**Parameters**

- `face` (`usize`): The face, 0 to 3.

**Returns**

[`Option<Vector3>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3): The centroid, or `None` when `face` is above 3.

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

### TetrahedronState::face_normal

**Method** · `deformable::scene::TetrahedronState::face_normal`

```rust
pub fn face_normal(&self, face: usize) -> Option<Vector3>
```

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

**Parameters**

- `face` (`usize`): The face, 0 to 3.

**Returns**

[`Option<Vector3>`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/math/#vector3): The normal, or `None` when `face` is above 3.

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

## FaceEvent

**Struct** · `deformable::scene::FaceEvent`

```rust
pub struct FaceEvent {
    pub tetrahedron: u32,
    pub exposed_faces: u8,
}
```

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 [`boundary_faces`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/meshes/#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` (`u32`): The tetrahedron's index in its object's mesh.
- `exposed_faces` (`u8`): Bit k is set when face k, opposite corner k, is shared with no other tetrahedron.

**Implements** `Clone` · `Copy` · `Debug` · `Eq` · `PartialEq` · `Send` · `Sync`

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

## NODE_REPLACED

**Constant** · `deformable::scene::NODE_REPLACED`

```rust
pub const NODE_REPLACED: u32 = 0x10;
```

The bit of [`TetrahedronState::flags`](https://help.tangerina.io/deformable/v0.2.0/api-references/rust/scene/#tetrahedronstate) 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** [C `DEFORMABLE_NODE_REPLACED`](https://help.tangerina.io/deformable/v0.2.0/api-references/c/scene/#deformable_node_replaced) · [Python `NODE_REPLACED`](https://help.tangerina.io/deformable/v0.2.0/api-references/python/scene/#node_replaced)
