Iray Programmer's Manual

Render context options

There are a number of render context options that are available for all Iray Bridge render contexts. These render context options control various aspects of the video streaming and which server to connect to.

There are also some options that are only available to specific Iray Bridge render contexts.

Options are set by calling set_option() on one of the Iray Bridge render contexts and passing the name of the context as a string and an mi::IData instance of the correct type as a value.

Server configuration options

mi::IString bridge_address = ""

The address of the Iray Bridge application to connect to. Empty by default. If set this value will override the value configured by using the mi::bridge::IIray_bridge_client API component.

mi::IString bridge_security_token = ""

The security token to use when connecting to the Iray Bridge application. Empty by default. If set this value will override the value configured by using the mi::bridge::IIray_bridge_client API component.

Video streaming options

The video streaming options control various aspects of how video frames are transmitted from the server to the client. The default values are tuned to give good interactive performance with decent quality over a fairly modest Internet connection, but may need to be tuned to give better performance, or quality, or both, depending on the network performance and use case.

mi::IString video_mode = "streaming"

The mode to use for the video stream. Can be "streaming" (default), "synchronous" or "batch".

  • Streaming mode is optimized for interactive performance, but permits some lag.

  • Synchronous mode renders synchronously with the server.

  • Batch mode renders a single frame on request, similar to synchronous mode, but does not continue to render in the background. Batch mode always uses lossless compression and supports render targets with multiple canvases. These characteristics make batch mode ideal for compositing tasks that use, for example, light path expressions (LPEs).

mi::IString video_format = "h264"

The video stream format to use for the frames sent on the video stream from the server. Default is "h264", but this can be set to any image format supported by Iray, like jpg, png, exr, and so on.

Note:
  • The different image formats will affect the precision (floating point to 8-bit truncation, loss of alpha channel, and so on) of the resulting canvas on the client side and the lossy formats will also degrade quality. Most formats are very expensive to encode and decode and will use considerably more bandwidth than H.264.

  • Iray Bridge also supports the format "lossless" which performs a lossless compression of the original canvas without loosing any information.

This option is ignored if video_mode is set to "batch".

mi::IUint32 video_framerate = 15

Sets the maximum video frame rate. The server will not send out frames faster than the specified setting, but will allow the frame rate to drop if the server-side render loop is slower than the set frame rate. If H.264 is used as a video format, this setting will be used together with the bit rate to calculate the budget for video frames. Setting the frame rate to a needlessly high value might, therefore, degrade quality when using H.264.

This setting has no effect if video mode is set to "batch".

mi::IUint32 video_bitrate = 5000000

This bit rate decides, together with the frame rate, the budget for each frame.

Only used if the video format is set to "h264", in which case, the H.264 encoder will be configured to use this bit rate.

mi::IUint32 video_maxlag = 3

This setting controls the maximum number of frames the server will allow in transit at the same time before automatically reducing frame rate to avoid flooding the network with frames faster than they can be sent to the client. Note that only the video stream frame rate is affected, not convergence time, since the server will keep rendering iterations in the background. This value might need to be set higher than the default of 3 frames if the frame rate is increased, and also if network latency is very high.

Only used when video mode is set to "streaming".

mi::ISint32 nvcuvid_device = -1

The index of the device to use on the client for hardware H.264 decoding. If set to -1 (the default), a suitable device will be selected automatically.

Note:

  • Only NVIDIA GPUs that support hardware H.264 decoding can be used. The resolution limit depends on the GPU. Higher resolutions than the card supports will cause decoding to fail.

  • The GPU must not be in TCC (Tesla Compute Cluster) driver mode. H.264 hardware decoding does not work in this mode.

mi::IFloat32 idle_timeout = 1.0

The time in seconds for which the server side render loop will keep rendering in the background without any render requests coming from the client. Defaults to 1 second.

Photoreal Cloud render mode options

These options are specific to the "iray_cloud" render context:

mi::IString scheduler_mode = "interactive"

The scheduler mode used by the Iray renderer on the server side. Can be set to "interactive" or "batch". Should be set to "interactive" for interactive use cases and "batch" for final renderings. The batch scheduler mode is best used together with the video mode "batch". The interactive scheduler mode should be used with the "streaming" and "synchronous" video modes.

mi::IFloat32 batch_update_interval = 1e36

How often a progressive image update is rendered when in batch mode. Ignored when scheduler_mode is set to "interactive".

IQ Cloud render mode options

These options are specific to the "nitro_cloud" render context:

mi::IString scheduler_mode = "interactive"

The scheduler mode used by the IQ renderer on the server side. Can be set to "interactive", "streaming", or "batch". Should be set to "interactive" or "streaming" for interactive use cases and "batch" for final renderings.

The "batch" scheduler mode is best used together with the video mode "batch".

The "interactive" scheduler mode is best used with the "streaming" and "synchronous" video modes.

The "streaming" scheduler mode improves the frame rate by introducing a small lag which allows rendering to continue while the previous frame is composited. This means that, generally, the rendered frame does not contain the changes of the transaction used to render. The "streaming" scheduler mode is best used with the "streaming" video mode.

Note: Using the "streaming" scheduler mode with the "synchronous" or "batch" video modes voids the guarantee that the state of the rendered frame corresponds to the transaction used when calling render() on the client.
mi::IFloat32 batch_update_interval = 1e36

How often a progressive image update is rendered when in batch mode. Ignored when sheduler_mode is set to "interactive".

mi::IUint32 min_samples_per_update = 1

The minimum number of samples per update. Each frame will contain at least this many iterations. Defaults to 1.

mi::IUint32 max_samples_per_update = 0

The maximum number of samples per update. Each frame will contain at the most this many iterations. Defaults to 0, which means unlimited. The render context will automatically increase the number of iterations per frame over time when there are no changes to the scene to increase efficiency. Setting this to, for instance, 1 means that there will be one rendered frame per iteration. Setting this to 0 can mean that after rendering for a while, restarting interactive usage can take a long time.

Interactive Cloud render mode options

The render mode "irt_cloud" currently does not have any render mode specific options.