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.

void VRCloseNodeHandle(

HNode

node

)

Closes a node handle, clearing its connection to VRTree.

Parameters

node	handle to close. Becomes unusable.

int VRCloseSecurityContext(

HAuth

context

)

Releases a previously requested security context.

void VRCloseUserSlotHandle(

HUserSlot

slot

)

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

HNode VRCopyNodeHandle(

HNode

node

)

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

size_t VRCountOpenNodeHandles(

void

)

Diagnostic function.

Returns: the number of open node handles

int VRGetAPIVersionMajor(

void

)

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.

int VRGetAPIVersionMinor(

void

)

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

int VRGetNodeVersion(

HNode

node

)

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

int VRIsNodeHandleValid(

HNode

node

)

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

HUserSlot VRNewUserSlotHandle(

void

)

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