SoDrawInstanced

InventorModule
author MeVis Medical Solutions AG
package MeVisLab/Standard
dll SoRenderers
definition SoRenderers.def
keywords multi, instances, array

Purpose

The SoDrawInstanced module can be used to render the same geometry thousands of times, each using different attributes.

The module supports the following attributes:

  • color
  • position
  • scale
  • rotation

Please note that the module currently does not calculate the correct bounding box of the rendered instances. This is due to the performance implications.

You can add an invisible bounding geometry (e.g., a SoSphere with SoDrawStyle set to invisible) to the scene to ensure a large enough bounding box.

Usage

You can place most Open Inventor geometries below this module and they will be rendered Num Instances times.

To provide the per-instance attributes, place SoVertexAttribute3f, SoVertexAttributeRotation, SoVertexAttribute4ub, or SoVertexAttribute4f modules into the scene. Make sure that you enable the “Per Instance” checkbox on each of these attributes.

Use the following name and type for the attributes:

Type Name
SoVertexAttributeRotation instanceRotation
SoVertexAttribute3f instanceScale
SoVertexAttribute3f instanceTranslation
SoVertexAttribute4ub/4f instanceColor

The transformations are applied in this order:

  • translate to objectCenter
  • scale
  • rotate
  • translate

To ensure that rotation works well, your rendered geometry should be centered around (0, 0, 0) in object space. Normals are transformed using the inverse transpose of the matrix that encodes scaling, rotation, and translation, ensuring that shading on the transformed instances works well.

The model-view matrix is applied after the per instance transformation.

Details

The module supports the following Open Inventor geometries:

The SoWEMRenderer and other modules that are based on the above modules will work as well.

The geometries of the following module are not directly supported:

Use the modules SoWEMConvertInventor and SoWEMRenderer on the output of the above modules to create a geometry that can be rendered by SoDrawInstanced.

Tips

If filling a SoVertexAttribute3f or SoVertexAttributeRotation is too slow or if the string representation of the module gets too big, consider creating a C++ module. This module should instantiate a SoVertexAttribute* attribute internally and add it to the scene.

Alternatively, you can use the Python Open Inventor bindings to create SoVertexAttribute* nodes, fill them with NumPy, and add them to a custom scene in a macro module.

This module makes use of the GLSL Shader Pipeline. It can be extended with additional per-instance vertex attributes and the shader can be modified/extended as well.

Parameter Fields

Visible Fields

Num Instances

name: numInstances, type: Integer, default: 100

Sets the number of instances that are rendered.

Auto Detect Num Instances

name: autoDetectNumInstances, type: Bool, default: TRUE

If checked, the number of instances is automatically detected from the per-instance vertex attributes that are provided.

Instance Translation

name: instanceTranslation, type: Bool, default: TRUE

If checked, the use of per-instance translation is enabled. Provide a SoVertexAttribute3f named instanceTranslation.

Instance Rotation

name: instanceRotation, type: Bool, default: FALSE

If checked, the use of per-instance rotation is enabled. Provide a SoVertexAttributeRotation named instanceRotation. The rotation is passed as a quaternion using vec4.

Instance Scale

name: instanceScale, type: Bool, default: FALSE

If checked, the use of per-instance scaling is enabled. Provide a SoVertexAttribute3f named instanceScale.

Instance Color

name: instanceColor, type: Bool, default: FALSE

If checked, the use of per-instance colors is enabled. Provide a SoVertexAttribute4ub or SoVertexAttribute4f named instanceColor.

Use Hardware Instancing

name: useHardwareInstancing, type: Bool, default: TRUE

If checked, glDrawArraysInstanced or glDrawElementsInstanced is used.

Otherwise, each instance is drawn using a glDrawArrays or glDrawElements call and the per-instance properties are passed to the shader using uniforms. This module takes care of automatically transferring the data from the per-instance vertex attributes to the uniforms.

Hardware Instancing Supported

name: hardwareInstancingSupported, type: Bool, persistent: no

Shows whether hardware instancing is supported. Hardware instancing requires OpenGL 3.3.

Object Center

name: objectCenter, type: Vector3, default: 0 0 0

Sets a translation that defines the object center (in object coordinates) of the instance geometry. By default, this is (0,0,0).

Hidden Fields

renderCaching

name: renderCaching, type: Enum, default: AUTO

Values:

Title Name
On ON
Off OFF
Auto AUTO

boundingBoxCaching

name: boundingBoxCaching, type: Enum, default: AUTO

Values:

Title Name
On ON
Off OFF
Auto AUTO

renderCulling

name: renderCulling, type: Enum, default: AUTO

Values:

Title Name
On ON
Off OFF
Auto AUTO

pickCulling

name: pickCulling, type: Enum, default: AUTO

Values:

Title Name
On ON
Off OFF
Auto AUTO

allowLocalTransforms

name: allowLocalTransforms, type: Bool, default: TRUE