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” check box 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 make sure that rotation works well, your rendered geometry should be centered around (0,0,0) in object space. Normals are transformed using the inverse transposed of the scale/rotate/translate matrix, so 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 module 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 OpenInventor 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

The number of instances that are drawn.

Auto Detect Num Instances

name: autoDetectNumInstances, type: Bool, default: TRUE

Auto-detects the number of instances from the per-instance vertex attributes that are provided.

Instance Translation

name: instanceTranslation, type: Bool, default: TRUE

Enables per-instance translation. Provide a SoVertexAttribute3f named instanceTranslation.

Instance Rotation

name: instanceRotation, type: Bool, default: FALSE

Enables per-instance rotation. Provide a SoVertexAttributeRotation named instanceRotation. The rotation is passed as a quaternion using vec4.

Instance Scale

name: instanceScale, type: Bool, default: FALSE

Enables per-instance scaling. Provide a SoVertexAttribute3f named instanceScale.

Instance Color

name: instanceColor, type: Bool, default: FALSE

Enables per-instance colors. Provide a SoVertexAttribute4ub or SoVertexAttribute4f named instanceColor.

Use Hardware Instancing

name: useHardwareInstancing, type: Bool, default: TRUE

If enabled, glDrawArraysInstanced or glDrawElementsInstanced is used. If disabled, 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 to automatically transfer 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

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