Skip to main content

Tree

Module: Nodes

Functions for operating on the node structure of the VR Tree.

Functions​

TypeName
HNodeVRCloneNode(HNode parentNode, HNode nodeToClone, int recursive)
Clones an existing node.
voidVRCloseNodeHandle(HNode node)
Closes a node handle, clearing its connection to VRTree.
voidVRCloseUserSlotHandle(HUserSlot slot)
Releases a unique userdata slot handle.
intVRCompareNode(HNode lhs, HNode rhs, int checkNameMatches)
Compares all the properties on both nodes to make sure they are equal.
HNodeVRCopyNodeHandle(HNode node)
Creates a new node handle based off the old one.
size_tVRCountOpenNodeHandles(void )
Diagnostic function.
HNodeVRCreateNode(HNode parentNode, const char * metaName, const char * nodeName)
Creates a node.
HNodeVRCreateNodeEx(HNode parentNode, const char * metaName, const char * nodeName, uint64_t flags, uint64_t idLO, uint64_t idHI, int userChange)
Creates a node.
intVRDeleteNode(HNode node)
Deletes a node and all its children.
HNodeVRFind(HNode startNode, const char * path)
Finds a descendant of startNode using its path.
HNodeVRFindChild(HNode startNode, const char * childName, uint32_t index)
Finds a direct child of startNode. Index is used to specify n'th child if multiple children have the same name.
HNodeVRFindChildPooled(HNode startNode, const char * metaNode, const char * childName)
Finds a direct child of startNode by specifying name and type.
HNodeVRFindOrCreateChild(HNode parentNode, const char * metaName, const char * nodeName)
Gets or creates a node matching metanode and name.
HNodeVRFindOrCreateChildEx(HNode parentNode, const char * metaName, const char * nodeName, uint64_t flags, uint64_t idLO, uint64_t idHI, int userChange)
Gets or creates a node matching metanode and name.
HNodeVRGetChild(HNode node)
Gets the first child of node.
HNodeVRGetChildOfType(HNode node, const char * childMetaNode)
Gets the first child of a specific type.
HNodeVRGetLibrariesNode(void )
Gets the VRTree libraries node.
HMetaVRGetMetaNode(HNode node)
Gets the metanode of a node.
HNodeVRGetNext(HNode node)
Gets the next sibling of a node.
HNodeVRGetNextOfType(HNode node, const char * nextMetaNode)
Gets the next sibling of a specific type.
HNodeVRGetNodeFromUUID(uint64_t lo, uint64_t hi)
Gets the node with the specified UUID.
size_tVRGetNodeName(HNode node, char * buffer, size_t bufferLength)
Gets the name of a node.
size_tVRGetNodeNameLength(HNode node)
Gets the length of a node's name, plus 1 for the trailing null terminator.
size_tVRGetNodePath(HNode node, char * buffer, size_t bufferLength)
Gets the path of a node.
size_tVRGetNodePathLength(HNode node)
Gets the length of a node's path.
void *VRGetNodeUserData(HNode node, HUserSlot slot)
Stores a pointer on the node.
intVRGetNodeVersion(HNode node)
Gets the metanode version of the specified node.
HNodeVRGetParent(HNode node)
Gets the parent of a node.
HNodeVRGetPrev(HNode node)
Gets the previous sibling of a node.
HNodeVRGetPrevOfType(HNode node, const char * prevMetaNode)
Gets the previous sibling of a specific type.
HNodeVRGetRootNode(void )
Gets the VRTree root node.
HNodeVRGetScenesNode(void )
Gets the VRTree scenes node.
HNodeVRGetSystemLibraryNode(void )
Gets the VRTree system library node.
HNodeVRGetThisUser(void )
Gets the VRTree user node.
size_tVRGetType(HNode node, char * buffer, size_t bufferLength)
Gets the type of a node.
size_tVRGetTypeLength(HNode node)
Gets the length of the type name of a node.
HNodeVRGetUsersNode(void )
Gets the VRTree users node.
uint64_tVRGetUUIDHigh(HNode node)
Gets the high 64-bits of a node's unique ID.
uint64_tVRGetUUIDLow(HNode node)
Gets the low 64-bits of a node's unique ID.
intVRIsAncestor(HNode a, HNode b)
Checks if node a is an ancestor of node b.
intVRIsDirty(HNode node, const char * propName)
Determines if a node value has been changed/dirtied.
intVRIsDirtyEx(HNode node, uint32_t prop)
Determines if a node value has been changed/dirtied.
intVRIsNodeName(HNode node, const char * name)
Checks if the name of the node is equal to parameter.
intVRIsNodeHandleValid(HNode node)
Checks if a node handle is valid.
intVRIsSameNode(HNode a, HNode b)
Checks if two node handles are pointing at the same node.
intVRIsType(HNode node, const char * metaName)
Determines if a node is of a particular type.
HNodeVRLoadTree(HNode targetNode, const char * fileName)
Loads a VRText or VRNative format file from disk.
HNodeVRLoadTreeEx(HNode targetNode, const char * fileName, uint64_t ioFlags, uint32_t builderFlags, uint32_t builderMetaFlags)
Loads a VRText or VRNative format file from disk.
HUserSlotVRNewUserSlotHandle(void )
Requests a unique userdata slot identifier.
intVRSaveTree(HNode rootNode, const char * fileName)
Saves the tree to a VRText or VRNative format file on disk.
intVRSaveTreeEx(HNode rootNode, const char * fileName, uint64_t ioFlags)
Saves the tree to a VRText or VRNative format file on disk.
intVRSetNodeName(HNode node, const char * name)
Sets the name of a node.
void *VRSetNodeUserData(HNode node, HUserSlot slot, void * data)
Stores a pointer on the node.
intVRSetParent(HNode node, HNode parent)
Sets the parent of a node, adding it as the last child.
intVRSetParentEx(HNode node, HNode parent, HNode afterSibling)
Sets the parent of a node, specifying a sibling to insert after.

