Best Practices

This page documents some best practices when using the VRTree API.

Scripts

Local vs Global

When defining functions and variables in Lua, you should use the local keyword to prevent them from being added to the global Lua state. If you don't, they will be considered global by default, which can lead to naming clashes with the API or plugins.

Good
Bad

local function foo()
  local bar = 0
end

function foo()
  bar = 0
end

Iterating over Child Nodes

Use vrNodeGetChild() and vrNodeGetSibling() to iterate over the children of a node. The vrNodeGetChildCount() and vrNodeGetChildByIndex() functions are not optimised for this purpose and may result in poor performance when iterating over lots of nodes.

Good
Bad

local child = vrNodeGetChild(node)
while child do
  -- Do something with the child.

  child = vrNodeGetSibling(child)
end

for i = 1, vrNodeGetChildCount(node) do
  local child = vrNodeGetChildByIndex(node, i)
  -- Do something with the child.
end

Plugins

Handles

Handles are used to reference internal objects such as nodes. If you request a handle using any API function that returns one (VRGetScenesNode, etc.), you must close it when you are finished, using VRCloseNodeHandle.

Handles passed into plugin API functions (e.g. VRPImportProc) and callback functions (e.g. those registered with VRAddCallbackUpdate) are managed by the host application and do not need to be closed. They are closed when the callback function returns. If you require a given handle to persist beyond the end of the callback function, use VRCopyNodeHandle to create a new handle to the same node, remembering to close the copy yourself when you are done with it.