Tree

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

Functions


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

Returns

the copy of nodeToClone


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)

Returns

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


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

Returns

node handle


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.


int VRDeleteNode(HNode node)

Deletes a node and all its children.

Parameters
node

the node to delete

Returns

0 if deletion successful


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

Returns

handle to requested node or NULL if not found


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

Returns

handle to requested node or NULL if not found


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

Returns

handle to found node or NULL if not found


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

Returns

node handle


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

Returns

node handle


Gets the first child of node.

Returns

first child or NULL if no children


HNode VRGetChildOfType(HNode node,
const char * childMetaNode
)

Gets the first child of a specific type.

Parameters
childMetaNode

the type of child to get

Returns

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


Gets the VRTree libraries node.


Gets the metanode of a node.

Returns

metanode or NULL if no metanode


Gets the next sibling of a node.

Returns

sibling or NULL if no siblings


HNode VRGetNextOfType(HNode node,
const char * nextMetaNode
)

Gets the next sibling of a specific type.

Parameters
nextMetaNode

the type of sibling to get

Returns

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


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

Returns

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


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

Parameters
node

handle to the node


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

Returns

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

Note

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


Gets the length of a node's path.

Parameters
node

handle to the node


void * VRGetNodeUserData(HNode node,
HUserSlot slot
)

Stores a pointer on the node.

Parameters
node

handle to the node

Returns

user data bound to slot


Gets the parent of a node.

Returns

parent node or NULL if no parent (root node)


Gets the previous sibling of a node.

Returns

sibling or NULL if no siblings


HNode VRGetPrevOfType(HNode node,
const char * prevMetaNode
)

Gets the previous sibling of a specific type.

Parameters
prevMetaNode

the type of sibling to get

Returns

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


Gets the VRTree root node.


Gets the VRTree scenes node.


Gets the VRTree system library node.


Gets the VRTree user node.


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

Returns

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


size_t VRGetTypeLength(HNode node)

Gets the length of the type name of a node.


Gets the VRTree users node.


Checks if node a is an ancestor of node b.

Parameters
a

first node

b

second node

Returns

1 if a is an ancestor of b


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

Returns

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


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

Returns

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


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

Returns

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


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

Parameters
a

first node

b

second node

Returns

1 if the nodes are the same


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

Returns

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


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

Returns

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


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

Returns

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


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

Returns

0 if the save was successful


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.

Returns

0 if the save was successful.


int VRSetNodeName(HNode node,
const char * name
)

Sets the name of a node.

Parameters
node

handle to the node

name

the new node name

Returns

0 on success


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

Returns

previously bound data, if any


int VRSetParent(HNode node,
HNode parent
)

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

Returns

0 on success


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

Returns

0 on success

No Results.

Getting StartedArchitectureBest PracticesHow ToAdvanced TopicsChangelogvrtree_cppCoreForeign Function InterfaceMetanodesMigrationsObserversPropertiesTreeUtilitiesAPI DefinitionsVR ExchangePluginsLua API