Functions Documentation​

VRCloneNode​

HNode VRCloneNode(
    HNode parentNode,
    HNode nodeToClone,
    int recursive
)

Clones an existing node.

Parameters:

  • parentNode Handle to the parent of the new node
  • nodeToClone the node to copy
  • recursive if not 0, also copies descendants

Return: the copy of nodeToClone

VRCloseNodeHandle​

void VRCloseNodeHandle(
    HNode node
)

Closes a node handle, clearing its connection to VRTree.

Parameters:

  • node handle to close. Becomes unusable.

VRCloseUserSlotHandle​

void VRCloseUserSlotHandle(
    HUserSlot slot
)

Releases a unique userdata slot handle.

Parameters:

  • slot an open 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.

VRCompareNode​

int VRCompareNode(
    HNode lhs,
    HNode rhs,
    int checkNameMatches
)

Compares all the properties on both nodes to make sure they are equal.

Parameters:

  • lhs first node to compare
  • rhs second node to compare
  • checkNameMatches whether to compare the node name as well as the properties (non-zero to enable)

Return: 1 if the nodes are the same, 0 if they are not

VRCopyNodeHandle​

HNode VRCopyNodeHandle(
    HNode node
)

Creates a new node handle based off the old one.

Parameters:

  • node handle stays open.

Return: new node handle, VRCloseNodeHandle when you are done with it

VRCountOpenNodeHandles​

size_t VRCountOpenNodeHandles(
    void 
)

Diagnostic function.

Return: the number of open node handles

VRCreateNode​

HNode VRCreateNode(
    HNode parentNode,
    const char * metaName,
    const char * nodeName
)

Creates a node.

Parameters:

  • parentNode Handle to the parent of the new node
  • metaName type of node to create
  • nodeName name of the new node

Return: node handle

VRCreateNodeEx​

HNode VRCreateNodeEx(
    HNode parentNode,
    const char * metaName,
    const char * nodeName,
    uint64_t flags,
    uint64_t idLO,
    uint64_t idHI,
    int userChange
)

Creates a node.

Parameters:

  • parentNode Handle to the parent of the new node
  • metaName type of node to create
  • nodeName name of the new node
  • flags creation flags (bits) to provide to the new node
  • idLO low 64bits of a unique id (or 0 for auto ID)
  • idHI high 64bits of a unique id (or 0 for auto ID)
  • userChange whether the change is a response to a user action

Note: Flags larger than 16bits will be truncated.

VRDeleteNode​

int VRDeleteNode(
    HNode node
)

Deletes a node and all its children.

Parameters:

  • node the node to delete

Return: 0 if deletion successful

VRFind​

HNode VRFind(
    HNode startNode,
    const char * path
)

Finds a descendant of startNode using its path.

Parameters:

  • startNode node to search from
  • path path from start node to requested node

Return: handle to requested node or NULL if not found

VRFindChild​

HNode VRFindChild(
    HNode startNode,
    const char * childName,
    uint32_t index
)

Finds a direct child of startNode. Index is used to specify n'th child if multiple children have the same name.

Parameters:

  • startNode node to get the child from
  • childName name of the child
  • index index of child with non-unique name

Return: handle to requested node or NULL if not found

VRFindChildPooled​

HNode VRFindChildPooled(
    HNode startNode,
    const char * metaNode,
    const char * childName
)

Finds a direct child of startNode by specifying name and type.

Parameters:

  • startNode node to get child from
  • metaNode type of child node to get
  • childName name of the child node to return

Return: handle to found node or NULL if not found

VRFindOrCreateChild​

HNode VRFindOrCreateChild(
    HNode parentNode,
    const char * metaName,
    const char * nodeName
)

