You are viewing the documentation for Deformable v0.7.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
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 Free’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
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
pub fn kind(&self) -> ErrorKindWhat went wrong.
Error::first_index
Method · deformable::Error::first_index
pub fn first_index(&self) -> u32The 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.
Error::second_index
Method · deformable::Error::second_index
pub fn second_index(&self) -> u32The second index the failure names (the region’s polygon, the edge’s second vertex, or Free’s tetrahedron limit), or 0.
Error::message
Method · deformable::Error::message
pub fn message(&self) -> &strThe 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
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,
LicenseSignInFailed,
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, 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.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. TheDegenerateKindsays 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 Free, 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: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.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.LicenseSignInFailedThe 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, or the licensing service could not read the request.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
pub fn is_license(self) -> boolWhether 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 five license kinds, from TetrahedronLimitExceeded to
LicenseSignInFailed.
Example
use deformable::ErrorKind;
assert!(ErrorKind::TetrahedronLimitExceeded.is_license());
assert!(!ErrorKind::InvalidArgument.is_license());See also Python Status.is_license
version
Function · deformable::version
pub fn version() -> &'static strThe version of the linked libdeformable, as major.minor.patch. It matches the crate’s version when the two come
from the same release.
Example
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
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
let cancel = CancelFlag::new();
cancel.set(true);
let parameters = TriangulateParameters::default();
let result = triangulate(&polygons, &[], ¶meters, 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
pub fn new() -> SelfA 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
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)truesets the flag,falseclears 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
pub fn is_set(&self) -> boolTrue when the flag is set.
See also C deformable_cancel_flag_is_set · Python CancelFlag.is_set