You are on page 1of 16

iray EDUCATIONAL

IRAY STRING OPTIONS FOR AUTODESK 3DS MAX AND 3DS MAX DESIGN
APRIL 2011

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

CONTENTS
CONTENTS INTRODUCTION HOW TO SET STRING OPTIONS IN 3DS MAX AND 3DS MAX DESIGN 2 3 4

Creating a MAXscript file .............................................................................................................. 4 Using the MAXscript file ................................................................................................................ 5 Step 1 ............................................................................................................................... 5 Step 2 .............................................................................................................................. 5 STRING OPTIONS 6

Device Management ...................................................................................................................... 6 Rendering Devices ........................................................................................................... 6 Interactivity / Performance.............................................................................................. 7 Rendering Control ......................................................................................................................... 8 Environment Lighting Control ........................................................................................ 8 Path Length ...................................................................................................................... 9 Background Color Override ............................................................................................ 10 Framebuffer ................................................................................................................... 10 Progressive Mode .......................................................................................................... 11 Shadow catcher ground plane / environment dome .................................................................. 12 Important Note .............................................................................................................. 12 Environment Dome ........................................................................................................ 12 Shadow/Reflection catcher ground plane ..................................................................... 13 MORE INFORMATION 16

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 2

INTRODUCTION
iray is designed to be a push-button photorealistic rendering solution. By simulating the behavior of light in a physically accurate manner, many of the algorithms such as final gather, ambient occlusion and photon mapping, which characterize the relative complexity of global illumination control decks in mainstream production renderers, are not used by iray. As a result, iray's control interface is extremely simple and intuitive, allowing the user to focus on her work rather than spending time adjusting the rendering settings. However, iray still offers the possibility of customizing its behavior, beyond the settings exposed in the graphical user interface. In this booklet, you will learn how to access iray's advanced settings and features by using its string options.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 3

HOW TO SET STRING OPTIONS IN 3DS MAX AND 3DS MAX DESIGN
String options can be set using a few simple MAXscript calls. In this section, we will see how to create a pre-render step which customizes iray's behavior, by using the string options explained in the following pages.

CREATING A MAXSCRIPT FILE


We will now create a MAXscript file that contains the necessary instructions to set our string options. By doing so, it will be possible to reuse the script with several scenes.

Select "MAXScript" from the main menu bar, then choose "New Script". The MAXScript editor will open. We can now proceed to write the code that will set our string options.

iray string options are found in the same structure where mental ray stores its own options. This is because iray is actually part of the mental ray component, although iray is a distinct rendering engine. The options structure can be retrieved, both for reading and writing, with the following: m = mental_ray_string_options Once this is done, the variable "m" references mental ray's options structure, and we can begin to add or modify options in it. The safest way of setting up the options structure is to clean it up every time the script is executed, to avoid eventual unwanted behavior. Resetting the options structure can be done with the following code: for i = 1 to m.numOptions do m.removeOption 0 After the last command, the options structure is completely empty and we can begin to add our options. For example: m.addOption "iray threads" 0 m.addOption "iray devices" "0 1"

Finally, save the script on disk.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 4

USING THE MAXSCRIPT FILE


Our script performs the following actions: 1. 2. 3. Fetch the mental ray's options structure Clean it Populate it with iray-related options

The next step would be to instruct 3ds Max to run the sequence every time the current scene is being rendered. STEP 1 Select "Rendering" from the main menu bar, then choose "Render Setup...". The Render Setup dialog box will open.

STEP 2 Within the "Common" tab, scroll down and open the "Scripts" folder by clicking on it. Click on the "File..." button within the "PreRender" group, and select the MAXscript file that you have just saved. The process is now complete. The string options will be set every time a rendering is performed.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 5

STRING OPTIONS
DEVICE MANAGEMENT
iray is capable of using both CPU cores and CUDA devices at the same time to maximize performance. By default, iray will try to use all CPUs and all CUDA devices present in the system.

RENDERING DEVICES "iray devices" <string devices> With this option, it is possible to control which CUDA devices can be used by iray. Parameters: devices - Specifies the IDs of the CUDA devices to be used by iray, separated by a space. In order to identify the CUDA devices IDs, it is recommended to enable the render log messages (Customize -> Preferences... -> Rendering -> Messages "Show / Log Information Messages"), then open the rendering messages window (Rendering -> Render Message Window...) and finally launch a render, which can be canceled after a few passes; at this point, the render message window will contain several statements: search for the CUDA device lines like the following one: IRAY 0.7 info : CUDA device 0: "Quadro 5000" (compute capability 2.0, 2523MB total, 2313MB available) In the example above, the system has one CUDA device with ID = 0. Examples: m.addOption "iray devices" "0 1 4" Will use CUDA devices 0, 1, and 4. m.addOption "iray devices" "" Will disable all CUDA devices.

