C SDK

Render surfaces

Embed a detailed render mesh in a simulated object from C, skin it every frame, and show the inner faces that cracks open.

On this page

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 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.

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.
at rest: embed once each frame: deform
Embed the surface once at rest, then deform it every frame after the step.

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:

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.
at rest: inner faces hidden after a crack: inner faces show
Inner faces stay hidden at rest and show only where a crack opens the object.

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.

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.
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 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. 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, 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.

at rest: caps hidden broken: each splinter shows its caps
Each closed cell of the cage becomes one piece, whose hidden cap faces show when the piece breaks loose.

This snippet splits the cube of the example into four pieces with the four-cell drawing from Tools. 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