Settings

These functions permit you to access and edit user and scene settings. They always apply to the setting that is currently active, whether it is a user setting or a scene override.

Functions

Type	Name
void	vrSettingAddToScene(string path, Any defaultVal, Any slot =nil, Any complete =nil, string typestr =0) Creates a scene setting as an override to an existing setting or a scene-only setting.
void	vrSettingCreateArrayDouble(string path, number length, vrnode user =nil, number ... ) Creates a new double array user setting.
void	vrSettingCreateArrayFloat(string path, number length, vrnode user =nil, number ... ) Creates a new float array user setting.
void	vrSettingCreateArrayInt(string path, number length, vrnode user =nil, number ... ) Creates a new integer array user setting.
void	vrSettingCreateBool(string path, boolean defaultVal =false, vrnode user =nil) Creates a new boolean user setting.
void	vrSettingCreateDouble(string path, number defaultVal =0.0, vrnode user =nil, number minVal =VR_DOUBLE_MIN, number maxVal =VR_DOUBLE_MAX) Creates a new double user setting.
void	vrSettingCreateFloat(string path, number defaultVal =0.0, vrnode user =nil, number minVal =VR_FLOAT_MIN, number maxVal =VR_FLOAT_MAX) Creates a new float user setting.
void	vrSettingCreateInt(string path, number defaultVal =0, vrnode user =nil, number minVal =VR_INT_MIN, number maxVal =VR_INT_MAX) Creates a new integer user setting.
void	vrSettingCreateLink(string path, string filter =0, vrnode user =nil) Creates a new link user setting.
void	vrSettingCreateString(string path, string defaultVal =0, vrnode user =nil) Creates a new string user setting.
vrsetting	vrSettingGet(string path, vrnode user =nil) Gets an application setting from the user registry, or a scene override if it exists.
vrsetting	vrSettingGetNode(string path, vrnode user =nil) Gets an application setting node from the user registry, or a scene override if it exists.
vrnode	vrSettingGetRoot() Gets the node associated with the root of the settings hierarchy.
vrnode	vrSettingGetSceneRoot() Gets the root of the settings overrides in the scenes tree if it exists.
Any	vrSettingRead(string path, vrnode user =nil) Reads the value of a setting.
boolean	vrSettingRemoveFromScene(string path) Removes a scene setting.
void	vrSettingSetCaption(string path, string caption, vrnode user) Assigns a custom caption to a setting, allowing the text displayed in user interface to be different from the setting name.
void	vrSettingSetFilter(string path, string filter, vrnode user) Assigns a filter to a setting. The meaning of the filter depends on the setting type.
void	vrSettingSetStep(string path, number step, vrnode user) Assigns a step size to a numerical setting.
void	vrSettingSetType(string path, string type, vrnode user) Assigns a type to a setting, which determines how the setting is presented in the user interface.
void	vrSettingWrite(string path, Any value, vrnode user =nil) Writes the value of a setting.

Functions Documentation

vrSettingAddToScene

void vrSettingAddToScene(
    string path,
    Any defaultVal,
    Any slot =nil,
    Any complete =nil,
    string typestr =0
)

Creates a scene setting as an override to an existing setting or a scene-only setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal Default value if the scene setting is not an override
• slot Function to call when the setting value changes
• complete Function to call when the node has been created, which may not be immediately
• typestr Hint at which number type should be used instead of a double to create a scene-only setting (int, float, world)

Example 1:

This example shows how to add a scene override for a user setting.

Script

vrSettingAddToScene("Renderer/Scene/ClipRange", {0,0})
vrSettingWrite("Renderer/Scene/ClipRange", {1.0, 200.0})

print(vrSettingRead("Renderer/Scene/ClipRange"))

Output

Running...
1.000, 200.000
Ended.

Example 2:

This example shows how to add new settings for a specific scene. These settings are not saved in the user registry, only with the scene. They do, however, automatically trigger the generation of a new Settings category to allow instant user interaction with scene configuration settings.

vrSettingAddToScene("MyScene/CustomSetting", 5)

This results in an additional category in the settings interface, and an interface control for editing the setting value.

vrSettingCreateArrayDouble

void vrSettingCreateArrayDouble(
    string path,
    number length,
    vrnode user =nil,
    number ... 
)

Creates a new double array user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• length The length of the array (2, 3, 4, 9 or 16)
• user The user that this setting belongs to (defaults to the current user)
• ... The default value(s) to apply to the array elements

vrSettingCreateArrayFloat

void vrSettingCreateArrayFloat(
    string path,
    number length,
    vrnode user =nil,
    number ... 
)

Creates a new float array user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• length The length of the array (2, 3, 4, 9 or 16)
• user The user that this setting belongs to (defaults to the current user)
• ... The default value(s) to apply to the array elements

vrSettingCreateArrayInt

void vrSettingCreateArrayInt(
    string path,
    number length,
    vrnode user =nil,
    number ... 
)

Creates a new integer array user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• length The length of the array (2, 3 or 4)
• user The user that this setting belongs to (defaults to the current user)
• ... The default value(s) to apply to the array elements

vrSettingCreateBool

void vrSettingCreateBool(
    string path,
    boolean defaultVal =false,
    vrnode user =nil
)

Creates a new boolean user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal The default value to apply to the setting
• user The user that this setting belongs to (defaults to the current user)

vrSettingCreateDouble

void vrSettingCreateDouble(
    string path,
    number defaultVal =0.0,
    vrnode user =nil,
    number minVal =VR_DOUBLE_MIN,
    number maxVal =VR_DOUBLE_MAX
)

Creates a new double user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal The default value to apply to the setting
• user The user that this setting belongs to (defaults to the current user)
• minVal The minimum value that can be assigned to the setting
• maxVal The maximum value that can be assigned to the setting