"iray threads" <int threads> This option specifies the number of CPU cores to be used by iray for rendering (in addition to the CUDA devices). By default, not all cores are fully utilized if using CUDA devices as well, because the resulting latencies can cause an overall performance drop. Parameters: threads - Number of CPU cores to be used by iray. Examples: m.addOption "iray threads" 4 Will use 4 CPU cores to aid rendering computations.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 6

m.addOption "iray threads" 0 Will disable the use of CPUs. This situation is recommended when using multiple high-end GPUs, as the CPUs would slow them down. INTERACTIVITY / PERFORMANCE "iray min frame time" <float time> iray achieves its maximum performance on CUDA devices when the amount of samples to be processed is high enough. If the output image's resolution is low, the resulting workload might not be enough to achieve maximum performance. This particular situation can happen when multiple CUDA devices are used. The resulting performance drop due to insufficient workload can be as high as 90%. For this reason, iray will try to optimally distribute the workload on the available GPUs. While this yields better device utilization and parallelization, there are cases where this might be undesirable, especially when the CUDA device used for rendering is also the computer's primary display device: in such situation, it is possible to experience degraded system responsiveness or even driver timeouts. In order to overcome such eventual side effects, this option can be used to specify the minimum time a CUDA device should render in one call. If the device is spending less than this time in one render call, the number of samples per iteration will be increased. Parameters: time - the minimum time a CUDA device should render in one call, in seconds. The default value is 1.0, which means that iray will increase the workload until one render call executes in one second. The effects of values smaller than 1.0 should be carefully tested on long running renderings, since they can yield performance drops of 90% or even more. Example: m.addOption "iray min frame time" 1.2 "iray max cuda fragment size" <int size> By default, iray tries to work around driver timeout/interactivity problems by using fragments smaller than the overall resolution. The initial default was chosen so that early CUDA 1.0 devices can still render complex scenes without running into driver timeout/interactivity problems. These small fragments are then rebalanced over time until the frame time matches the one specified by "iray min frame time" to gain more total rendering performance for faster CUDA devices. It might still be possible though that a scene is too complex and/or the CUDA device is so slow so that the rendering of the first frame fails. With this option, it is possible to enforce a fragment size that will not be modified over the course of time. Parameters: size - maximum number of pixels that are computed at once on one CUDA device. The default is 64*1024. The effects of values smaller than 64*1024 should be carefully tested on long running renderings, since they can yield performance drops of 90% or even more. Example: m.addOption "iray max cuda fragment size" 65560

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 7

RENDERING CONTROL
ENVIRONMENT LIGHTING CONTROL iray uses mental ray built-in functionality for most its environment lighting (IBL) preprocessing.

"environment lighting resolution" <int resolution> This option specifies the resolution of the baked environment used for Image Based Lighting. Higher resolutions result in higher construction times and increase memory requirements. Lower resolutions will result in washed-out shadows and highlights if the environment shader has strong hot spots. Parameters: resolution - Resolution of the of the baked environment. The default value is 1024. Examples: m.addOption "environment lighting resolution" 512 m.addOption "environment lighting resolution" 256

resolution = 128

resolution = 256

resolution = 512

resolution = 1024

resolution = 2048

resolution = 4096

"environment lighting shader samples" <int samples> This option specifies the number of samples to take per measurement during preprocessing. If "environment lighting resolution" is very low, the samples can be increased to avoid dropping too much lighting information due to insufficient resolution. Higher sample counts will extend preprocessing time. Parameters: samples - Number of samples. The default value is 2. Examples: m.addOption "environment lighting shader samples" 4 Will use four samples per measurement during the environment lighting preprocessing m.addOption "environment lighting shader samples" 1 Will use one sample per measurement during the environment lighting preprocessing

"environment lighting blur" <bool blur>

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 8

This option allows to blur the environment, particularly useful when using low resolution environments, which tend to look pixelated otherwise, and the result of such pixelation can be evident in the lighting/shading of objects in the scene (especially when there are few bright spots in the environment). Parameters: blur - Set to On to activate blur (3x3 Gauss). Set to Off to disable blur. Example: m.addOption "environment lighting blur" on

