You are viewing the documentation for Deformable v0.2.0, 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 trial’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 that would take part in a trial scene), or 0.second_index(uint32_t)The second index the failure names (the region’s polygon, the edge’s second vertex, or the trial’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_LICENSE_REQUIRED(44)No usable trial or license: the Standard trial ended, this device cannot have one, or the Standard license was removed; or the Developer trial key ended. The message is the license status line, such as “Standard trial ended — Buy license”, written to show the user as it is.DEFORMABLE_STATUS_TRIAL_LIMIT_EXCEEDED(45)The Standard trial allows at most 2,500 tetrahedrons per scene and this call would go over:first_indexis the tetrahedrons that would take part, those of the scene’s enabled objects (a disabled object does not count),second_indexthe limit. The message says both numbers, such as “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.DEFORMABLE_STATUS_LICENSE_NEEDS_ONLINE(46)One online check is needed: the Standard trial never started, the Standard license went without a renewal for longer than it may run offline, or the clock is behind. The message is the license status line.DEFORMABLE_STATUS_LICENSE_KEY_REJECTED(48)The license key was refused. The licensing service refused the Standard key: unknown, revoked or expired, of another product, or its seat is in use on another device; or the service takes no more devices. Or the Developer key was revoked, is a trial key that ended, or was given inside a plugin host, where only a Standard license works.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILED(49)The per-user license state 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