Core

Core API functions.

Functions


int VRBulkData(void)

Specifies if there a large amount of data pending transfer between vrtree instances.

Returns

1 on success

Permission: SC_NETWORK


void VRClearLastError(void)

Manually clear the last error code.


Closes a node handle, clearing its connection to VRTree.

Parameters
node

handle to close. Becomes unusable.


Releases a previously requested security context.


Releases a unique userdata slot handle.

This does not remove userdata stored on nodes using this slot handle. That data must be cleaned up before closing the slot handle to avoid data leaks.

Parameters
slot

an open slot handle


int VRConnect(const char * addr,
int port
)

Connect to another instance of VRTree (e.g. Visionary Render) and synchronise trees.

Parameters
addr

address of the remote instance

port

TCP port that the remote instance is listening on

Returns

1 on success

Permission: SC_NETWORK


Creates a new node handle based off the old one.

Parameters
node

handle stays open.

Returns

new node handle, VRCloseNodeHandle when you are done with it


Diagnostic function.

Returns

the number of open node handles


Gets the VRTree API Major version.

This version represents backward compatibility. It should be checked when loading the library, against an expected value. If it is not what is expected, the API may not function according to the expectations of the program using it.


Gets the VRTree API Minor version.

This version number represents additions to the API and does not affect backward compatibility.


uint32_t VRGetLastError(void)

Gets the last error code.

This function does not clear the error.

Returns

The last error code


const char * VRGetLastErrorString(void)

Gets the last error string.

This function DOES clear the error using VRClearLastError. The returned string is only valid until the next operation that sets a new error string.

Returns

the error string, or NULL if there is no error string to return.


HNode VRGetNodeFromUUID(uint64_t lo,
uint64_t hi
)

Gets the node with the specified UUID.

Parameters
lo

low 64-bits of the UUID

hi

high 64-bits of the UUID

Returns

node handle, or 0 on error / non-existant

Permission: SC_READ


Gets the metanode version of the specified node.

Parameters
node

node to query

Returns

version, or -1 on error / non-existant

Permission: SC_READ


uint64_t VRGetUUIDHigh(HNode node)

Gets the high 64-bits of a node's unique ID.

Returns

high 64-bits or 0 on error

Permission: SC_READ


uint64_t VRGetUUIDLow(HNode node)

Gets the low 64-bits of a node's unique ID.

Returns

low 64-bits or 0 on error

Permission: SC_READ


int VRInit(int port)

Initialise VRTree.

Parameters
port

the TCP port on which to listen for collaboration connection requests

Returns

0 on success

Permission: SC_INIT


Checks if a node handle is valid.

Parameters
node

handle to check

Returns

1 if the handle is valid, 0 if it is invalid (i.e. if it was closed already)

Permission: SC_READ


Requests a unique userdata slot identifier.

The userdata slot system can be used by plugins to attach plugin-specific data to a specific node and retrieve it again later.

Generally a plugin should request one or more unique data slots on initialization and keep them open for the lifetime of the plugin. It does not need one per node - the userdata slot handle should be considered the unique slot identifier for plugin data on ALL nodes. Using more than one is only necessary if the plugin needs to store more than one piece of data on a single node, and even then only in the case where storing it in a struct in the first slot is not appropriate.

This data is not managed by the application, so it is up to the plugin to make sure it removes any userdata it adds before closing its user slot handle.

Returns

slot handle, or 0 on error

Permission: SC_MODIFY


HAuth VRRequestSecurityContext(const char * auth,
const char * name
)

Requests a change in the API security context to grant access to API functions by categories specified in the auth string.

Most plugins should let the plugin manager deal with this automatically by exporting their signature string as a VRPSignatureProc. This API exists for programs that load vrtree.dll independently of Visionary Render, in which case the auth string is likely to be required to specify SC_INIT permissions in order to be able to do anything useful.

Parameters
auth

full contents of an API license (signed xml)

name

the name of the application requesting the context

Returns

a new auth handle indicating successful context switch, or 0 on error / invalid auth

Note

New contexts are pushed onto a stack, meaning that when the returned context is closed, access controls revert to the level provided by the previous security context.


void VRSetAPIErrorLevel(uint32_t flags)

Sets the API error level, which controls which types of errors are reported and logged.

Parameters
flags

one or more Logging masks which enable error reporting by type


void VRSetImmediateErrorLog(char enabled)

Specifies that errors tracked by VRSetAPIErrorLevel are also logged the the application log immediately rather than only being stored for VRGetLastErrorString.

Parameters
enabled

1 or above to enable immediate error logging


void VRShutdown(void)

Disconnect from the network and shut down.

Permission: SC_NETWORK


void VRUpdate(double deltaTime)

Perform a full update, notifying observers and updating actors.

Parameters
deltaTime

the time since the last frame (or any other value that will affect the step size of any actors)

Permission: SC_OBSERVE

No Results.

Getting StartedArchitectureBest PracticesHow ToAdvanced TopicsChangelogvrtree_cppCoreForeign Function InterfaceMetanodesMigrationsObserversPropertiesTreeUtilitiesAPI DefinitionsVR ExchangePluginsLua API