You are viewing the documentation for Deformable v0.1.0, an older version. Read the latest, v0.9.0
C API Reference
License
The license state of this device, and the calls that refresh, activate and deactivate it.
On this page
The license of this device and user: its state, and the calls that refresh, activate and deactivate it. Every engine call checks the license first, and a call the license refuses fails with a license DeformableStatus; the error’s message is written to show the user as it is, such as “Trial ended — Buy license” or “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.
The library keeps one license state per device and user, shared by every program that loads it: the plugins and the SDKs. deformable_license_status never contacts the licensing service and is cheap enough to call on every redraw. deformable_license_refresh, deformable_license_activate and deformable_license_deactivate wait on the network for at most their timeout, so a host with an interface calls them off its interface thread. deformable_license_set_online_access keeps a process off the network when its user asked for that.
DeformableLicenseState
Enum · deformable.h
typedef int32_t DeformableLicenseState;The license state of this device and user, as DeformableLicenseStatus reports it in state. Every program that
loads the library shares it.
Values
DEFORMABLE_LICENSE_STATE_NOT_STARTED(0)No trial or license yet: the nextdeformable_license_refresh, or the first engine call, starts the trial online.DEFORMABLE_LICENSE_STATE_TRIAL(1)The trial runs: every feature, at mosttetrahedron_limit(2,500) tetrahedrons per scene.DEFORMABLE_LICENSE_STATE_TRIAL_ENDED(2)The trial ended, or this device cannot have one; engine calls giveDEFORMABLE_STATUS_LICENSE_REQUIREDuntil a license is activated.DEFORMABLE_LICENSE_STATE_LICENSED(3)A license is active on this device; no limit.DEFORMABLE_LICENSE_STATE_NEEDS_ONLINE(4)A license (or the trial) needs one online check before engine calls work again.DEFORMABLE_LICENSE_STATE_DEVELOPMENT(5)A development build of the library: licensing is off, engine calls always work and nothing contacts the licensing service.
See also Guide: License · Rust LicenseState · Python LicenseState
DeformableLicenseStatus
Struct · deformable.h
typedef struct DeformableLicenseStatus {
DeformableLicenseState state;
uint32_t days_left;
uint32_t tetrahedron_limit;
uint8_t usable;
uint8_t needs_online;
uint8_t has_license_key;
char message[64];
} DeformableLicenseStatus;The license state as a status line shows it.
Fields
state(DeformableLicenseState)Which license state the device is in; the other fields detail it.days_left(uint32_t)InDEFORMABLE_LICENSE_STATE_TRIAL, the whole days left, 7 down to 1, counting the current day; 0 in any other state.tetrahedron_limit(uint32_t)The most tetrahedrons one scene may hold: 2,500 inDEFORMABLE_LICENSE_STATE_TRIAL; 0 when there is no limit.usable(uint8_t)1 when engine calls work (trial, licensed or development).needs_online(uint8_t)1 when the state changes only after an online check (not started, or needs online).has_license_key(uint8_t)1 when a license key is stored on this device, so a host offers Deactivate rather than Activate.message(char[64])The status line, NUL-terminated UTF-8: “Trial: 7 days left”, “Trial ended — Buy license”, “Licensed”, …
See also Guide: License · Rust LicenseStatus · Python LicenseStatus
deformable_license_status
Function · deformable.h
DeformableStatus deformable_license_status(
DeformableLicenseStatus *status);Writes the license state of this device and user to status. It never contacts the licensing service and never
waits on the network: it reads the per-user license state at most once every 2 seconds, so it is cheap enough to
call on every redraw.
Parameters
status(DeformableLicenseStatus *)Out. Receives the license state.
Errors
- Only the statuses every call can give, which the conventions describe.
Example
DeformableLicenseStatus status;
CHECK(deformable_license_status(&status));
if (!status.usable)
puts(status.message);See also Guide: License · Rust status · Python license.status
deformable_license_refresh
Function · deformable.h
DeformableStatus deformable_license_refresh(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Brings the license up to date with the licensing service when a contact is due, waiting at most timeout_milliseconds.
A device that never started its trial starts it; a trial reports itself once a day and keeps the earliest start the
service remembers for this device, so a reinstall does not restart it; a stored license renews when its last renewal
is 6 hours old or it needs online. Otherwise nothing is sent.
It waits on the network, so a host with an interface calls it off its interface thread, such as when the program starts. Contacts run one at a time per process: a second caller waits for the first.
Parameters
timeout_milliseconds(uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise.status(DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTtimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, ordeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service no longer accepts the stored license: it was revoked, this device was removed, or it is not a Deformable license. The license is then forgotten.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license state could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
if (deformable_license_refresh(15000, &status))
puts(deformable_last_error_message());
else
puts(status.message);See also Guide: License · Rust refresh · Python license.refresh
deformable_license_activate
Function · deformable.h
DeformableStatus deformable_license_activate(
const char *license_key,
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Activates license_key on this device with the licensing service, waiting at most timeout_milliseconds; the state is
then DEFORMABLE_LICENSE_STATE_LICENSED. A key already active here is renewed instead. It waits on the network, so a
host with an interface calls it off its interface thread.
On failure, deformable_last_error_message says why the key was not activated, written to show the user as it is.
Parameters
license_key(const char *)The license key, NUL-terminated UTF-8, such as"TGDF-XXXX-XXXX-XXXX"; letter case, spaces and dashes do not matter.timeout_milliseconds(uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise.status(DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTlicense_keyis not UTF-8 or no license key, another key is stored on this device (“Deactivate the current license first”), ortimeout_millisecondsis 0. Nothing changes then.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service refused the key: it does not exist, was revoked or expired, is not a Deformable license, or its seat is in use on another device; or the service takes no more devices.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, ordeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license state could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
const char *key = "TGDF-XXXX-XXXX-XXXX";
if (deformable_license_activate(key, 15000, &status))
puts(deformable_last_error_message());
else
puts(status.message);See also Guide: License · Rust activate · Python license.activate
deformable_license_deactivate
Function · deformable.h
DeformableStatus deformable_license_deactivate(
uint32_t timeout_milliseconds,
DeformableLicenseStatus *status);Frees this device’s seat with the licensing service, then forgets the key, waiting at most timeout_milliseconds, so
the license can be activated on another computer. The key is forgotten only once the service confirms, or says the
seat is already gone. With no key stored it does nothing and succeeds. It waits on the network, so a host with an
interface calls it off its interface thread.
Parameters
timeout_milliseconds(uint32_t)How long to wait for the service, in milliseconds: at least 1; above 60,000 counts as 60,000. 15,000 (15 s) suits a host with no reason to choose otherwise.status(DeformableLicenseStatus *)Out. Receives the license state after the call, on success and on aDEFORMABLE_STATUS_LICENSE_*failure, so a host shows the state after a failure too. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTtimeout_millisecondsis 0.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not confirm, ordeformable_license_set_online_accessforbade every contact. Nothing changes then; the device can also be removed in the license portal.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license state could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
CHECK(deformable_license_deactivate(15000, &status));
// has_license_key is 0 now: the host offers Activate again.
puts(status.message);See also Guide: License · Rust deactivate · Python license.deactivate
deformable_license_set_online_access
Function · deformable.h
DeformableStatus deformable_license_set_online_access(uint8_t allowed);Allows (allowed not 0, the default) or forbids (allowed 0) every contact with the licensing service from this
process, for a host whose user turned online access off. Forbidden, nothing is sent: deformable_license_refresh,
deformable_license_activate and deformable_license_deactivate give DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE and
change nothing, and engine calls neither start the trial nor renew the license on their own, so a state that needs
the service stays as it is and a lease runs out as it would offline. It grants nothing, and it fails only when the
library fails inside.
Parameters
allowed(uint8_t)Not 0 allows every contact, 0 forbids them.
Errors
- Only the statuses every call can give, which the conventions describe.
Example
// The user turned online access off in the host's settings.
CHECK(deformable_license_set_online_access(0));See also Guide: License · Rust set_online_access · Python license.set_online_access