﻿---
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.1.1/api-references/c/render-surfaces/
---

# Render surfaces – C API Reference – Deformable v0.1.1

A render surface is the mesh a host draws. [`deformable_embed_surface`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_embed_surface) prepares it once against the rest mesh of an object, and the [`DeformableSurfaceEmbedding`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembedding) 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.

## DeformableClipMode

**Enum** · `deformable.h`

```c
typedef int32_t DeformableClipMode;
```

How [`deformable_embed_surface`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_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
(the `splinter_cage` of [`DeformablePreparationParameters`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablepreparationparameters)), the two modes other than `DEFORMABLE_CLIP_MODE_ASSIGN_ONLY`
take the splinter path instead.

**Values**

- `DEFORMABLE_CLIP_MODE_ASSIGN_ONLY` (`0`): 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.
- `DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES` (`2`): 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.
- `DEFORMABLE_CLIP_MODE_TETRAHEDRAL_MESH_BOUNDARY` (`3`): 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.

**See also** [Guide: Prepare the surface](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/render-surfaces/#prepare-the-surface) · [Rust `ClipMode`](https://help.tangerina.io/deformable/v0.1.1/api-references/rust/render-surfaces/#clipmode) · [Python `ClipMode`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#clipmode)

## DeformablePreparationParameters

**Struct** · `deformable.h`

```c
typedef struct DeformablePreparationParameters {
    DeformableClipMode clip_mode;
    double uv_scale;
    const DeformablePolygonMeshView *splinter_cage;
} DeformablePreparationParameters;
```

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

**Fields**

- `clip_mode` ([`DeformableClipMode`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformableclipmode)): How the surface is cut, and which inner faces it gets.
- `uv_scale` (`double`): 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` ([`const DeformablePolygonMeshView *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/meshes/#deformablepolygonmeshview)): The splinter cage in the surface's space, already moved by the host's splinter transform, or `NULL`. With
  vertices and a clip mode other than [`DEFORMABLE_CLIP_MODE_ASSIGN_ONLY`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformableclipmode-deformable_clip_mode_assign_only), 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. `DEFORMABLE_CLIP_MODE_ASSIGN_ONLY` ignores the cage, but its polygons are still
  checked.

**Example**

```c
// A surface that bends with the object but never breaks.
DeformablePreparationParameters parameters = {0};
parameters.clip_mode = DEFORMABLE_CLIP_MODE_ASSIGN_ONLY;
parameters.uv_scale = 1.0;
DeformableSurfaceMeshView surface = {0};
surface.mesh = polygons;
DeformableSurfaceEmbedding *embedding = NULL;
CHECK(deformable_embed_surface(&mesh, &surface, &parameters,
                               &embedding));
deformable_surface_embedding_destroy(embedding);
```

**See also** [Guide: Prepare the surface](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/render-surfaces/#prepare-the-surface) · [Rust `PreparationParameters`](https://help.tangerina.io/deformable/v0.1.1/api-references/rust/render-surfaces/#preparationparameters) · [Python `PreparationParameters`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#preparationparameters)

## DeformableSkinningOptions

**Struct** · `deformable.h`

```c
typedef struct DeformableSkinningOptions {
    uint8_t show_inner_faces;
    uint8_t start_splintered;
} DeformableSkinningOptions;
```

The per-frame skinning options: which hidden faces [`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) shows. A zeroed struct turns
both off.

**Fields**

- `show_inner_faces` (`uint8_t`): Not 0: shows every inner face and cap, exposed or not, so no face is hidden: useful to inspect the
  preparation.
- `start_splintered` (`uint8_t`): Not 0: 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.

**Example**

```c
DeformablePreparationParameters parameters = {0};
parameters.clip_mode = DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES;
DeformableSurfaceMeshView surface = {0};
surface.mesh = polygons;
DeformableSurfaceEmbedding *embedding = NULL;
CHECK(deformable_embed_surface(&mesh, &surface, &parameters,
                               &embedding));
const DeformableTetrahedronState *states;
size_t count;
CHECK(deformable_scene_tetrahedron_states(scene, object,
                                          &states, &count));
DeformableAffineTransform identity = {
    {{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0, 0, 0}};
// Every inner face shown, to inspect the preparation.
DeformableSkinningOptions options = {1, 0};
DeformableDeformedSurface *deformed = NULL;
CHECK(deformable_deformed_surface_create(&deformed));
CHECK(deformable_surface_embedding_deform(embedding, states, count,
                                          &identity, &options,
                                          deformed));
deformable_deformed_surface_destroy(deformed);
deformable_surface_embedding_destroy(embedding);
```

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

## DeformableDeformedSurface

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

```c
typedef struct DeformableDeformedSurface DeformableDeformedSurface;
```

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

Made with [`deformable_deformed_surface_create`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_deformed_surface_create) and refilled by every [`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) into it: keep
one per surface across frames, so its buffers are allocated once. One deform may fill it at a time: give each
thread that skins its own. Read it with [`deformable_deformed_surface_view`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_deformed_surface_view) and free it with
[`deformable_deformed_surface_destroy`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_deformed_surface_destroy).

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

### deformable_deformed_surface_create

**Function** · `deformable.h`

```c
DeformableStatus deformable_deformed_surface_create(
    DeformableDeformedSurface **deformed);
```

Creates an empty skinned surface for [`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) to fill. Make one per surface and reuse it
every frame: each deform into it replaces its contents and reuses its buffers.

**Parameters**

- `deformed` ([`DeformableDeformedSurface **`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformabledeformedsurface)): Out. Receives a new handle; free it with [`deformable_deformed_surface_destroy`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_deformed_surface_destroy).

**Errors**

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

### deformable_deformed_surface_view

**Function** · `deformable.h`

```c
DeformableStatus deformable_deformed_surface_view(
    const DeformableDeformedSurface *deformed,
    DeformableDeformedSurfaceView *view);
```

Lends the arrays of a skinned surface: the positions, the corner normals and the faces to hide.

**Parameters**

- `deformed` ([`const DeformableDeformedSurface *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformabledeformedsurface)): The skinned surface to read.
- `view` ([`DeformableDeformedSurfaceView *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformabledeformedsurfaceview)): Out. Receives the arrays, owned by `deformed` and valid until the next [`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) into it or its destruction.

**Errors**

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

### deformable_deformed_surface_destroy

**Function** · `deformable.h`

```c
void deformable_deformed_surface_destroy(
    DeformableDeformedSurface *deformed);
```

Destroys a skinned surface; `NULL` is ignored. Views of it become invalid.

**Parameters**

- `deformed` ([`DeformableDeformedSurface *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformabledeformedsurface)): The skinned surface to destroy, or `NULL`.

## DeformableDeformedSurfaceView

**Struct** · `deformable.h`

```c
typedef struct DeformableDeformedSurfaceView {
    const float (*positions)[3];
    size_t position_count;
    const float (*normals)[3];
    size_t normal_count;
    const uint8_t *hidden_faces;
    size_t face_count;
} DeformableDeformedSurfaceView;
```

The arrays of a skinned surface, as [`deformable_deformed_surface_view`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_deformed_surface_view) lends them: owned by it, in the object space
of the host's shape.

**Fields**

- `positions` (`const float (*)[3]`): The deformed position of each output vertex, mapped by the inverse world transform.
- `position_count` (`size_t`): The number of output vertices.
- `normals` (`const float (*)[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 left zero; none when the surface has no normals.
- `normal_count` (`size_t`): The number of corner normals: the corner count, or 0 without normals.
- `hidden_faces` (`const uint8_t *`): 1 for each face the host hides (an inner face or cap not shown yet), 0 for the others.
- `face_count` (`size_t`): The number of faces.

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

## DeformableSurfaceEmbedding

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

```c
typedef struct DeformableSurfaceEmbedding DeformableSurfaceEmbedding;
```

A prepared surface in rest space, made by [`deformable_embed_surface`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_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. Read it with [`deformable_surface_embedding_view`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_view), skin it with
[`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform) and free it with [`deformable_surface_embedding_destroy`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_destroy).

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.

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

### deformable_surface_embedding_view

**Function** · `deformable.h`

```c
DeformableStatus deformable_surface_embedding_view(
    const DeformableSurfaceEmbedding *embedding,
    DeformableSurfaceEmbeddingView *view);
```

Lends the arrays of a surface embedding: the prepared surface in rest space, the flag word of each corner, the
source face of each face, and the tetrahedron and weights each vertex follows.

**Parameters**

- `embedding` ([`const DeformableSurfaceEmbedding *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembedding)): The embedding to read.
- `view` ([`DeformableSurfaceEmbeddingView *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembeddingview)): Out. Receives the arrays, owned by `embedding` and valid until it is destroyed.

**Errors**

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

**See also** [Python `SurfaceEmbedding.arrays`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#surfaceembedding-arrays)

### deformable_surface_embedding_deform

**Function** · `deformable.h`

```c
DeformableStatus deformable_surface_embedding_deform(
    const DeformableSurfaceEmbedding *embedding,
    const DeformableTetrahedronState *states,
    size_t state_count,
    const DeformableAffineTransform *world_transform,
    const DeformableSkinningOptions *options,
    DeformableDeformedSurface *deformed);
```

Skins the surface on the current tetrahedron states into `deformed`, in the object space of the host's shape:
positions and unit normals in float, 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 deformed surface.

**Parameters**

- `embedding` ([`const DeformableSurfaceEmbedding *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembedding)): The embedding to skin.
- `states` ([`const DeformableTetrahedronState *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/scene/#deformabletetrahedronstate)): The object's tetrahedron states this frame, one per rest tetrahedron, as [`deformable_scene_tetrahedron_states`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/scene/#deformable_scene_tetrahedron_states) lends them.
- `state_count` (`size_t`): The number of `states`.
- `world_transform` ([`const DeformableAffineTransform *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/math/#deformableaffinetransform)): The world matrix of the host's shape; the identity when the surface is in world space.
- `options` ([`const DeformableSkinningOptions *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformableskinningoptions)): Which hidden faces to show.
- `deformed` ([`DeformableDeformedSurface *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformabledeformedsurface)): The skinned surface to fill, its contents replaced; keep one per surface across frames. Views of it taken before become invalid.

**Errors**

- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): `state_count` is not the tetrahedron count of the rest mesh.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): An entry of `world_transform` is NaN or infinite.
- [`DEFORMABLE_STATUS_SINGULAR_TRANSFORM`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_singular_transform): `world_transform` has no inverse: the determinant of its linear part is 0, or the inverse overflows.
- The [license statuses](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/memory-and-errors/#license-statuses) every engine call can return.

**Example**

```c
DeformablePreparationParameters parameters = {0}; // assign only
DeformableSurfaceMeshView surface = {0};
surface.mesh = polygons;
DeformableSurfaceEmbedding *embedding = NULL;
CHECK(deformable_embed_surface(&mesh, &surface, &parameters,
                               &embedding));
DeformableDeformedSurface *deformed = NULL;
CHECK(deformable_deformed_surface_create(&deformed));
// Every frame, after the step:
const DeformableTetrahedronState *states;
size_t count;
CHECK(deformable_scene_tetrahedron_states(scene, object,
                                          &states, &count));
DeformableAffineTransform identity = {
    {{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0, 0, 0}};
DeformableSkinningOptions options = {0, 0};
CHECK(deformable_surface_embedding_deform(embedding, states, count,
                                          &identity, &options,
                                          deformed));
deformable_deformed_surface_destroy(deformed);
deformable_surface_embedding_destroy(embedding);
```

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

### deformable_surface_embedding_destroy

**Function** · `deformable.h`

```c
void deformable_surface_embedding_destroy(
    DeformableSurfaceEmbedding *embedding);
```

Destroys a surface embedding; `NULL` is ignored. Views of it become invalid.

**Parameters**

- `embedding` ([`DeformableSurfaceEmbedding *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembedding)): The embedding to destroy, or `NULL`.

**See also** [Python `SurfaceEmbedding.close`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#surfaceembedding-close)

## DeformableSurfaceEmbeddingView

**Struct** · `deformable.h`

```c
typedef struct DeformableSurfaceEmbeddingView {
    DeformableSurfaceMeshView surface;
    const uint32_t *corner_flags;
    size_t corner_flag_count;
    const int32_t *source_faces;
    size_t source_face_count;
    const uint32_t *vertex_tetrahedrons;
    size_t vertex_tetrahedron_count;
    const double (*vertex_weights)[4];
    size_t vertex_weight_count;
    const double (*normal_weights)[4];
    size_t normal_weight_count;
    const uint32_t *brick_tetrahedrons;
    size_t brick_tetrahedron_count;
    const uint32_t *vertex_cell_tetrahedrons;
    size_t vertex_cell_tetrahedron_count;
} DeformableSurfaceEmbeddingView;
```

The arrays of a surface embedding, as [`deformable_surface_embedding_view`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_view) lends them: owned by the embedding and
valid until it is destroyed.

**Fields**

- `surface` ([`DeformableSurfaceMeshView`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/meshes/#deformablesurfacemeshview)): 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 [`DEFORMABLE_CLIP_MODE_ASSIGN_ONLY`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformableclipmode-deformable_clip_mode_assign_only) it
  keeps one vertex per input vertex a polygon uses. Build the render mesh from it once.
- `corner_flags` (`const uint32_t *`): The flag word of each corner of `surface`, in corner order: bits 0 to 28 the controlling tetrahedron, bits 29
  and 30 the tetrahedron face of an inner face, bit 31 set on the corners of 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.
- `corner_flag_count` (`size_t`): The number of corner flag words: the corner count of `surface`.
- `source_faces` (`const int32_t *`): The input face each output face was cut from, in face order; -1 for inner faces and caps.
- `source_face_count` (`size_t`): The number of output faces.
- `vertex_tetrahedrons` (`const uint32_t *`): The controlling tetrahedron of each output vertex, the one it follows.
- `vertex_tetrahedron_count` (`size_t`): The number of output vertices.
- `vertex_weights` (`const double (*)[4]`): The barycentric weights of each output vertex in its tetrahedron; some are negative for a vertex outside it.
- `vertex_weight_count` (`size_t`): The number of vertex weights: one per output vertex.
- `normal_weights` (`const double (*)[4]`): The barycentric weights of `p + n` for each corner, the tip of its normal `n` at its position `p`, in its
  vertex's tetrahedron; none when the surface has no normals.
- `normal_weight_count` (`size_t`): The number of normal weights: the corner count, or 0 without normals.
- `brick_tetrahedrons` (`const uint32_t *`): The controlling tetrahedron of each brick of the splinter path, one brick per cage cell that holds a part of
  the surface; none without splinter data.
- `brick_tetrahedron_count` (`size_t`): The number of bricks.
- `vertex_cell_tetrahedrons` (`const uint32_t *`): The cell tetrahedron of each output vertex on the splinter path, the one it follows once its cell has broken
  loose; none without splinter data.
- `vertex_cell_tetrahedron_count` (`size_t`): The number of cell tetrahedrons: one per output vertex, or 0 without splinter data.

**See also** [Guide: The prepared surface](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/render-surfaces/#the-prepared-surface) · [Python `SurfaceEmbeddingArrays`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#surfaceembeddingarrays)

## deformable_embed_surface

**Function** · `deformable.h`

```c
DeformableStatus deformable_embed_surface(
    const DeformableTetrahedralMeshView *rest,
    const DeformableSurfaceMeshView *surface,
    const DeformablePreparationParameters *parameters,
    DeformableSurfaceEmbedding **embedding);
```

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
[`DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformableclipmode-deformable_clip_mode_clip_with_inner_faces) 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. The
call copies what it needs: the inputs may be freed once it returns.

**Parameters**

- `rest` ([`const DeformableTetrahedralMeshView *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/meshes/#deformabletetrahedralmeshview)): The object's tetrahedral mesh at rest, in the space of `surface`: the mesh given to [`deformable_scene_add_object`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/scene/#deformable_scene_add_object), or that mesh before the host moved it to world space, with the same tetrahedrons in the same order.
- `surface` ([`const DeformableSurfaceMeshView *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/meshes/#deformablesurfacemeshview)): The render surface: its polygons, and per-corner normals, UV sets and colours where it has them.
- `parameters` ([`const DeformablePreparationParameters *`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablepreparationparameters)): How the surface is cut, the scale of the UVs the call makes, and an optional splinter cage.
- `embedding` ([`DeformableSurfaceEmbedding **`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformablesurfaceembedding)): Out. Receives a new handle; free it with [`deformable_surface_embedding_destroy`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_ok), and the prepared surface with its embedding in `embedding`: read it with [`deformable_surface_embedding_view`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_view), and skin it every frame with [`deformable_surface_embedding_deform`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/render-surfaces/#deformable_surface_embedding_deform).

**Errors**

- [`DEFORMABLE_STATUS_EMPTY_MESH`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_empty_mesh): `rest` has no tetrahedrons.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): 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.
- [`DEFORMABLE_STATUS_LENGTH_MISMATCH`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_length_mismatch): The polygon sizes of `surface` or of the splinter cage do not add up to its `corner_count`, the `normal_count` or `colour_count` of `surface` is neither 0 nor its corner count, or `surface` has more than 2,147,483,647 polygons.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A position of `rest`, `surface` or the splinter cage, a normal, UV or colour of `surface`, or `uv_scale` is NaN or infinite.
- [`DEFORMABLE_STATUS_NON_MANIFOLD_FACE`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_non_manifold_face): Three or more tetrahedrons of `rest` share a face.
- [`DEFORMABLE_STATUS_INVALID_SPLINTER_CAGE`](https://help.tangerina.io/deformable/v0.1.1/api-references/c/errors/#deformablestatus-deformable_status_invalid_splinter_cage): A polygon of the splinter cage has fewer than 3 vertices, or on the splinter path, a brick has 3 faces or fewer.
- The [license statuses](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/memory-and-errors/#license-statuses) every engine call can return.

**Example**

```c
DeformablePreparationParameters parameters = {0};
parameters.clip_mode = DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES;
parameters.uv_scale = 1.0;
DeformableSurfaceMeshView surface = {0};
surface.mesh = polygons;
DeformableSurfaceEmbedding *embedding = NULL;
CHECK(deformable_embed_surface(&mesh, &surface, &parameters,
                               &embedding));
deformable_surface_embedding_destroy(embedding);
```

**See also** [Guide: Prepare the surface](https://help.tangerina.io/deformable/v0.1.1/user-guides/c/render-surfaces/#prepare-the-surface) · [Rust `embed_surface`](https://help.tangerina.io/deformable/v0.1.1/api-references/rust/render-surfaces/#embed_surface) · [Python `embed_surface`](https://help.tangerina.io/deformable/v0.1.1/api-references/python/render-surfaces/#embed_surface)