without blur

with blur

PATH LENGTH "iray max path length" <int length> iray does not use the traditional trace-depth parameters of mental ray, but has a more consistent option to limit the maximum length that a light transport path is allowed to have. Parameters: length - Maximum depth of light transport paths, unlimited by default. Examples: m.addOption "iray max path length" 1 Only light sources will be visible. m.addOption "iray max path length" 2 Light sources and direct lighting will be visible. m.addOption "iray max path length" 3 Light sources, direct lighting and one indirect bounce will be visible.

max path length = 1

max path length = 2

max path length = 3

max path length = 4

max path length = 5

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 9

BACKGROUND COLOR OVERRIDE "iray background color" <float r, float g, float b> This option replaces the environment map color with the given RGB color (for primary rays only). The final framebuffer exposes an alpha estimate which is based on separating paths that end in infinity/environment and ones that end on scene geometry. Setting the optional environment background color, will force iray into a secondary alpha mode, where all objects will deliver an opaque alpha value. Primary rays hitting the environment will depend on the shadow value of the (optional) ground plane. This mode is suited to replace the environment in a postprocess with a new environment/background-photo. Parameters: [r, g, b] - A color to replace the environment. Example: m.addOption "iray background color" [0.0, 1.0, 0.0] Replaces the environment map color with a bright green (for primary rays only).

regular rendering

with background color = [0, 1, 0]

FRAMEBUFFER "filter" <string type> <float size_x, float size_y> This options controls iray's filter. Filters do not impact rendering performance. Parameters: type - Can be one of the following: "box", "gauss", "triangle" [size_x, size_y] - The filter's diameter is calculated by averaging size_x and size_y. The recommended default value is "gauss" [3, 3]. Examples: m.addOption "filter" "box" [2.0, 2.0] Sets the filter to box with size x=2 and y=2. m.addOption "filter" "gauss" [3.0, 3.0] Sets the filter to gauss with size x=3 and y=3.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 10

PROGRESSIVE MODE "progressive error threshold" <float threshold> This option instructs iray to stop rendering when the variance of the pixels falls below the given threshold. Parameters: threshold - The threshold value ranges from 0 to 1. The default value for this option is 0.15. Example: m.addOption "progressive error threshold" 0.3 Stops the rendering process when two subsequent frames have an error threshold of 0.3. "progressive max time" <float time> This option instructs iray to stop rendering after the given time has elapsed. Parameters: time - Specifies, in seconds, how long iray will render a frame. Example: m.addOption "progressive max time" 60.0 Stops the rendering process after one minute.

"progressive max samples" <float samples> This option instructs iray to stop rendering after a given amount of sampling iterations. Parameters: samples - The amount of sampling iterations to be rendered. Example: m.addOption "progressive max samples" 500 Stops the rendering process after 500 sampling iterations.

"progressive min samples" <float samples> This option prevents iray from terminating the rendering process to early, for example when the option "progressive error threshold" is used there might be false positives during the computation of the very first frames. Parameters: samples - The minimum number of sampling iterations that must be computed before evaluating the termination condition. Example: m.addOption "progressive in samples" 50 iray will not stop rendering until at least 50 sampling iterations have been completed.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 11

SHADOW CATCHER GROUND PLANE / ENVIRONMENT DOME


IMPORTANT NOTE Some of the following options may introduce inconsistencies in the rendering process (i.e. a bias resulting in more or less dramatic artifacts).

ENVIRONMENT DOME iray features the ability to fake a geometric environment dome instead of the infinite environment provided by the environment shader. Note that the illumination is still computed from the original infinite environment, thus artifacts can occur when position, radius or dome mode are changed. "environment dome position" <float x, float y, float z> This option sets the center of the environment dome. Parameters: [x, y, z] - Location of the dome's center. By default, the dome is positioned at [0, 0, 0]. Example: m.addOption "environment dome position" [0.0, 0.0, -100.0] Sets the position of the dome at x=0, y=0, z=-100. "environment dome rotation axis" <float x, float y, float z> This option sets the dome's rotation axis, which coincides with the dome's and plane's up-vector. The given value is expected to be in the form [x, y, z] and describes Parameters: [x, y, z] - A normal vector specifying the dome's up-vector and rotation axis. The default value is [0, 1, 0]. Example: m.addOption "environment dome rotation axis" [0.0, 0.0, 1.0] Sets the dome's up-vector and rotation axis to at x=0, y=0, z=1, which is consistent with 3ds Max's coordinate system. "environment dome rotation angle" <float angle> This option sets the dome's rotation angle. Parameters: angle - The rotation angle, which ranges between 0 and 1. When 0, there will be no rotation. When 1, there will be a full revolution around the rotation axis (2*PI). By default, the dome's rotation is 0.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 12

