Controlling the New VFB Programmatically

This page contains information for controlling the New V-Ray Frame Buffer through environment variables and MaxScript.

Overview

The New V-Ray Frame Buffer can be controlled programmatically in two ways: the first is by using MaxScript commands and the second, by using various environment variables.

There is some mismatch in the supported commands for the old VFB (3ds Max 2017 and older) and the new VFB. Data on the supported commands for each VFB version must be taken from their respective documentation pages only. This current page contains information only on the supported commands for the new VFB. Information about the old VFB can be found here: Controlling the VFB Programmatically

vfbControl #help lists commands which are available for the old and new VFB but not all of them work with both frame buffers.

From MaxScript

vfbControl() MaxScript Function

The vfbControl() MaxScript function modifies the various aspects of the New VFB. These commands can be used in the MAXScript Listener or in an executable script. Commands follow this structure:

vfbControl (parameter) 
vfbControl (parameter) (argument)

For example, to turn off the red channel in the New VFB, type:

vfbControl #red false

To see a list of available options, type one of the following:

vfbControl()
vfbControl #help

Here are some guidelines for using MaxScript:

  • Arguments listed as Boolean can only receive true/false values. These options turn a feature on (true) or off (false).

  • 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, or 2. String values of this argument type are input with quote marks. For example, vfbControl #stamphalign "right"

  • Successfully loading a file or setting a numerical value implicitly enables the corresponding option. For example, using #setregion to 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.

  • Many commands will return the current values for the parameter when used without arguments. This feature has been enabled for all commands for which it makes sense to do so.

Global VFB function

Description

vfbControl()

Allows control over the various aspects of the New VFB. Type vfbControl() for a list of available parameters.

vfbControl #show

[true/false]

Opens (true) or Closes (false) the VFB window or returns its current display state if called without a value.

vfbControl #getregion*

Returns an array with four integer elements, representing the pixel coordinates of the VFB render region (left, top, right, bottom ). The left and top coordinates are included in the region, the right and bottom one are not.

vfbControl #setregion*

Sets the VFB render region to the specified coordinates. Uses 4 integer values.

For example, vfbControl #setregion 300 100 400 200

* The returned values in the New VFB are relative to the New VFB window margins instead of to the actual rendered image.

Color Correction

Parameter

Description

Arguments

Examples

#ocio

Enables the OCIO mode in the Display Correction layer or sets to None

Boolean

 

#icc

Enables the ICC mode in the Display Correction layer or sets to None

Boolean

 

#srgb

Enables the sRGB mode in the Display Correction layer or sets to None

Boolean

 

#ccociovt

Sets OCIO View Transform by number in the dropdown list

Integer

 

#ccocioics

Sets OCIO Input Colorspace by number in the dropdown list

Integer

 

#ccociodd

Sets OCIO Display Device by number in the dropdown list

Integer

 

#ocioinputcolorspace

Sets OCIO Input Colorspace by name

String

 

#ociodisplaydevice

Sets OCIO Display Device by name

String

 

#ocioviewtransform

Sets OCIO View Transform by name

String

 

#itemsociocs

Returns a list of all available OCIO Input Colorspace values

None

 

#itemsociodd

Returns a list of all available OCIO Display Device values

None

 

#itemsociovt

Returns a list of all available OCIO View Transform values

None

 

#itemsiccri

Returns a list of all available ICC Rendering Intent values

None

 

#cciccblackpoint

Enables/disables ICC black point compression

Boolean

 

#cciccrenderintent

1 - Perceptual
2 - Relative colorimetric
3 - Saturation
4 - Absolute colorimetric

1 | 2 | 3 | 4

 

#loadocio

Specifies file for OCIO correction

String (filename)

 

#loadicc

Specifies file for ICC correction

String (filename)

 

#saveglobalccpreset

Save Global preset for the Corrections control panel to a specified .vccglb or .vfbl file

String (filename)

 

#loadglobalccpreset

Load Global preset for the Corrections control panel from a specified .vccglb or .vfbl file

String (filename)

 

#iccfile
#ociofile

Returns the filename (string) used in the corresponding Correction Control rollout

None

 

#ociosaveinfile
#bkgrsaveinfile
#lutsaveinfile

Enables the respective "save to image" checkboxes in the VFB.

Boolean

vfbcontrol #ociosaveinfile true
vfbcontrol #bkgrsaveinfile true
vfbcontrol #lutsaveinfile true

#gamma22

Enables Gamma 2.2 mode in the Display Correction layer or sets to None

Boolean

 

Debug Shading

Parameter

Description

Value Options

Examples

#debugshading

Enables/Disables Debug Shading

Boolean

vfbControl #debugshading true

