Page Contents ×

 

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

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

 

Color Correction

ParameterDescriptionArgumentsExamples
#ocioEnables the OCIO mode in the Display Correction layer or sets to NoneBoolean 
#iccEnables the ICC mode in the Display Correction layer or sets to NoneBoolean 
#srgbEnables the sRGB mode in the Display Correction layer or sets to NoneBoolean 
#ccociovtSets OCIO View Transform by number in the dropdown listInteger 
#ccocioicsSets OCIO Input Colorspace by number in the dropdown listInteger 
#ccocioddSets OCIO Display Device by number in the dropdown listInteger 
#ocioinputcolorspaceSets OCIO Input Colorspace by nameString 
#ociodisplaydeviceSets OCIO Display Device by nameString 
#ocioviewtransformSets OCIO View Transform by nameString 
#itemsociocsReturns a list of all available OCIO Input Colorspace valuesNone 
#itemsocioddReturns a list of all available OCIO Display Device valuesNone 
#itemsociovtReturns a list of all available OCIO View Transform valuesNone 
#itemsiccriReturns a list of all available ICC Rendering Intent valuesNone 
#cciccblackpointEnables/disables ICC black point compressionBoolean 
#cciccrenderintent1 - Perceptual 
2 - Relative colorimetric
3 - Saturation
4 - Absolute colorimetric
1 | 2 | 3 | 4 
#loadocioSpecifies file for OCIO correctionString (filename) 
#loadiccSpecifies file for ICC correctionString (filename) 
#saveglobalccpreset



Save Global preset for the Corrections control panel to a specified .vccglb or .vfbl fileString (filename) 
#loadglobalccpresetLoad Global preset for the Corrections control panel from a specified .vccglb or .vfbl fileString (filename) 

#iccfile
#ociofile

Returns the filename (string) used in the corresponding Correction Control rolloutNone 
#ociosaveinfile
#bkgrsaveinfile
#lutsaveinfile
Enables the respective "save to image" checkboxes in the VFB.Boolean

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

#gamma22Enables Gamma 2.2 mode in the Display Correction layer or sets to NoneBoolean 

 

Debug Shading

ParameterDescriptionValue OptionsExamples
#debugshadingEnables/Disables Debug ShadingBooleanvfbControl #debugshading true
#debugshadinglockedselectionSwitches from Isolate Selected to Isolate Locked Selection Debug Shading modeBooleanvfbControl #debugshadinglockedselection true
#debugshadingmodeSets Debug Shading mode with an integer:
0 - Isolate Selected/Isolate Locked Selection;
1 - Lighting;
2 - Ambient Occlusion;
3 - Wireframe;
4 - Normals;
5 - UVs;
IntegervfbControl #debugshadingmode 1

 

History

ParameterDescriptionArgumentsExamples
#historyEnables/Disables HistoryBoolean 
#showhistoryShows/Hides History panelBoolean 
#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

 
#historysaveSaves the current VFB image in historyNone 
#historyselect

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

IntegervfbControl #historyselect 2
#historyload
#historyseta
#historysetb
#historyremove
Performs an operation on the History image that was selected with #historyselect on the previous lineNonevfbControl #historyselect 0 (required before next command)
vfbControl #historyseta 
#historyclearDeletes all images from historyNone 
#historycommentAdds a comment to the History image that was selected with #historyselect on the previous lineStringvfbControl #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

TypeAccessExampleNotes
numLayersIntegerRead onlyvfbLayers.numLayersReturn the number of layers
displayCorrectionLayerLayerRead onlyvfbLayers.displayCorrectionLayerAccess to the display correction layer - it is a singleton layer so this is a helper to get it directly

sourceLayer

LayerRead onlyvfbLayers.sourceLayerAccess to the source layer
denoiserLayerLayerRead onlyvfbLayers.denoiserLayer 
sharpenBlurLayerLayerRead OnlyvfbLayers.sharpenBlurLayer 
lensEffectsLayerLayerRead onlyvfbLayers.lensEffectsLayer 

lightMixLayer

