You are viewing the documentation for Deformable v0.5.0, an older version. Read the latest, v0.9.0

Rust 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 ErrorKind that names what went wrong, and the Error that carries it. Then the library version, and the CancelFlag that stops a long call from another thread.

Error

Struct · deformable::Error

rust
pub struct Error { /* private fields */ }

A failed call: what went wrong, the library’s message and up to two element indices.

The indices name the tetrahedron, region, polygon, face, vertex or edge the failure concerns, or the Free license’s tetrahedron count and limit, as the ErrorKind variant says; they are 0 when it names none. Its Display is the message. Arguments the C interface cannot carry are refused by the crate itself, before the library is called, with the same type and indices of 0.

Implements Clone · Debug · Display · Eq · PartialEq · std::error::Error · Send · Sync

Example

rust
let error = scene.set_worker_count(0).unwrap_err();
assert_eq!(error.kind(), ErrorKind::InvalidWorkerCount);
assert_eq!(error.first_index(), 0);
println!("{error}");

See also Guide: The error type · C DeformableErrorDetails · Python DeformableError

Error::kind

Method · deformable::Error::kind

rust
pub fn kind(&self) -> ErrorKind

What went wrong.

Error::first_index

Method · deformable::Error::first_index

rust
pub fn first_index(&self) -> u32

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.

Error::second_index

Method · deformable::Error::second_index

rust
pub fn second_index(&self) -> u32

The second index the failure names (the region’s polygon, the edge’s second vertex, or the Free license’s tetrahedron limit), or 0.

Error::message

Method · deformable::Error::message

rust
pub fn message(&self) -> &str

The description of the failure, in English: the library’s, or the crate’s own for an argument it refused. A license kind’s message is written to show the user as it is.

See also C deformable_last_error_message

ErrorKind

Enum · deformable::ErrorKind

rust
pub enum ErrorKind {
    NullPointer,
    InvalidArgument,
    Panicked,
    IndexOutOfRange,
    UnknownMaterial,
    UnknownObject,
    LengthMismatch,
    NonFiniteValue,
    EmptyMesh,
    NonManifoldFace,
    DegenerateTetrahedron(DegenerateKind),
    ScaleOutOfRange,
    DegenerateRegion,
    TimeWentBackwards,
    InvalidWorkerCount,
    Cancelled,
    OutputTooLarge,
    DegeneratePolygon,
    NonManifoldEdge,
    NonClosedBoundary,
    CouldNotConverge,
    BadScales,
    MeshingFailed,
    NoTetrahedrons,
    InvalidCage,
    NonPositiveThickness,
    NotIsomorphic,
    UnknownVertex,
    DuplicateVertex,
    MultipleBoundaries,
    DegenerateFace,
    NullNormal,
    EmptyInput,
    StepLimitReached,
    InvalidSplinterCage,
    EmptyImage,
    NoVertices,
    NoCells,
    EndlessCycle,
    FaceAlreadySet,
    SingularTransform,
    TetrahedronLimitExceeded,
    LicenseServiceUnavailable,
    LicenseKeyRejected,
    LicenseStorageFailed,
    Unrecognized(i32),
}

What went wrong: one kind per failure status of the library, the three degenerate tetrahedron statuses in one kind with a DegenerateKind.

The indices of the Error name the element a kind concerns, as each variant says; they are 0 when it names none. The enum is #[non_exhaustive], since a newer library can add statuses: a status this crate does not know comes as Unrecognized.

