You are viewing the documentation for Deformable v0.8.0, 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
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
// 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 edgeSee also Rust Vector2 · Python Vector2
DeformableVector3
Struct · deformable.h
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
// 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
typedef struct DeformableMatrix3 {
DeformableVector3 rows[3];
} DeformableMatrix3;A 3 by 3 matrix of doubles, stored by rows: the linear part of a DeformableAffineTransform.
Fields
rows(DeformableVector3[3])The three rows, from top to bottom.
See also Rust Matrix3
DeformableAffineTransform
Struct · deformable.h
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
// 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
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
// 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(®ion, point, &inside));
puts(inside ? "inside" : "outside"); // insideSee also Guide: Glue objects together · Rust Plane · Python Plane
DeformableConvexRegion
Struct · deformable.h
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_countbounding planes, borrowed for the call that takes the region.plane_count(size_t)The number of planes; with 0,planesmay beNULLand the region holds every point.
Example
// 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"); // insideSee also Guide: Glue objects together · Rust ConvexRegion · Python ConvexRegion
deformable_convex_region_contains
Function · deformable.h
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
region(const DeformableConvexRegion *)The region to test against.point(DeformableVector3)The point to test, in the units of the plane offsets.inside(uint8_t *)Out. Receives 1 whenpointis inside, 0 when it is outside.
Errors
- Only the statuses every call can give, which the conventions describe.
See also Guide: Glue objects together · Rust ConvexRegion::contains · Python ConvexRegion.contains