LayerRead onlyvfbLayers.lightMixLayer 
stampLayerLayerRead onlyvfbLayers.stampLayerAccess 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 TypeNameArgumentExamplesNotes
integer arraygetAllLayerIDs-vfbLayers.getAllLayerIDs()Get the IDs of all layers
LayergetLayerInt layerID

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

Get a layer object for the given layer ID
string arraygetCreatableLayerClasses-vfbLayers.getCreatableLayerClasses()

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

LayercreateLayerInt 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

BooleansaveLayersToFileFilenamevfbLayers.saveLayersToFile "C:\\temp\\layerstree.vfbl"Save all layers to .vfbl file
BooleanloadLayersFromFileFilenamevfbLayers.loadLayersFromFile "C:\\temp\\layerstree.vfbl"Load layers from .vfbl file
BooleanbakeLayersToLUTFilenamevfbLayers.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.
StringsaveLayersToJSON-jsonlayers = vfbLayers.saveLayersToJSON()Save all layers to a string containing the information in a JSON format
BooleanloadLayersFromJSONJSON

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
BooleantransferLightMixToScene-vfbLayers.transferLightMixToScene()Transfers LightMix corrections to the actual lights in the scene


Lens Effects

ParameterDescriptionArguments

#glareversion

Return the version of the lens effects 

#glare

Turn lens effects On/OffBoolean

#glaresize

Sets Glare Size valueFloat

#glarebloom

Sets Bloom valueFloat

#glareintensity

Sets intensity value for the glare effectFloat

#glarethreshold

Sets a Threshold valueFloat

#glarefilterrot

Sets Rotation of the final result effectFloat

#glarecoldwarm

Turns on/off Cold/WarmBoolean

#glareblades

Enables/disables BladesBoolean

#glaresides

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

#glarebladesrot

Sets Glare Blades rotationFloat

#glarestreakblur

Sets Streak Blur valueFloat

#glaresaturation

Sets Saturation valueFloat

#glarehwdacc

Turns on/off Hardware accelerateBoolean

#glareinteractive

Turns on/off InteractiveBoolean

#glaregrating

Turns on/off Peripheral GratingBoolean

#glaregratingstrength

Sets Strength value of the blades effectsFloat

#glaregratingdensity

Sets Density of the grating effect in percentFloat

#glaregratingzoom

Sets Zoom valueFloat

#glaregratingslope

Sets Slope valueFloat

#glaregratinglength

Sets Length for the of the grate linesFloat

#glareocc

Turns on/off OcclusionBoolean

#glareoccsymmetric

Turns on/off SymetricBoolean

#glareoccpercent

Sets occlusion Percent valueFloat

#glareoccrot

Sets occlusion Rotation valueFloat

#glareoccarc

Sets occlusion Arc valueFloat

#glarescr

Turns on/off Lens ScratchesBoolean

#glarescrsymmetric

Turns on/off Symmetric for scratchesBoolean

#glarescrpattern

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

#glarescrstreaks

Sets lens scratches Streaks valueInteger

#glarescrseed

Sets Seed valueInteger

#glarescrdensity

Sets lens scratches Density valueFloat

#glarescrlength

Sets lens scratches Length valueFloat

#glarescrslopevar

Sets lens scratches Slope Variance valueFloat

#glarescrwidthvar

Sets lens scratches Width Variance valueFloat

#glarescrzoom

Sets lens scratches Zoom valueFloat

#glarescrrot

Sets lens scratches Rotation valueFloat

#glarescrstrength

Sets lens scratches Strength valueFloat

#glaredust

Turns on/off Lens DustBoolean

#glaredustpattern

0 - random
1 - square
2 - hexagonal

0 | 1 | 2

#glaredustdensity

Sets lens dust Density valueFloat

#glaredustradvar

Sets lens dust Radius Variance valueFloat

#glaredustjitter

Sets lens dust Jitter valueFloat

#glaredustzoom

Sets lens dust Zoom valueFloat

#glaredustrot

Sets lens dust Rotation valueFloat

#glareduststrength

Sets lens dust Strength valueFloat

#glareobstacle

Enables/disables Use Obstacle imageBoolean

#glareobstacleimage

Sets Path to the obstacle imagePath String

#glareobstaclezoom

