You are viewing the documentation for Deformable v0.3.0, 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

c
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

c
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

c
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

Errors

  • Only the statuses every call can give, which the conventions describe.

deformable_tetrahedral_mesh_destroy

Function · deformable.h

c
void deformable_tetrahedral_mesh_destroy(
    DeformableTetrahedralMesh *mesh);

Destroys a tetrahedral mesh the library made; NULL is ignored. Views of it become invalid.

Parameters

DeformableTetrahedralMeshView

Struct · deformable.h

c
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_count node positions.
  • position_count (size_t)The number of nodes.
  • tetrahedrons (const uint32_t (*)[4])tetrahedron_count groups of four node indices.
  • tetrahedron_count (size_t)The number of tetrahedrons.

Example

c
// 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

c
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

c
DeformableAutocageParameters parameters;
CHECK(deformable_autocage_parameters_default(&parameters));
DeformableTriangleMesh *wrapped = NULL;
CHECK(deformable_autocage(&polygons, &parameters, 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

c
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

Errors

  • Only the statuses every call can give, which the conventions describe.

deformable_triangle_mesh_destroy

Function · deformable.h

c
void deformable_triangle_mesh_destroy(DeformableTriangleMesh *mesh);

Destroys a triangle mesh the library made; NULL is ignored. Views of it become invalid.

Parameters

DeformableTriangleMeshView

Struct · deformable.h

c
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_count vertex positions.
  • position_count (size_t)The number of vertices.
  • triangles (const uint32_t (*)[3])triangle_count groups of three vertex indices.
  • triangle_count (size_t)The number of triangles.

Example

c
// 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

c
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

c
// A failed call leaves splinters NULL, which destroy ignores.
DeformablePixelGrid blank = {0};
DeformableSplinterImageParameters parameters;
CHECK(deformable_splinter_image_parameters_default(&parameters));
DeformablePolygonMesh *splinters = NULL;
if (deformable_splinters_from_image(&blank, &parameters, &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

c
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

Errors

  • Only the statuses every call can give, which the conventions describe.

deformable_polygon_mesh_destroy

Function · deformable.h

c
void deformable_polygon_mesh_destroy(DeformablePolygonMesh *mesh);

Destroys a polygon mesh the library made; NULL is ignored. Views of it become invalid.

Parameters

DeformablePolygonMeshView

Struct · deformable.h

c
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_count vertex positions.
  • position_count (size_t)The number of vertices.
  • polygon_sizes (const uint32_t *)The corner count of each of the polygon_count polygons.
  • polygon_count (size_t)The number of polygons.
  • polygon_vertices (const uint32_t *)The vertex index of each of the corner_count corners.
  • corner_count (size_t)The number of corners.

See also Guide: Mesh views · Rust PolygonMesh · Python PolygonMesh

DeformableFaceHole

Struct · deformable.h

c
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

c
// 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

c
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_count corner normals.
  • normal_count (size_t)The number of corner normals: 0 or the corner count.
  • uvs (const DeformableVector2 *)uv_set_count UV 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_count corner colours: red, green, blue and alpha.
  • colour_count (size_t)The number of corner colours: 0 or the corner count.

Example

c
// 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, &parameters, &embedded));
deformable_surface_embedding_destroy(embedded);

See also Guide: The render surface · Rust SurfaceMesh · Python SurfaceMesh

deformable_face_corners

Function · deformable.h

c
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

Example

c
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

c
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

c
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

Errors

  • Only the statuses every call can give, which the conventions describe.

deformable_boundary_faces_destroy

Function · deformable.h

c
void deformable_boundary_faces_destroy(DeformableBoundaryFaces *faces);

Destroys boundary-face masks; NULL is ignored. The masks they lent become invalid.

Parameters

deformable_boundary_faces

Function · deformable.h

c
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

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

Example

c
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