Iray Programmer's Manual

Rendering and canvases

Rendering is the operation of creating a 2D image from a 3D scene. The 3D scene is the data that is stored in the database.

For rendering, the scene data, in the form of a group node (the root group), needs to be combined with a camera instance and an options object into an IScene object. A camera instance and an options object are, for example, available in the mi::neuraylib::IImport_result object returned by scene imports.

Rendering then happens in two steps; first you select a render mode by creating a render context from the scene, and second you call one of the render methods on the render context. The relevant methods are:

Method signature Description 
IRender_context* IScene::get_render_context (
    ITransaction* transaction,
    const char* renderer )

Returns a render context suitable for rendering the scene with a given render mode. See Render mode selection for available render modes. 

int32 IRender_context::render (
    ITransaction* transaction,
    IRender_target_base* render_target_base,
    IProgress_callback* progress_callback)

Renders the scene associated with this render context to the given render target according to the passed in parameters using the render mode associated with the context.

It is necessary to commit the transaction after calling this method before making any changes in the scene database that should be taken into account in a future render call. To the contrary, if no scene changes are necessary and future render calls are just used for progressive refinements, in that case it is beneficial for the rendering performance to use the same transactions for all progressive render calls.

This method returns when rendering is finished. The return value is non-negative if rendering was successful, and negative if an error occurred or the render was cancelled. Progressive rendering returns one if the image is sufficiently refined according to the chosen quality parameters and returns the same image as in the last call in this case.

 
Sint32 IRender_context::render_async (
    ITransaction* transaction,
    IRender_target_base* render_target_base,
    IReady_callback* ready_callback,
    IProgress_callback* progress_callback)

Renders the scene associated with this render context to the given render target according to the passed in parameters using the render mode associated with the context.

It is necessary to commit the transaction after calling this method before making any changes in the scene database that should be taken into account in a future render call. To the contrary, if no scene changes are necessary and future render calls are just used for progressive refinements, in that case it is beneficial for the rendering performance to use the same transactions for all progressive render calls.

In contrast to the IRender_context::render call this call will return immediately while the rendering continues. The ready_callback is called when rendering is finished.

Abstract classes

The mi::neuraylib::IRender_target class together with its related mi::neuraylib::ICanvas and mi::neuraylib::ITile classes are abstract interfaces which have to be implemented by the application which uses this API to render. This gives the application the ability to tailor the rendering process very specific to its needs. For a simple example implementation of these interfaces, see A first image.

The mi::neuraylib::IRender_target class contains the canvases into which the render mode renders its results. The name of the canvas is determined through the mi::neuraylib::IRender_target_base::get_canvas_name() method. This name determines the exact result written in that canvas. The list of results and their names are documented in Canvas names in render targets.

Given a rendering result in an mi::neuraylib::ICanvas implementation, you can conveniently store it in an image format to disc or convert it to an image format in a memory buffer ready to be stored, encode it and give it to the video streaming server or send it as an answer to an HTTP request.

Method signature Description 
Sint32 IExport_api::export_canvas (
    const char* uri transaction,
    const ICanvas* canvas,
    Uint32 quality)

Exports a canvas, for example, to an image file on disk.

See Scene file formats for the URI naming conventions supported for the uri parameter and Image file formats for the available image formats and the quality parameter.

 
IBuffer* IImage_encoder_api::create_buffer_from_canvas (
    const ICanvas* canvas,
    const char* file_format,
    const char* quality)

Converts a canvas into an image file format and returns it in a buffer. See Image file formats for the available image formats and the quality parameter.