﻿---
title: Render surfaces
description: Embed a detailed render mesh in a simulated object from C, skin it every frame, and show the inner faces that cracks open.
url: https://help.tangerina.io/deformable/v0.4.0/user-guides/c/render-surfaces/
---

# Render surfaces – C SDK – Deformable v0.4.0

`deformable_embed_surface` binds a render surface to an object's tetrahedrons once, at rest. Then
`deformable_surface_embedding_deform` moves it with the simulation every frame. What a render surface keeps, the clip
modes, and how inner faces and splinters show where an object breaks are on
[Render surfaces](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/render-surfaces/) in the Engine guide; this page shows the calls. For
the full signature and documentation of every function and struct, see the
[C API Reference](https://help.tangerina.io/deformable/v0.4.0/api-references/c/render-surfaces/).

## The flow

1. Build the object's rest tetrahedral mesh, and add it with `deformable_scene_add_object`.
2. Call `deformable_embed_surface` once with the same rest mesh and your render surface. It writes a
   `DeformableSurfaceEmbedding`.
3. Read the prepared surface with `deformable_surface_embedding_view`, and give it to your renderer.
4. Create one `DeformableDeformedSurface` per object with `deformable_deformed_surface_create`.
5. Each frame, after the step, pass the object's tetrahedron states to `deformable_surface_embedding_deform`, then
   copy the positions, normals and hidden faces from `deformable_deformed_surface_view` into your renderer.

![A render surface sits inside the rest tetrahedral mesh, and when the tetrahedrons bend, the surface bends with them.](https://help.tangerina.io/deformable/v0.4.0/images/sdk-surface-embedded-in-tetrahedrons.svg)

## The render surface

A `DeformableSurfaceMeshView` is a polygon mesh with optional channels, one entry per corner:

- `normals` is empty (count 0) or holds one normal per corner. The embedding keeps your normals, hard edges
  included.
- `uvs` holds `uv_set_count` UV sets one after the other, each with one coordinate pair per corner.
- `colours` is empty or holds one red, green, blue and alpha colour per corner.

The surface is in the same space and units as the rest mesh of the object.

## Prepare the surface

`deformable_embed_surface` takes the rest mesh, the render surface and a `DeformablePreparationParameters`. The rest
mesh is the mesh you passed to `deformable_scene_add_object`, with the same nodes in the same order. The clip mode says
how the surface is cut; which one suits which object is on
[Clip modes](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/render-surfaces/#clip-modes):

| Clip mode | What the call makes |
|---|---|
| `DEFORMABLE_CLIP_MODE_ASSIGN_ONLY` | Each vertex follows the tetrahedron it lies in. Nothing is cut, and no inner face is made. |
| `DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES` | Cuts the surface along the tetrahedron faces, and adds the inside of each face as a hidden inner face. |
| `DEFORMABLE_CLIP_MODE_TETRAHEDRAL_MESH_BOUNDARY` | The tetrahedral mesh is the surface; every interior face becomes an inner face. |

![A block with a crack path marked on its surface, then broken in two along tetrahedron faces, with the inner faces along the crack now showing.](https://help.tangerina.io/deformable/v0.4.0/images/sdk-inner-faces-show-on-cracks.svg)

`uv_scale` scales the planar UVs of the inner faces; 1 is a good start. `splinter_cage` is `NULL`, or a splinter
cage; see [Break along splinters](#break-along-splinters).

The embedding is a new handle. It never changes after it is made, so any number of threads can read and skin one
embedding at the same time.

### The prepared surface

`deformable_surface_embedding_view` lends the prepared surface: your surface cut along the tetrahedrons, plus the
inner faces. Render this mesh, not your input mesh: it has its own vertices, faces and corners.

| Field of `DeformableSurfaceEmbeddingView` | What it holds |
|---|---|
| `surface` | The prepared surface at rest, a `DeformableSurfaceMeshView` with every channel your input had. |
| `source_faces` | For each prepared face, the input face it was cut from, or -1 for an inner face or a cap. Use it to keep per-face materials, and give the -1 faces your [inner material](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/render-surfaces/#inner-faces). |
| `corner_flags` | For each corner, the tetrahedron that controls it 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. 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. |
| `vertex_tetrahedrons`, `vertex_weights` | For each vertex, its tetrahedron and its four barycentric weights. |
| `normal_weights` | For each corner, the weights that carry its normal; empty without normals. |
| `brick_tetrahedrons`, `vertex_cell_tetrahedrons` | The splinter data; empty without a splinter cage. |

## Skin it every frame

A `DeformableDeformedSurface` holds the skinned surface. Create one per object and reuse it every frame. Each frame:

1. Read the object's states with `deformable_scene_tetrahedron_states`.
2. Call `deformable_surface_embedding_deform` with them. The state count must equal the tetrahedron count of the
   rest mesh, or the call returns `DEFORMABLE_STATUS_LENGTH_MISMATCH`.
3. Read the result with `deformable_deformed_surface_view`, and copy it into your renderer.

The `DeformableDeformedSurfaceView` holds:

- `positions`: one position per prepared vertex, as three `float` values.
- `normals`: one unit normal per corner, as three `float` values. It is empty when your surface had no normals.
- `hidden_faces`: 1 for each face to hide, and 0 for each face to show. An inner face stays hidden until a crack
  exposes the tetrahedron face it lies on. With `show_inner_faces` not 0 in the `DeformableSkinningOptions`, every
  face is shown.

The arrays stay valid until the next `deformable_surface_embedding_deform` into the same handle.

### World transform

The simulation works in world space, but a host usually stores a mesh in its object's own space. The world
transform is the object's world matrix: the call maps the skinned surface back through its inverse, so the result is
in the object's space. Pass the identity when your surface is already in world space.

A `DeformableAffineTransform` maps a point p, as a row vector, to p · `linear` + `translation`. This one places an
object at (0, 2.5, 0) without rotation or scale:

```c
const DeformableAffineTransform world = {{{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0, 2.5, 0}};
```

A transform with no inverse gives `DEFORMABLE_STATUS_SINGULAR_TRANSFORM`.

## Example

This program drops the glass cube of [Scene](https://help.tangerina.io/deformable/v0.4.0/user-guides/c/scene/#the-frame-loop) again, now with a
render surface: six quads with normals and one UV set. It reuses everything above `main` on that page: the
`#include` lines, the `CHECK` macro and the `solid_box` function. Put them above this `main`.

```c
int main(void) {
    DeformableTetrahedralization *ground_solid = solid_box((DeformableVector3){-3, -0.5, -3},
                                                          (DeformableVector3){3, 0, 3}, 1.0, 1.0);
    DeformableTetrahedralization *cube_solid = solid_box((DeformableVector3){-0.5, 2, -0.5},
                                                         (DeformableVector3){0.5, 3, 0.5}, 0.05, 0.3);
    DeformableTetrahedralizationView ground_view, cube_view;
    CHECK(deformable_tetrahedralization_view(ground_solid, &ground_view));
    CHECK(deformable_tetrahedralization_view(cube_solid, &cube_view));

    /* The cube's render surface: six quads, a normal and a UV pair per corner. */
    DeformableVector3 positions[8];
    for (int corner = 0; corner < 8; ++corner) {
        positions[corner].x = corner & 1 ? 0.5 : -0.5;
        positions[corner].y = corner & 2 ? 3.0 : 2.0;
        positions[corner].z = corner & 4 ? 0.5 : -0.5;
    }
    const uint32_t sizes[6] = {4, 4, 4, 4, 4, 4};
    const uint32_t corners[24] = {0, 2, 3, 1, 4, 5, 7, 6, 0, 1, 5, 4, 2, 6, 7, 3, 0, 4, 6, 2, 1, 3, 7, 5};
    const DeformableVector3 face_normals[6] = {{0, 0, -1}, {0, 0, 1}, {0, -1, 0}, {0, 1, 0}, {-1, 0, 0}, {1, 0, 0}};
    const DeformableVector2 square[4] = {{0, 0}, {1, 0}, {1, 1}, {0, 1}};
    DeformableVector3 normals[24];
    DeformableVector2 uvs[24];
    for (int corner = 0; corner < 24; ++corner) {
        normals[corner] = face_normals[corner / 4];
        uvs[corner] = square[corner % 4];
    }
    DeformableSurfaceMeshView surface = {
        {positions, 8, sizes, 6, corners, 24},
        normals, 24,
        uvs, 1,
        NULL, 0,
    };

    /* Bind the surface to the cube's rest mesh, with inner faces for the cracks. */
    DeformablePreparationParameters preparation = {DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES, 1.0, NULL};
    DeformableSurfaceEmbedding *embedding = NULL;
    CHECK(deformable_embed_surface(&cube_view.mesh, &surface, &preparation, &embedding));

    DeformableSurfaceEmbeddingView prepared;
    CHECK(deformable_surface_embedding_view(embedding, &prepared));
    size_t inner_faces = 0;
    for (size_t face = 0; face < prepared.source_face_count; ++face) {
        inner_faces += prepared.source_faces[face] == -1;
    }
    printf("prepared: %zu vertices, %zu faces, %zu inner faces\n", prepared.surface.mesh.position_count,
           prepared.surface.mesh.polygon_count, inner_faces);

    DeformableScene *scene = NULL;
    CHECK(deformable_scene_create(&scene));
    DeformableMaterialParameters parameters;
    uint32_t stone = 0, glass = 0;
    CHECK(deformable_material_preset_find("stone", &parameters));
    CHECK(deformable_scene_add_material(scene, &parameters, &stone));
    CHECK(deformable_material_preset_find("glass", &parameters));
    CHECK(deformable_scene_add_material(scene, &parameters, &glass));

    DeformableObjectOptions options;
    CHECK(deformable_object_options_default(&options));
    DeformableTetrahedronMaterials ground_materials = {DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM, stone, NULL, 0};
    DeformableTetrahedronMaterials cube_materials = {DEFORMABLE_MATERIAL_ASSIGNMENT_UNIFORM, glass, NULL, 0};
    uint32_t ground = 0, cube = 0;
    CHECK(deformable_scene_add_object(scene, &ground_view.mesh, &ground_materials, &options, &ground));
    CHECK(deformable_scene_add_object(scene, &cube_view.mesh, &cube_materials, &options, &cube));

    size_t ground_node_count = ground_view.mesh.position_count;
    DeformableDrivenVertex *held = malloc(ground_node_count * sizeof *held);
    for (size_t node = 0; node < ground_node_count; ++node) {
        held[node].vertex = (uint32_t)node;
        held[node].target = ground_view.mesh.positions[node];
    }
    CHECK(deformable_scene_drive(scene, ground, held, ground_node_count));
    free(held);

    /* The surface is in world space, so the world transform is the identity. */
    DeformableDeformedSurface *deformed = NULL;
    CHECK(deformable_deformed_surface_create(&deformed));
    const DeformableAffineTransform identity = {{{{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}}, {0, 0, 0}};
    const DeformableSkinningOptions skinning = {0, 0};

    for (int frame = 0; frame <= 48; ++frame) {
        DeformableStepReport report;
        CHECK(deformable_scene_step(scene, frame / 24.0, 10, NULL, &report));

        const DeformableTetrahedronState *states = NULL;
        size_t state_count = 0;
        CHECK(deformable_scene_tetrahedron_states(scene, cube, &states, &state_count));
        CHECK(deformable_surface_embedding_deform(embedding, states, state_count, &identity, &skinning, deformed));

        DeformableDeformedSurfaceView view;
        CHECK(deformable_deformed_surface_view(deformed, &view));
        size_t shown = 0;
        for (size_t face = 0; face < view.face_count; ++face) {
            shown += !view.hidden_faces[face];
        }
        if (frame % 12 == 0) {
            printf("frame %2d: %zu of %zu faces shown, vertex 0 at y = %.3f\n", frame, shown, view.face_count,
                   view.positions[0][1]);
        }
    }

    deformable_deformed_surface_destroy(deformed);
    deformable_surface_embedding_destroy(embedding);
    deformable_scene_destroy(scene);
    deformable_tetrahedralization_destroy(ground_solid);
    deformable_tetrahedralization_destroy(cube_solid);
    return 0;
}
```

```text
prepared: 5556 vertices, 1852 faces, 1638 inner faces
frame  0: 214 of 1852 faces shown, vertex 0 at y = 3.000
frame 12: 214 of 1852 faces shown, vertex 0 at y = 1.764
frame 24: 654 of 1852 faces shown, vertex 0 at y = 0.977
frame 36: 658 of 1852 faces shown, vertex 0 at y = 0.958
frame 48: 658 of 1852 faces shown, vertex 0 at y = 0.938
```

The six quads become 214 faces, cut along the tetrahedrons. The 1,638 inner faces stay hidden until the cube hits
the slab; then the cracks show 444 of them.

## Break along splinters

A splinter cage makes the surface break into the shapes of its cells; see
[Splinters](https://help.tangerina.io/deformable/v0.4.0/user-guides/engine/fracture-and-splinters/#splinters). Each closed cell of the cage becomes one
piece. The cage is a polygon mesh in the space of the render surface. Make one with
[`deformable_splinters_from_image`](https://help.tangerina.io/deformable/v0.4.0/user-guides/c/tools/#make-splinters-from-a-drawing), or load one of the
splinter meshes in the plugin zips.

Pass the cage in the preparation parameters with `DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES`. The surface is then
cut along the cell walls, and the walls become hidden cap faces that show when the piece breaks loose.

![A wall surface with its splinter cells marked, then broken into separate brick splinters whose cap faces show.](https://help.tangerina.io/deformable/v0.4.0/images/sdk-surface-breaks-into-splinters.svg)

This snippet splits the cube of the example into four pieces with the four-cell drawing from
[Tools](https://help.tangerina.io/deformable/v0.4.0/user-guides/c/tools/#make-splinters-from-a-drawing). Put the lines of that snippet that build `image`
first, then this snippet in place of the call to `deformable_embed_surface` in the example:

```c
DeformableSplinterImageParameters splinter_parameters;
CHECK(deformable_splinter_image_parameters_default(&splinter_parameters));
splinter_parameters.size = (DeformableVector3){1, 1, 1};       /* the cube's width, height and depth */
splinter_parameters.origin = (DeformableVector3){-0.5, 2, 0.5}; /* its lower-left corner and its front face */
DeformablePolygonMesh *splinters = NULL;
CHECK(deformable_splinters_from_image(&image, &splinter_parameters, &splinters));
DeformablePolygonMeshView splinter_cage;
CHECK(deformable_polygon_mesh_view(splinters, &splinter_cage));

DeformablePreparationParameters preparation = {DEFORMABLE_CLIP_MODE_CLIP_WITH_INNER_FACES, 1.0, &splinter_cage};
DeformableSurfaceEmbedding *embedding = NULL;
CHECK(deformable_embed_surface(&cube_view.mesh, &surface, &preparation, &embedding));
deformable_polygon_mesh_destroy(splinters); /* The embedding keeps what it needs. */
```

With this cage, the example prints:

```text
prepared: 71 vertices, 57 faces, 33 inner faces
frame  0: 24 of 57 faces shown, vertex 0 at y = 2.969
frame 12: 24 of 57 faces shown, vertex 0 at y = 1.732
frame 24: 57 of 57 faces shown, vertex 0 at y = 0.940
frame 36: 57 of 57 faces shown, vertex 0 at y = 0.915
frame 48: 57 of 57 faces shown, vertex 0 at y = 0.894
```

The 33 faces with no source face are the hidden caps and inner faces, and `brick_tetrahedron_count` in the
embedding view is 4: one per piece. On impact the four pieces break loose, and every hidden face shows. To show the caps from the first frame, as for an object that starts out already
split, set `start_splintered` in the `DeformableSkinningOptions`.

## Next steps

- [Memory and errors](https://help.tangerina.io/deformable/v0.4.0/user-guides/c/memory-and-errors/): who owns the embedding's arrays, and which calls are
  thread-safe.
- [C API Reference](https://help.tangerina.io/deformable/v0.4.0/api-references/c/render-surfaces/): every field of the embedding and skinning structs.
