<< Click to Display Table of Contents >> Navigation:  XStream® HDVR® SDK > Implementation Concepts > Rendering Concepts > Render Parameters

C++ C++ Java Java .NET .NET

Summary

 

One of the most important structures in the XStream® HDVR® SDK is the RENDER_PARAMS structure. This defines the type of render engine used and the complete state of the rendering engine. All engine parameters, including viewpoint position and orientation, lighting, clipping planes, transfer function, image quality, and other parameters, are contained in this structure that determines how the rendering engine renders the dataset.

 

Once defined, a RENDER_PARAMS structure is applied using either the RenderEngineContext.SetRenderParams() or RenderQueue.SetRenderParams() method. See RenderEngineContext vs RenderQueue about the different types of engines, and for more information on how to apply a RENDER_PARAMS structure to a render engine. See Rendering Modes for additional information about the different render engine types that are available.

 

The RENDER_PARAMS Structure

 

The following is an overview of the different member variables in the RENDER_PARAMS structure and their uses.

 

ENUM_RENDER_PARAMS_MASK RENDER_PARAMS::Mask

 

This field is a bitmask used to set those fields of the RENDER_PARAMS structure that contain valid data. The ENUM_RENDER_PARAMS_MASK enumeration can be treated as a set of bit flags that can be combined with a logical OR operation. Only those RENDER_PARAMS fields flagged as valid by the RENDER_PARAMS::Mask bitmask will be interpreted by the engine. See the documentation for ENUM_RENDER_PARAMS for a detailed list of the available flags and their purpose.

 

The Mask is an important field, since it directly affects the optimization of the engine by determining which unchanged parts of the rendering pipeline can be bypassed.

 

In the below example, the transform and zoom factors have been updated. Even if other fields were set or modified, those other fields would be ignored because the Mask field does not contain the bitflags signaling their use.

 

 

int RENDER_PARAMS::Ambience

int RENDER_PARAMS::Brightness

int RENDER_PARAMS::Reflection

int RENDER_PARAMS::Shininess

 

The above fields are used to set the Phong lighting model that will illuminate the 3D scene. Phong lighting is only applicable in ENUM_RENDER_TYPE::RT_PERSPECTIVE and ENUM_RENDER_TYPE::RT_PARALLEL rendering modes. For more detailed information on configuring these parameters, see the Phong Lighting Model documentation page.

 

 

short RENDER_PARAMS::AutoNav

double RENDER_PARAMS::AutoNavSpeed

 

These fields are used to turn the auto-navigation feature on and off, and to set the speed of the viewpoint movement. Auto-navigation is used to 'fly' the viewpoint through a vessel or other navigable structure. The Autonavigation Mouse Adaptor also uses the auto-navigation feature.

 

Setting RENDER_PARAMS::AutoNav to 1 will enable auto-navigation. Setting it to 0 will disable it.

 

If auto-navigation is on, use the RENDER_PARAMS::AutoNavSpeed member to set the speed of the viewpoint movement. This value is a multiplier of the viewpoint base speed, which depends on the size of the vessel being navigated. Larger vessels have higher base speeds while smaller vessels have lower base speeds.

 

 

int RENDER_PARAMS::BackColor

 

This member sets the background color used when rendering the scene. Use the HDRC_RGB() macro to pack the red, green, and blue color components into the 4 byte integer value for this field. Note that due to implementation details at this time, valid values are 0 to 254 for each component. Therefore, pure white (255,255,255) is not achievable.

 

 

CUT_PLANE_PARAMS RENDER_PARAMS::CutPlanes [MAX_CUTPLANES]

ENUM_CUT_PLANE_MODE RENDER_PARAMS::CutPlanesMode

 

This member is an array of 16 different cut planes that is used to perform planar segmentation of the volume. Areas outside of the cut planes are not rendered. Note that two additional cut planes are implicitly provided by the projection plane itself and the slab thickness. The RENDER_PARAMS::CutPlanes member may only be used with the RT_PARALLEL and RT_THICK_* render modes.

 