Sets Size of the obstacle imageFloat

#glareobstaclerot

Sets Rotation for the obstacle imageFloat

#glareobstaclestrength

Sets Strength value for the obstacle imageFloat

#glarefilter

Turns on/off Filter ImageBoolean

#glarefilterimage

Specifies path to a filter kernelPath String

 

Stamps

ParameterDescriptionValue OptionsExamples
#stampEnables/disables the stampBooleanvfbControl #stamp true
#stamphalignSets horizontal alignment for stamp"left" | "center" | "right" 
#stampvalignSets vertical alignment for stamp"top" | "bottom" 
#stamptextSets the text string to appear on the stampStringvfbControl #stamptext "Test rendering"


Toolbar

ParameterDescriptionArgumentsExamples
#helpDisplays options for the vfbControl commandNone 
#showOpens (true) or closes (false) the VFB window or returns its current display state if called without a valueBoolean 

#red
#green
#blue
#alpha
#mono

Enables/disables the corresponding VFB toolbar featureBooleanvfbControl #alpha true
#trackmouseEnables/disables the Track mouse while rendering featureBoolean 
#setcompareabEnables/disables Compare horizontal and Compare vertical features

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

vfbControl #setcompareab "h"
#loadimageLoads the specified image in VFBString (filename) 
#saveimageSaves the VFB current channel as an imageString (filename) 
#saveallimageSaves all VFB render channels to separate images or a single .vrimg fileString (filename) 
#savemultiimageSaves a multichannel .exr or .vrimg file with all VFB render channels insideString (filename)vfbcontrol #savemultiimage "D:\output\image.exr"
#clearimageClears the VFB imageNone 
#duplicateDuplicates the VFBNone 
#hideHides the VFBNone 
#getchannelReturns the index of the currently selected render element channel.None 
#getchannelnamesReturns a list of the channels available in the current imageNone 
#setchannelSelects the render element channel with an indexIntegervfbControl #setchannel 0
#setregionSets the render region in pixels, or resets to entire imageIntegers: left top right bottom
"reset"
vfbControl #setregion 0 0 640 480
vfbControl #setregion "reset"
#clamp

Enables/disables Force color clamping

BooleanvfbControl #clamp true
#viewclampEnables/disables View clamped colors Boolean 
#pixelaspectEnables/disables Use pixel aspectBoolean 
#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"
#testresolutionEnables/disables the Test resolution scale.Booleanvfbcontrol #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 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 iReturn 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 iReturns the alias for the i-th channel. Indexes start from 1.
vrayVFBGetChannelBitmap iReturns 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 NameDescription
VRAY_VFB_SRGBTurn On (1) or Off (2) sRGB option of VFB by default.
VRAY_VFB_PIXEL_ASPECTTurn On (1) or Off (2) Use pixel aspect option of VFB by default.
VRAY_VFB_GLOBAL_PRESET_FILE_USEEnable (1) or Disable (0) automatic loading of a global .vccglb preset for the VFB.
VRAY_VFB_GLOBAL_PRESET_FILESpecify default .vccglb filename (string) to be used when loading automatic global preset.
VRAY_VFB_ICCEnable (1) or Disable (2) the ICC correction in VFB by default.
VRAY_VFB_ICC_FILESpecify default ICC correction file for VFB. It will be automatically loaded when ICC is enabled.
VRAY_VFB_OCIOEnable (1) or Disable (2) the OCIO correction in VFB by default.
VRAY_VFB_OCIO_INPUT_COLORSPACESpecify default input OCIO color space. A default OCIO configuration can be specified by the OCIO environment variable.
VRAY_VFB_OCIO_DISPLAY_DEVICESpecify default OCIO display device. A default OCIO configuration can be specified by the OCIO environment variable.
VRAY_VFB_OCIO_VIEW_TRANSFORMSpecify default OCIO view transform. A default OCIO configuration can be specified by the OCIO environment variable.
VRAY_VFB_LUTEnable (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_AFFECT_SWATCHESApply 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_TOPSpecify a ALWAYS ON TOP behavior:
0 - disabled
1 - force enable always on top
2 - force disable always on top