Iray Programmer's Manual

Preface
Getting started
- Release overview
- Example programs
- How to compile a program
- How to run a program
- Starting and shutting down the Iray API
- A first image
Library design
- API modules
- Shared library
- Naming conventions
- Include files
- Include file compile-time configuration
- Main API access point
- Version numbers and compatibility
- Interfaces
- Reference counting
- Handle class
- Resources
- Strings
- Error handling
- Database, transactions and scopes
  - Transactions
  - Database scopes
- Runtime configuration
Rendering
- Rendering overview
- Rendering and canvases
- Render mode selection
- Progressive rendering of a scene
- Own canvas class
- Asynchronous rendering
- Multiple render contexts
Iray Photoreal
- Introduction
- System requirements
- Limitations
- Matte objects and matte lights
- Refractive objects and IOR handling
- Progressive rendering
- Caustic sampler
- Architectural sampler
- Light portals
- Rendering options
- Mixed mode rendering and load balancing
- Timeout prevention
- Integrated noise reduction
- Integrated bloom
Iray Interactive
- Introduction
- System requirements
- Limitations
- Progressive rendering
- Lighting
- Rendering options
- Path space filtering
- Output format
- Global performance settings
- Comparison with Iray Photoreal
Iray Realtime
- Introduction
- System requirements
- Limitations
- Rendering options
Iray Blend
- Introduction
- Rendering options
Scene database
- Overview of the scene database elements
- Creating a scene programmatically
Geometry
- Creating triangle meshes
- Creating polygon meshes
- Creating on-demand meshes
- Creating subdivision surfaces
- Creating freeform surfaces
Materials
- Material Definition Language
- Measured materials
- Editing and creating materials
Decals
Sources of light
- Emission distribution functions
- Light distribution from scene elements
Environment dome and implicit groundplane
- Environment function
- Environment dome
- Implicit groundplane
Camera
- Tonemapping
  - Photographic tonemapper
  - Custom tonemapper
- Depth of field
- Virtual backplate
- Motion blur
Physically plausible scene setup
- Recommendations for geometry preparation
- Recommendations for lights
  - Using photometric lights
  - Using environment and sunlight
- Recommendations for materials
- Recommendations for cameras
Networking
- Networking overview
- Networking modes
- Iray Bridge
Delivering an image from server-based rendering
- Running an HTTP server
- RTMP server
- RTMP client
- Running an RTMP and HTTP server with mouse interaction
Customization
- Extending the database with user-defined classes
- Extending neuray with plugins
- Extending supported file formats with plugins
Appendix
- Supported file formats and URI schemes
- Result canvas names
- Light path expression grammar
Bibliography

Environment function

The MDL environment function is controlled with the following attribute on the IOptions class:

mi::IRef environment_function

The environment function used for the lookup of the conventional infinite spherical environment, and also for the projections onto the different dome geometries. All MDL functions are supported whose return type is either color or base::texture_return. In the latter case, only the tint field is used and mono filed is ignored.

The following two MDL functions are natively supported in the render modes and allow fast updates on parameter changes, while all other MDL functions will be baked into a texture that is then used for environment lookups.

base::environment_spherical
base::sun_and_sky

Simple transformations on the environment function can be applied using two further attributes on the mi::IOptions class without triggering texture baking:

mi::Float32 environment_function_intensity = 1: A linear scale that is applied to the intensity returned by the environment function.
mi::Float32_3_3 environment_function_orientation = mi::Float32_3_3(1,0,0,0,1,0,0,0,1): This matrix defines the transform from canonical directions (used for the environment function evaluation) to world space. It can be used to freely rotate the environment. The matrix needs to be orthonormal.

A number of options allow fine-tuning the baking of environment functions to a texture. As before, these options are modeled as attributes on the mi::IOptions class.

mi::Sint32 environment_lighting_resolution = 512: This option controls the number of pixels used for the resolution of the polar angle. The azimuthal resolution is always twice the polar resolution. Higher resolutions result in more detail in the visible environment and sharper shadows if bright details of the environment function are small. However, baking times are increased accordingly.
bool environment_lighting_blur = false: The visual quality of low-resolution environments may sometimes be improved by enabling a small Gaussian filter kernel.