You are viewing the documentation for Deformable v0.1.1, an older version. Read the latest, v0.9.0

C API Reference

Math

The points, vectors, transforms, planes and convex regions the other pages take and return.

On this page

The points, vectors and transforms the other pages take and return, and the planes and convex regions that bound a part of space.

DeformableVector2

Struct · deformable.h

c
typedef struct DeformableVector2 {
    double x;
    double y;
} DeformableVector2;

A point or vector in the plane, such as the UV coordinates of a corner: two doubles.

Fields

  • x (double)The first component; u for a UV coordinate pair.
  • y (double)The second component; v for a UV coordinate pair.

Example

c
// The UV coordinates of a corner, halfway along the top edge.
DeformableVector2 uv = {0.5, 1.0};
puts(uv.y == 1.0 ? "on the top edge" : "below it"); // on the top edge

See also Rust Vector2 · Python Vector2

DeformableVector3

Struct · deformable.h

c
typedef struct DeformableVector3 {
    double x;
    double y;
    double z;
} DeformableVector3;

A point or vector in space: three doubles.

Fields

  • x (double)The first component.
  • y (double)The second component.
  • z (double)The third component.

Example

c
// Gravity along -z, for a scene whose z axis points up.
DeformableVector3 gravity = {0.0, 0.0, -9.81};
CHECK(deformable_scene_set_gravity(scene, gravity));

See also Rust Vector3 · Python Vector3

DeformableMatrix3

Struct · deformable.h

c
typedef struct DeformableMatrix3 {
    DeformableVector3 rows[3];
} DeformableMatrix3;

A 3 by 3 matrix of doubles, stored by rows: the linear part of a DeformableAffineTransform.

Fields

See also Rust Matrix3

DeformableAffineTransform

Struct · deformable.h

c
typedef struct DeformableAffineTransform {
    DeformableMatrix3 linear;
    DeformableVector3 translation;
} DeformableAffineTransform;

An affine map of row vectors: a point p maps to p times linear, plus translation.

So linear.rows[i] is where axis i goes. A matrix M that maps column vectors (M times p, as in most engines) gives its transpose: linear.rows[i] holds column i of M. deformable_surface_embedding_deform takes the world transform of the host’s shape as one, and a DeformableMaterialRegion its map into the mesh’s object space.

Fields

  • linear (DeformableMatrix3)The linear part. A point is multiplied from the left as a row vector, so row i is where axis i goes.
  • translation (DeformableVector3)The translation added after the linear part.

Example

c
// Turns the x axis into the y axis, then moves 5 along z.
const DeformableAffineTransform turn = {
    {{{0.0, 1.0, 0.0}, {-1.0, 0.0, 0.0}, {0.0, 0.0, 1.0}}},
    {0.0, 0.0, 5.0},
};
// The point (1, 0, 0) as a row vector, times linear, plus translation.
const double point[3] = {1.0, 0.0, 0.0};
DeformableVector3 mapped = turn.translation;
for (int axis = 0; axis < 3; axis++) {
    DeformableVector3 row = turn.linear.rows[axis];
    mapped.x += point[axis] * row.x;
    mapped.y += point[axis] * row.y;
    mapped.z += point[axis] * row.z;
}
printf("(%g, %g, %g)\n", mapped.x, mapped.y, mapped.z); // (0, 1, 5)

See also Guide: World transform · Rust AffineTransform · Python AffineTransform

DeformablePlane

Struct · deformable.h

c
typedef struct DeformablePlane {
    DeformableVector3 normal;
    double offset;
} DeformablePlane;

A bounding plane of a convex region: a point p is inside it when the dot product of normal and p, plus offset, is 0 or less.

The normal points out of the region and can have any length: scaling the normal and the offset by one factor gives the same plane. With a unit normal, minus offset is how far the plane lies from the origin along the normal. For the plane through a point q, the offset is minus the dot product of the normal and q.

Fields

  • normal (DeformableVector3)The outward normal, of any length.
  • offset (double)The offset, in the units of the points it bounds.

Example

c
// Keeps the points with y at most 0.1: the normal points out.
const DeformablePlane plane = {{0.0, 1.0, 0.0}, -0.1};
DeformableConvexRegion region = {&plane, 1};
DeformableVector3 point = {3.0, -0.25, 0.0};
uint8_t inside;
CHECK(deformable_convex_region_contains(&region, point, &inside));
puts(inside ? "inside" : "outside"); // inside

See also Guide: Glue objects together · Rust Plane · Python Plane

DeformableConvexRegion

Struct · deformable.h

c
typedef struct DeformableConvexRegion {
    const DeformablePlane *planes;
    size_t plane_count;
} DeformableConvexRegion;

A convex region: the points inside every one of its planes. With no plane it holds every point.

deformable_scene_add_glue_region takes one, in world space and host units, to choose the tetrahedrons it glues.

Fields

  • planes (const DeformablePlane *)plane_count bounding planes, borrowed for the call that takes the region.
  • plane_count (size_t)The number of planes; with 0, planes may be NULL and the region holds every point.

Example

c
// The slab of points with x from 0 to 1.
const DeformablePlane planes[2] = {{{1, 0, 0}, -1}, {{-1, 0, 0}, 0}};
DeformableConvexRegion slab = {planes, 2};
DeformableVector3 point = {0.5, 7.0, -2.0};
uint8_t inside;
CHECK(deformable_convex_region_contains(&slab, point, &inside));
puts(inside ? "inside" : "outside"); // inside

See also Guide: Glue objects together · Rust ConvexRegion · Python ConvexRegion

deformable_convex_region_contains

Function · deformable.h

c
DeformableStatus deformable_convex_region_contains(
    const DeformableConvexRegion *region,
    DeformableVector3 point,
    uint8_t *inside);

Writes whether point is inside every plane of region: the dot product of the plane’s normal and point, plus its offset, is 0 or less.

It is the test the library runs for glue regions; a host runs it for regions of its own, such as passive regions that hold the vertices inside them. Every point is inside a region with no plane; otherwise a NaN, in the point or in a plane, puts the point outside.

Parameters

Errors

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

See also Guide: Glue objects together · Rust ConvexRegion::contains · Python ConvexRegion.contains