You are viewing the documentation for Deformable v0.1.1, 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 trial’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 that would take part in a trial scene), 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 trial’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,
    LicenseRequired,
    TrialLimitExceeded,
    LicenseNeedsOnline,
    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, and for another key while one is stored.
  • 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.
  • LicenseRequiredNo 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.
  • TrialLimitExceededThe trial allows at most 2,500 tetrahedrons per scene and the call would go over: the first index is the tetrahedrons that would take part, those of the scene’s enabled objects (a disabled object does not count), the second the limit. The message says both numbers, such as “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.
  • LicenseNeedsOnlineOne 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.
  • LicenseServiceUnavailableThe 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.
  • LicenseKeyRejectedThe 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.
  • LicenseStorageFailedThe per-user license state 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 device and user rather than the call’s arguments; its message is then a status line or the licensing service’s answer, written to show the user as it is.

It is true for the six license kinds, from LicenseRequired to LicenseStorageFailed.

Example

rust
use deformable::ErrorKind;

assert!(ErrorKind::TrialLimitExceeded.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