Controlling the VFB Programmatically

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

Overview

The 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 old VFB. Information about the new VFB can be found here: Controlling the New 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 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 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, #setregion "reset"

  • 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 V-Ray 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.

Color Correction

Parameter

Description

Arguments

Examples

#showcc

Shows/hides the Color Corrections panel

Boolean

 

#exposure

Enables/disables Exposure correction

Boolean

 

#whitebalance

Enables/disables White Balance correction

Boolean

 

#huesat

Enables/disables Hue / Saturation correction

Boolean

 

#colorbalance

Enables/disables Color Balance correction

Boolean

 

#levels

Enables/disables Levels correction

Boolean

 

#curve

Enables/disables Curve correction

Boolean

 

#bkgr

Enables/disables Background Image correction

Boolean

 

#lut

Enables/disables LUT correction

Boolean

 

#ocio

Enables/disables OCIO correction

Boolean

 

#icc

Enables/disables ICC correction

Boolean

 

#srgb

Enables/disables sRGB gamma correction

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

 

#colorbalancemode

Sets the Color Balance mode with an integer:
0 - All
1 - Shadows
2 - Midtones
3 - Highlights

0 | 1 | 2 | 3

vfbControl #colorbalancemode 3

#colorbalancevalue

Sets the Color Balance values
for Cyan, Magenta, Yellow

# # #
Where each # is an
integer or float

vfbControl #colorbalancevalue 0.2 0 0.1

#huesaturationvalue

Sets the Hue/Saturation values
for Hue, Saturation, Brightness

# # #
Where each # is an
integer or float

 

#cclevels_rgb
#cclevels_red
#cclevels_green
#cclevels_blue

Enables/disables color components in Levels correction

Boolean

 

#bkgrimgasforegr

Enables/disables the use of Background correction image as foreground

Boolean

 

#lutconverttolog

Enables/disables Log space conversion before applying LUT

Boolean

 

#cciccblackpoint

Enables/disables ICC black point compression

Boolean

 

#cciccrenderintent

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

1 | 2 | 3 | 4

 

#setexposure

Sets Exposure value

Float

 

#sethighlightburn

Sets Highlight Burn value

Float

 

#setcontrast

Sets Contrast value

Float

 

#setlevelsmin

Sets Levels min value

Float

 

#setlevelsmax

Sets Levels max value

Float

 

#setlutweight

Sets the LUT Weight value

Float

vfbcontrol #setlutweight 0.5

#setwhitebalanceval

Sets White Balance Temperature value

Float

 

#getexposure

Returns the current Exposure float value

None

 

#gethighlightburn

Returns the current Highlight Burn value

None

 

#getcontrast

Returns the current Contrast float value

None

 

#getlevelsmin

Returns the current Levels min float value

None

 

#getlevelsmax

Returns the current Levels max float value

None

 

#getwhitebalanceval

Returns the current White Balance Temperature float value

None

 

#getlutweight

Returns the current LUT Weight value.

None

 

#loadbkgrimage

Specifies file for Background image correction

String (filename)

 

#loadlut

Specifies file for LUT correction

String (filename)

 

#loadocio

Specifies file for OCIO correction

String (filename)

 

#loadicc

Specifies file for ICC correction

String (filename)

 

#loadcurve

Load Curve shape from the specified .bcurve file

String (filename)

 

#savecurve

Save Curve shape in the specified .bcurve file

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)

 

#saveccpreset

Save preset for corrections control rollout to a specified file.
Presets for each separate Correction control rollout use different file extensions.

String (filename)

 

#loadccpreset

Load preset in corrections control rollout from a specified file.
Presets for each separate Correction control rollout use different file extensions.

String (filename)

 

#resetcc
#resetccexp
#resetccwb
#resetcchsl
#resetccbal
#resetcclvl
#resetcccrv
#resetcclut
#resetccicc
#resetccocio
#resetccbgimg

Resets parameters from corresponding
Correction Control rollouts to default values.

None

vfbcontrol #resetcc - Resets all correction control parameters
vfbcontrol #resetccbal - Resets only parameters in Color Balance rollout

#bkgrimgfile
#lutfile
#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

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;
6 - Barycentric coordinates

Integer

vfbControl #debugshadingmode 1

. ipr_debugshading_wireframe_subtris

Shows/Hides subtriangles in Wireframe shading mode.

Boolean

renderers.current.ipr_debugshading_wireframe_subtris true

.ipr_debugshading_wireframe_width_pix

Sets pixel width for Wireframe shading mode.

Float

renderers.current.ipr_debugshading_wireframe_width_pix 0.5

.ipr_debugshading_ao_radius_pix

Sets radius in pixels for the Ambient Occlusion shading mode.

Float

renderers.current.ipr_debugshading_ao_radius_pix 20

History

Parameter

Description

Arguments

Examples

#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"

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

#glaremode

Sets the Glare mode

"image" | "renderelem" | "both"

#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

 

#rgb
#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

 

#linkpdp

Enables/disables the Link VFB to PDPlayer feature

Boolean

 

#swapab

Enables/disables the Swap A/B 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"

#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"

#getregion

Returns the current left, top, right, and bottom settings for region rendering

None

vfbControl #getregion

#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

#clamp

Enables/disables Force color clamping

Boolean

vfbControl #clamp true

#viewclamp

Enables/disables View clamped colors

Boolean

 

#info

Enables/disables Show Pixel information

Boolean

 

#pixelaspect

Enables/disables Use pixel aspect

Boolean

 

#stereo

Sets the Stereo value using an integer:
0 - Inactive
1 - Red/cyan mode
2 - Green/magenta mode

0 | 1 | 2

vfbControl #stereo 1

#pos

Controls the position of the VFB window:
<top> - the vertical coordinates of the VFB window
<left> - the horizontal coordinates of the VFBwindow
"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%

Integer:

1 | 2 | 3 | 4

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 V-Ray 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 V-Ray 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. See the RegionChannelAlias enum in the file "pixelbuffer.h" from the V-Ray SDK.

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.

Environment Variables

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

Variable Name

Description

VRAY_VFB_SRGB

Turn On (1) or Off (2) sRGB option of V-Ray VFB by default.

VRAY_VFB_PIXEL_ASPECT

Turn On (1) or Off (2) Use pixel aspect option of V-Ray 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 V-Ray VFB. It will be automatically loaded when ICC is enabled.

VRAY_VFB_OCIO

Enable (1) or Disable (2) the OCIO correction in V-Ray 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 V-Ray VFB by default.

VRAY_VFB_LUT_FILE

Specify default LUT correction file for V-Ray 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