Controlling the Renderer

The render() method invokes the current 3ds Max renderer.

Other than calling the max quick render command which is equivalent to clicking the Render icon in the Main Toolbar, the render() method can take many optional parameters to control the rendering independently from the current Render Scene Dialog settings.

Note: As mentioned above, the render() method does NOT use the current render settings found in the Render Scene Dialog. Thus, calling render() will NOT save to the output file name specified in the Render Scene Dialog or via the rendOutputFilename global, but will use the output specified via the outputfile: optional parameter and/or simply return a bitmap value.

Below is the list of optional parameters that can be used to control the rendering using the render() method.

Optional Parameters:

render [camera: <camera_node> ]

Specifies the camera to render. If not specified, defaults to the active viewport.

[ frame: <number> | #current]

Specifies the frame to render. If not specified or set to #current , defaults to rendering the current frame.

[ framerange: <interval> | #active]
[ fromframe: <time> ]
[ toframe: <time> ]
[ nthframe: <time> ]

Specifies the frame range to render. If specified, one render() call will generate multiple frames. If not supplied, only one frame will be rendered.

Defaults to unsupplied , in which case the frame: value described above controls which frame to render.

For Example:

render framerange:(interval 0 30)

Starting with 3ds Max 5, the parameters frame: , fromframe: and toframe: accept time values instead of numbers. Setting them to float values allows for sub-frame rendering!

[ outputwidth: <number> ]

Sets the width of the output image.

Defaults to the current render width specified in the Render Scene Dialog.

[ outputheight: <number> ]

Sets the height of the output image.

Defaults to current render height specified in the Render Scene Dialog.

[ outputSize: <point2> ]

An alternative way to specify the output size of the rendered image.

The point2 value is in the form: [width,height]

[ pixelaspect: <number> ]

Specifies the pixel aspect ratio.

If not supplied, defaults to 1.0.

[ renderhiddenobjects: <boolean> ]

When supplied as true, hidden objects will be rendered.

When supplied as false, hidden objects will not be rendered.

If not supplied, defaults to the current renderer's Render Hidden Objects state.

[ rendSimplifyAreaLights: <boolean> ]

When supplied as true, lets the renderer simplify area lights by rendering them as point lights when appropriate.

When supplied as false, the renderer will process area lights completely.

When not supplied, the state of the "Area Lights/Shadows as Points" checkbox in the Render Scene Dialog controlled by the global variable rendSimplifyAreaLights will be used.

[ superblack: <boolean> ]

Defaults to current renderer's "Superblack" checkbox state.

[ force2sided: <boolean> ]

Defaults to current renderer Force 2 Sided state.

[ renderatmosphericeffects: <boolean> ]

Defaults to current renderer Render Atmospheric Effects state.

[ renderfields: <boolean> ]

Defaults to current renderer Render Fields state.

[ fieldorder: #odd | #even]

Defaults to current renderer preferences Field Order state.

[ outputfile: <string> ]

The frame number is appended to the filename if the file image type is a single image type (.bmp, .jpg, .tga, etc.), and a frame range is being rendered. Defaults to rendering to just the virtual frame buffer.

[ vfb: <boolean> ]

When set to true, opens a Rendered Frame Window to display the rendered image. When set to false, the rendered image will not be displayed.

Defaults to current renderer Rendered Frame Window state.

*HISTORY Note: *

In versions prior 3ds Max 6, the "Rendered Frame Window" was known as the "Virtual Frame Buffer" (thus abbreviated as VFB and not RFW).

[ pos: #vfb_upper_left | #vfb_lower_left | #vfb_upper_right | #vfb_lower_right | #vfb_center | #vfb_renderer_position | #vfb_vprimary_position | #vfb_vsecondary_position]

Lets you specify the screen position the Rendered Frame Window (a.k.a. Virtual Frame Buffer - see note above) will open at when the vfb: option is supplied as true .

Default is #vfb_renderer_position , which is the last position the user left the window after a render.

Available in 3ds Max 2009 and higher.

[ outputHDRbitmap:<boolean> ]

When set to true, the new 32 bit floating-point frame buffer will be used. When set to false or not supplied, the standard frame buffer will be used. Available in 3ds Max 8 and higher.

[ netrender: <boolean> ]

Submits the render to Backburner for network rendering.

Defaults to current renderer Net Render state.

[ renderType: #normal | #region | #regionCrop | #blowup | #selection | #regionselected | #cropselected | #bakeSelected]
[ region: #(left,top,right,bottom) ]

Provides control over the type of rendering, corresponding to the Render Type menu in the 3ds Max toolbar.

If #region , #regionCrop or #blowUp is selected, the region: parameter may be used to override the currently set regions for the active viewport, specified as pixel coordinates relative to the top-left corner in the bitmap (VFB). The region argument is ignored for all other render types. The region argument can be a Box2 value.

If the rendertype is #blowup , and a region is specified, the region rectangle must have the same aspect as the render output size aspect. The top, bottom, and left component values are taken from the region argument, but the width is re-calculated to force the proper aspect.

Note: #region`, `#regionCrop and #blowUp can only be selected for an active viewport rendering. An error will be reported if they are specified for a camera rendering. Defaults to #normal .

Here is a full list of the supported types, their aliases and the UI types they correspond to:

#view, #normal - correspond to View

#selection, #selected - correspond to Selected

#region - corresponds to Region

#regionCrop, #crop - correspond to Crop

#blowUp - corresponds to Blowup

#regionselected - corresponds to Region Selected

#cropselected - corresponds to Crop Selected

Note: Render type #boxselected , which corresponds to Box Selected, is currently not supported.

The #bakeSelected rendertype is used by the Render To Texture toolset to invoke the renderer after defining one or more BakeElements and preparing objects for baking. Please see the source code of the Render To Texture script for an example of its usage.

[ to: <bitmap> ]

Specifies an existing bitmap to render into. The render() function takes image size and other parameter settings from the existing bitmap. If not supplied, a new bitmap is created and returned by the render() function.

[ channels: <array_of_channel_names> ]

Specifies which g-buffer channels should be created during the rendering.

EXAMPLE

bm = render camera:$cam2 channels:#(#zDepth, #coverage, #objectID)

causes $cam2 to be rendered into a new bitmap that will contain z-depth, pixel coverage and object g-buffer ID channels

The channels: argument must always be an array of channels identifiers, chosen from the following:

#zDepth
#matID
#objectID
#UVCoords
#normal
#unClamped
#coverage
#node
#mask
#shaderColor
#shaderTransparency
#velocity
#weight

Defaults to no g-buffer channels.

[ aperture: <float> ]

Defaults to current renderer Aperture Width value.

[ ditherTrueColor: <boolean> ]

Defaults to current rendering preferences Dither True Color state.

[ ditherPaletted: <boolean> ]

Defaults to current rendering preferences Dither Paletted state.

[ videocolorcheck: <boolean> ]

Defaults to current renderer Video Color Check state.

[ renderPAL: <boolean> ]

Defaults to current rendering preferences Video Color Check NTSC/PAL state. If true , and video color checking is enabled, PAL video color checking is performed.

[ superBlackThreshold: <integer> ]

Defaults to current rendering preferences Super Black Threshold value.

[ maxPixelSize: <float> ]

This property is available in the Render Scene dialog and is also accessible through the RadiosityPreferences interface.

[ useRadiosity: <boolean> ]

This property is available in the Render Scene dialog and is also accessible through the RadiosityPreferences interface.

[ ComputeRadiosity: <boolean> ]

This propertyisavailable in the Render Scene dialog and is also accessible through the RadiosityPreferences interface.

[ cancelled: <&var> ]

If the render is cancelled, the variable var will contain true, otherwise it will contain false.

FOR EXAMPLE

bm = render cancelled:&wasCancelled
if (not wasCancelled) do....

[ progressbar: <boolean> ]

If true, the entire viewport display is disabled and a progress bar and Cancel button are displayed in the status panel. If false or not present, the viewport display is not disabled. In both cases, Esc will cancel the render.

[ renderMultiPassEffects:<boolean> ]

If true or not specified, if the view being rendered is a camera view, and a multipass effect is enabled for that camera, the rendering will be performed using that multipass effect. If explicitly supplied as false, no multipass effect will be rendered. Available in 3ds Max 8 and higher.

[ renderElements:<boolean> ]

If true or not specified, if render elements are present in the scene, those render elements will be rendered. If the outputfile: argument is specified, the render element output will be written to disk in the same manner as if rendered from the Render Scene dialog with the Render Output filename specified. If false, render elements will not be rendered. Available in 3ds Max 8 and higher.

[ renderElementBitmaps:<&var> ]

If render elements are rendered, the render element output bitmaps are placed in an array (one array element per rendered render element), and this array is returned through the specified variable by-reference. If multiple frames are rendered, the final frame's output is used. Available in 3ds Max 8 and higher.

FOR EXAMPLE

render renderMultiPassEffects:true renderElements:true renderElementBitmaps:&reb
if reb != undefined do for b in reb do display b

The following properties are available if the standard scanline renderer is being used:

[ antiAliasing: <boolean> ]

Defaults to current renderer Anti-Aliasing state.

[ antiAliasFilterSize: <float> ]

Defaults to current renderer Anti-Aliasing Filter Size value.

[ antiAliasFilter: <filter> ]

Defaults to current renderer Anti-Aliasing filter.

[ enablePixelSampler: <boolean> ]

Defaults to the current renderer Global SuperSampling state. This state is true if Disable all Samplers is checked, otherwise false .

[ mapping: <boolean> ]

Defaults to current renderer Mapping state.

[ shadows: <boolean> ]

Defaults to current renderer Shadows state.

[ autoReflect: <boolean> ]

Defaults to current renderer Auto-Reflect/Refract and Mirrors state.

[ forceWireframe: <boolean> ]

Defaults to current renderer Force Wireframe state.

[ wireThickness: <float> ]

Defaults to 1.0.

[ filterMaps: <boolean> ]

Defaults to current renderer Anti-Aliasing Filter Maps state.

[ objectMotionBlur: <boolean> ]

Defaults to current renderer Object Motion Blur Apply state.

[ objectBlurDuration: <float> ]

Defaults to 0.5.

[ objectBlurSamples: <integer> ]

Defaults to 10.

[ objectBlurSubdivisions: <integer> ]

Defaults to 10.

[ imageMotionBlur: <boolean> ]

Defaults to current renderer Image Motion Blur Apply state.

[ imageBlurDuration: <float> ]

Defaults to 0.5.

[ autoReflectLevels: <integer> ]

Defaults to 1.

Note: Since 3ds Max 5, the render() method passes any keyword arguments on to the renderer class instance, so any renderer parameter block or FPS interface property can be set via the keyword argument. This behavior replaces the hardcoded keyword arguments documented in the above topic. The default scanline renderer FPS interface properties were named to maintain consistency with existing scripts.

Quiet Mode Options:

[ quiet: <boolean> ]

If true , suppress participating dialogs.

[ missingExtFilesAction: <actions> ]

Actions to take on Missing External Files, where <actions> is: #logmsg , #logToFile , #abort and/or an integer, or an array of one or more of those items.

[ missingExtFilesList: &variable ]

If #logmsg is specified as action, the by-reference variable will be filled in with array of the missing external file names.

[ missingUVWAction: <actions> ]

Actions to take on Missing UVWs, where <actions> is: #logmsg , #logToFile , #abort and/or an integer, or an array of one or more of those items.

[ missingUVWList: &variable ]

If #logmsg is specified as action, the by-reference variable will be filled in with array of strings containing the missing map channel and node name.

[ unsupportedRenderEffectAction: <actions> ]

Actions to take on Unsupported Render Effects, where <actions> is: #logmsg, #logToFile, #abort, #default and/or an integer, or an array of one or more of those items. Available in 3ds Max 8 and higher.

[ unsupportedRenderEffectList: &variable ]

If #logmsg is specified as action, the by-reference variable will be filled in with array of the unsupported render effect names. Available in 3ds Max 8 and higher.

See Quiet Mode for details.

Note: The render() function is interruptible mid-frame using the Esc key.

Renderer Output

You can invoke the renderer and have it do one or more of four things with the rendered output:

Display it in a virtual frame buffer (the default), controlled with the vfb: parameter.
Store the rendering in an image file by supplying an outputfile: parameter. The type of image file to be created is determined from the file suffix you specify.
Return the result as a MAXScript Bitmap value that you can perform Bitmap operations on (see the Bitmap Values topic).
Store the rendering in an existing MAXScript Bitmap value by supplying the to: parameter. Supplying this parameter causes settings such as height, width, aspect, gamma, file name, etc. to be taken from the supplied bitmap.

EXAMPLES

render camera:$cam01 outputwidth:320 outputheight:240

for c in cameras do
render c outputFile:(c.name + ".bmp") vfb:off

rollout1.image.bitmap = render camera:$cam01

Memory Management Considerations

When calling render() inside a loop without assigning the output to an explicit MAXScript Bitmap Value, each call will create a bitmap value which will be kept around until a Garbage Collection is triggered either automatically or manually. Since the MAXScript Heap will store very little data (the pointer to the C++ bitmap data), chances are the automatic garbage collection won't be triggered before the end of the loop.

To avoid memory problems in this case, the resulting bitmap can be assigned to an explicit MAXScript variable, allowing the manual release of the memory using the close() method.

Alternatively, an empty MAXScript Bitmap Value can be initialized before the loop starts, and the to: keyword can be used to output the render() result to it. The same bitmap value will be reused in each loop iteration.