Skip to main content

Settings

Visionary Render allows control over user and scene settings using the Lua API The Lua API works transparently with Scene Overrides – the API functions for accessing setting values always apply to the value that is currently active, whether that is the scene override value or the user value.

vrSettingRead​

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

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

vrSettingWrite​

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

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

vrSettingGet​

Lua can also get a handle to the setting and its value, which can be used for reading and writing.

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

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

Scene Overrides and Settings​

The Lua interface is capable of adding and removing scene overrides of user settings

Add Override​

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

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

The first parameter to vrSettingAddToScene is the default value to assign if the setting does not exist in the system registry. (see Adding scene settings.) We then set the value of the setting, which applies it to the copy in the scene rather than the user setting.

Remove Override​

vrSettingRemoveFromScene("Renderer/Scene/ClipRange")

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

The scene override has been removed and the value is read from the user setting.

Add Scene Settings in Lua​

The Lua interface can also add new settings specifically for the scene providing the script. 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.

The same function is used for this, vrSettingAddToScene.

vrSettingAddToScene("MyScene/CustomSetting", 5)

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

Removing this setting with vrSettingRemoveFromScene will remove this category from the settings window.

vrSettingRemoveFromScene("MyScene/CustomSetting")

Observe Settings​

If querying the setting regularly is not convenient, the values can be observed

vrAddSettingObserver​

This function makes use of the capability of passing local Lua functions into the API to be called later. The following line of code provides a simple function to print the value of a setting whenever it changes. Whenever the Clip Planes setting in the Renderer/Scene category is changed (e.g. by the user interface), the script will print the new value of the setting.

vrAddSettingObserver("clipobs", function(value) print(value) end, "Renderer/Scene/ClipRange")

This doesn’t have to be an anonymous function, either, it can be a separate function defined locally or globally, and can also accept a string as the name of a global function.

local function printer(value) 
  print(value) 
end

vrAddSettingObserver("clipobs", printer, "Renderer/Scene/ClipRange")

vrRemoveObserver​

As with all other Lua observers, a setting observer is removed using its key with a call to vrRemoveObserver

vrRemoveObserver("clipobs")