﻿---
title: Overview
description: "The reference of the deformable Rust crate: its conventions, and the pages that list every public item."
url: https://help.tangerina.io/deformable/v0.4.0/api-references/rust/overview/
---

# Overview – Rust API Reference – Deformable v0.4.0

The Rust SDK is the `deformable` crate. These pages list every public item of the crate with its signature and documentation, generated from its source. They group the items by topic rather than by module: the kind line under each heading gives the item's path in the crate.

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

## Pages

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

## Conventions

- **Errors.** Every fallible call returns [`Error`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#error); arguments the C interface cannot carry (a UV set of the wrong length) are refused by the crate itself with the same type.
- **Units.** Lengths cross in host units; time, forces, gravity, masses and material values in simulation units. The scene's scale converts host lengths to simulation lengths.
- **Threads.** A [`scene::Scene`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/scene/#scene) is `Send` and takes one call at a time; tools, [`scene::SurfaceEmbedding`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/render-surfaces/#surfaceembedding) and [`CancelFlag`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#cancelflag) may be used from several threads at once.
- **License.** Nothing ever refuses to run: without a license the Free license runs, and a scene simulates at most 2,500 tetrahedrons. `license` reads the license and activates a license key. A Standard license belongs to this device and user; a Developer license, refused inside the plugins, licenses the program that activates its key at every start. A license failure is an [`Error`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#error) whose [`ErrorKind::is_license`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#errorkind-is_license) is true, and whose message is written to show the user as it is.
- **Examples.** The examples share a few values set up out of view, in hidden lines: `cage`, the unit cube as a closed [`tools::TriangleMesh`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/meshes/#trianglemesh) with outward normals; `polygons`, the same cube as a [`mesh::PolygonMesh`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/meshes/#polygonmesh) of six quads; `mesh`, the cage filled with tetrahedrons; `scene`, a [`scene::Scene`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/scene/#scene) holding one object made of `mesh` with one default material; and `material` and `object`, the handles of that material and object.

## The crate

Finite element deformation and fracture of tetrahedral meshes, with the mesh tools that prepare them.

This is the Rust SDK of Tangerina Deformable: a safe API over libdeformable, the shared library of the C SDK. The
crate holds no engine code; it calls the library. The first build downloads the library of the crate's version for
the target platform from <https://downloads.tangerina.io> with `curl`, checks it against the SHA-256 checksums the
crate carries, and keeps it in the build folder, where `cargo run` and `cargo test` find it. To build without a
download, set the `DEFORMABLE_LIB_DIR` environment variable to the absolute path of the `lib` folder of the C SDK
for your platform (from <https://tangerina.io/deformable#download-c>). A program built with the crate needs the
shared library at run time, so ship `libdeformable.dylib`, `libdeformable.so` or `deformable.dll` next to it.

The public surface:

- `scene`: one scene a host drives frame by frame — materials, objects, glue, driven vertices, forces,
  the frame `step` and its outputs — and the render surfaces embedded in its objects and skinned each frame.
- `tools`: mesh functions, with no scene state, that prepare a scene's inputs — polygon mesh
  triangulation, tetrahedralize, layer extrusion, autocage, splinters from an image, surface verification and mesh
  intersection.
- `mesh`: the tetrahedral and polygon meshes their signatures share, and the faces of a tetrahedron.
- `math`: the vectors, matrices and transforms their signatures share.
- [`Error`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#error): the error of every fallible call, with the [`ErrorKind`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#errorkind) of the failure, the library's message and
  the element indices it names.
- [`CancelFlag`](https://help.tangerina.io/deformable/v0.4.0/api-references/rust/errors/#cancelflag): stops a long tool or step from another thread.
- `license`: the license of this program, which sets how many tetrahedrons a scene simulates: the Free license,
  a Standard license on this device or a Developer license, and activating either license key.

The typical host flow builds an object from a closed cage, embeds the render surface in it, steps the scene each
frame and skins the surface:

```rust
use deformable::math::{AffineTransform, Vector3};
use deformable::mesh::PolygonMesh;
use deformable::scene::{
    DeformedSurface, MaterialParameters, ObjectOptions, Scene,
    SkinningOptions, StepOutcome, TetrahedronMaterials, embed_surface,
};
use deformable::tools::{
    Anisotropy, ClipMode, PreparationParameters, SurfaceMesh,
    TetrahedralizeParameters, TriangleMesh, tetrahedralize,
};

// A closed unit cube with outward triangles: the tetrahedralization
// cage and the render surface at once.
let positions: Vec<Vector3> = (0..8)
    .map(|corner: u32| {
        let bit = |shift: u32| f64::from(corner >> shift & 1);
        Vector3::new(bit(0), bit(1), bit(2))
    })
    .collect();
let triangles = vec![
    [0, 2, 3], [0, 3, 1], [4, 5, 7], [4, 7, 6], [0, 1, 5], [0, 5, 4],
    [2, 6, 7], [2, 7, 3], [0, 4, 6], [0, 6, 2], [1, 3, 7], [1, 7, 5],
];
let cage = TriangleMesh {
    positions: positions.clone(),
    triangles: triangles.clone(),
};

// The cage, filled with tetrahedrons.
let parameters = TetrahedralizeParameters {
    maximum_edge_length: 0.5,
    anisotropy: [Anisotropy::default(); 2],
    density_regions: Vec::new(),
};
let rest = tetrahedralize(&cage, &parameters, None)?.mesh;

// The tetrahedral mesh, made an object of a scene.
let mut scene = Scene::new();
let material = scene.add_material(&MaterialParameters::default())?;
let object = scene.add_object(
    &rest,
    TetrahedronMaterials::Uniform(material),
    ObjectOptions::default(),
)?;

// The render surface, embedded in the rest mesh.
let surface = SurfaceMesh {
    mesh: PolygonMesh {
        positions,
        polygon_sizes: vec![3; triangles.len()],
        polygon_vertices: triangles.concat(),
    },
    ..SurfaceMesh::default()
};
let preparation = PreparationParameters {
    clip_mode: ClipMode::AssignOnly,
    uv_scale: 1.0,
    splinter_cage: None,
};
let embedding = embed_surface(&rest, &surface, &preparation)?;

// Frames at 24 per second, 10 substeps each; the first call only
// records the time.
let first = scene.step(0.0, 10, None)?;
assert_eq!(first.outcome, StepOutcome::FirstCall);
for frame in 1..=6 {
    let report = scene.step(f64::from(frame) / 24.0, 10, None)?;
    assert_eq!(report.outcome, StepOutcome::Stepped);
}

// The tetrahedron states skin the render surface, in the object space
// of a shape whose world transform is the identity: the whole cube has
// fallen under gravity, top (rest y = 1) and bottom (rest y = 0).
let mut states = Vec::new();
scene.tetrahedron_states(object, &mut states)?;
let mut deformed = DeformedSurface::default();
let world = AffineTransform::IDENTITY;
let options = SkinningOptions::default();
embedding.deform(&states, &world, options, &mut deformed)?;
let heights = || deformed.positions.iter().map(|position| position[1]);
assert!(heights().all(|height| height < 0.9));
assert!(heights().any(|height| height < -0.1));
```