Each cut plane is defined by the CUT_PLANES_PARAMS structure. This structure contains a PLANEEQF member that defines the plane, a member of the ENUM_CUT_PLANE_STATUS enumeration that defines the activity status of the cut plane, and a member of the ENUM_CUT_PLANE_TYPE enumeration that defines the cut plane type. Currently only ENUM_CUT_PLANE_TYPE::CUT_PLANE_TYPE_POSITIVE is valid for this field.

 

The RENDER_PARAMS::CutPlanesMode member should be set to ENUM_CUT_PLANE_MODE::CUT_PLANE_MODE_STANDARD (0).

 

 

int RENDER_PARAMS::DesiredFPS

int RENDER_PARAMS::MinQualityBias

 

This member is a request for the desired frame rate setting from the rendering engine. 0 is a special value that disables the automatic quality/performance balancing sub-system. Set the RENDER_PARAMS::DesiredFPS member to 0 if you wish to get a valid frame rate benchmark from the engine.

 

If not set to 0, the RENDER_PARAMS::DesiredFPS value will dictate the minimum acceptable frame rate for the engine. After each frame is rendered, the engine will assess the elapsed rendering time. If the frame rate appears to be unacceptably low, then the quality of interactive rendering will be reduced to increase the frame rate. A lower threshold limits degradation of the quality, so it is possible to get a lower frame rate than that requested by RENDER_PARAMS::DesiredFPS. Similarly, if the machine is so fast that the highest quality level is achieved, then the frame rate may be higher than the RENDER_PARAMS::DesiredFPS.

 

The RENDER_PARAMS::MinQualityBias member sets the minimum quality threshold for the RENDER_PARAMS::DesiredFPS member. The engine will not reduce the quality level below this value while attempting to achieve the desired frame rate. If the RENDER_PARAMS::MinQualityBias is set to a high quality level, the frame rate set in RENDER_PARAMS::DesiredFPS may not be achievable. Valid values for RENDER_PARAMS::MinQualityBias are 256 to 768. The higher the number, the lower the quality level can go. 256 is the default and is the highest minimum quality allowed.

 

 

ENUM_RENDER_FLAGS RENDER_PARAMS::Flags

ENUM_RENDER_FLAGS RENDER_PARAMS::FlagsMask

 

The RENDER_PARAMS::Flags and RENDER_PARAMS::FlagsMask members are used together to set a variety of render parameters available in the ENUM_RENDER_FLAGS enumeration. The values in the ENUM_RENDER_FLAGS enumeration affect how the rendering engine produces the final image, and can be used to produce a variety of custom effects. For more information on these custom rendering options, see the ENUM_RENDER_FLAGS documentation.

 

The ENUM_RENDER_FLAGS options are turned on and off using the RENDER_PARAMS::Flags and RENDER_PARAMS::FlagsMask members together. The RENDER_PARAMS::FlagsMask member is used to designate valid bit flags in the RENDER_PARAMS::Flags member. To turn an ENUM_RENDER_FLAGS state flag on or off, set the appropriate bit flag in RENDER_PARAMS::FlagsMask to 1, and then set the corresponding bit flag in RENDER_PARAMS::Flags to 1 or 0, depending on if the ENUM_RENDER_FLAGS option is to be turned on or off.

 

 

unsigned int RENDER_PARAMS::FrontSlabPolygonTransparency

unsigned int RENDER_PARAMS::RearSlabPolygonTransparency

 

These members are used to set the transparency of polygon objects in front of or behind the projection plane. If 0, objects in front of the projection plane are fully visible. If 255, objects in front of the projection plane are not visible at all. Values between 0 and 255 represent intermediate levels of transparency. This feature must be used together with the slab navigation feature.

 

 

int RENDER_PARAMS::GradInsenSlab

 

This member designates an area in which the renderer will not perform the lighting calculation, defined by the distance from any cut plane (including the front of the slab) and measured in volume units. This includes the cut planes defined by the slab created between the projection plane position and said position, plus RENDER_PARAMS::SlabThickness. This field is only valid for parallel rendering. Note that the lighting calculation can be altered by toggling lighting for a COLORED_POINT on the transfer function, or setting the render flag RF_USE_GRADIENTS to false. Acceptable values are [0, 4096].

 

