Using RenderEngine

The general work-flow with a rendering engine is as following:

1. Specify the dataset for rendering
2. Set the rendering parameters
   • Rendering type (3D/MIP/FMIP/MPR)
   • Projection plane
   • Transfer function / Render ranges
   • Optional rendering parameters
3. Execute rendering
   • Blocking execution
   • Non-blocking execution
4. If progressive quality improvement is required, then repeat step 3 with next rendering stage.
5. Display image on the screen (GDI/DirectX/OpenGL/etc)
6. Repeat from step 2

IRenderEngine is the main interface for all rendering modes. Below is the 
above procedure for execution in terms of methods from the IRenderEngine 
interface:
<ol> 
    <li>Call IRenderEngine::SetVolumeData()</li>
    <li>Setup RENDER_PARAMS structure
    <ul>
        <li> RENDER_PARAMS::Mask
        <li> RENDER_PARAMS::RenderType 
        <li> RENDER_PARAMS::Transform       (Projection Plane description)
        <li> RENDER_PARAMS::Zoom
        <li> RENDER_PARAMS::RenderRanges    (Transfer function description)
        <li> RENDER_PARAMS::RenderRangeMin  (For MIP/MPR/FMIP)
        <li> RENDER_PARAMS::RenderRangeMax  (for MIP/MPR/FMIP)
        <li> Call IRenderEngine::SetRenderParams</li>
    </ul>
    </li>
    <li>Execute rendering
        <ul>
            <li>Blocking execution:
                <ul>
                <li>Call IRenderEngine::Render with ENUM_RENDER_STAGE::RENDER_STAGE_PROGR0</li>
                </ul>
            </li>
            <li>Non-blocking execution:
                <ul>
                <li>Call IRenderEngine::StartRender with ENUM_RENDER_STAGE::RENDER_STAGE_PROGR0</li>
                <li>Perform any non rendering related task(s) (optional) </li>
                <li>Call IRenderEngine::WaitRender </li>
                </ul>
        </ul>
    </li>       
    <li>If progressive quality improvement is required, then repeat step 3 with next rendering stage.
        Currently, ENUM_RENDER_STAGE::RENDER_STAGE_PROGR0 & ENUM_RENDER_STAGE::RENDER_STAGE_FINAL are
        the two relevant stages. You must always render with ENUM_RENDER_STAGE::RENDER_STAGE_PROGR0
        before rendering ENUM_RENDER_STAGE::RENDER_STAGE_FINAL if the RENDER_PARAMS have changed.</li>
    <li>Display the result image (GDI/DirectX/OpenGL/etc)</li>
</ol>

In @b non-blocking execution the calls IRenderEngine::StartRender() and IRenderEngine::WaitRender() 
for specific render engine shall be matched.

Rendering Parameters Overview

All rendering parameters and render engine behavior are defined by the RENDER_PARAMS structure. It is important to be familiar with the RENDER_PARAMS structure variables, their impact, valid range and applicability to a rendering type (ENUM_RENDER_TYPE). The documentation for RENDER_PARAMS structure provides important information on this topic. Additionally, each rendering engine will provide more documentation on the effect of the RENDER_PARAMS structure.

The transfer function is created from one or more render ranges represented by the RENDER_RANGE_PARAMS structure.

Some render modes may implement additional functionality such as IRenderEngine::ShootRay, IRenderEngine::ProjectPoint, and/or IRenderEngine::GetNavigationVector. If an render mode does not support the functionality an error code is returned.

Viewer Position

Various rendering modes have different requirements for the RENDER_PARAMS::Transform parameter. Improper values in the transform matrix may lead to incorrect rendering and/or unpredictable results.

At all times the orientation vectors shall be normalized (the length of the vector is equal to 1) and shall be orthogonal to each other (the dot product with each other be zero). The bottom row of the matrix shall be filled with zeros, with the exception of the bottom right element (m44), which shall be set to 1. An identity matrix satisfies the above requirements, and generally is a good starting point for developers.

The valid range for the offset parameters in the transform (m14, m24, m34) depend on the rendering mode as noted below:

• RT_THIN_MIP, RT_THIN_FMIP, RT_THIN_AVE – no restrictions
• RT_PARALLEL – the length of the offset shall not be greater than half of the diagonal of XY plane of the dataset
• RT_PERSPECTIVE – the offset shall not specify a coordinate outside the dataset
• RT_THICK_MIP, RT_THICK_FADED_MIP – the length of the offset shall not be greater than half of the diagonal of the dataset

Positioning Elements on the Image

Sometimes it is desired to show additional information on the rendered image. Consistency between 3D objects and 2D rendered image can be obtained via the IRenderEngine::ProjectPoint and IRenderEngine::ShootRay functions. Both functions can accept an array of vertices, allowing quick conversion between from one form to another.

• IRenderEngine::ProjectPoint function is useful for placing additional text information near a 3D object.
• IRenderEngine::ShootRay allows you to get the ray information from a specific point on the rendered image.
• IRenderEngine::GetNavigationVector provides the general vector pointing towards the "point of least resistance" in the last rendered image. The magnitude of this vector is equal to the average depth of the rendered scene.

Deallocation of Rendered Image Data

Rendering engines produce output in the form of VOLVISIMAGE structure. The structure describes an image allocated in memory. Once the rendered image is no longer needed it needs to be deallocated from the memory. The VOLVISIMAGE::Data points to the beginning of the image data, this pointer shall be passed to the deallocation function. IImageUtil::ImageFree() is the most direct way to perform this operation.

Failing to follow the above procedure will cause a significant memory leak and may quickly drain system resources.