﻿---
title: Render surfaces
description: Embed a render surface in a tetrahedral mesh, and deform it with the simulation every frame.
url: https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/
---

# Render surfaces – Rust API Reference – Deformable v0.4.1

A render surface is the mesh a host draws. [`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface) prepares it once against the rest mesh of an object, and the [`SurfaceEmbedding`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding) it returns deforms it with the simulated nodes every frame. A breakable surface gets inner faces, which lie on tetrahedron faces inside the object and stay hidden until a crack exposes them. With a splinter cage it takes the splinter path instead: it is cut into bricks, one per cell of the cage, and caps close the cuts.

## ClipMode

**Enum** · `deformable::tools::ClipMode`

```rust
pub enum ClipMode {
    AssignOnly,
    ClipWithInnerFaces,
    TetrahedralMeshBoundary,
}
```

How [`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface) prepares a render surface against the rest mesh: whether
it cuts the surface along the tetrahedron faces, and which inner faces it adds.

An inner face lies on a tetrahedron face inside the object, hidden until a crack exposes it. With a
[`splinter_cage`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#preparationparameters), the two modes other than
[`AssignOnly`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode-assignonly) take the splinter path instead.

**Values**

- `AssignOnly`: Each vertex follows the tetrahedron it lies in, or the nearest one by its weights when it lies outside the
  mesh; nothing is cut and no inner face is made. For objects that bend but never break.
- `ClipWithInnerFaces`: Breakable: the surface is cut along the tetrahedron faces, and the part of each interior tetrahedron
  face inside the surface becomes an inner face. A polygon wholly outside the mesh is kept whole on the nearest
  tetrahedron by its weights.
- `TetrahedralMeshBoundary`: The tetrahedral mesh is the surface: each polygon follows the tetrahedron its centre lies in, uncut, and
  every interior tetrahedron face becomes an inner face. For showing the tetrahedrons themselves.

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

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#choose-how-to-prepare-it) · [C `DeformableClipMode`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformableclipmode) · [Python `ClipMode`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#clipmode)

## PreparationParameters

**Struct** · `deformable::tools::PreparationParameters`

```rust
pub struct PreparationParameters<'a> {
    pub clip_mode: ClipMode,
    pub uv_scale: f64,
    pub splinter_cage: Option<&'a PolygonMesh>,
}
```

The settings of [`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface): how it cuts the surface, the scale of the
planar UVs it makes, and an optional splinter cage.

**Fields**

- `clip_mode` ([`ClipMode`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode)): How the surface is cut, and which inner faces it gets.
- `uv_scale` (`f64`): Scale of the planar UVs of inner and cap faces; the random offsets of inner faces are not scaled. 1 is a good
  start.
- `splinter_cage` ([`Option<&'a PolygonMesh>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#polygonmesh)): The splinter cage in the surface's space, already moved by the host's splinter transform, or `None`. With
  vertices and a clip mode other than [`AssignOnly`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode-assignonly), the surface takes the splinter path:
  it is cut into one brick per cage cell, and the cuts are capped. When no cell holds a part of the surface, the
  surface is prepared as without a cage. [`AssignOnly`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode-assignonly) ignores the cage, but its polygons
  are still checked.

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

**Example**

```rust
// A surface that bends with the object but never breaks.
let parameters = PreparationParameters {
    clip_mode: ClipMode::AssignOnly,
    uv_scale: 1.0,
    splinter_cage: None,
};
let surface = SurfaceMesh { mesh: polygons, ..SurfaceMesh::default() };
let embedding = embed_surface(&mesh, &surface, &parameters)?;
assert_eq!(embedding.surface().mesh.positions.len(), 8);
```

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#choose-how-to-prepare-it) · [C `DeformablePreparationParameters`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformablepreparationparameters) · [Python `PreparationParameters`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#preparationparameters)

## CornerFlags

**Struct** · `deformable::tools::CornerFlags`

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

The flag word of a corner of a prepared surface, as
[`SurfaceEmbedding::corner_flags`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding-corner_flags) gives it: the corner's
controlling tetrahedron in bits 0 to 28, the tetrahedron face of an inner face in bits 29 and 30, and bit 31 set
on the corners of inner faces.

The face bits are set only on inner faces. On the splinter path, the tetrahedron is that of the corner's brick, the
face bits are not set, and bit 31 marks the corners of caps.

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

**See also** [Guide: Read the prepared surface](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#read-the-prepared-surface)

### CornerFlags::TETRAHEDRON_MASK

**Associated constant** · `deformable::tools::CornerFlags::TETRAHEDRON_MASK`

```rust
pub const TETRAHEDRON_MASK: u32 = 0x1FFF_FFFF;
```

The bits holding the controlling tetrahedron: bits 0 to 28.

### CornerFlags::FACE_SHIFT

**Associated constant** · `deformable::tools::CornerFlags::FACE_SHIFT`

```rust
pub const FACE_SHIFT: u32 = 29;
```

The shift of the two face bits, 29 and 30.

### CornerFlags::INNER_FACE

**Associated constant** · `deformable::tools::CornerFlags::INNER_FACE`

```rust
pub const INNER_FACE: u32 = 0x8000_0000;
```

Bit 31, set on the corners of inner faces, and of caps on the splinter path.

### CornerFlags::TETRAHEDRON_LIMIT

**Associated constant** · `deformable::tools::CornerFlags::TETRAHEDRON_LIMIT`

```rust
pub const TETRAHEDRON_LIMIT: usize =
    Self::TETRAHEDRON_MASK as usize + 1;
```

The number of tetrahedrons the word can address, 2 to the power 29: the most the rest mesh of
[`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface) may have.

### CornerFlags::surface

**Associated function** · `deformable::tools::CornerFlags::surface`

```rust
pub const fn surface(tetrahedron: u32) -> Self
```

The word of a corner of the input surface inside `tetrahedron`.

**Parameters**

- `tetrahedron` (`u32`): The controlling tetrahedron; the bits above bit 28 are dropped.

### CornerFlags::inner

**Associated function** · `deformable::tools::CornerFlags::inner`

```rust
pub const fn inner(tetrahedron: u32, face: u32) -> Self
```

The word of a corner of the inner face on face `face` (opposite local node `face`) of `tetrahedron`.

**Parameters**

- `tetrahedron` (`u32`): The tetrahedron whose face the inner face lies on; the bits above bit 28 are dropped.
- `face` (`u32`): The face, 0 to 3, the one opposite local node `face`; only its two low bits are kept.

### CornerFlags::splinter

**Associated function** · `deformable::tools::CornerFlags::splinter`

```rust
pub const fn splinter(cell_tetrahedron: u32, cap: bool) -> Self
```

The word of a corner on the splinter path: the brick's controlling tetrahedron, with the inner bit on
the corners of cap faces and no face bits.

**Parameters**

- `cell_tetrahedron` (`u32`): The controlling tetrahedron of the corner's brick; the bits above bit 28 are dropped.
- `cap` (`bool`): Whether the corner is on a cap face, which sets the inner bit.

### CornerFlags::tetrahedron

**Method** · `deformable::tools::CornerFlags::tetrahedron`

```rust
pub const fn tetrahedron(self) -> u32
```

The controlling tetrahedron: bits 0 to 28.

### CornerFlags::face

**Method** · `deformable::tools::CornerFlags::face`

```rust
pub const fn face(self) -> u32
```

The tetrahedron face of an inner face, 0 to 3: bits 29 and 30, which are 0 on other corners.

### CornerFlags::is_inner

**Method** · `deformable::tools::CornerFlags::is_inner`

```rust
pub const fn is_inner(self) -> bool
```

True on the corners of inner faces, and of caps on the splinter path: bit 31.

## SkinningOptions

**Struct** · `deformable::scene::SkinningOptions`

```rust
pub struct SkinningOptions {
    pub show_inner_faces: bool,
    pub start_splintered: bool,
}
```

The per-frame skinning options: which hidden faces [`SurfaceEmbedding::deform`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding-deform) shows. The default turns both off.

**Fields**

- `show_inner_faces` (`bool`): Shows every inner face and cap, exposed or not, so no face is hidden: useful to inspect the preparation.
  Default `false`.
- `start_splintered` (`bool`): With splinter data, shows the caps from the start instead of once a tetrahedron of theirs is flagged, as for an
  object that starts out split. Default `false`.

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

**Example**

```rust
let surface = SurfaceMesh { mesh: polygons, ..SurfaceMesh::default() };
let parameters = PreparationParameters {
    clip_mode: ClipMode::ClipWithInnerFaces,
    uv_scale: 1.0,
    splinter_cage: None,
};
let embedding = embed_surface(&mesh, &surface, &parameters)?;
let mut states = Vec::new();
scene.tetrahedron_states(object, &mut states)?;
let mut deformed = DeformedSurface::default();
// Every inner face shown, to inspect the preparation.
let options = SkinningOptions {
    show_inner_faces: true,
    ..SkinningOptions::default()
};
let identity = AffineTransform::IDENTITY;
embedding.deform(&states, &identity, options, &mut deformed)?;
assert!(deformed.hidden_faces.iter().all(|&hidden| !hidden));
```

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#skin-it-every-frame) · [C `DeformableSkinningOptions`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformableskinningoptions) · [Python `SkinningOptions`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#skinningoptions)

## DeformedSurface

**Struct** · `deformable::scene::DeformedSurface`

```rust
pub struct DeformedSurface {
    pub positions: Vec<[f32; 3]>,
    pub normals: Vec<[f32; 3]>,
    pub hidden_faces: Vec<bool>,
    /* private fields */
}
```

A skinned surface in the object space of the host's shape: f32 positions per output vertex, unit f32
normals per corner (empty when the surface has none) and the faces to hide.

Made with `DeformedSurface::default` and refilled by every [`SurfaceEmbedding::deform`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding-deform) into it: keep one per
surface across frames, so the library's skinning buffers are allocated once.

**Fields**

- `positions` (`Vec<[f32; 3]>`): The deformed position of each output vertex, mapped by the inverse world transform.
- `normals` (`Vec<[f32; 3]>`): The deformed normal of each corner, `embed(p + n) - embed(p)` mapped by the linear part of the inverse world
  transform and made unit length; a zero vector stays zero. Empty when the surface has no normals.
- `hidden_faces` (`Vec<bool>`): True for each face the host hides: an inner face or cap not shown yet.

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

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#skin-it-every-frame) · [C `DeformableDeformedSurface`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformabledeformedsurface) · [C `DeformableDeformedSurfaceView`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformabledeformedsurfaceview) · [Python `DeformedSurface`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#deformedsurface)

## SurfaceEmbedding

**Struct** · `deformable::scene::SurfaceEmbedding`

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

A prepared surface in rest space, made by [`embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#embed_surface): the output surface, the tetrahedron and barycentric
weights each output vertex follows, the flag word of each corner, the weights of the corner normals, and on the
splinter path each vertex's cell tetrahedron.

An input vertex becomes one output vertex for each flag word and tetrahedron among its corners, so the surface can
open along the cracks. A vertex outside the rest mesh follows the nearest tetrahedron by its weights (the one whose
smallest barycentric weight is largest), with weights that extrapolate. Reading and skinning never change the
embedding, so any number of threads may use one embedding at the same time. It owns the library's arrays and frees
them when dropped.

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

**See also** [Guide: Read the prepared surface](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#read-the-prepared-surface) · [C `DeformableSurfaceEmbedding`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformablesurfaceembedding) · [Python `SurfaceEmbedding`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#surfaceembedding)

### SurfaceEmbedding::surface

**Method** · `deformable::scene::SurfaceEmbedding::surface`

```rust
pub fn surface(&self) -> &SurfaceMesh
```

The prepared surface in rest space: output vertices, polygons and per-corner channels. It can have more vertices
than the input, as a vertex is split where a crack can open; with
[`ClipMode::AssignOnly`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode-assignonly) it keeps one vertex per input vertex a polygon
uses. Build the render mesh from it once.

### SurfaceEmbedding::corner_flags

**Method** · `deformable::scene::SurfaceEmbedding::corner_flags`

```rust
pub fn corner_flags(&self) -> &[CornerFlags]
```

The flag word of each corner of [`surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding-surface), in corner order: its controlling tetrahedron, the
tetrahedron face of an inner face, and whether it is on an inner face or cap.

### SurfaceEmbedding::source_faces

**Method** · `deformable::scene::SurfaceEmbedding::source_faces`

```rust
pub fn source_faces(&self) -> &[i32]
```

The input face each output face was cut from, in face order; -1 for inner faces and caps.

### SurfaceEmbedding::vertex_tetrahedrons

**Method** · `deformable::scene::SurfaceEmbedding::vertex_tetrahedrons`

```rust
pub fn vertex_tetrahedrons(&self) -> &[u32]
```

The controlling tetrahedron of each output vertex, the one it follows.

### SurfaceEmbedding::vertex_weights

**Method** · `deformable::scene::SurfaceEmbedding::vertex_weights`

```rust
pub fn vertex_weights(&self) -> &[BarycentricCoordinates]
```

The barycentric weights of each output vertex in its tetrahedron; some are negative for a vertex outside it.

### SurfaceEmbedding::normal_weights

**Method** · `deformable::scene::SurfaceEmbedding::normal_weights`

```rust
pub fn normal_weights(&self) -> &[BarycentricCoordinates]
```

The barycentric weights of `p + n` for each corner, the tip of its normal `n` at its position `p`, in its
vertex's tetrahedron; empty when the surface has no normals.

### SurfaceEmbedding::brick_tetrahedrons

**Method** · `deformable::scene::SurfaceEmbedding::brick_tetrahedrons`

```rust
pub fn brick_tetrahedrons(&self) -> &[u32]
```

The controlling tetrahedron of each brick of the splinter path, one brick per cage cell that holds a part of
the surface; empty without splinter data.

### SurfaceEmbedding::vertex_cell_tetrahedrons

**Method** · `deformable::scene::SurfaceEmbedding::vertex_cell_tetrahedrons`

```rust
pub fn vertex_cell_tetrahedrons(&self) -> &[u32]
```

The cell tetrahedron of each output vertex on the splinter path, the one it follows once its cell has broken
loose; empty without splinter data.

### SurfaceEmbedding::deform

**Method** · `deformable::scene::SurfaceEmbedding::deform`

```rust
pub fn deform(
    &self,
    states: &[TetrahedronState],
    world_transform: &AffineTransform,
    options: SkinningOptions,
    output: &mut DeformedSurface,
) -> Result<(), Error>
```

Skins the surface on the current tetrahedron states into `output`, in the object space of the host's shape:
positions and unit normals in f32, mapped by the inverse of `world_transform`, and the faces to hide.

Each output vertex follows its tetrahedron by its weights. On the splinter path it switches to its cell
tetrahedron once its cell has broken loose: once that tetrahedron or its own has a state flag word other than
0, or the two sit in different islands. Each corner normal is mapped by the linear part of the inverse, then
made unit length; a zero one stays zero. A face is hidden while it is an inner face whose tetrahedron face no
fracture has exposed, or a cap whose brick tetrahedron and the own tetrahedron of its first corner both still
have a state flag word of 0, unless `options` say to show it. The states are
not checked: a NaN or infinite corner gives NaN or infinite positions. Skinning never changes the embedding,
so several threads may skin one embedding at the same time, each into its own output.

**Parameters**

- `states` ([`&[TetrahedronState]`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#tetrahedronstate)): The object's tetrahedron states this frame, one per rest tetrahedron, as
  [`Scene::tetrahedron_states`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#scene-tetrahedron_states) gives them.
- `world_transform` ([`&AffineTransform`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#affinetransform)): The world matrix of the host's shape; [`AffineTransform::IDENTITY`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/math/#affinetransform-identity) when the surface is in
  world space.
- `options` ([`SkinningOptions`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#skinningoptions)): Which hidden faces to show.
- `output` ([`&mut DeformedSurface`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#deformedsurface)): Filled with the skinned surface, its contents replaced; keep one per surface across frames.

**Errors**

- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-lengthmismatch): `states` does not hold one state per
  tetrahedron of the rest mesh.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): An entry of `world_transform` is NaN or
  infinite.
- [`SingularTransform`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-singulartransform): `world_transform` has no inverse: the
  determinant of its linear part is 0, or the inverse overflows.

**Example**

```rust
let surface = SurfaceMesh { mesh: polygons, ..SurfaceMesh::default() };
let parameters = PreparationParameters {
    clip_mode: ClipMode::AssignOnly,
    uv_scale: 1.0,
    splinter_cage: None,
};
let embedding = embed_surface(&mesh, &surface, &parameters)?;
let mut states = Vec::new();
let mut deformed = DeformedSurface::default();
// Every frame, after the step:
scene.tetrahedron_states(object, &mut states)?;
let identity = AffineTransform::IDENTITY;
let options = SkinningOptions::default();
embedding.deform(&states, &identity, options, &mut deformed)?;
assert_eq!(deformed.positions.len(), 8);
```

**See also** [Guide: Skin it every frame](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#skin-it-every-frame) · [C `deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) · [Python `SurfaceEmbedding.deform`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#surfaceembedding-deform)

## embed_surface

**Function** · `deformable::scene::embed_surface`

```rust
pub fn embed_surface(
    rest: &TetrahedralMesh,
    surface: &SurfaceMesh,
    parameters: &PreparationParameters<'_>,
) -> Result<SurfaceEmbedding, Error>
```

Prepares a render surface against the rest mesh of an object: cuts it as the clip mode says, adds inner faces
with random planar UVs times `uv_scale`, takes the splinter path when a splinter cage is given, then embeds each
output vertex in a tetrahedron by barycentric weights.

The prepared surface keeps every channel the input has, with opaque white as the colour of inner faces. With
[`ClipMode::ClipWithInnerFaces`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#clipmode-clipwithinnerfaces) and on the splinter path, a polygon of
fewer than 3 corners is left out. The random stream that turns and offsets the UVs of inner faces has a fixed seed,
so equal input gives equal UVs.

**Parameters**

- `rest` ([`&TetrahedralMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#tetrahedralmesh)): The object's tetrahedral mesh at rest, in the space of `surface`: the mesh given to
  [`Scene::add_object`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/scene/#scene-add_object), or that mesh before the host moved it to world
  space, with the same tetrahedrons in the same order.
- `surface` ([`&SurfaceMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/meshes/#surfacemesh)): The render surface: its polygons, and per-corner normals, UV sets and colours where it has them.
- `parameters` ([`&PreparationParameters<'_>`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#preparationparameters)): How the surface is cut, the scale of the UVs the call makes, and an optional splinter cage.

**Returns**

[`SurfaceEmbedding`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding): The prepared surface with its embedding, to skin every frame with [`SurfaceEmbedding::deform`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/render-surfaces/#surfaceembedding-deform).

**Errors**

- [`EmptyMesh`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-emptymesh): `rest` has no tetrahedrons.
- [`IndexOutOfRange`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-indexoutofrange): A tetrahedron of `rest` names a node past
  the end of its positions, `rest` has more tetrahedrons than a corner flag word addresses (2 to the power 29),
  or a corner of `surface` or of the splinter cage names a vertex past the end of its positions.
- [`LengthMismatch`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-lengthmismatch): The polygon sizes of `surface` or of the
  splinter cage do not add up to its corner count, the normals or the colours of `surface` hold neither 0 entries
  nor one per corner, a UV set of `surface` does not hold one pair per corner, or `surface` has more than
  2,147,483,647 polygons.
- [`NonFiniteValue`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonfinitevalue): A position of `rest`, `surface` or the
  splinter cage, a normal, UV or colour of `surface`, or `uv_scale` is NaN or infinite.
- [`NonManifoldFace`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-nonmanifoldface): Three or more tetrahedrons of `rest` share a
  face.
- [`InvalidSplinterCage`](https://help.tangerina.io/deformable/v0.4.1/api-references/rust/errors/#errorkind-invalidsplintercage): A polygon of the splinter cage has
  fewer than 3 vertices, or on the splinter path, a brick has 3 faces or fewer.

**Example**

```rust
let surface = SurfaceMesh { mesh: polygons, ..SurfaceMesh::default() };
let parameters = PreparationParameters {
    clip_mode: ClipMode::ClipWithInnerFaces,
    uv_scale: 1.0,
    splinter_cage: None,
};
let embedding = embed_surface(&mesh, &surface, &parameters)?;
assert!(embedding.source_faces().contains(&-1)); // inner faces
```

**See also** [Guide: Choose how to prepare it](https://help.tangerina.io/deformable/v0.4.1/user-guides/rust/render-surfaces/#choose-how-to-prepare-it) · [C `deformable_embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/c/render-surfaces/#deformable_embed_surface) · [Python `embed_surface`](https://help.tangerina.io/deformable/v0.4.1/api-references/python/render-surfaces/#embed_surface)
