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

c
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 Free’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_OK when 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 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 Free’s tetrahedron limit), or 0.

See also Guide: Status codes and the last error · Rust Error · Python DeformableError

DeformableStatus

Enum · deformable.h

c
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 is NULL, or an array pointer is NULL while 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, an Application license key that does not verify, another Standalone key while one is stored, a Standalone key while a Standalone subscription is signed in or a sign-in while a key is stored or another sign-in has not ended, a wait for or a take-over of a sign-in that is not there, another Application key once one is set, and a Standalone key or a sign-in in a program on an Application 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)Tetrahedron first_index has a positive orientation determinant above 1e-15 and at most 1e-9, or a NaN one.
  • DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_FLAT (12)Tetrahedron first_index has an orientation determinant of magnitude at most 1e-15.
  • DEFORMABLE_STATUS_DEGENERATE_TETRAHEDRON_INVERTED (13)Tetrahedron first_index is 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)Polygon second_index of material region first_index has 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, for deformable_autocage, the targets ask for triangles finer than the tool resolves.
  • DEFORMABLE_STATUS_DEGENERATE_POLYGON (20)Polygon first_index has 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 vertices first_index and second_index borders three or more polygons.
  • DEFORMABLE_STATUS_NON_CLOSED_BOUNDARY (22)The edge between vertices first_index and second_index borders 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)Face first_index names a vertex past the end of the positions.
  • DEFORMABLE_STATUS_DUPLICATE_VERTEX (31)Face first_index uses one vertex at two corners.
  • DEFORMABLE_STATUS_MULTIPLE_BOUNDARIES (32)The faces around vertex first_index form more than one fan.
  • DEFORMABLE_STATUS_DEGENERATE_FACE (33)Face first_index has a zero normal.
  • DEFORMABLE_STATUS_NULL_NORMAL (34)The angle-weighted normals around vertex first_index cancel 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 Free, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates: first_index is the tetrahedrons the scene would simulate with it (those of the objects it simulates now, and the object’s), second_index the limit. Nothing is created and the rest of the scene runs. The message says both numbers, such as “Free: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.
  • DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE (45)The licensing service could not be reached (no network, a timeout, a busy service), did not answer, or gave an answer that did not verify or that this device’s clock contradicts; or online access is off in this process; or another Deformable program on this device held the sign-in past the call’s timeout.
  • DEFORMABLE_STATUS_LICENSE_KEY_REJECTED (46)The license key was refused. The licensing service refused the Standalone 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 Application 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.
  • DEFORMABLE_STATUS_LICENSE_SIGN_IN_FAILED (48)The sign-in to a Standalone subscription failed: it was denied, its code is no longer valid, this version of the library may not sign in, the licensing service could not read the request, or its answer did not verify.

See also Guide: The status codes · Rust ErrorKind · Python Status

deformable_last_error_message

Function · deformable.h

c
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

c
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

c
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

Errors

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

Example

c
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

c
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

c
// 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"); // cleared

See also Guide: Status codes and the last error

deformable_version

Function · deformable.h

c
const char *deformable_version(void);

The library version, as major.minor.patch, in a static NUL-terminated string the host never frees.

Example

c
const char *version = deformable_version();
puts(version);

See also Rust version · Python library_version

DeformableCancelFlag

Opaque handle · deformable.h

c
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

c
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(&parameters));
DeformableTriangulation *result = NULL;
DeformableStatus status = deformable_triangulate(&polygons, NULL, 0,
                                                 &parameters, 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

c
DeformableStatus deformable_cancel_flag_create(
    DeformableCancelFlag **flag);

Creates a cancel flag, not set, and writes its handle to flag.

Parameters

Errors

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

See also Rust CancelFlag::new

deformable_cancel_flag_destroy

Function · deformable.h

c
void deformable_cancel_flag_destroy(DeformableCancelFlag *flag);

Destroys a cancel flag; NULL is ignored. No call, on any thread, may be using it.

Parameters

See also Python CancelFlag.close

deformable_cancel_flag_set

Function · deformable.h

c
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

c
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

Errors

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

See also Rust CancelFlag::is_set · Python CancelFlag.is_set