This page provides information on how to control the V-Ray Frame Buffer programmatically.
Overview
The VFB can be controlled programmatically in two ways: the first is using various environment variables, and the second is using the vray vfbControl command.
The vray vfbControl commands are supported in batch rendering mode.
VFB commands are designed to work with MEL scripting. To use them with Python, the MEL script should be wrapped in Python using the maya.cmds module.
Example of vray vfbControl in Python:
- Selects the fourth image in the VFB history and loads it into the VFB:
import maya.cmds as cmds
cmds.vray('vfbControl', '-historyselect', 4, '-historyload')
2. Loads an OCIO configuration file in the VFB:
import maya.cmds as cmds
cmds.vray('vfbControl', '-loadocio', 'C:\\path\\config.ocio')
From MEL script
The vray vfbControl command modifies the various aspects of the VFB. Commands follow the following structure:
vray vfbControl <flag>; vray vfbControl <flag> <argument>;
For example, to turn off the red channel in the VFB, type:
vray vfbControl -red false;
With the VFB2 we have added commands to access the properties of each layer. This allows further customization and flexibility when controlling the VFB programmatically. For example - creating a white balance layer and setting its properties:
int $dc = vray vfbControl -displayCorrectionLayer; int $wb = vray vfbControl -createLayer "chaos.cc.whiteBalance" $dc; vray vfbControl -layer $wb -set temp 5000 -layer $wb -set tint 0.3 -layer $wb -set color_tint 0.9 1 0.9;
To see a list of available options, run one of the following commands:
vray vfbControl; vray vfbControl help; vray vfbControl -help;
To open up or hide the VFB, use the following MEL commands:
vray showVFB; vray hideVFB;
MEL Flags
Below is a list of available options. Note the following about these commands:
- Arguments listed as Boolean can only receive true/false values. These options turn a feature on (true) or off (false). Acceptable values are
0,1,on,off,yes,no,true,false,enable, anddisable. - Remember that float values include a decimal, while integers do not. This means that integers can be used when a float is required, but float values cannot be used where integers are required.
- String values must be enclosed in double quotes.
- Available values from enumerated lists are presented with a pipe (|) separator. For example, 0 | 1 | 2 means the argument value can only be a
0,1, or2. String values of this argument type are input with quote marks. - Successfully loading a file or setting a numerical value implicitly enables the corresponding option. For example, using
-setregionto set a region for rendering automatically turns on region rendering. If you want to disable a feature, do it after running the load/set command. - Options with Set/Get will return the current values for the parameter when used without arguments.
VFB Toolbar Options
| Flag | Description | Arguments | Set/Get | Example |
|---|---|---|---|---|
| help -help | Displays options for the vray vfbControl command. The help lines will also print when vray vfbControl is called without any flags. | N/A | vray vfbControl; vray vfbControl help; vray vfbControl -help; | |
-red | Enables/disables the corresponding VFB channel. | Boolean | yes | vray vfbControl -alpha true; // shows the alpha channel vray vfbControl -alpha 1; // shows the alpha channel vray vfbControl -alpha false; // disables alpha channel display vray vfbControl -alpha 0; // disables alpha channel display |
| -trackmouse | Enables/disables the Track mouse while rendering feature. | Boolean | yes | vray vfbControl -trackmouse 1; //enables "track mouse" |
| -setcompareab | Enables/disables the Compare horizontal and Compare vertical features. | h | hor | horizontal v | ver | vertical | vray vfbControl -setcompareab h; | |
| -loadimage | Loads the specified image in VFB. | String (filename) | vray vfbControl -loadimage "C:/Temp/image.jpg"; | |
| -saveimage | Saves the VFB RGB color channel as an image. | String (filename) | vray vfbControl -saveimage "C:/Temp/image.jpg"; | |
| -saveallimage | Saves all VFB render channels to separate images or a single vrimg file. | String (filename) | vray vfbControl -saveallimage "C:/Temp/image.jpg"; | |
| -savemultiimage | Saves a multichannel .exr or .vrimg file with all VFB render channels inside. | String (filename) | vray vfbControl -savemultiimage "C:/Temp/image.exr"; | |
| -setregion | Sets the render region in pixels or resets/disables the render region. | Integers (left top right bottom) reset | vray vfbControl -setregion 0 0 640 480; vray vfbControl -setregion reset; | |
| -setregionrel | Sets the render region in coordinates, relative to the image resolution [0-1]. | Floats (left top right bottom) | vray vfbControl -setregionrel 0 0 0.5 0.5; | |
| -getregion | Returns the current coordinates (left top right bottom) of the render region. | N/A | vray vfbControl -getregion; // Result: 0 0 500 350 | |
| -setregionenabled | Enables/disables the render region. | Boolean | vray vfbControl -setregionenabled 1; //enables the region | |
| -clearimage | Clears the VFB image. | N/A | vray vfbControl -clearimage; | |
| -testresolutionenabled | Enables/disables the Test resolution opton in the VFB. | Boolean | yes | vray vfbControl -testresolutionenabled 1; //Enables test resolution |
| -testresolution | A zero-based index between 0 and 7 which sets the test resolution respectively to: 10%, 25%, 50%, 75%, 100%, 110%, 125% and 150% of the original image resolution. | Integer (0 to 7) | yes | vray vfbControl -testresolution 2; // Sets the test resolution to 50% vray vfbControl -testresolution; //Result 2 // |
| -bucketlock | The rendering buckets will start from a locked point. Use -bucketlockpoint to choose the point. This also sets -trackmouse to true. | Boolean | yes | |
| -bucketlockpoint | The pixel coordinates (left, top) for the bucket starting point. To be used with -bucketlock. | yes | ||
| -duplicate | Duplicates the VFB image to the Maya Render View window. | N/A | vray vfbControl -duplicate; | |
| -getchannelnames | Returns a string[]. Indices correspond with -get/setchannel. | N/A | ||
| -getchannel | Returns the index of the current channel in string[0]. | N/A | vray vfbControl -getchannel; //Result: 0 when viewing RGB Color //Result: 1 when viewing Alpha // the index increments for each next channel viewed in the VFB, for example render elements are stored after the RGB and Alpha. | |
| -setchannel | Selects the render element channel with an index. | Integer | Set | vray vfbControl -setchannel 0; // Switches to the channel at index 0. If viewing a render element, this will switch the display to the RGB Color (at index 0 by default) |
VFB Color Correction Options
| Flag | Description | Arguments | Set/Get | Example |
|---|---|---|---|---|
| -clamp | Enables/disables the Force color clamping feature. | Boolean | yes | |
| -viewclamp | Enables/disables displaying the clamped colors in the VFB. | Boolean | yes | |
| -pixelaspect | Enables/disables visualization of the pixel aspect ratio. | Boolean | yes | |
| -ocio | Enables/disables OCIO correction. | Boolean | yes | |
| -icc | Enables/disables ICC correction. | Boolean | yes | |
| -srgb | Enables/disables displaying the image in sRGB color space. | Boolean | yes | |
| -lutlin2log | Converts to log space before applying LUT. | Boolean | yes | |
| -ccocioics | Sets OCIO Input Colorspace by number in the dropdown list. | Integer | yes | |
| -ccociodd | Sets OCIO Display Device by number in the dropdown list. | Integer | yes | |
| -ccociovt | Sets OCIO View Transform by number in the dropdown list. | Integer | yes | |
| -ocioinputcolorspace | Sets OCIO Input Colorspace by name. | String | yes | |
| -ociodisplaydevice | Sets OCIO Display Device by name. | String | yes | |
| -ocioviewtransform | Sets OCIO View Transform by name. | String | yes | |
| -itemsociocs | Returns a list of all available OCIO Input Colorspace values. | N/A | ||
| -itemsociodd | Returns a list of all available OCIO Display Device values. | N/A | ||
| -itemsociovt | Returns a list of all available OCIO View Transform values. | N/A | ||
| -itemsiccri | Returns a list of all available ICC Rendering Intent values. | N/A | ||
| -cciccrenderintent | Specifies ICC render intent with an integer: | 1 | 2 | 3 | 4 | yes | |
| -loadocio | Specifies file for OCIO correction. | String (filename) | ||
| -loadicc | Specifies file for ICC correction. | String (filename) | ||
| -loadpreset | Loads a global preset file. | String (filename) | ||
| -savepreset | Saves a global preset file. | String (filename) | ||
| -iccfile -ociofile | Returns the filename String used in the corresponding Correction Control rollout. | N/A |
Layer Access
| Flag | Description | Arguments | Set/Get | Example |
-listLayers | Returns a list of all the created layers. | vray vfbControl -listLayers; | ||
-layer <ID> -name | Returns the name of/Renames the layer with the selected ID. | String | yes | vray vfbControl -layer 1 -name; //Gets the name of the layer with ID 1 |
-layer <ID> -class | Displays the class of the layer with the selected ID. | vray vfbControl -layer 1 -class; //Prints the class of the layer with ID 1 | ||
-layer <ID> -isEnabled | Displays whether or not a layer with the selected ID is enabled. | vray vfbControl -layer 1 -isEnabled; //Prints whether the layer with ID 1 is enabled | ||
-layer <ID> -en | Enables or disables a layer. The argument can be omitted and defaults can be enabled. | Boolean | vray vfbControl -layer 1 -enable 0; //Disables the layer with ID 1 vray vfbControl -layer 1 -enable 1; //Enables the layer with ID 1 | |
-layer <ID> -listProperties | Returns a list of the property names of the layer with the selected ID. | vray vfbControl -layer 1 -listProperties; //Lists all the properties of the layer with ID 1 | ||
-layer <ID> -propertyType | Returns a list of the property types of the layer with the selected ID. | String | vray vfbControl -layer 1 -propertyType "exposure"; //Gets the ID type of the property "exposure" for the Display Correction layer with ID 1 * | |
-layer <ID> -propertyValues | Returns the list of strings accepted as values for an Enum property. | String | vray vfbControl -layer 1 -propertyValues "profile"; //Gets a list of possible values for Enum properties of the Display Correction layer with ID 1 * | |
-layer <ID> -g | Displays the value of a chosen property. | String | vray vfbControl -layer 1 -get "exposure"; //Gets the value of the Exposure parameter of the Display Correction layer with ID 1 * | |
-layer <ID> -s | Specifies the value of a chosen property. | String | vray vfbControl -layer 1 -set "exposure" 0.05; //Sets the value of the Exposure parameter of the Display Correction layer to 0.05 * | |
-layer <ID> -parent | Returns the ID of the layer's parent. | vray vfbControl -layer 1 -parent; //Gets the layer IDs of the parent layers of the Display Correction Layer with ID 1 * | ||
-layer<ID> -listChildren | Returns a list of the children of the layer with the selected ID. | vray vfbControl -layer 1 -listChildren; //Gets a list with the layer IDs of all the child layers of the Display Correction Layer with ID 1 * | ||
-layer <ID> -delete | Deletes the layer with the selected ID. | vray vfbControl -layer 9 -delete; //Deletes the layer with ID 9. | ||
| -createlayer <class name> <parent id> | Creates a layer of the given class as a child of the given layer, returns the new layer's ID. The new layer is created as the topmost child of the parent layer. | vray vfbControl -createLayer "chaos.cc.exposure" 1; //Creates an exposure layer under the Display Correction group * | ||
-listLayerClasses | Returns a list of creatable layer classes. | vray vfbControl -listLayerClasses; | ||
-findLayerByName | Returns the ID of a layer with the given name or -1 if no such layer is found. | String | vray vfbControl -findLayerByName "Display Correction"; //Gets the ID of the Display Correction layer. | |
-findLayersByClass | Returns a list of the IDs of all layers of the given class. | String | vray vfbControl -findLayersByClass "chaos.displayCorrection"; //Gets the ID of the layer from the chaos.displayCorrection class | |
-displayCorrectionLayer | Returns the ID of the display correction layer. | vray vfbControl -displayCorrectionLayer; | ||
-sourceLayer | Returns the ID of the source layer. | vray vfbControl -sourceLayer; //Returns the ID of the source layer | ||
-denoiserLayer | Returns the ID of the denoiser layer. | vray vfbControl -denoiserLayer; //Returns the ID of the denoiser layer | ||
-lensEffectsLayer | Returns the ID of the lens effects layer. | vray vfbControl -lensEffectsLayer; //Returns the ID of the Lens Effects layer | ||
-lightMixLayer | Returns the ID of the light mix layer. | vray vfbControl -lightMixLayer; //Returns the ID of the Light Mix layer | ||
-saveLayersToJSON | Returns a JSON string representing the state of all layers. | vray vfbControl -saveLayersToJSON; //Returns a JSON string representing the state of all layers | ||
-loadLayersFromJSON | Loads settings from a JSON string. | String | vray vfbControl -loadLayersFromJSON "\insert here the JSON string that represents the state of all layers from the -saveLayersToJSON argument; | |
-saveLayersToFile | Saves layers to a file. | String (filename) | vray vfbControl -saveLayersToFile "C:\Path\To\Location\layers.txt"; //Saves a text file representing the state of all layers | |
-loadLayersFromFile | Loads layers from a file. | String (filename) | vray vfbControl -loadLayersFromFile "C:\Path\To\Location\layers.txt"; //Loads the layers with all the states represented in the file | |
-bakeLayersToLUT | Bakes all layers to a LUT file. | String (filename) | vray vfbControl -bakeLayersToLUT "C:\Path\To\Location\layers.lut"; //Bakes all layers to a lut file |
NOTE: The ID of the Display Correction layer is different for each session. The given examples will not work, if the Display Correction layer's ID is not the same as in the examples.
VFB History
| Flag | Description | Arguments | Set/Get | Example |
|---|---|---|---|---|
| -showhistory | Enables/disables the VFB History window. | Boolean | yes | |
| -history | Shows/hides the VFB history in the History panel. | Boolean | yes | |
| -historymaxsize | Returns/specifies the size of the VFB History in MB. | Integer | yes | |
| -historyselect | Selects an image in the VFB History (0-based index) for use with additional commands in this section. | Integer | vray vfbControl -historyselect 2; | |
| -historyload -historysave -historyseta -historysetb -historyremove | Performs an operation on the History image that was selected with the -historyselect flag. | N/A | vray vfbControl -historyselect 2 ; vray vfbControl -historyseta; | |
| -historyclear | Deletes all images from the VFB History. | N/A | ||
| -historytemppath | Returns/specifies the path used for the History Directory. | String (path) | yes | |
| -historycomment | Adds a comment to the History image that was selected with the -historyselect tag. | String (comment) | yes |
Lens Effects
| Flag | Description | Arguments | Set/Get | Example |
|---|---|---|---|---|
| -bloom | Enables/disables the Bloom Effect. | Boolean | yes | vray vfbControl -bloom true; |
| -glare | Enables/disables the Glare Effect. | Boolean | yes | |
| -bloomfill | Enables/disables the Bloom Fill Edges option. | Boolean | yes | |
| -glarefill | Enables/disables the Glare Fill Edges option. | Boolean | yes | |
| -bloommode | Specifies if the bloom will be applied to the RGB image, stored in a separate render element, or both. | image | both | renderelem | yes | vray vfbControl -bloommode image; |
| -glaretype | Specifies how the glare is computed. It can be computed from the image, render camera, or camera parameters. | image | rendercam | camparams | yes | |
| -glaremode | Determines if the glare effect will be applied to the final image, stored into a separate render element, or both. | image | both | renderelem | yes | |
| -bloomweight | Sets the Bloom Weight value. | Float | yes | |
| -bloomsize | Sets the Bloom Size value. | Float | yes | |
| -bloomshape | Sets the Bloom Shape value. | Float | yes | |
| -glareweight | Sets the Glare Weight value. | Float | yes | |
| -glaresize | Sets the Glare Size value. | Float | yes | |
| -bloomintensity | Enables/disables the Bloom Mask Intensity option. | Boolean | yes | |
| -bloomobject | Enables/disables the Bloom Mask Object ID option. | Boolean | yes | |
| -bloommaterial | Enables/disables the Bloom Mask Material ID option. | Boolean | yes | |
| -glareintensity | Enables/disables the Glare Mask Intensity option. | Boolean | yes | |
| -glareobject | Enables/disables the Glare Mask Object ID option. | Boolean | yes | |
| -glarematerial | Enables/disables the Glare Mask Material ID option. | Boolean | yes | |
| -bloomsetintensity | Sets the Bloom Mask Intensity value. | Float | ||
| -glaresetintensity | Sets the Glare Mask Intensity value. | Float | ||
| -bloomgetintensity | Returns the Bloom Mask Intensity Float value. | N/A | ||
| -glaregetintensity | Returns the Glare Mask Intensity Float value. | N/A | ||
| -bloomsetobject | Sets the Bloom Mask Object ID value. | Integer | ||
| -bloomsetmaterial | Sets the Bloom Mask Material ID value. | Integer | ||
| -glaresetobject | Sets the Glare Mask Object ID value. | Integer | ||
| -glaresetmaterial | Sets the Glare Mask Material ID value. | Integer | ||
| -bloomgetobject | Returns the Bloom Mask Object ID Integer value. | N/A | ||
| -bloomgetmaterial | Returns the Bloom Mask Material ID Integer value. | N/A | ||
| -glaregetobject | Returns the Glare Mask Object ID Integer value. | N/A | ||
| -glaregetmaterial | Returns the Glare Mask Material ID Integer value. | N/A | ||
| -glarediffraction | Enables/disables Glare Diffraction option. | Boolean | yes | |
| -glareuseobstacle | Enables/disables the Glare Use Obstacle image option. | Boolean | yes | |
| -glareblades | Enables/disables the Glare Blades option. | Boolean | yes | |
| -glarebladesrot | Sets the Glare Blades rotation. | Float | yes | |
| -glarefnumber | Sets the Glare F-Number value. | Float | yes | |
| -glaresetblades | Sets the Glare Blades number. | Float | ||
| -glaregetblades | Returns the Glare Blades Float value. | N/A | ||
| -glareimage | Specifies the Glare Image. | String (filename) | yes | |
| -glareobstacleimage | Specifies the Glare Obstacle image. | String (filename) | yes | |
| -glarescr | Turns on/off Lens Scratches. | Boolean | yes | |
| -glarescrsymmetric | Turns on/off Symmetric for scratches. | Boolean | yes |
Stamps
| Flag | Description | Arguments | Set/Get | Example |
|---|---|---|---|---|
| -stamp | Enables/disables the stamp to the VFB image. | Boolean | yes | vray vfbControl -stamp true; |
| -stamphalign | Sets the horizontal alignment for the stamp. | left | center | right | yes | |
| -stampvalign | Sets the vertical alignment for the stamp. | top | bottom | yes | |
| -stamptext | Specifies the text String to appear on the stamp. | String | yes | vray vfbControl -stamptext "Test rendering"; |
Environment Variables
Some aspects of the VFB can also be controlled with various environment variables:
| Variable Name | Description |
|---|---|
VRAY_WRITE_COLOR_CORRECTIONS | When present and set to 0, specifies that by default any color corrections to the final images written to the disk should be disabled. |
VRAY_VFB_SRGB | Turn On (1) or Off (2) sRGB option of New VFB by default. |
VRAY_VFB_PIXEL_ASPECT | Turn On (1) or Off (2) Use pixel aspect option of New VFB by default. |
OCIO | Specifies the default OCIO color configuration if OCIO display color correction is enabled. |
VRAY_VFB_OCIO | Enable (1) or Disable (2) the OCIO correction in New VFB by default. |
VRAY_VFB_OCIO_INPUT_COLORSPACE | Specify default input OCIO color space. A default OCIO configuration can be specified by the OCIO environment variable. |
VRAY_VFB_OCIO_VIEW_TRANSFORM | Specify default OCIO view transform. A default OCIO configuration can be specified by the OCIO environment variable. |
VRAY_VFB_ICC | Enable (1) or Disable (2) the ICC correction in VFB by default. |
VRAY_VFB_ALWAYS_ON_TOP | Specify an ALWAYS ON TOP behavior: 0 - disabled |