You are viewing the documentation for Deformable v0.4.0, an older version. Read the latest, v0.9.0
C API Reference
License
The license state of this device, or of this program under a Developer license, and the calls that refresh, activate and deactivate it.
On this page
The license: its state, and the calls that refresh, activate and deactivate it. Nothing ever refuses to run: without a license the Free license runs, and a scene simulates at most 2,500 tetrahedrons. Two licenses lift the limit: the Standard license of this device and user, and the Developer license that a program activates for itself. A license failure’s message is written to show the user as it is, such as “Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.
deformable_license_activate takes both kinds of key. A Standard key is activated online once and stays on the device; the library keeps one Standard state per device and user, shared by every program that loads it: the plugins and the SDKs. A Developer key is checked offline and holds for the process only, so a program activates it at every start, before any other engine call; with it, the other calls contact nothing, and a plugin host refuses it. 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 program, as DeformableLicenseStatus reports it in state: its Developer license, or else
the Free or Standard license of this device and user, which every program that loads the library shares.
Values
DEFORMABLE_LICENSE_STATE_FREE_LICENSE(0)No license key: the Free license, at mosttetrahedron_limit(2,500) tetrahedrons per scene.DEFORMABLE_LICENSE_STATE_STANDARD_LICENSE(1)A Standard license key with a lease that licenses this device; no limit.DEFORMABLE_LICENSE_STATE_NEEDS_ONLINE(2)A Standard license key whose lease ran out, or that this device’s clock leaves untrusted: the Free license runs until the next renewal online.DEFORMABLE_LICENSE_STATE_DEVELOPMENT(3)A development build of the library: licensing is off, no limit, and nothing contacts the licensing service. It is not the Developer license.DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL(4)A Developer trial key runs in this program: no limit, until the key ends.DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL_ENDED(5)The Developer trial key of this program ended: the Free license runs.DEFORMABLE_LICENSE_STATE_DEVELOPER_LICENSE(6)A full Developer license key runs in this program; no limit.
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 has_license_key;
char message[128];
} DeformableLicenseStatus;The license state as a status line shows it.
Fields
state(DeformableLicenseState)Which license state the program is in; the other fields detail it.days_left(uint32_t)InDEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL, the whole days until the trial key ends counting the current day; 0 in any other state.tetrahedron_limit(uint32_t)The most tetrahedrons one scene simulates: 2,500 under the Free license and every state that falls back to it, 0 when there is no limit.has_license_key(uint8_t)1 when a Standard license key is stored on this device, so a host offers Deactivate rather than Activate; 0 under a Developer license.message(char[128])The status line, NUL-terminated UTF-8: “Free license: up to 2,500 tetrahedrons per scene — Buy license”, “Standard license”, “Developer license: Acme Inc.”, … The company of a Developer license is cut to fit.
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 program to status: its Developer license, or else the Free or Standard license of
this device and user. It never contacts the licensing service and never waits on the network: it reads the per-user
license store 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.tetrahedron_limit)
printf("%s (%u per scene)\n", status.message,
(unsigned)status.tetrahedron_limit);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);Renews the stored Standard key’s lease when it no longer licenses this device, or when it is 6 hours old or ends
within a day and no contact ran in the last 5 minutes, waiting at most timeout_milliseconds. Without a key, and under
a Developer license, nothing is sent and it gives the state as it is. The engine renews the lease on its own while it
runs, so a host calls this when the program starts and when its user asks.
It waits on the network, so a host with an interface calls it off its interface thread. 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 or did not answer, its answer did not verify or this device’s clock contradicts it, ordeformable_license_set_online_accessforbade every contact. The lease is kept until it runs out.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service no longer accepts the key: it was revoked or refunded, or this device was removed. The license is then forgotten at once and the Free license runs.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store 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, a Standard or a Developer license key, told apart by their shape: a Standard key is
tgdfp-xxxxx-xxxxx-xxxxx-xxxxx, a Developer key tgdfp-<payload hex>-<signature hex>.
A Standard key is activated on this device with the licensing service, waiting at most timeout_milliseconds; the
state is then DEFORMABLE_LICENSE_STATE_STANDARD_LICENSE. The key already stored here renews its lease instead. It
waits on the network, so a host with an interface calls it off its interface thread.
A Developer key is checked offline, without waiting, and licenses this program for as long as it runs: nothing is
stored or sent, so the program activates it at every start, as its first Deformable call, before status and refresh.
The state is then DEFORMABLE_LICENSE_STATE_DEVELOPER_LICENSE, or DEFORMABLE_LICENSE_STATE_DEVELOPER_TRIAL for a trial
key. The same key again changes nothing. A full key covers the versions of the library released until its updates
end, and keeps working in them forever. A development build of the library checks the key the same way but stays
DEFORMABLE_LICENSE_STATE_DEVELOPMENT.
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, where letter case does not matter and spaces and line breaks are removed.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. A Developer key never waits.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, except after a refused Developer key in a program that has neither set a Developer license nor read its license state yet, so a refused key leaves nothing on the device. May beNULL.
Errors
DEFORMABLE_STATUS_INVALID_ARGUMENTlicense_keyis not UTF-8 or no license key (“This is not a license key”), a Developer key that does not verify (“This license key is not valid”), another Standard key while one is stored on this device (“Deactivate the current license first”), another Developer key once one is set (“Another Developer license key is already set in this program”), or a Standard key in a program on a Developer license (“This program uses a Developer license”); ortimeout_millisecondsis 0. Nothing changes then.DEFORMABLE_STATUS_LICENSE_KEY_REJECTEDThe service refused the Standard key: it does not exist, was revoked or refunded, is not for Deformable, or every seat of the license is in use. Or the Developer key was revoked (“This Developer license key was revoked”), is a trial key that ended (“Developer trial ended — Buy license”), covers only versions released before this one, or was given inside a plugin host, where it does not work.DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, ordeformable_license_set_online_accessforbade every contact.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be written; the message names its folder.
Example
DeformableLicenseStatus status;
const char *key = "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx";
if (deformable_license_activate(key, 15000, &status))
puts(deformable_last_error_message());
else
puts(status.message);
// An app on a Developer license activates its key, exactly as
// copied from the Licenses page, first thing at every start.
// This one is shaped like a Developer key but signed by
// nobody, so it is refused.
const char *developer_key =
"tgdfp-7b2276657273696f6e223a317d-"
"0000000000000000000000000000000000000000000000000000000000000000"
"0000000000000000000000000000000000000000000000000000000000000000";
if (deformable_license_activate(developer_key, 15000, &status))
puts(deformable_last_error_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);Forgets the Standard license on this device at once, even offline, so the Free license runs; then frees its seat with
the licensing service, waiting at most timeout_milliseconds, so the key can be activated on another device. When the
seat cannot be freed, the customer removes this device on the Licenses page. With no key stored, or under a
Developer license, 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 seat could not be freed: the service could not be reached, ordeformable_license_set_online_accessforbade every contact. The license is forgotten here all the same.DEFORMABLE_STATUS_LICENSE_STORAGE_FAILEDThe per-user license store could not be changed; 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 and
deformable_license_activate give DEFORMABLE_STATUS_LICENSE_SERVICE_UNAVAILABLE and change nothing,
deformable_license_deactivate forgets the license without freeing its seat, and the engine never renews the lease on
its own, so it runs out as it would offline. A Developer key is checked offline and is not affected. It grants
nothing and reads no license state, 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