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.

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, 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 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

* Note that if using V-Ray 5, update 2.2 or earlier, the returned values in the VFB are relative to the VFB window margins instead of to the actual rendered image. Starting with V-Ray 5, update 2.3, the returned values in the VFB are relative to the 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
sharpenBlurLayer	Layer	Read Only	vfbLayers.sharpenBlurLayer
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"

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
#testresolution	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 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 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 VFB are relative to the VFB window margins instead of to the actual rendered image.

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 VFB by default.
VRAY_VFB_PIXEL_ASPECT	Turn On (1) or Off (2) Use pixel aspect option of 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 VFB. It will be automatically loaded when ICC is enabled.
VRAY_VFB_OCIO	Enable (1) or Disable (2) the OCIO correction in 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 VFB by default.
VRAY_VFB_LUT_FILE	Specify default LUT correction file for VFB. It will be automatically loaded when LUT is enabled.
VRAY_VFB_COLOR_CORRECT_ALL	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

Content

Space Tools

Overview

From MaxScript

vfbControl() MaxScript Function

Color Correction

Debug Shading

History

Layers

Lens Effects

Stamps

Other MaxScript Functions

Environment Variables

Content

Space Tools

Controlling the VFB Programmatically

Overview

From MaxScript

vfbControl() MaxScript Function

Color Correction

Debug Shading

History

Layers

Lens Effects

Stamps

Toolbar

Other MaxScript Functions

Environment Variables