#debugshadinglockedselection

Switches from Isolate Selected to Isolate Locked Selection Debug Shading mode

Boolean

vfbControl #debugshadinglockedselection true

#debugshadingmode

Sets Debug Shading mode with an integer:
0 - Isolate Selected/Isolate Locked Selection;
1 - Lighting;
2 - Ambient Occlusion;
3 - Wireframe;
4 - Normals;
5 - UVs;

Integer

vfbControl #debugshadingmode 1

History

Parameter

Description

Arguments

Examples

#history

Enables/Disables History

Boolean

 

#showhistory

Shows/Hides History panel

Boolean

 

#historytemppath

Returns the path used for History Directory

Sets path used for History Directory

None

Path string

 

#historymaxsize

Returns the Size of VFB History in MB

Sets the Size of VFB History in MB

None

Integer

 

#historysave

Saves the current VFB image in history

None

 

#historyselect

Selects a History image based on index.
Selection is used in conjunction with the commands that follow.
First image has 0 index.

Integer

vfbControl #historyselect 2

#historyload
#historyseta
#historysetb
#historyremove

Performs an operation on the History image that was selected with #historyselect on the previous line

None

vfbControl #historyselect 0 (required before next command)
vfbControl #historyseta

#historyclear

Deletes all images from history

None

 

#historycomment

Adds a comment to the History image that was selected with #historyselect on the previous line

String

vfbControl #historyselect 1
vfbControl #historycomment "Rendered with GI off"

Layers

