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

HNode VRGetChild(

HNode

node

)

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

HNode VRGetLibrariesNode(

void

)

Gets the VRTree libraries node.

HMeta VRGetMetaNode(

HNode

node

)

Gets the metanode of a node.

Returns: metanode or NULL if no metanode

HNode VRGetNext(

HNode

node

)

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)

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

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

size_t VRGetNodePathLength(

HNode

node

)

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

HNode VRGetParent(

HNode

node

)

Gets the parent of a node.

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

HNode VRGetPrev(

HNode

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

HNode VRGetRootNode(

void

)

Gets the VRTree root node.

HNode VRGetScenesNode(

void

)

Gets the VRTree scenes node.

HNode VRGetSystemLibraryNode(

void

)

Gets the VRTree system library node.

HNode VRGetThisUser(

void

)

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.

HNode VRGetUsersNode(

void

)

Gets the VRTree users node.

int VRIsAncestor(	HNode	a,
	HNode	b
	)

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

int VRIsSameNode(	HNode	a,
	HNode	b
	)

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