You are viewing the documentation for Deformable v0.1.1, an older version. Read the latest, v0.9.0
C API Reference
Meshes
The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
On this page
The meshes the tools and the scene take and return. A call takes a mesh as a view of arrays the host owns: a DeformableTetrahedralMeshView for each simulated object, a DeformableTriangleMeshView or a DeformablePolygonMeshView for cages, and a DeformableSurfaceMeshView for the surface a host renders. A mesh a tool returns is a handle, such as DeformableTetrahedralMesh, that lends the same view of its own arrays. The faces of a tetrahedron come last.
DeformableTetrahedralMesh
Opaque handle · deformable.h
typedef struct DeformableTetrahedralMesh DeformableTetrahedralMesh;A tetrahedral mesh the library made, with deformable_extrude or deformable_span_layers. Read it with
deformable_tetrahedral_mesh_view and free it with deformable_tetrahedral_mesh_destroy.
Example
DeformableTetrahedralMesh *shell = NULL;
DeformableExtrudeDirection both = DEFORMABLE_EXTRUDE_DIRECTION_BOTH;
CHECK(deformable_extrude(&cage, 0.1, both, &shell));
DeformableTetrahedralMeshView view;
CHECK(deformable_tetrahedral_mesh_view(shell, &view));
// view lends the arrays of shell until it is destroyed.
deformable_tetrahedral_mesh_destroy(shell);See also Guide: Mesh views · Rust TetrahedralMesh · Python TetrahedralMesh
deformable_tetrahedral_mesh_view
Function · deformable.h
DeformableStatus deformable_tetrahedral_mesh_view(
const DeformableTetrahedralMesh *mesh,
DeformableTetrahedralMeshView *view);Lends the arrays of a tetrahedral mesh the library made: its positions and tetrahedrons, as the view every call that takes a tetrahedral mesh reads.
Parameters
mesh(const DeformableTetrahedralMesh *)The mesh to read.view(DeformableTetrahedralMeshView *)Out. Receives the arrays, owned bymeshand valid until it is destroyed.
Errors
- Only the statuses every call can give, which the conventions describe.
deformable_tetrahedral_mesh_destroy
Function · deformable.h
void deformable_tetrahedral_mesh_destroy(
DeformableTetrahedralMesh *mesh);Destroys a tetrahedral mesh the library made; NULL is ignored. Views of it become invalid.
Parameters
mesh(DeformableTetrahedralMesh *)The mesh to destroy, orNULL.
DeformableTetrahedralMeshView
Struct · deformable.h
typedef struct DeformableTetrahedralMeshView {
const DeformableVector3 *positions;
size_t position_count;
const uint32_t (*tetrahedrons)[4];
size_t tetrahedron_count;
} DeformableTetrahedralMeshView;A tetrahedral mesh as borrowed arrays: shared node positions and four node indices per tetrahedron, positively oriented (left-handed).
With corners X0 to X3 and ei = Xi - X0, a tetrahedron is positive when -e1 · (e2 × e3) is above 0, and swapping
two corners turns a right-handed tetrahedron positive. deformable_scene_add_object asks for more: it refuses a
mesh with a tetrahedron whose value, in simulation units, is not above 1e-9, and the
DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_* statuses say how such a tetrahedron fails. The tools make positive
tetrahedrons, though a thick deformable_extrude shell can invert some on sharp curvature, and
deformable_span_layers keeps the flat tetrahedrons of layers that touch.
Fields
positions(const DeformableVector3 *)position_countnode positions.position_count(size_t)The number of nodes.tetrahedrons(const uint32_t (*)[4])tetrahedron_countgroups of four node indices.tetrahedron_count(size_t)The number of tetrahedrons.
Example
// One positive tetrahedron: its corners are left-handed.
const DeformableVector3 corners[4] = {
{0, 0, 0}, {1, 0, 0}, {0, 0, 1}, {0, 1, 0}};
const uint32_t nodes[1][4] = {{0, 1, 2, 3}};
DeformableTetrahedralMeshView single = {corners, 4, nodes, 1};
DeformableTetrahedronMaterials uniform = {0};
uniform.material = material;
DeformableObjectOptions options;
CHECK(deformable_object_options_default(&options));
uint32_t added;
CHECK(deformable_scene_add_object(scene, &single, &uniform,
&options, &added));See also Guide: Mesh views · Rust TetrahedralMesh · Python TetrahedralMesh
DeformableTriangleMesh
Opaque handle · deformable.h
typedef struct DeformableTriangleMesh DeformableTriangleMesh;A triangle mesh the library made, with deformable_autocage. Read it with deformable_triangle_mesh_view and
free it with deformable_triangle_mesh_destroy.
Example
DeformableAutocageParameters parameters;
CHECK(deformable_autocage_parameters_default(¶meters));
DeformableTriangleMesh *wrapped = NULL;
CHECK(deformable_autocage(&polygons, ¶meters, NULL, &wrapped));
DeformableTriangleMeshView view;
CHECK(deformable_triangle_mesh_view(wrapped, &view));
// view lends the arrays of wrapped until it is destroyed.
deformable_triangle_mesh_destroy(wrapped);See also Guide: Mesh views · Rust TriangleMesh · Python TriangleMesh
deformable_triangle_mesh_view
Function · deformable.h
DeformableStatus deformable_triangle_mesh_view(
const DeformableTriangleMesh *mesh,
DeformableTriangleMeshView *view);Lends the arrays of a triangle mesh the library made: its positions and triangles, as the view every call that takes a triangle mesh reads.
Parameters
mesh(const DeformableTriangleMesh *)The mesh to read.view(DeformableTriangleMeshView *)Out. Receives the arrays, owned bymeshand valid until it is destroyed.
Errors
- Only the statuses every call can give, which the conventions describe.
deformable_triangle_mesh_destroy
Function · deformable.h
void deformable_triangle_mesh_destroy(DeformableTriangleMesh *mesh);Destroys a triangle mesh the library made; NULL is ignored. Views of it become invalid.
Parameters
mesh(DeformableTriangleMesh *)The mesh to destroy, orNULL.
DeformableTriangleMeshView
Struct · deformable.h
typedef struct DeformableTriangleMeshView {
const DeformableVector3 *positions;
size_t position_count;
const uint32_t (*triangles)[3];
size_t triangle_count;
} DeformableTriangleMeshView;A triangle mesh as borrowed arrays: shared vertex positions and three vertex indices per triangle.
A closed cage, as deformable_tetrahedralize takes, lists the corners of each triangle counter-clockwise as seen
from outside, so its normals point outward.
Fields
positions(const DeformableVector3 *)position_countvertex positions.position_count(size_t)The number of vertices.triangles(const uint32_t (*)[3])triangle_countgroups of three vertex indices.triangle_count(size_t)The number of triangles.
Example
// One triangle, counter-clockwise seen from +z, its normal side.
const DeformableVector3 corners[3] = {{0, 0, 0}, {1, 0, 0}, {0, 1, 0}};
const uint32_t triangle[1][3] = {{0, 1, 2}};
DeformableTriangleMeshView one = {corners, 3, triangle, 1};
DeformableExtrudeDirection up = DEFORMABLE_EXTRUDE_DIRECTION_UP;
DeformableTetrahedralMesh *prism = NULL;
CHECK(deformable_extrude(&one, 0.1, up, &prism));
deformable_tetrahedral_mesh_destroy(prism);See also Guide: Mesh views · Rust TriangleMesh · Python TriangleMesh
DeformablePolygonMesh
Opaque handle · deformable.h
typedef struct DeformablePolygonMesh DeformablePolygonMesh;A polygon mesh the library made, with deformable_splinters_from_image. Read it with deformable_polygon_mesh_view
and free it with deformable_polygon_mesh_destroy.
Example
// A failed call leaves splinters NULL, which destroy ignores.
DeformablePixelGrid blank = {0};
DeformableSplinterImageParameters parameters;
CHECK(deformable_splinter_image_parameters_default(¶meters));
DeformablePolygonMesh *splinters = NULL;
if (deformable_splinters_from_image(&blank, ¶meters, &splinters))
puts(deformable_last_error_message());
deformable_polygon_mesh_destroy(splinters);See also Guide: Mesh views · Rust PolygonMesh · Python PolygonMesh
deformable_polygon_mesh_view
Function · deformable.h
DeformableStatus deformable_polygon_mesh_view(
const DeformablePolygonMesh *mesh,
DeformablePolygonMeshView *view);Lends the arrays of a polygon mesh the library made: its positions, the corner count of each polygon and the vertex of every corner, as the view every call that takes a polygon mesh reads.
Parameters
mesh(const DeformablePolygonMesh *)The mesh to read.view(DeformablePolygonMeshView *)Out. Receives the arrays, owned bymeshand valid until it is destroyed.
Errors
- Only the statuses every call can give, which the conventions describe.
deformable_polygon_mesh_destroy
Function · deformable.h
void deformable_polygon_mesh_destroy(DeformablePolygonMesh *mesh);Destroys a polygon mesh the library made; NULL is ignored. Views of it become invalid.
Parameters
mesh(DeformablePolygonMesh *)The mesh to destroy, orNULL.
DeformablePolygonMeshView
Struct · deformable.h
typedef struct DeformablePolygonMeshView {
const DeformableVector3 *positions;
size_t position_count;
const uint32_t *polygon_sizes;
size_t polygon_count;
const uint32_t *polygon_vertices;
size_t corner_count;
} DeformablePolygonMeshView;A polygon mesh as borrowed arrays: shared positions, the corner count of each polygon, and the vertex of every corner, polygon after polygon.
A closed mesh lists the corners of each polygon counter-clockwise as seen from outside, so its normals point
outward. A polygon with holes lists its outer loop first, then each hole loop, and a DeformableFaceHole names each
hole run.
Fields
positions(const DeformableVector3 *)position_countvertex positions.position_count(size_t)The number of vertices.polygon_sizes(const uint32_t *)The corner count of each of thepolygon_countpolygons.polygon_count(size_t)The number of polygons.polygon_vertices(const uint32_t *)The vertex index of each of thecorner_countcorners.corner_count(size_t)The number of corners.
See also Guide: Mesh views · Rust PolygonMesh · Python PolygonMesh
DeformableFaceHole
Struct · deformable.h
typedef struct DeformableFaceHole {
uint32_t face;
uint32_t first_corner;
uint32_t corner_count;
} DeformableFaceHole;A run of a polygon’s corners that forms one hole loop; the corners before the polygon’s first hole form its outer loop.
deformable_triangulate and deformable_verify_surface take an array of them, and a polygon that none of them names
has no hole.
Fields
face(uint32_t)The index of the polygon that holds the hole.first_corner(uint32_t)The run’s first corner, counted from the polygon’s first corner.corner_count(uint32_t)The number of corners in the run.
Example
// Polygon 0: corners 0 to 3 its outer square, 4 to 7 a square hole.
DeformableVector3 corners[] = {{0}, {3, 0, 0}, {3, 3, 0}, {0, 3, 0},
{1, 1, 0}, {1, 2, 0}, {2, 2, 0}, {2, 1, 0}};
uint32_t size = 8, vertices[] = {0, 1, 2, 3, 4, 5, 6, 7};
DeformablePolygonMeshView frame = {corners, 8, &size, 1, vertices, 8};
DeformableFaceHole hole = {0, 4, 4};
DeformableTriangulateParameters open;
CHECK(deformable_triangulate_parameters_default(&open));
open.closed_boundary = 0;
DeformableTriangulation *result = NULL;
CHECK(deformable_triangulate(&frame, &hole, 1, &open, NULL, &result));
deformable_triangulation_destroy(result);See also Guide: A polygon with a hole · Rust FaceHole · Python FaceHole
DeformableSurfaceMeshView
Struct · deformable.h
typedef struct DeformableSurfaceMeshView {
DeformablePolygonMeshView mesh;
const DeformableVector3 *normals;
size_t normal_count;
const DeformableVector2 *uvs;
size_t uv_set_count;
const double (*colours)[4];
size_t colour_count;
} DeformableSurfaceMeshView;A render surface as borrowed arrays: a polygon mesh with per-corner channels, the normals, UV sets and colours that
deformable_embed_surface carries through its clip.
Each channel is empty (count 0) or holds one entry per corner, in the order of the mesh’s polygon_vertices.
uvs holds the UV sets one after the other, each with one pair per corner.
Fields
mesh(DeformablePolygonMeshView)The positions and polygons.normals(const DeformableVector3 *)normal_countcorner normals.normal_count(size_t)The number of corner normals: 0 or the corner count.uvs(const DeformableVector2 *)uv_set_countUV sets one after the other, each with one coordinate pair per corner.uv_set_count(size_t)The number of UV sets.colours(const double (*)[4])colour_countcorner colours: red, green, blue and alpha.colour_count(size_t)The number of corner colours: 0 or the corner count.
Example
// The cube as a render surface with no normals, UV sets or colours.
DeformableSurfaceMeshView cube = {0};
cube.mesh = polygons;
DeformablePreparationParameters parameters = {
DEFORMABLE_CLIP_MODE_ASSIGN_ONLY, 1.0, NULL};
DeformableSurfaceEmbedding *embedded = NULL;
CHECK(deformable_embed_surface(&mesh, &cube, ¶meters, &embedded));
deformable_surface_embedding_destroy(embedded);See also Guide: The render surface · Rust SurfaceMesh · Python SurfaceMesh
deformable_face_corners
Function · deformable.h
DeformableStatus deformable_face_corners(
uint32_t face,
uint32_t (*corners)[3]);Writes to corners the three local corners (0 to 3) of one face of a tetrahedron: the face opposite corner face.
Seen from outside a positively oriented (left-handed) tetrahedron, the corners of each face run clockwise: with
corners a, b and c in that order, (b - a) × (c - a) points into the tetrahedron, toward corner face. The face
bits of DeformableFaceEvent and of deformable_boundary_faces number the faces this way.
Parameters
face(uint32_t)The face, 0 to 3: the face opposite that corner.corners(uint32_t (*)[3])Out. Receives the three corners of the face, in the order above.
Errors
DEFORMABLE_STATUS_INDEX_OUT_OF_RANGEfaceis above 3.
Example
uint32_t corners[3];
CHECK(deformable_face_corners(1, &corners));
// corners holds 0, 3 and 2: face 1 is the face opposite corner 1.See also Guide: Tetrahedron faces · Rust FACES · Python face_corners
DeformableBoundaryFaces
Opaque handle · deformable.h
typedef struct DeformableBoundaryFaces DeformableBoundaryFaces;The boundary-face masks deformable_boundary_faces makes, one byte per tetrahedron: read them with
deformable_boundary_faces_masks and free them with deformable_boundary_faces_destroy.
See also Guide: Tetrahedron faces
deformable_boundary_faces_masks
Function · deformable.h
DeformableStatus deformable_boundary_faces_masks(
const DeformableBoundaryFaces *faces,
const uint8_t **masks,
size_t *count);Lends the masks of faces: one per tetrahedron of the mesh, in mesh order, valid until faces is destroyed.
Parameters
faces(const DeformableBoundaryFaces *)The masksdeformable_boundary_facesmade.masks(const uint8_t **)Out. Receives a pointer to the first mask, owned byfaces.count(size_t *)Out. Receives how many masks it lends: the mesh’s tetrahedron count.
Errors
- Only the statuses every call can give, which the conventions describe.
deformable_boundary_faces_destroy
Function · deformable.h
void deformable_boundary_faces_destroy(DeformableBoundaryFaces *faces);Destroys boundary-face masks; NULL is ignored. The masks they lent become invalid.
Parameters
faces(DeformableBoundaryFaces *)The masks to destroy, orNULL.
deformable_boundary_faces
Function · deformable.h
DeformableStatus deformable_boundary_faces(
const DeformableTetrahedralMeshView *mesh,
DeformableBoundaryFaces **faces);The outer faces of each tetrahedron of a mesh, as one mask per tetrahedron: bit k is set when no other tetrahedron shares face k, the face opposite corner k.
The masks depend only on which tetrahedrons share faces, not on the positions, so a host computes them once from
an object’s rest mesh and can set them in its own per-tetrahedron output flags. The exposed faces of a
DeformableFaceEvent include them: clear them from it to keep only the faces a fracture opened. The orientation of
the tetrahedrons is not checked.
Parameters
mesh(const DeformableTetrahedralMeshView *)The tetrahedral mesh, such as the rest mesh of an object.faces(DeformableBoundaryFaces **)Out. Receives a new handle; free it withdeformable_boundary_faces_destroy.
Returns
DEFORMABLE_STATUS_OK, and the handle in faces: read the masks, one per tetrahedron in mesh order, with deformable_boundary_faces_masks. Bit k stands for face k, as deformable_face_corners numbers the faces.
Errors
DEFORMABLE_STATUS_EMPTY_MESHThe mesh has no tetrahedron.DEFORMABLE_STATUS_INDEX_OUT_OF_RANGEA tetrahedron uses a node index past the end of the positions.DEFORMABLE_STATUS_NON_FINITE_VALUEA position is NaN or infinite.DEFORMABLE_STATUS_NON_MANIFOLD_FACEThree or more tetrahedrons share one face.- The license statuses every engine call can return.
Example
DeformableBoundaryFaces *faces = NULL;
CHECK(deformable_boundary_faces(&mesh, &faces));
const uint8_t *masks;
size_t count, outer = 0;
CHECK(deformable_boundary_faces_masks(faces, &masks, &count));
for (size_t face = 0; face < 4 * count; face++)
outer += (masks[face / 4] >> face % 4) & 1;
printf("%zu outer faces\n", outer); // 12: the cage's triangles
deformable_boundary_faces_destroy(faces);See also Guide: Tetrahedron faces · Rust boundary_faces · Python boundary_faces