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

• SoPointSet
• SoFaceSet
• SoLineSet
• SoIndexedLineSet
• SoCube
• SoSphere
• SoCylinder
• SoCone

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:

• SoIndexedFaceSet
• SoTriangleStripSet
• SoIndexedTriangleSet
• SoIndexedTriangleStripSet

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

Field Index

allowLocalTransforms: Bool	Num Instances: Integer
Auto Detect Num Instances: Bool	Object Center: Vector3
boundingBoxCaching: Enum	pickCulling: Enum
Hardware Instancing Supported: Bool	renderCaching: Enum
Instance Color: Bool	renderCulling: Enum
Instance Rotation: Bool	Use Hardware Instancing: Bool
Instance Scale: Bool
Instance Translation: Bool

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