Examples: m.addOption "environment dome rotation angle" 0.5 Rotates the dome of 180 degrees around its rotation axis. m.addOption "environment dome rotation angle" 0.25 Rotates the dome of 90 degrees around its rotation axis. "environment dome radius" <float radius> This option sets the radius of the environment dome sphere (and the optional ground to be able to do the texture projection). Parameters: radius - The radius of the environment dome sphere, in raw units. By default, the dome's radius is 100. Example: m.addOption "environment dome radius" 1500 Sets the dome radius to 1500. "environment dome mode" <string mode> This option sets the environment dome mode. Parameters: mode - Can be one of the following options: Example: "infinite" Standard infinite environment lookup. This is the default setting. "sphere" Sphere-shaped dome. "hemisphere" Sphere-shaped dome where the lower hemisphere is projected on the plane dividing upper and lower hemisphere. "ground" Infinite environment with a textured ground as in hemisphere mode.

m.addOption "environment dome mode" "sphere" Sets the dome mode to "sphere".

SHADOW/REFLECTION CATCHER GROUND PLANE When the dome mode is enabled, an additional "shadow catcher" ground plane can be specified. The shadow catcher is a transparent plane that weights the environment lookup using a progressive estimation of the amount of shadow that it receives from the objects in the scene (for all direct light coming from the environment alone). Note that the illumination is still computed from the original infinite environment, thus artifacts can occur if any of the following parameters is changed.

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 13

"environment dome ground" <bool ground> This option enables or disables the shadow catcher plane. By default, the shadow catcher plane is disabled. Parameters: ground - Set to On to activate the shadow catcher plane. Set to Off to disable it. Example: m.addOption "environment dome ground" on Enables the shadow catcher plane. "environment dome ground reflectivity" <float r, float g, float b> This option sets the reflectivity of the ground plane. If not used, or if at least one of the values are lesser than zero, reflectivity will be turned off. Parameters: [r, g, b] - The RGB factors for reflectivity. Examples: m.addOption "environment dome ground reflectivity" [0.0, 0.0, 0.0] With [R=0, G=0, B=0], there will be subtle diffuse reflections on the ground. m.addOption "environment dome ground reflectivity" [1.0, 1.0, 1.0] With [R=1, G=1, B=1], there will be strong diffuse reflections on the ground. m.addOption "environment dome ground reflectivity" [-1.0, -1.0, -1.0] With [R=-1, G=-1, B=-1], there will be no reflections on the ground. "environment dome ground glossiness" <float glossiness> If ground reflections were enabled, this option sets the glossiness of the ground plane. Parameters: glossiness - Glossiness factor, ranges from zero to infinity. Example: m.addOption "environment dome ground glossiness" 0.8 "environment dome ground position" <float x, float y, float z> This option sets the position of the ground plane. By default, the ground plane is located at [0, 0, 0]. Parameters: [x, y, z] - Position of the ground plane's center. Example: m.addOption "environment dome ground position" [100.0, 100.0, -300.0]

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 14

"environment dome ground texturescale" <float scale> This option sets the scale factor of the ground plane texture. Parameters: scale - Scaling factor. If equal to or lesser than zero, a secondary projection mode will be enabled, where scale is interpreted as the height above the ground plane location, from where a spherical projection will be performed for all dome "geometry". Examples: m.addOption "environment dome ground texturescale" 0.5 m.addOption "environment dome ground texturescale" -50.0

The following MAXscript provides an example of a typical dome setup: m = mental_ray_string_options for i = 1 to m.numOptions do m.removeOption 0 m.addOption "environment dome ground" on m.addOption "environment dome rotation axis" [0,0,1] m.addOption "environment dome ground position" [0,0,0] m.addOption "environment dome radius" 20000.0 m.addOption "environment dome ground reflectivity" [0.2,0.2,0.2] m.addOption "environment dome mode" "sphere"

without environment dome

with environment dome and ground plane

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 15

MORE INFORMATION
For more tutorials, tips and hints www.irayrender.com

For technical questions

forum.mentalimages.com

To stay up to date

Twitter Autodesk Area

2011 NVIDIA | iray string options for Autodesk 3ds Max and 3ds Max Design

Page 16

You might also like