You are viewing the documentation for Deformable v0.6.0, an older version. Read the latest, v0.9.0
Rust API Reference
Overview
The reference of the deformable Rust crate: its conventions, and the pages that list every public item.
On this page
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.
Pages
- Scene: The scene, and everything it takes or returns: materials, objects, glue, driven vertices, steps and outputs.
- Tools: Tetrahedralize, triangulate, extrude, span layers, autocage and splinters from an image, with their parameters and results.
- Mesh checks: Check a surface for problems before you use it, and find tetrahedral meshes that overlap.
- 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: Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
- Math: The points, vectors, transforms, planes and convex regions the other pages take and return.
- Errors: Errors and status codes, the library version, and the cancel flag that stops a long call.
- License: The license state of this device, or of this program under an Application license, and the calls that refresh it, sign in to a subscription, and activate and deactivate a license.
Conventions
- Errors. Every fallible call returns
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::SceneisSendand takes one call at a time; tools,scene::SurfaceEmbeddingandCancelFlagmay be used from several threads at once. - License. Nothing ever refuses to run: without a subscription or a license, Free runs, and a scene simulates at most 2,500 tetrahedrons.
licensereads the license, signs in to a Standalone subscription and activates a license key. A Standalone subscription or license belongs to this device and user; an Application license, refused inside the plugins, licenses the program that activates its key at every start. A license failure is anErrorwhoseErrorKind::is_licenseis 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 closedtools::TriangleMeshwith outward normals;polygons, the same cube as amesh::PolygonMeshof six quads;mesh, the cage filled with tetrahedrons;scene, ascene::Sceneholding one object made ofmeshwith one default material; andmaterialandobject, 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://assets.tangerina.io/releases 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:
sceneone scene a host drives frame by frame — materials, objects, glue, driven vertices, forces, the framestepand its outputs — and the render surfaces embedded in its objects and skinned each frame.toolsmesh 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.meshthe tetrahedral and polygon meshes their signatures share, and the faces of a tetrahedron.maththe vectors, matrices and transforms their signatures share.Errorthe error of every fallible call, with theErrorKindof the failure, the library’s message and the element indices it names.CancelFlagstops a long tool or step from another thread.licensethe license of this program, which sets how many tetrahedrons a scene simulates: Free, a Standalone subscription or a Standalone license on this device, or an Application license; signing in to the subscription 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:
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, ¶meters, 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));