vrSettingCreateFloat

void vrSettingCreateFloat(
    string path,
    number defaultVal =0.0,
    vrnode user =nil,
    number minVal =VR_FLOAT_MIN,
    number maxVal =VR_FLOAT_MAX
)

Creates a new float user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal The default value to apply to the setting
• user The user that this setting belongs to (defaults to the current user)
• minVal The minimum value that can be assigned to the setting
• maxVal The maximum value that can be assigned to the setting

vrSettingCreateInt

void vrSettingCreateInt(
    string path,
    number defaultVal =0,
    vrnode user =nil,
    number minVal =VR_INT_MIN,
    number maxVal =VR_INT_MAX
)

Creates a new integer user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal The default value to apply to the setting
• user The user that this setting belongs to (defaults to the current user)
• minVal The minimum value that can be assigned to the setting
• maxVal The maximum value that can be assigned to the setting

vrSettingCreateLink

void vrSettingCreateLink(
    string path,
    string filter =0,
    vrnode user =nil
)

Creates a new link user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• filter A comma-separated list of metanode types that can be linked to (e.g. "Assembly" or "Visual,Sequence")
• user The user that this setting belongs to (defaults to the current user)

vrSettingCreateString

void vrSettingCreateString(
    string path,
    string defaultVal =0,
    vrnode user =nil
)

Creates a new string user setting.

Parameters:

• path Path to the setting (relative to the registry root)
• defaultVal The default value to apply to the setting
• user The user that this setting belongs to (defaults to the current user)

vrSettingGet

vrsetting vrSettingGet(
    string path,
    vrnode user =nil
)

Gets an application setting from the user registry, or a scene override if it exists.

Parameters:

• path Path to the setting (relative to the registry root)
• user The user that this setting belongs to (defaults to the current user)

Example:

Script

local clipPlanes = vrSettingGet("Renderer/Scene/ClipRange")

print(clipPlanes)
print(clipPlanes.Value)
print(clipPlanes.Value.x)
print(clipPlanes.Value.y)

Output

Running...
Setting: [000000004E90D2A0, path:Renderer/Scene/ClipRange]
0.100, 1000.000
0.10000000149
1000
Ended.

vrSettingGetNode

vrsetting vrSettingGetNode(
    string path,
    vrnode user =nil
)

Gets an application setting node from the user registry, or a scene override if it exists.

Parameters:

• path Path to the setting (relative to the registry root)
• user The user that this setting belongs to (defaults to the current user)

vrSettingGetRoot

vrnode vrSettingGetRoot()

Gets the node associated with the root of the settings hierarchy.

Return: The user settings root node, or nil

vrSettingGetSceneRoot

vrnode vrSettingGetSceneRoot()

Gets the root of the settings overrides in the scenes tree if it exists.

Return: The scene overrides root node, or nil

vrSettingRead

Any vrSettingRead(
    string path,
    vrnode user =nil
)

Reads the value of a setting.

Parameters:

• path Path to the setting (relative to the registry root
• user The user that this setting belongs to (defaults to the current user)

Example:

Script

local clipPlanes = vrSettingRead("Renderer/Scene/ClipRange")

print(clipPlanes)
print(clipPlanes.x)
print(clipPlanes.y)

Output

Running...
0.100, 1000.000
0.10000000149
1000
Ended.

vrSettingRemoveFromScene

boolean vrSettingRemoveFromScene(
    string path
)

Removes a scene setting.

Parameters:

• path Path to the setting (relative to the registry root)

Return: True if the setting was removed

Example:

Script

vrSettingRemoveFromScene("Renderer/Scene/ClipRange")

print(vrSettingRead("Renderer/Scene/ClipRange"))

Output

Running...
0.300, 500.000
Ended.

vrSettingSetCaption

void vrSettingSetCaption(
    string path,
    string caption,
    vrnode user
)

Assigns a custom caption to a setting, allowing the text displayed in user interface to be different from the setting name.

Parameters:

• path Path to the setting (relative to the registry root)
• caption The caption to be displayed in the user interface
• user The user that this setting belongs to (defaults to the current user)

vrSettingSetFilter

void vrSettingSetFilter(
    string path,
    string filter,
    vrnode user
)

Assigns a filter to a setting. The meaning of the filter depends on the setting type.

Parameters:

• path Path to the setting (relative to the registry root)
• filter List of allowable file extensions for a file property or node types for a link property
• user The user that this setting belongs to (defaults to the current user)

vrSettingSetStep

void vrSettingSetStep(
    string path,
    number step,
    vrnode user
)

Assigns a step size to a numerical setting.

Parameters:

• path Path to the setting (relative to the registry root)
• step The step size
• user The user that this setting belongs to (defaults to the current user)

vrSettingSetType

void vrSettingSetType(
    string path,
    string type,
    vrnode user
)

Assigns a type to a setting, which determines how the setting is presented in the user interface.

Parameters:

• path Path to the setting (relative to the registry root)
• type The type name (e.g. 'image', 'file', 'slider', 'colour', 'rect', 'sphere', 'matrix', etc.)
• user The user that this setting belongs to (defaults to the current user)

vrSettingWrite

void vrSettingWrite(
    string path,
    Any value,
    vrnode user =nil
)

Writes the value of a setting.

Parameters:

• path Path to the setting (relative to the registry root
• value The value to set
• user The user that this setting belongs to (defaults to the current user)

Example:

Script

vrSettingWrite("Renderer/Scene/ClipRange", {0.3, 500.0})

local clipPlanes = vrSettingRead("Renderer/Scene/ClipRange")
print(clipPlanes)

Output

Running...
0.300, 500.000
Ended.