VFB Layers API

Introduction

The VFB can be controlled programmatically via App SDK in many ways. One of them being by using various environment variables. Another is by getting and setting the VFB layer JSON string, which includes parsing it (easier in languages like Python and JavaScript, but difficult in C++ and C# without the help of specialized libraries). We introduce an API for easier manipulation of the VFB layers.

There are two abstractions created in every App SDK binding: the VFB Layer Manager abstraction, and the VFB Layer abstraction which is a handle to a real VFB Layer (since it is a handle, then there may be some cases when the current instance may be invalidated, and you have to get a new handle).

VFB Layer Manager

You can do the following operations using the Layer Manager:

• reset the Layer Manager layers to default (there are specific condition one must meet before invoking this operation, which are described in the documentation);
• load and save VFB layers as a file;
• get and set VFB layers as a JSON string;
• load OCIO or ICC configuration files and get/set some of the UI exposed properties related to them;
• get the layer classes which are creatable by a user;
• bake all layers to a LUT (.cube) file;
• create or delete layers. There are some particularities to what layers you can create with the specified parent layer and what layers you can delete (not all are deletable);
• access the common layers on a whim: Root layer, Display Correction layer, Stamp layer, Source layer, Denoiser layer, Sharpen/Blur layer, Lens Effects layer and Light Mix layer.

There are some auxiliary functions which can accumulate layers with some user specified property: e.g., get all the layers which are enabled or get all the layers with a specific class. If you want to perform thread-safe operations and batch operations, there are ways to lock and then unlock the Layer Manager

VFB Layer

If you choose to get a VFB Layer handle, there are multiple common operations you can perform:

• check is it is a valid handle;
• get the unique path from the root layer to the current layer using their indices as children of their parent layer (indices from the list of children of the parent layer). E.g. '/0/1' corresponds to get the Root layer, then get the child with index zero in the list of children of the Root layer. Then get the child of the zeroth child of the Root layer with index 1 in the list of the zeroth child of the Root layer;
• get other more basic read-only properties like: the class of a layer, if the layer can be deleted or if it is blendable;
• get/set properties like: the name of the layer, whether it is enabled, the opacity of a layer and the blend mode of the layer if it is blendable;
• get the parent of a layer, its children, or get a specific child;
• get the layer properties which can be modified (there are some which are not mutable and some which are immutable when specific conditions are present);
• get the layer properties which are read-only, or you can get the layer properties of a specific type (like integer, float, enumerable, Color, etc.).

Some specific layer property methods are that you can:

• get the layer display name;
• reset the layer property to its default value;
• check if it is read-only;
• get its type;
• get its flags;
• get/set the value of a property depending on its type.

Specifics

Now it is good to discuss some of the peculiarities that we have mentioned earlier:

The first one is that if you want to work with the VFB layer settings from a loaded vrscene when you are not rendering at the moment, you must manage the "loading" and "unloading" of those settings (using fillSettingsVFB, applySettingsVFB and the Layer Manager method reset) on your own.

Python

C++

C#.NET

Node.js

When beginning a rendering, by default the parameters from the SettingsVFB plugin vfb2_layers and cc_settings are used to overwrite the contents of the Layer Manager. If this is not a desired effect, then you can set the dont_affect_settings parameter of the SettingsVFB plugin in the scene to true (the default value is false). Then the contents of the Layer Manager will remain unchanged. If you don't want to use this parameter, you can use a combination of fillSettingsVFB and applySettingsVFB methods to write the changes of the layers to the SettingsVFB plugin, which will be later read when the rendering starts.

Example snippet using the dont_affect_settings parameter.

Python

C++

C#.NET

Node.js

And an example when we avoid using the dont_affect_settings parameter.

Python

C++

C#.NET

Node.js

As we said earlier, a VFB layer instance is a handle to the real layer, so it can be invalidated. Some of the events when this may happen are: after it is deleted successfully, after a load or a set operation, after a new render begins (if not specified with the dont_affect_settings parameter of the SettingsVFB plugin, that the contents of the Layer Manager must not be overwritten with the ones coming from the SettingsVFB plugin, if any), etc.

Example

In this example we will show how to do some manipulations with this API. The full example is available as a file in the examples/{language}/advanced folder with infix vfb-layers-api.

Python

C++

C#.NET

Node.js