Gets or creates a node matching metanode and name.

Parameters:

  • parentNode Handle to the parent of the node
  • metaName type of node to create
  • nodeName name of the new node

Return: node handle

VRFindOrCreateChildEx​

HNode VRFindOrCreateChildEx(
    HNode parentNode,
    const char * metaName,
    const char * nodeName,
    uint64_t flags,
    uint64_t idLO,
    uint64_t idHI,
    int userChange
)

Gets or creates a node matching metanode and name.

Parameters:

  • parentNode Handle to the parent of the node
  • metaName type of node to create
  • nodeName name of the new node

Return: node handle

VRGetChild​

HNode VRGetChild(
    HNode node
)

Gets the first child of node.

Return: first child or NULL if no children

VRGetChildOfType​

HNode VRGetChildOfType(
    HNode node,
    const char * childMetaNode
)

Gets the first child of a specific type.

Parameters:

  • childMetaNode the type of child to get

Return: first child of requested type, or NULL if no children/no children of this type

VRGetLibrariesNode​

HNode VRGetLibrariesNode(
    void 
)

Gets the VRTree libraries node.

VRGetMetaNode​

HMeta VRGetMetaNode(
    HNode node
)

Gets the metanode of a node.

Return: metanode or NULL if no metanode

VRGetNext​

HNode VRGetNext(
    HNode node
)

Gets the next sibling of a node.

Return: sibling or NULL if no siblings

VRGetNextOfType​

HNode VRGetNextOfType(
    HNode node,
    const char * nextMetaNode
)

Gets the next sibling of a specific type.

Parameters:

  • nextMetaNode the type of sibling to get

Return: next sibling of requested type, or NULL if no siblings/no siblings of this type

VRGetNodeFromUUID​

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

Return: node handle, or 0 on error / non-existant

Par: Permission: SC_READ

VRGetNodeName​

size_t VRGetNodeName(
    HNode node,
    char * buffer,
    size_t bufferLength
)

Gets the name of a node.

Parameters:

  • node handle to the node
  • buffer a buffer to receive the node name as a null terminated string
  • size size of the buffer

Return: the number of characters written to the buffer (including trailing null)

VRGetNodeNameLength​

size_t VRGetNodeNameLength(
    HNode node
)

Gets the length of a node's name, plus 1 for the trailing null terminator.

Parameters:

  • node handle to the node

VRGetNodePath​

size_t VRGetNodePath(
    HNode node,
    char * buffer,
    size_t bufferLength
)

Gets the path of a node.

Parameters:

  • node handle to the node
  • buffer a buffer to recieve the node path as a null terminated string
  • size size of the buffer

Return: the number of characters written to the buffer (including trailing null)

Note: if buffer is null, function returns the required size of the buffer

VRGetNodePathLength​

size_t VRGetNodePathLength(
    HNode node
)

Gets the length of a node's path.

Parameters:

  • node handle to the node

VRGetNodeUserData​

void * VRGetNodeUserData(
    HNode node,
    HUserSlot slot
)

Stores a pointer on the node.

Parameters:

  • node handle to the node

Return: user data bound to slot

VRGetNodeVersion​

int VRGetNodeVersion(
    HNode node
)

Gets the metanode version of the specified node.

Parameters:

  • node node to query

Return: version, or -1 on error / non-existant

Par: Permission: SC_READ

VRGetParent​

HNode VRGetParent(
    HNode node
)

Gets the parent of a node.

Return: parent node or NULL if no parent (root node)

VRGetPrev​

HNode VRGetPrev(
    HNode node
)

Gets the previous sibling of a node.

Return: sibling or NULL if no siblings

VRGetPrevOfType​

HNode VRGetPrevOfType(
    HNode node,
    const char * prevMetaNode
)

Gets the previous sibling of a specific type.

Parameters:

  • prevMetaNode the type of sibling to get

Return: previous sibling of requested type, or NULL if no siblings/no siblings of this type

VRGetRootNode​

HNode VRGetRootNode(
    void 
)

Gets the VRTree root node.

VRGetScenesNode​

HNode VRGetScenesNode(
    void 
)

Gets the VRTree scenes node.

VRGetSystemLibraryNode​

HNode VRGetSystemLibraryNode(
    void 
)

Gets the VRTree system library node.

VRGetThisUser​

HNode VRGetThisUser(
    void 
)

Gets the VRTree user node.

VRGetType​

size_t VRGetType(
    HNode node,
    char * buffer,
    size_t bufferLength
)

Gets the type of a node.

Parameters:

  • node handle to the node
  • buffer a buffer to recieve the node type name as a null terminated string
  • size size of the buffer

Return: the number of characters written to the buffer (including trailing null)

VRGetTypeLength​

size_t VRGetTypeLength(
    HNode node
)

Gets the length of the type name of a node.