IMPORTANT: The area affected by this field is calculated along a vector extending from the view position in the view direction. Therefore, the lighting depth of all cut planes (with the exception of the front of the slab) will change based upon the relationship of the viewing angle to the cut plane. The exception to this is when RENDER_PARAMS::GradInsenSlab is set to 1. This special case will turn off lighting for the surface of the cut plane and will not have this view direction dependent behavior. As a result, 0,1, and 4096 are the recommended values to use for this field.

 

 

float RENDER_PARAMS::SlabThickness

 

This member describes slab thickness when rendering in MIP modes or in RT_PARALLEL with RF_USE_SLAB_PAR or FR_USE_SLAB_MIP defined. This defines in volume units the distance from the projection plane to the end points of rays cast. A slab thickness of 0 is an infinitely thin slab: in MIP/MPR rendering the voxels are sampled directly in a thin slice. The maximum recommended value for RT_THIN_* rendering modes is 50. For adaptive rendering modes, the maximum acceptable value is 4096.

 

 

 

LIGHT_DEFINITION RENDER_PARAMS::LightParams

 

This member is used to set the direction vector for the light and the light attachment type. The light can be attached either to the camera or the dataset. The light properties are set with the LIGHT_DEFINITION structure.

 

 

ENUM_RENDER_QUALITY RENDER_PARAMS::Quality

 

This member defines the overall level of quality for the final rendered image. The image quality is set with a value from the ENUM_RENDER_QUALITY enumeration. The progressive rendering stage ENUM_RENDER_STAGE::RENDER_STAGE_PROGR0 is also influenced by the RENDER_PARAMS::DesiredFPS field, but both the progressive and final rendering modes are affected by the RENDER_PARAMS::Quality field.

 

Thin rendering modes do not use this value. They are always at the highest quality level.

 

 

RENDER_PARAMS::RaycastingPrecision

 

This member affects the precision of ray casting operations on semi-transparent surfaces in the volume. This value should generally be set to 0, which allows the engine to automatically determine the optimal internal ray casting precision level. For more information on how to manually determine a value for the RENDR_PARAMS::RaycastingPrecision value, see the documentation page on Performance Considerations.

 

 

SIZE RENDER_PARAMS::RenderImageSize

 

This member defines the size of the rendering image matrix. Rendering image size affects the speed and quality of the output image. Large image sizes provide more detail, while smaller image sizes increase rendering speed.

 

The width and height must be multiples of 16. The current maximum render image size is 4096 x 4096.

 

 

int RENDER_PARAMS::RenderRangeMin

int RENDER_PARAMS::RenderRangeMax

 

These members set the window minimum and maximum values for window level and window width. Window level is the average of these two values, and window width is the difference between them. These values are applicable to Thin and Thick MIP/MPR modes. If ENUM_RENDER_FLAGS::RF_DONT_NORMALIZE_TF is set, the parameter range is specified by the actual volume data. Otherwise, the minimum scalar value is mapped to 0 and the maximum scalar value is mapped to 65535. All other values are interpolated using these anchor points. Note that values outside of the data range are acceptable.

 

 

RENDER_RANGE_PARAMS RENDER_PARAMS::RenderRanges[MAX_RENDER_RANGES_PARAMS]

 

These ranges specify the transfer function for parallel and perspective rendering. MAX_RENDER_RANGES_PARAMS may be set for these ranges; they represent control points that specify color and opacity for a specific segment. Voxels with values outside of a render range are completely transparent. A render range can be quickly turned off by setting its RENDER_RANGE_PARAMS::Status to RENDER_RANGE_STATUS_DISABLED. This field is not used by rendering modes other than RT_PARALLEL and RT_PERSPECTIVE.

 

The RENDER_PARAMS::RenerRanges field is not used by rendering modes other than RT_PARALLEL and RT_PERSPECTIVE.

 

The value of MAX_RENDER_RANGES_PARAMS can vary according to the XStream HDVR distribution, but is generally 8. Each render range can have up to 50 control points: MAX_RENDER_RANGE_POINTS (50).

 

