You are viewing the documentation for Deformable v0.7.0, an older version. Read the latest, v0.9.0
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
- Build the object’s rest tetrahedral mesh, and add it with
deformable_scene_add_object. - Call
deformable_embed_surfaceonce with the same rest mesh and your render surface. It writes aDeformableSurfaceEmbedding. - Read the prepared surface with
deformable_surface_embedding_view, and give it to your renderer. - Create one
DeformableDeformedSurfaceper object withdeformable_deformed_surface_create. - Each frame, after the step, pass the object’s tetrahedron states to
deformable_surface_embedding_deform, then copy the positions, normals and hidden faces fromdeformable_deformed_surface_viewinto your renderer.
The render surface
A DeformableSurfaceMeshView is a polygon mesh with optional channels, one entry per corner:
normalsis empty (count 0) or holds one normal per corner. The embedding keeps your normals, hard edges included.uvsholdsuv_set_countUV sets one after the other, each with one coordinate pair per corner.coloursis 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_ |
Each vertex follows the tetrahedron it lies in. Nothing is cut, and no inner face is made. |
DEFORMABLE_ |
Cuts the surface along the tetrahedron faces, and adds the inside of each face as a hidden inner face. |
DEFORMABLE_ |
The tetrahedral mesh is the surface; every interior face becomes an inner face. |
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 Deformable |
What it holds |
|---|---|
surface |
The prepared surface at rest, a Deformable with every channel your input had. |
source_ |
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_ |
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_, vertex_ |
For each vertex, its tetrahedron and its four barycentric weights. |
normal_ |
For each corner, the weights that carry its normal; empty without normals. |
brick_, vertex_ |
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:
- Read the object’s states with
deformable_scene_tetrahedron_states. - Call
deformable_surface_embedding_deformwith them. The state count must equal the tetrahedron count of the rest mesh, or the call returnsDEFORMABLE_STATUS_LENGTH_MISMATCH. - Read the result with
deformable_deformed_surface_view, and copy it into your renderer.
The DeformableDeformedSurfaceView holds:
positions: one position per prepared vertex, as threefloatvalues.normals: one unit normal per corner, as threefloatvalues. 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. Withshow_inner_facesnot 0 in theDeformableSkinningOptions, 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:
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.
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", ¶meters));
CHECK(deformable_scene_add_material(scene, ¶meters, &stone));
CHECK(deformable_material_preset_find("glass", ¶meters));
CHECK(deformable_scene_add_material(scene, ¶meters, &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;
}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.938The 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.
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:
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:
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.894The 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: who owns the embedding’s arrays, and which calls are thread-safe.
- C API Reference: every field of the embedding and skinning structs.