VRGetUsersNode​

HNode VRGetUsersNode(
    void 
)

Gets the VRTree users node.

VRGetUUIDHigh​

uint64_t VRGetUUIDHigh(
    HNode node
)

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

Return: high 64-bits or 0 on error

Par: Permission: SC_READ

VRGetUUIDLow​

uint64_t VRGetUUIDLow(
    HNode node
)

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

Return: low 64-bits or 0 on error

Par: Permission: SC_READ

VRIsAncestor​

int VRIsAncestor(
    HNode a,
    HNode b
)

Checks if node a is an ancestor of node b.

Parameters:

  • a first node
  • b second node

Return: 1 if a is an ancestor of b

VRIsDirty​

int VRIsDirty(
    HNode node,
    const char * propName
)

Determines if a node value has been changed/dirtied.

Parameters:

  • node handle to the node
  • propName name of the property on this node

Return: 1 if node property is dirty, 0 if it is not

VRIsDirtyEx​

int VRIsDirtyEx(
    HNode node,
    uint32_t prop
)

Determines if a node value has been changed/dirtied.

Parameters:

  • node handle to the node
  • prop the index of the property to set

Return: 1 if node property is dirty, 0 if it is not

VRIsNodeHandleValid​

int VRIsNodeHandleValid(
    HNode node
)

Checks if a node handle is valid.

Parameters:

  • node handle to check

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

Par: Permission: SC_READ

VRIsNodeName​

int VRIsNodeName(
    HNode node,
    const char * name
)

Checks if the name of the node is equal to parameter.

Parameters:

  • node handle to the node
  • name to check against

Return: 1 if name is equal -1 if node invalid 0 if not equal

VRIsSameNode​

int VRIsSameNode(
    HNode a,
    HNode b
)

Checks if two node handles are pointing at the same node.

Parameters:

  • a first node
  • b second node

Return: 1 if the nodes are the same

VRIsType​

int VRIsType(
    HNode node,
    const char * metaName
)

Determines if a node is of a particular type.

Parameters:

  • node handle to the node
  • metaName name of the node type to match

Return: 1 if node is of type metaName, 0 if it is not

VRLoadTree​

HNode VRLoadTree(
    HNode targetNode,
    const char * fileName
)

Loads a VRText or VRNative format file from disk.

Parameters:

  • targetNode the node to load the file onto (usually root)
  • fileName the full path to the file to load

Return: The first new child of targetNode, or NULL if load failed

VRLoadTreeEx​

HNode VRLoadTreeEx(
    HNode targetNode,
    const char * fileName,
    uint64_t ioFlags,
    uint32_t builderFlags,
    uint32_t builderMetaFlags
)

Loads a VRText or VRNative format file from disk.

Parameters:

  • targetNode the node to load the file onto (usually root)
  • fileName the full path to the file to load
  • ioFlags Input flags to apply while loading the tree
  • builderFlags flags which adjust the behaviour of the builder
  • builderMetaFlags additional MetaNode flags applied to nodes created by the tree builder

Return: The first new child of targetNode, or NULL if load failed

VRNewUserSlotHandle​

HUserSlot VRNewUserSlotHandle(
    void 
)

Requests a unique userdata slot identifier.

Return: slot handle, or 0 on error

Par: Permission: SC_MODIFY

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.

VRSaveTree​

int VRSaveTree(
    HNode rootNode,
    const char * fileName
)

Saves the tree to a VRText or VRNative format file on disk.

Parameters:

  • rootNode the node to start saving from (usually root)
  • fileName the full path to the file to save to

Return: 0 if the save was successful

VRSaveTreeEx​

int VRSaveTreeEx(
    HNode rootNode,
    const char * fileName,
    uint64_t ioFlags
)

Saves the tree to a VRText or VRNative format file on disk.

Parameters:

  • rootNode the node to start saving from (usually root).
  • fileName the full path to the file to save to.

Return: 0 if the save was successful.

VRSetNodeName​

int VRSetNodeName(
    HNode node,
    const char * name
)

Sets the name of a node.

Parameters:

  • node handle to the node
  • name the new node name

Return: 0 on success

VRSetNodeUserData​

void * VRSetNodeUserData(
    HNode node,
    HUserSlot slot,
    void * data
)

Stores a pointer on the node.

Parameters:

  • node handle to the node
  • data which you wish to store in slot, can be null to remove data

Return: previously bound data, if any

VRSetParent​

int VRSetParent(
    HNode node,
    HNode parent
)

Sets the parent of a node, adding it as the last child.

Return: 0 on success

VRSetParentEx​

int VRSetParentEx(
    HNode node,
    HNode parent,
    HNode afterSibling
)

Sets the parent of a node, specifying a sibling to insert after.

Parameters:

  • afterSibling the node after which to insert this node. If null, inserts as first child of parent

Return: 0 on success