You are viewing the documentation for Deformable v0.1.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

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 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_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 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

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, and for another key while one is stored.
  • 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_LICENSE_REQUIRED (44)No usable trial or license on this device: the trial ended, this device cannot have one, or the license was removed. The message is the license status line, such as “Trial ended — Buy license”, written to show the user as it is.
  • DEFORMABLE_STATUS_TRIAL_LIMIT_EXCEEDED (45)The trial allows at most 2,500 tetrahedrons per scene and this call would go over: first_index is the tetrahedrons that would take part, those of the scene’s enabled objects (a disabled object does not count), second_index the 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 trial never started, the 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_SERVICE_UNAVAILABLE (47)The licensing service could not be reached (no network, a timeout, a busy service), refused this copy of the library, or gave an answer that did not verify; or online access is off in this process.
  • DEFORMABLE_STATUS_LICENSE_KEY_REJECTED (48)The licensing service refused the license key: unknown, revoked or expired, of another product, or its seat is in use on another device; or the service takes no more devices.
  • 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

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