﻿---
title: Meshes
description: The tetrahedral meshes, triangle meshes, polygon meshes and render surfaces the other pages take and return, and the faces of a tetrahedron.
url: https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/
---

# Meshes – C API Reference – Deformable v0.3.1

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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmeshview) for each simulated object, a [`DeformableTriangleMeshView`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletrianglemeshview) or a [`DeformablePolygonMeshView`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmeshview) for cages, and a [`DeformableSurfaceMeshView`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablesurfacemeshview) for the surface a host renders. A mesh a tool returns is a handle, such as [`DeformableTetrahedralMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_extrude) or [`deformable_span_layers`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_span_layers). Read it with
[`deformable_tetrahedral_mesh_view`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_tetrahedral_mesh_view) and free it with [`deformable_tetrahedral_mesh_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `TetrahedralMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#tetrahedralmesh) · [Python `TetrahedralMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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**

- `mesh` ([`const DeformableTetrahedralMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmesh)): The mesh to read.
- `view` ([`DeformableTetrahedralMeshView *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmeshview)): Out. Receives the arrays, owned by `mesh` and valid until it is destroyed.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#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**

- `mesh` ([`DeformableTetrahedralMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmesh)): The mesh to destroy, or `NULL`.

## 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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_extrude) shell can invert some on sharp curvature, and
[`deformable_span_layers`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_span_layers) keeps the flat tetrahedrons of layers that touch.

**Fields**

- `positions` ([`const DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `TetrahedralMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#tetrahedralmesh) · [Python `TetrahedralMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#tetrahedralmesh)

## DeformableTriangleMesh

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableTriangleMesh DeformableTriangleMesh;
```

A triangle mesh the library made, with [`deformable_autocage`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_autocage). Read it with [`deformable_triangle_mesh_view`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_triangle_mesh_view) and
free it with [`deformable_triangle_mesh_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `TriangleMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#trianglemesh) · [Python `TriangleMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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**

- `mesh` ([`const DeformableTriangleMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletrianglemesh)): The mesh to read.
- `view` ([`DeformableTriangleMeshView *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletrianglemeshview)): Out. Receives the arrays, owned by `mesh` and valid until it is destroyed.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#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**

- `mesh` ([`DeformableTriangleMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletrianglemesh)): The mesh to destroy, or `NULL`.

## 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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_tetrahedralize) takes, lists the corners of each triangle counter-clockwise as seen
from outside, so its normals point outward.

**Fields**

- `positions` ([`const DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `TriangleMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#trianglemesh) · [Python `TriangleMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#trianglemesh)

## DeformablePolygonMesh

**Opaque handle** · `deformable.h`

```c
typedef struct DeformablePolygonMesh DeformablePolygonMesh;
```

A polygon mesh the library made, with [`deformable_splinters_from_image`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_splinters_from_image). Read it with [`deformable_polygon_mesh_view`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_polygon_mesh_view)
and free it with [`deformable_polygon_mesh_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `PolygonMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#polygonmesh) · [Python `PolygonMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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**

- `mesh` ([`const DeformablePolygonMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmesh)): The mesh to read.
- `view` ([`DeformablePolygonMeshView *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmeshview)): Out. Receives the arrays, owned by `mesh` and valid until it is destroyed.

**Errors**

- Only the statuses every call can give, which the [conventions](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#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**

- `mesh` ([`DeformablePolygonMesh *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmesh)): The mesh to destroy, or `NULL`.

## 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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablefacehole) names each
hole run.

**Fields**

- `positions` ([`const DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#mesh-views) · [Rust `PolygonMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#polygonmesh) · [Python `PolygonMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/tools/#deformable_triangulate) and [`deformable_verify_surface`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/mesh-checks/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#a-polygon-with-a-hole) · [Rust `FaceHole`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#facehole) · [Python `FaceHole`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/render-surfaces/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformablepolygonmeshview)): The positions and polygons.
- `normals` ([`const DeformableVector3 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#deformablevector3)): `normal_count` corner normals.
- `normal_count` (`size_t`): The number of corner normals: 0 or the corner count.
- `uvs` ([`const DeformableVector2 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/math/#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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/render-surfaces/#the-render-surface) · [Rust `SurfaceMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#surfacemesh) · [Python `SurfaceMesh`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#deformablefaceevent) and of [`deformable_boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#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_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): `face` is above 3.

**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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#tetrahedron-faces) · [Rust `FACES`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#faces) · [Python `face_corners`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#face_corners)

## DeformableBoundaryFaces

**Opaque handle** · `deformable.h`

```c
typedef struct DeformableBoundaryFaces DeformableBoundaryFaces;
```

The boundary-face masks [`deformable_boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces) makes, one byte per tetrahedron: read them with
[`deformable_boundary_faces_masks`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces_masks) and free them with [`deformable_boundary_faces_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces_destroy).

**See also** [Guide: Tetrahedron faces](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#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**

- `faces` ([`const DeformableBoundaryFaces *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformableboundaryfaces)): The masks [`deformable_boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces) made.
- `masks` (`const uint8_t **`): Out. Receives a pointer to the first mask, owned by `faces`.
- `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](https://help.tangerina.io/deformable/v0.3.1/api-references/c/overview/#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**

- `faces` ([`DeformableBoundaryFaces *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformableboundaryfaces)): The masks to destroy, or `NULL`.

## 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`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/scene/#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 *`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformabletetrahedralmeshview)): The tetrahedral mesh, such as the rest mesh of an object.
- `faces` ([`DeformableBoundaryFaces **`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformableboundaryfaces)): Out. Receives a new handle; free it with [`deformable_boundary_faces_destroy`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces_destroy).

**Returns**

[`DEFORMABLE_STATUS_OK`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_ok), and the handle in `faces`: read the masks, one per tetrahedron in mesh order, with [`deformable_boundary_faces_masks`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_boundary_faces_masks). Bit k stands for face k, as [`deformable_face_corners`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/meshes/#deformable_face_corners) numbers the faces.

**Errors**

- [`DEFORMABLE_STATUS_EMPTY_MESH`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_empty_mesh): The mesh has no tetrahedron.
- [`DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_index_out_of_range): A tetrahedron uses a node index past the end of the positions.
- [`DEFORMABLE_STATUS_NON_FINITE_VALUE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_finite_value): A position is NaN or infinite.
- [`DEFORMABLE_STATUS_NON_MANIFOLD_FACE`](https://help.tangerina.io/deformable/v0.3.1/api-references/c/errors/#deformablestatus-deformable_status_non_manifold_face): Three or more tetrahedrons share one face.

**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](https://help.tangerina.io/deformable/v0.3.1/user-guides/c/tools/#tetrahedron-faces) · [Rust `boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/rust/meshes/#boundary_faces) · [Python `boundary_faces`](https://help.tangerina.io/deformable/v0.3.1/api-references/python/meshes/#boundary_faces)