Instance of this object can be created with a call like vfbLayers=(vfbControl #getLayerMgr)[1]

Properties:

Name

Type

Access

Example

Notes

numLayers

Integer

Read only

vfbLayers.numLayers

Return the number of layers

displayCorrectionLayer

Layer

Read only

vfbLayers.displayCorrectionLayer

Access to the display correction layer - it is a singleton layer so this is a helper to get it directly

sourceLayer

Layer

Read only

vfbLayers.sourceLayer

Access to the source layer

denoiserLayer

Layer

Read only

vfbLayers.denoiserLayer

 

lensEffectsLayer

Layer

Read only

vfbLayers.lensEffectsLayer

 

lightMixLayer

Layer

Read only

vfbLayers.lightMixLayer

 

stampLayer

Layer

Read only

vfbLayers.stampLayer

Access to the Stamp layer

Use the Showinterface Maxscript command to explore the available properties and methods to each VFB2 layer.

For example: showinterface vfbLayers.displayCorrectionLayer

Methods:

Return Type

Name

Argument

Examples

Notes

integer array

getAllLayerIDs

-

vfbLayers.getAllLayerIDs()

Get the IDs of all layers

Layer

getLayer

Int layerID

layerA = vfbLayers.getLayer #
note: use a valid layer number to replace the # symbol

Get a layer object for the given layer ID

string array

getCreatableLayerClasses

-

vfbLayers.getCreatableLayerClasses()

Return a list of the class names of layer classes that can be created

Layer

createLayer

Int parentLayerID, String layerClass

vfbLayers.createLayer # "chaos.ref.re.colormask"
note: use a valid layer number to replace the # symbol"

Create a new layer and add it as a child of the given parent

Boolean

saveLayersToFile

Filename

vfbLayers.saveLayersToFile "C:\\temp\\layerstree.vfbl"

Save all layers to .vfbl file

Boolean

loadLayersFromFile

Filename

vfbLayers.loadLayersFromFile "C:\\temp\\layerstree.vfbl"

Load layers from .vfbl file

Boolean

bakeLayersToLUT

Filename

vfbLayers.bakeLayersToLUT "C:\\temp\\lutcc.cube"

Bake all layers (that can be baked) to a .cube file

Void

deleteLayer

Layer

layerA = vfbLayers.getLayer #
vfbLayers.deleteLayer layerA

Delete a layer.

String

saveLayersToJSON

-

jsonlayers = vfbLayers.saveLayersToJSON()

Save all layers to a string containing the information in a JSON format

Boolean

loadLayersFromJSON

JSON

vfbLayers.loadLayersFromJSON jsonlayers
note: the jsonlayers variable in the example already contains layers json data

Load layers from a string containing the information in a JSON format

Boolean

transferLightMixToScene

-

vfbLayers.transferLightMixToScene()

Transfers LightMix corrections to the actual lights in the scene

Lens Effects

Parameter

Description

Arguments

#glareversion

Return the version of the lens effects

 

#glare

Turn lens effects On/Off

Boolean

#glaresize

Sets Glare Size value

Float

#glarebloom

Sets Bloom value

Float

#glareintensity

Sets intensity value for the glare effect

Float

#glarethreshold

Sets a Threshold value

Float

#glarefilterrot

Sets Rotation of the final result effect

Float

#glarecoldwarm

Turns on/off Cold/Warm

Boolean

#glareblades

Enables/disables Blades

Boolean

#glaresides

Sets the value of the Sides, i.e. the number of "rays" of the glare

Integer

#glarebladesrot

Sets Glare Blades rotation

Float

#glarestreakblur

Sets Streak Blur value

Float

#glaresaturation

Sets Saturation value

Float

#glarehwdacc

Turns on/off Hardware accelerate

Boolean

#glareinteractive

Turns on/off Interactive

Boolean

#glaregrating

Turns on/off Peripheral Grating

Boolean

#glaregratingstrength

Sets Strength value of the blades effects

Float

#glaregratingdensity

Sets Density of the grating effect in percent

Float

#glaregratingzoom

Sets Zoom value

Float

#glaregratingslope

Sets Slope value

Float

#glaregratinglength

Sets Length for the of the grate lines

Float

#glareocc

Turns on/off Occlusion

Boolean

#glareoccsymmetric

Turns on/off Symetric

Boolean

#glareoccpercent

Sets occlusion Percent value

Float

#glareoccrot

Sets occlusion Rotation value

Float

#glareoccarc

Sets occlusion Arc value

Float

#glarescr

Turns on/off Lens Scratches

Boolean

#glarescrsymmetric

Turns on/off Symmetric for scratches

Boolean

#glarescrpattern

0 - random
1 - stripe
2 - square
3 - hexagonal

0 | 1 | 2 | 3

#glarescrstreaks

Sets lens scratches Streaks value

Integer

#glarescrseed

Sets Seed value

Integer

#glarescrdensity

Sets lens scratches Density value

Float

#glarescrlength

Sets lens scratches Length value

Float

#glarescrslopevar

Sets lens scratches Slope Variance value

Float

#glarescrwidthvar

Sets lens scratches Width Variance value

Float

#glarescrzoom

Sets lens scratches Zoom value

Float

#glarescrrot

Sets lens scratches Rotation value

Float

#glarescrstrength

Sets lens scratches Strength value

Float

#glaredust

Turns on/off Lens Dust

Boolean

#glaredustpattern

0 - random
1 - square
2 - hexagonal

0 | 1 | 2

#glaredustdensity

Sets lens dust Density value

Float

#glaredustradvar

Sets lens dust Radius Variance value

Float

#glaredustjitter

Sets lens dust Jitter value

Float

#glaredustzoom

Sets lens dust Zoom value

Float

#glaredustrot

Sets lens dust Rotation value

Float

#glareduststrength

Sets lens dust Strength value

Float

#glareobstacle

Enables/disables Use Obstacle image

Boolean

#glareobstacleimage

Sets Path to the obstacle image

Path String

#glareobstaclezoom

Sets Size of the obstacle image

Float

#glareobstaclerot

Sets Rotation for the obstacle image

Float

#glareobstaclestrength

Sets Strength value for the obstacle image

Float

#glarefilter

Turns on/off Filter Image

Boolean

#glarefilterimage

Specifies path to a filter kernel

Path String

Stamps

Parameter

Description

Value Options

Examples

#stamp

Enables/disables the stamp

Boolean

vfbControl #stamp true

#stamphalign

Sets horizontal alignment for stamp

"left" | "center" | "right"

 

#stampvalign

Sets vertical alignment for stamp

"top" | "bottom"

 

#stamptext

Sets the text string to appear on the stamp

String

vfbControl #stamptext "Test rendering"

Toolbar

Parameter

Description

Arguments

Examples

#help

Displays options for the vfbControl command

None

 

#show

Opens (true) or closes (false) the VFB window or returns its current display state if called without a value

Boolean

 

#red
#green
#blue
#alpha
#mono

Enables/disables the corresponding VFB toolbar feature

Boolean

vfbControl #alpha true

#trackmouse

Enables/disables the Track mouse while rendering feature

Boolean

 

#setcompareab

Enables/disables Compare horizontal and Compare vertical features

"h" | "hor" | "horizontal"
"v" | "ver" | "vertical"

vfbControl #setcompareab "h"

#loadimage

Loads the specified image in VFB

String (filename)

 

#saveimage

Saves the VFB current channel as an image

String (filename)

 

#saveallimage

Saves all VFB render channels to separate images or a single .vrimg file

String (filename)

 

#savemultiimage

Saves a multichannel .exr or .vrimg file with all VFB render channels inside

String (filename)

vfbcontrol #savemultiimage "D:\output\image.exr"

#clearimage

Clears the VFB image

None

 

#duplicate

Duplicates the VFB

None

 

#hide

Hides the VFB

None

 

#getchannel

Returns the index of the currently selected render element channel.

None

 

#getchannelnames

Returns a list of the channels available in the current image

None

 

#setchannel

Selects the render element channel with an index

Integer

vfbControl #setchannel 0

#setregion

Sets the render region in pixels, or resets to entire image

Integers: left top right bottom
"reset"

vfbControl #setregion 0 0 640 480
vfbControl #setregion "reset"

#clamp

Enables/disables Force color clamping

Boolean

vfbControl #clamp true

#viewclamp

Enables/disables View clamped colors

Boolean

 

#pixelaspect

Enables/disables Use pixel aspect

Boolean

 

#pos

Controls the position of the VFB window:
<top> - the vertical coordinates of the VFB window
<left> - the horizontal coordinates of the VFB window
"reset" - returns the VFB window to its default position
Note: Running without any arguments will return the current position of the VFB window.

Integers: top left
"reset"

vfbControl #pos 100 150
vfbControl #pos "reset"

#testresolution

Enables/disables the Test resolution scale.

Boolean

vfbcontrol #testresolution true

Sets the Test resolution value using an integer:

1- 10%

2 - 25%

3 - 50%

4 - 75%

5 - 110%

6 - 125%

7 - 150%

Integer:

1 | 2 | 3 | 4 | 5 | 6 | 7

vfbcontrol #testresolution 1

#testresolutionpreset

Returns current scale preset number.

None

vfbcontrol #testresolutionpreset

Other MaxScript Functions

The following stand-alone functions complement the ones found in vfbControl():

Global VFB function

Description

vrayVFBGetRegionEnabled()

Returns whether region rendering in the New VFB is enabled (true) or disabled (false).

vrayVFBGetRegion()*

Returns an array with four integer elements, representing the pixel coordinates of the VFB render region (left, top, right, bottom). The left and top coordinates are included in the region, the right and bottom one are not.

vrayVFBSetRegionEnabled true|false

Turns on or off the VFB region render option.

vrayVFBSetRegion left top right bottom*

Sets the VFB render region to the specified coordinates.

vrayVFBGetNumChannels()

Returns the number of channels (render elements) in the New VFB. This will return 0 if the VFB is not initialized or does not store any data.

vrayVFBGetChannelName i

Return the name of the i-th channel. Indexes start from 1.

vrayVFBGetChannelType i

Returns the storage type of the i-th channel. Indexes start from 1. The return value specifies the type of data for each pixel in the given channel:
0 - the index is not valid or the VFB does not store an image;
1 - a single floating-point number (this is used, for example, for the z-depth channels);
2 - three floating-point numbers (this is used for regular color channels);
3 - two floating-point numbers;
4 - a single integer number (used, for example, by the render ID and material ID elements);
5 - three signed floating-point numbers (this is used, for example, for normals and world position channels);
6 - four floating-point numbers (this is used for channels like VRayMtlSelect and VRayCryptomatte where an Alpha component is present together with the RGB data).

vrayVFBGetChannelAlias i

Returns the alias for the i-th channel. Indexes start from 1.

vrayVFBGetChannelBitmap i

Returns the contents of the specified channel as a 3ds Max bitmap. Indexes start from 1. This will return undefined if the channel index is not valid or the VFB does not contain any data.

* The returned values in the New VFB are relative to the New VFB window margins instead of to the actual rendered image.

Environment Variables

Some aspects of the New VFB can also be controlled with various environment variables:

Variable Name

Description

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.

VRAY_VFB_GLOBAL_PRESET_FILE_USE

Enable (1) or Disable (0) automatic loading of a global .vccglb preset for the VFB.

VRAY_VFB_GLOBAL_PRESET_FILE

Specify default .vccglb filename (string) to be used when loading automatic global preset.

VRAY_VFB_ICC

Enable (1) or Disable (2) the ICC correction in VFB by default.

VRAY_VFB_ICC_FILE

Specify default ICC correction file for New VFB. It will be automatically loaded when ICC 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_DISPLAY_DEVICE

Specify default OCIO display device. 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_LUT

Enable (1) or Disable (2) the LUT correction in New VFB by default.

VRAY_VFB_LUT_FILE

Specify default LUT correction file for New VFB. It will be automatically loaded when LUT is enabled.

VRAY_VFB_AFFECT_SWATCHES

Apply VFB corrections to swatches in the Material Editor:
0 - none
1 - OCIO only
2 - all corrections except sRGB
3 - all corrections including sRGB

VRAY_VFB_ALWAYS_ON_TOP

Specify a ALWAYS ON TOP behavior:
0 - disabled
1 - force enable always on top
2 - force disable always on top