You are viewing the documentation for Deformable v0.3.1, an older version. Read the latest, v0.9.0
C API Reference
Errors
Errors and status codes, the library version, and the cancel flag that stops a long call.
On this page
What a failed call reports: the DeformableStatus that names what went wrong, and the DeformableErrorDetails that carries it. Then the library version, and the DeformableCancelFlag that stops a long call from another thread.
DeformableErrorDetails
Struct · deformable.h
typedef struct DeformableErrorDetails {
DeformableStatus status;
uint32_t first_index;
uint32_t second_index;
} DeformableErrorDetails;The status and indices of the last failed call on the calling thread, as deformable_last_error_details writes them;
deformable_last_error_message gives its message.
The indices name the tetrahedron, region, polygon, face, vertex or edge the failure concerns, or the Free license’s
tetrahedron count and limit, as each DeformableStatus code says; they are 0 when it names none.
Fields
status(DeformableStatus)The status the call returned;DEFORMABLE_STATUS_OKwhen the latest call succeeded.first_index(uint32_t)The first index the failure names (the tetrahedron, region, polygon, face, vertex or edge’s first vertex, or the tetrahedrons a Free license scene would simulate), or 0.second_index(uint32_t)The second index the failure names (the region’s polygon, the edge’s second vertex, or the Free license’s tetrahedron limit), or 0.
See also Guide: Status codes and the last error · Rust Error · Python DeformableError
DeformableStatus
Enum · deformable.h
typedef int32_t DeformableStatus;The outcome of a call: DEFORMABLE_STATUS_OK (0) on success, a positive DEFORMABLE_STATUS_* code otherwise.
The indices of the last error (DeformableErrorDetails) name the element a status concerns, as each code says; they
are 0 when it names none. A newer library can add statuses, so a host treats a code this header does not define as
a failure too.
Values
DEFORMABLE_STATUS_OK(0)The call succeeded.DEFORMABLE_STATUS_NULL_POINTER(1)A required pointer argument isNULL, or an array pointer isNULLwhile its count is not 0.DEFORMABLE_STATUS_INVALID_ARGUMENT(2)An argument the library cannot read: an undefined enumeration value, a misaligned pointer, an array larger than the address space or a material preset name the library does not ship. The license functions give it for a timeout of 0, a key that is not UTF-8 or no license key, a Developer license key that does not verify, another Standard key while one is stored, another Developer key once one is set, and a Standard key in a program on a Developer license.DEFORMABLE_STATUS_PANICKED(3)The library panicked; the handles the call used should be destroyed.DEFORMABLE_STATUS_INDEX_OUT_OF_RANGE(4)An index points past the end of the list it indexes; the first index names the polygon for the polygon tools.DEFORMABLE_STATUS_UNKNOWN_MATERIAL(5)A material handle names no material of the scene.DEFORMABLE_STATUS_UNKNOWN_OBJECT(6)An object handle names no object of the scene, or a removed one.DEFORMABLE_STATUS_LENGTH_MISMATCH(7)A list does not have the length its partner requires.DEFORMABLE_STATUS_NON_FINITE_VALUE(8)A position or parameter is NaN or infinite.DEFORMABLE_STATUS_EMPTY_MESH(9)A mesh has no tetrahedrons, vertices or polygons.DEFORMABLE_STATUS_NON_MANIFOLD_FACE(10)Three or more tetrahedrons share one face.DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_TOO_SMALL(11)Tetrahedronfirst_indexhas a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_FLAT(12)Tetrahedronfirst_indexhas an orientation determinant of magnitude at most 1e-15.DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_INVERTED(13)Tetrahedronfirst_indexis ordered right-handed (orientation determinant below -1e-15).DEFORMABLE_STATUS_SCALE_OUT_OF_RANGE(14)The length scale lies outside [0.001, 1,000].DEFORMABLE_STATUS_DEGENERATE_REGION(15)Polygonsecond_indexof material regionfirst_indexhas fewer than 3 vertices or a zero normal.DEFORMABLE_STATUS_TIME_WENT_BACKWARDS(16)A step’s time lies before the last step’s time.DEFORMABLE_STATUS_INVALID_WORKER_COUNT(17)A worker count of 0.DEFORMABLE_STATUS_CANCELLED(18)The cancel flag stopped a tool.DEFORMABLE_STATUS_OUTPUT_TOO_LARGE(19)The output would hold more elements than 32-bit indices address, or, fordeformable_autocage, the targets ask for triangles finer than the tool resolves.DEFORMABLE_STATUS_DEGENERATE_POLYGON(20)Polygonfirst_indexhas a loop of fewer than 3 vertices, a zero normal or loops the triangulator cannot mesh.DEFORMABLE_STATUS_NON_MANIFOLD_EDGE(21)The edge between verticesfirst_indexandsecond_indexborders three or more polygons.DEFORMABLE_STATUS_NON_CLOSED_BOUNDARY(22)The edge between verticesfirst_indexandsecond_indexborders only one polygon.DEFORMABLE_STATUS_COULD_NOT_CONVERGE(23)The triangulation of a polygon mesh did not settle at any quality.DEFORMABLE_STATUS_BAD_SCALES(24)An anisotropy scale or direction is NaN.DEFORMABLE_STATUS_MESHING_FAILED(25)The mesher stopped without a mesh, or the maximum edge length is 0 or less.DEFORMABLE_STATUS_NO_TETRAHEDRONS(26)The mesh has no tetrahedron.DEFORMABLE_STATUS_INVALID_CAGE(27)The cage is not closed, does not face outward, or crosses itself.DEFORMABLE_STATUS_NON_POSITIVE_THICKNESS(28)The extrusion thickness is 0, negative or NaN.DEFORMABLE_STATUS_NOT_ISOMORPHIC(29)The two layers do not have the same vertices and faces.DEFORMABLE_STATUS_UNKNOWN_VERTEX(30)Facefirst_indexnames a vertex past the end of the positions.DEFORMABLE_STATUS_DUPLICATE_VERTEX(31)Facefirst_indexuses one vertex at two corners.DEFORMABLE_STATUS_MULTIPLE_BOUNDARIES(32)The faces around vertexfirst_indexform more than one fan.DEFORMABLE_STATUS_DEGENERATE_FACE(33)Facefirst_indexhas a zero normal.DEFORMABLE_STATUS_NULL_NORMAL(34)The angle-weighted normals around vertexfirst_indexcancel out.DEFORMABLE_STATUS_EMPTY_INPUT(35)No polygon has three or more corners, or all the vertices they use coincide.DEFORMABLE_STATUS_STEP_LIMIT_REACHED(36)The autocage front did not close within its step cap.DEFORMABLE_STATUS_INVALID_SPLINTER_CAGE(37)A splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.DEFORMABLE_STATUS_EMPTY_IMAGE(38)The image width or height is 0.DEFORMABLE_STATUS_NO_VERTICES(39)The image has no vertex pixel, or none is left after the cleanup.DEFORMABLE_STATUS_NO_CELLS(40)The image has vertices but no closed cell.DEFORMABLE_STATUS_ENDLESS_CYCLE(41)A splinter face trace took more steps than there are vertices.DEFORMABLE_STATUS_FACE_ALREADY_SET(42)A splinter face trace met an edge side another face already holds.DEFORMABLE_STATUS_SINGULAR_TRANSFORM(43)The world transform has no inverse: its linear part is singular, or its inverse overflows.DEFORMABLE_STATUS_TETRAHEDRON_LIMIT_EXCEEDED(44)Under the Free license, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates:first_indexis the tetrahedrons the scene would simulate with it (those of the objects it simulates now, and the object’s),second_indexthe limit. Nothing is created and the rest of the scene runs. The message says both numbers, such as “Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.DEFORMABLE_STATUS_LICENSE_KEY_REJECTED(46)The license key was refused. The licensing service refused the Standard key: it does not exist, was revoked or refunded, is not for Deformable, every seat of the license is in use, or this device was removed. Or the Developer key was revoked, is a trial key that ended, covers only versions released before this one, or was given inside a plugin host.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILED(47)The per-user license store could not be written; the message names its folder.
See also Guide: The status codes · Rust ErrorKind · Python Status
deformable_last_error_message
Function · deformable.h
const char *deformable_last_error_message(void);The message of the last failed call on the calling thread, as a NUL-terminated UTF-8 string in English; empty when the latest status-returning call on this thread succeeded. A license status’s message is written to show the user as it is.
The string is owned by the library and stays valid until the next status-returning call on the same thread; copy it to keep it longer. This call itself never changes the last error.
Example
if (deformable_scene_set_worker_count(scene, 0))
puts(deformable_last_error_message());See also Guide: Status codes and the last error · Rust Error::message
deformable_last_error_details
Function · deformable.h
DeformableStatus deformable_last_error_details(
DeformableErrorDetails *details);Writes the status and indices of the last failed call on the calling thread to details; the status is
DEFORMABLE_STATUS_OK when the latest status-returning call on this thread succeeded.
Unlike every other call that returns a status, this one leaves the last error as it is, so a failure it reports (a
NULL details) is returned but not recorded.
Parameters
details(DeformableErrorDetails *)Out. Receives the status and the two indices.
Errors
- Only the statuses every call can give, which the conventions describe.
Example
DeformableStatus status =
deformable_scene_set_worker_count(scene, 0);
DeformableErrorDetails details;
CHECK(deformable_last_error_details(&details));
// details.status is status; this status names no element.
if (details.status == status && details.first_index == 0)
puts(deformable_last_error_message());See also Guide: Status codes and the last error
deformable_last_error_clear
Function · deformable.h
DeformableStatus deformable_last_error_clear(void);Clears the last error of the calling thread, so that the next failure is the only one reported. Any other call
that returns a status clears it too when it succeeds, except deformable_last_error_details.
Errors
- Only the statuses every call can give, which the conventions describe.
Example
// A count of 0 is refused, which leaves a last error.
DeformableStatus status =
deformable_scene_set_worker_count(scene, 0);
CHECK(deformable_last_error_clear());
DeformableErrorDetails details;
CHECK(deformable_last_error_details(&details));
puts(details.status != status ? "cleared" : "kept"); // clearedSee also Guide: Status codes and the last error
deformable_version
Function · deformable.h
const char *deformable_version(void);The library version, as major.minor.patch, in a static NUL-terminated string the host never frees.
Example
const char *version = deformable_version();
puts(version);See also Rust version · Python library_version
DeformableCancelFlag
Opaque handle · deformable.h
typedef struct DeformableCancelFlag DeformableCancelFlag;A cancel flag: set from any thread, it stops a running tool with DEFORMABLE_STATUS_CANCELLED or a running step with
DEFORMABLE_STEP_OUTCOME_CANCELLED.
deformable_scene_step, deformable_triangulate, deformable_tetrahedralize and deformable_autocage take one, or
NULL for none, and stop at their next check once it is set: a tool at once when it is already set, a step after its
first substep. The flag stays set until it is cleared, and one flag can serve several calls at once. Every call on
it is thread-safe, so a host’s interface thread can set it while a step or a tool reads it on another thread.
Example
DeformableCancelFlag *cancel = NULL;
CHECK(deformable_cancel_flag_create(&cancel));
// Set before the call, the tool stops at once.
CHECK(deformable_cancel_flag_set(cancel, 1));
DeformableTriangulateParameters parameters;
CHECK(deformable_triangulate_parameters_default(¶meters));
DeformableTriangulation *result = NULL;
DeformableStatus status = deformable_triangulate(&polygons, NULL, 0,
¶meters, cancel,
&result);
puts(status == DEFORMABLE_STATUS_CANCELLED ? "cancelled" : "ran");
deformable_cancel_flag_destroy(cancel);See also Guide: Cancel a long call · Rust CancelFlag · Python CancelFlag
deformable_cancel_flag_create
Function · deformable.h
DeformableStatus deformable_cancel_flag_create(
DeformableCancelFlag **flag);Creates a cancel flag, not set, and writes its handle to flag.
Parameters
flag(DeformableCancelFlag **)Out. Receives a new handle; free it withdeformable_cancel_flag_destroyonce no call uses it.
Errors
- Only the statuses every call can give, which the conventions describe.
See also Rust CancelFlag::new
deformable_cancel_flag_destroy
Function · deformable.h
void deformable_cancel_flag_destroy(DeformableCancelFlag *flag);Destroys a cancel flag; NULL is ignored. No call, on any thread, may be using it.
Parameters
flag(DeformableCancelFlag *)The flag to destroy, orNULL.
See also Python CancelFlag.close
deformable_cancel_flag_set
Function · deformable.h
DeformableStatus deformable_cancel_flag_set(
const DeformableCancelFlag *flag,
uint8_t cancelled);Sets (cancelled not 0) or clears (cancelled 0) the flag. Any thread may call it while another runs a call that reads
the flag; that call stops at its next check.
Parameters
flag(const DeformableCancelFlag *)The flag to set or clear.cancelled(uint8_t)Not 0 sets the flag, 0 clears it so the flag can be used again.
Errors
- Only the statuses every call can give, which the conventions describe.
See also Rust CancelFlag::set · Python CancelFlag.set
deformable_cancel_flag_is_set
Function · deformable.h
DeformableStatus deformable_cancel_flag_is_set(
const DeformableCancelFlag *flag,
uint8_t *cancelled);Writes 1 to cancelled when the flag is set and 0 otherwise.
Parameters
flag(const DeformableCancelFlag *)The flag to read.cancelled(uint8_t *)Out. Receives 1 when the flag is set, 0 otherwise.
Errors
- Only the statuses every call can give, which the conventions describe.
See also Rust CancelFlag::is_set · Python CancelFlag.is_set