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

Implicit groundplane

An additional implicit "shadow catcher" groundplane can be specified. This plane weights the environment contribution of the ground using a progressive estimation of the amount of shadow on the groundplane, caused by the objects in the scene (from direct light only). The mode of the environment lookup itself remains unchanged as it is specified by the environment dome settings.

The groundplane is controlled with the following attributes on the mi::IOptions class, shown here with their default settings:

bool environment_dome_ground = false: Controls whether the implicit groundplane is enabled or not.
mi::Float32_3 environment_dome_ground_position = mi::Float32_3(0,0,0): The origin of the ground plane.
mi::Color environment_dome_ground_reflectivity = mi::Color(-1,-1,-1,1): If set to a positive value, enables reflectivity on the groundplane weighted by the fresnel term.
mi::Float32 environment_dome_ground_glossiness = 100000.0: Controls the glossiness of the ground reflectivity. Useful values range from 0 (diffuse) to 100000.0 (perfect mirror).
mi::Float32 environment_dome_ground_shadow_intensity = 1.0: Controls the intensity of the shadow on the groundplane with a value greater or equal to 0.0. A value of 0.0 denotes no shadow at all and a value of 1.0 denotes regular shadow intensity, thus values between 0.0 and 1.0 denote a lighter shadow. Values above 1.0 increase the shadow intensity. Note that the range of useful values above 1.0 is rather limited and exceeding this range may lead to an unnatural dark shadow that can influence other additive lighting effects, such as reflections of the objects in the scene. The exact useful range is scene dependent.
mi::Float32 environment_dome_ground_texturescale = 0: Used to control the texture projection of the environment on the ground. This can be seen as an equivalent to the distance from ground where the real life camera was placed to take the captured environment map.