The RENDER_PARAMS::RenderRanges field can only be used to set transfer function 1. To set other transfer functions, use either the RenderEngineContext::SetTransferFunction() or RenderQueue::SetTransferFunction() method.

 

For more information on designing and configuring a transfer function, see the section on Transfer Functions.

 

 

ENUM_RENDER_TYPE RENDER_PARAMS::RenderType

 

This member is used to set the render engine mode. A variety of different render engine modes are available, depending on the type of visualization required by the application. For more information on render engine modes, see the chapter on Rendering Modes.

 

 

ENUM_STEREO_MODE RENDER_PARAMS::StereoMode

double RENDER_PARAMS::StereoSeparation

 

These members are used to configure a rendering engine for left/right stereo rendering. Two separate render engines are required for stereo rendering, one for the left eye and one for the right. Likewise, use of these members requires two separate rendering engines. The RENDER_PARAMS::StereoMode member takes a value from the ENUM_STEREO_MODE enumeration specifying rendering for the right or left eye.

 

The RENDER_PARAMS::StereoSeparation member sets the separation distance between the two eyes. Specify 0.0 for an automatic separation calculated based upon the average depth of the scene. Otherwise, specify a number in the range 0 to 1.

 

 

MATRIX44D RENDER_PARAMS::Transform

 

The transform used for rendering includes X, Y, Z orientation vectors and an offset from the origin. A variety of methods are available for creating a transform matrix in the MATRIX44D class. The position and orientation defined by the matrix is relative to the volume coordinate system specified in VOLUME_DATA_PARAMS::Dimension, VOLUME_DATA_PARAMS::Orientation and VOLUME_DATA_PARAMS::Spacing.

 

X - Defined as the direction from the left of the screen to the right of the screen.

Y - Defined as the direction from the top of the screen to the bottom of the screen.

Z - Defined as the view direction. In other words, a vector pointing "into" the screen.

Offset - The location of the center of the screen in the volume. In perspective rendering, this is the eye location in the volume.

 

The logical layout of the Transform structure is as follows:

 

 

For best results, the vectors of the transform should be normalized and orthogonal to each other.

 

In all but perspective rendering, scaling of the rendering is specified separately through the RENDER_PARAMS::Zoom field. In perspective, the RENDER_PARAMS::ViewAngle field becomes relevant.

 

The identity matrix will place the camera at the location 0,0,0 viewing axially.

 

Note that OpenGL API uses the inverse form of the above matrix. A general matrix inverse procedure can be used to interconnect the two APIs. Because the above matrix is normalized and orthogonal, great simplifications can be applied to the inverse procedure. (E.g., when offset vector is zero, the inverse of the matrix is equal to its transpose.)

 

 

float RENDER_PARAMS::ViewAngle

 

This member sets the field of view for perspective rendering when using RT_PERSPECTIVE. This value should be in the range 6 - 150 degrees.

 

 

float RENDER_PARAMS::Zoom

 

This member is used to set the dataset zoom value. Zoom is defined as the number of pixels per voxel in the rendered image. For example, if the Zoom is set to 2, that means that the size of every voxel is measured at 2 pixels in size. The voxel size in this definition is the size in volume units specified in VOLUME_DATA_PARAMS::Spacing x field. If VOLUME_DATA_PARAMS::Spacing is set to 2 and RENDER_PARAMS::Zoom is set to 3, then each voxel is rendered at a size of 6 units. Zoom is only useful in RT_PARALLEL rendering mode, and is ignored in RT_PERSPECTIVE rendering mode. The maximum acceptable value for Zoom is 700.0.

 

 

Deprecated Members

 

These members of the RENDER_PARAMS structure have been deprecated or are reserved and should no longer be used.

 

RENDER_PARAMS::ColorModel

RENDER_PARAMS::CropBox

RENDER_PARAMS::LightModel

RENDER_PARAMS::NumRenderingThreads

RENDER_PARAMS::RenderSamples

RENDER_PARAMS::Reserved