Values

  • NullPointerA required pointer was null. The safe API never passes one; seeing it means a defect in this crate.
  • InvalidArgumentAn argument the library cannot read: an undefined enumeration value, an array larger than the address space, or a material preset name the library does not ship. The license calls give it for text that is no license key, an Application license key that does not verify, another Standalone key while one is stored, another Application key once one is set, and a Standalone key in a program on an Application license.
  • PanickedThe library panicked; the handles the call used should be dropped.
  • IndexOutOfRangeAn index points past the end of the list it indexes; for the polygon tools the first index names the polygon.
  • UnknownMaterialA material handle names no material of the scene.
  • UnknownObjectAn object handle names no object of the scene, or a removed one.
  • LengthMismatchA list does not have the length its partner requires.
  • NonFiniteValueA position or parameter is NaN or infinite.
  • EmptyMeshA mesh has no tetrahedrons, vertices or polygons.
  • NonManifoldFaceThree or more tetrahedrons share one face.
  • DegenerateTetrahedron (DegenerateKind)The tetrahedron the first index names fails the quality check: its orientation determinant is not above 1e-9. The DegenerateKind says whether it is too small, flat or inverted.
  • ScaleOutOfRangeThe length scale lies outside [0.001, 1,000].
  • DegenerateRegionThe polygon the second index names, of the material region the first index names, has fewer than 3 vertices or a zero normal.
  • TimeWentBackwardsA step’s time lies before the last step’s time.
  • InvalidWorkerCountA worker count of 0.
  • CancelledThe cancel flag stopped a tool.
  • OutputTooLargeThe output would hold more elements than 32-bit indices address, or, for autocage, the targets ask for triangles finer than the tool resolves.
  • DegeneratePolygonThe polygon the first index names has a loop of fewer than 3 vertices, a zero normal or loops the triangulator cannot mesh.
  • NonManifoldEdgeThe edge between the vertices the first and second index name borders three or more polygons.
  • NonClosedBoundaryThe edge between the vertices the first and second index name borders only one polygon.
  • CouldNotConvergeThe triangulation of a polygon mesh did not settle at any quality.
  • BadScalesAn anisotropy scale or direction is NaN.
  • MeshingFailedThe mesher stopped without a mesh, or the maximum edge length is 0 or less.
  • NoTetrahedronsThe mesh has no tetrahedron.
  • InvalidCageThe cage is not closed, does not face outward, or crosses itself.
  • NonPositiveThicknessThe extrusion thickness is 0, negative or NaN.
  • NotIsomorphicThe two layers do not have the same vertices and faces.
  • UnknownVertexThe face the first index names has a vertex past the end of the positions.
  • DuplicateVertexThe face the first index names uses one vertex at two corners.
  • MultipleBoundariesThe faces around the vertex the first index names form more than one fan.
  • DegenerateFaceThe face the first index names has a zero normal.
  • NullNormalThe angle-weighted normals around the vertex the first index names cancel out.
  • EmptyInputNo polygon has three or more corners, or all the vertices they use coincide.
  • StepLimitReachedThe autocage front did not close within its step cap.
  • InvalidSplinterCageA splinter cage polygon has fewer than 3 vertices, or a brick has 3 faces or fewer.
  • EmptyImageThe image width or height is 0.
  • NoVerticesThe image has no vertex pixel, or none is left after the cleanup.
  • NoCellsThe image has vertices but no closed cell.
  • EndlessCycleA splinter face trace took more steps than there are vertices.
  • FaceAlreadySetA splinter face trace met an edge side another face already holds.
  • SingularTransformThe world transform has no inverse: its linear part is singular, or its inverse overflows.
  • TetrahedronLimitExceededUnder the Free license, adding the object would take the scene past the 2,500 tetrahedrons one scene simulates: the first index is the tetrahedrons the scene would simulate with it (those of the objects it simulates now, and the object’s), the second the 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”.
  • LicenseServiceUnavailableThe 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.
  • LicenseKeyRejectedThe 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.
  • LicenseStorageFailedThe per-user license store could not be written; the message names its folder.
  • Unrecognized (i32)A code this crate does not know, from a newer library: a status, a step outcome or a mesh issue kind.

Implements Clone · Copy · Debug · Eq · Hash · PartialEq · Send · Sync

See also Guide: Error kinds · C DeformableStatus · Python Status

ErrorKind::is_license

Method · deformable::ErrorKind::is_license

rust
pub fn is_license(self) -> bool

Whether the failure is about the license of this program rather than the call’s arguments; its message is then a status line, the licensing service’s answer or why an Application key was refused, written to show the user as it is.

It is true for the four license kinds, from TetrahedronLimitExceeded to LicenseStorageFailed.

Example

rust
use deformable::ErrorKind;

assert!(ErrorKind::TetrahedronLimitExceeded.is_license());
assert!(!ErrorKind::InvalidArgument.is_license());

See also Python Status.is_license

version

Function · deformable::version

rust
pub fn version() -> &'static str

The version of the linked libdeformable, as major.minor.patch. It matches the crate’s version when the two come from the same release.

Example

rust
let version = deformable::version();
assert_eq!(version.split('.').count(), 3);
println!("libdeformable {version}");

See also C deformable_version · Python library_version

CancelFlag

Struct · deformable::CancelFlag

rust
pub struct CancelFlag { /* private fields */ }

A cancel flag: set from any thread, it stops a running tool with ErrorKind::Cancelled or a running step with StepOutcome::Cancelled.

Scene::step, triangulate, tetrahedralize and autocage take one 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 through a shared reference while a step or a tool reads it on another thread.

Implements Debug · Default · Drop · Send · Sync

Example

rust
let cancel = CancelFlag::new();
cancel.set(true);
let parameters = TriangulateParameters::default();
let result = triangulate(&polygons, &[], &parameters, Some(&cancel));
assert_eq!(result.unwrap_err().kind(), ErrorKind::Cancelled);

See also Guide: Cancel a long call · C DeformableCancelFlag · Python CancelFlag

CancelFlag::new

Associated function · deformable::CancelFlag::new

rust
pub fn new() -> Self

A flag, not set. Dropping it frees it; a call that borrows it keeps it alive until the call ends.

Panics when the library fails inside and cannot create the flag.

See also C deformable_cancel_flag_create

CancelFlag::set

Method · deformable::CancelFlag::set

rust
pub fn set(&self, cancelled: bool)

Sets (true) or clears (false) the flag; a call that reads it stops at its next check.

Parameters

  • cancelled (bool)true sets the flag, false clears it so the flag can be used again.

See also C deformable_cancel_flag_set · Python CancelFlag.set

CancelFlag::is_set

Method · deformable::CancelFlag::is_set

rust
pub fn is_set(&self) -> bool

True when the flag is set.

See also C deformable_cancel_flag_is_set · Python CancelFlag.is_set