Heightfield rendering node. More...

#include <VolumeViz/nodes/SoHeightFieldRender.h>

Inheritance diagram for SoHeightFieldRender:

Public Types
enum	BoundaryCells { ALWAYS , SMART , NONE }
	Boundary cells mode. More...

Public Types inherited from SoSlice
enum	AlphaUse { ALPHA_AS_IS , ALPHA_OPAQUE , ALPHA_BINARY }
	Alpha component usage mode Used in the alphaUse field. More...

Public Types inherited from SoVolumeShape
enum	Interpolation { NEAREST , LINEAR , TRILINEAR , MULTISAMPLE_12 , CUBIC }
	Interpolation mode. More...

enum	Composition { MAX_INTENSITY = 0 , MIN_INTENSITY , SUM_INTENSITY , ALPHA_BLENDING , COMPOSITION_LAST }
	Composition mode. More...

Public Types inherited from SoShape
enum	ShapeType { POINTS , LINES , POLYGONS , TEXT }
	Basic type for antialiased rendering for this shape (Do not consider the SoDrawStyle property currently in the state). More...

Public Member Functions
virtual SoType	getTypeId () const
	Returns the type identifier for this specific instance.

	SoHeightFieldRender ()
	Constructor.

Public Member Functions inherited from SoVolumeShape
virtual void	setRenderProgress (SoProgressIndicator *ps)
	Set an application defined SoProgressIndicator object which will raise an event before and after the rendering task, before and after each subtask (in this case: Texture creation and Geometry creation) and after each step in the subtasks which represents in most cases individual tiles of data.

Public Member Functions inherited from SoShape
virtual SbBool	affectsState () const
	Overrides default method on SoNode.

ShapeType	getShapeType ()
	Gets the current shape Full Scene Antialiasing type.

Public Member Functions inherited from SoNode
virtual void	setOverride (const SbBool state)
	Turns the override flag on or off.

virtual SbBool	isOverride () const
	Returns the state of the override flag.

virtual SoNode *	copy (SbBool copyConnections=FALSE) const
	Creates and returns an exact copy of the node.

virtual void	touch ()
	Marks an instance as modified, simulating a change to it.

Public Member Functions inherited from SoFieldContainer
void	setToDefaults ()
	Sets all fields in this object to their default values.

SbBool	hasDefaultValues () const
	Returns TRUE if all of the object's fields have their default values.

SbBool	fieldsAreEqual (const SoFieldContainer *fc) const
	Returns TRUE if this object's fields are exactly equal to fc's fields.

void	copyFieldValues (const SoFieldContainer *fc, SbBool copyConnections=FALSE)
	Copies the contents of fc's fields into this object's fields.

SoNONUNICODE SbBool	set (const char *fieldDataString)
	Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.

SbBool	set (const SbString &fieldDataString)
	Sets one or more fields in this object to the values specified in the given string, which should be a string in the Open Inventor file format.

void	get (SbString &fieldDataString)
	Returns the values of the fields of this object in the Open Inventor ASCII file format in the given string.

virtual int	getFields (SoFieldList &list) const
	Appends references to all of this object's fields to resultList, and returns the number of fields appended.

virtual int	getAllFields (SoFieldList &list) const
	Returns a list of fields, including the eventIn's and eventOut's.

virtual SoField *	getField (const SbName &fieldName) const
	Returns a the field of this object whose name is fieldName.

virtual SoField *	getEventIn (const SbName &fieldName) const
	Returns a the eventIn with the given name.

virtual SoField *	getEventOut (const SbName &fieldName) const
	Returns the eventOut with the given name.

SbBool	getFieldName (const SoField *field, SbName &fieldName) const
	Returns the name of the given field in the fieldName argument.

SbBool	enableNotify (SbBool flag)
	Notification at this Field Container is enabled (if flag == TRUE) or disabled (if flag == FALSE).

SbBool	isNotifyEnabled () const
	Notification is the process of telling interested objects that this object has changed.

virtual void	setUserData (void *data)
	Sets application data.

void *	getUserData (void) const
	Gets user application data.

Public Member Functions inherited from SoBase
virtual SbName	getName () const
	Returns the name of an instance.

virtual void	setName (const SbName &name)
	Sets the name of an instance.

void	setSynchronizable (const bool b)
	Sets this to be a ScaleViz synchronizable object.

bool	isSynchronizable () const
	Gets the ScaleViz synchronizable state of this object.

Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.

void	unref () const
	Removes a reference from an instance.

void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.

int	getRefCount () const
	Returns current reference count.

void	lock () const
	lock this instance.

void	unlock () const
	unlock this instance.

Public Member Functions inherited from SoTypedObject
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.

template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

static SbBool	isSupported (SoState *state=NULL)
	Returns true if graphic card can render an SoHeightFieldRender.

Static Public Member Functions inherited from SoSlice
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Static Public Member Functions inherited from SoVolumeShape
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Static Public Member Functions inherited from SoLdmShape
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Static Public Member Functions inherited from SoShape
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

static SbBool	isPrimitiveRestartAvailable (SoState *state=NULL)
	Returns TRUE if the primitive restart feature is available.

Static Public Member Functions inherited from SoNode
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

static SoNode *	getByName (const SbName &name)
	A node's name can be set using SoBase::setName().

static int	getByName (const SbName &name, SoNodeList &list)
	A node's name can be set using SoBase::setName().

Static Public Member Functions inherited from SoFieldContainer
static SoType	getClassTypeId ()
	Returns the type of this class.

Static Public Member Functions inherited from SoBase
static SoType	getClassTypeId ()
	Returns type identifier for this class.

Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Public Attributes
SoSFBool	cellOutline
	If true, draw outline of each heightField cell (default is false).

SoSFFloat	cellOutlineWidth
	When cellOutline is TRUE, this value specifies the cell outline width in pixels.

SoSFColor	cellOutlineColor
	When cellOutline is TRUE, this value specifies the cell outline color.

SoSFEnum	boundaryCells
	Boundary cells mode.

Public Attributes inherited from SoSlice
SoSFBool	enableBumpMapping
	Specifies if a bump mapping effect will be applied to the slice.

SoSFFloat	bumpScale
	Specifies the intensity of the bump mapping effect.

SoSFNode	alternateRep
	This field optionally holds a subgraph containing only core Open Inventor nodes that can be used for rendering when VolumeViz is not available.

SoSFEnum	alphaUse
	Specifies how to use the alpha component of each voxel's RGBA value.

SoSFBool	useRGBA
	Specifies whether to create RGBA textures.

SoSFBool	largeSliceSupport
	Activate/deactivate direct loading of full resolution slice data.

Public Attributes inherited from SoVolumeShape
SoSFEnum	interpolation
	Interpolation mode.

SoDEPRECATED SoSFEnum	composition
	Specifies color composition mode.

Public Attributes inherited from SoShape
SoSFBool	boundingBoxIgnoring
	Whether to ignore this node during bounding box traversal.

Friends
class	SoVolumeStateHeightField

Detailed Description

Heightfield rendering node.

SoHeightFieldRender displays a uniform grid in the XY plane whose vertices are height (Z) values stored in 2D LDM format (any LDM data set with the Z dimension equal to 1). Adding the combination of LDM data management with advanced GPU features provides a way to handle extremely large surfaces. Just as with volume data, LDM uses tiles of data and multiple levels of resolution to enable interactive frame rates even for data sets that cannot fit in system memory.

This node is used similarly to other VolumeViz shapes, but instead of an SoVolumeData node, you use an SoHeightFieldGeometry for the data set (height values) and optionally one or more SoHeightFieldProperty nodes for property data sets. When one or more SoHeightFieldProperty nodes are used, because there are multiple data nodes, they must be children of an SoMultiDataSeparator node and the rules for multiple data sets apply (see SoVolumeData the parent class of SoHeightFieldGeometry). Otherwise, if no SoHeightFieldProperty nodes are used and only an SoHeightFieldGeometry node is present, the following rules apply:

If an SoTransferFunction node is on the state, then the SoHeightFieldGeometry node is also used as a property node and the height field is colored according to the height values and the transfer function, just as if an SoHeightFieldProperty node was defined with the same data.
If no SoTransferFunction node is on the state, then the height field is colored using the current material on state.

Note that SoHeightFieldRender is derived from SoSlice and those inherited fields affect the rendering. In particular note that the alphaUse field applies to height field rendering and the default value (since Open Inventor 10.0) is ALPHA_OPAQUE. It means, for example, that the transparency in the color map will not affect rendering of the height map unless alphaUse is set to ALPHA_AS_IS.

Data set values are converted to height values in 3D space in two ways depending on the data type:

Integer values are normalized between [0,1] ([-1,1] for signed types) based on the range of values for the specific data type. For example, for UNSIGNED BYTE values the range 0..255 is mapped to 0..1.
Floating point values are not normalized (are used "as is").

Any height value in the SoHeightFieldGeometry data set that is equal to the "undefined" value will be rendered as a hole in the mesh. The undefined value can be specified during the LDM conversion using the "-u" option to the LDM converter:

   convert -u 127 -b 1 inputFile.lst

Or by setting the undefinedValue field of the SoHeightFieldGeometry node. The default value is NaN (Not a Number).

An SoHeightFieldPropertyMask node can also be used to specify undefined cells in the mesh. An undefined cell effectively removes the four corresponding height values from the mesh. (SoVolumeMask does not apply to height field rendering.)

A lighted heightfield

VolumeViz provides default shaders that conveniently color the surface using a single property, as shown in the images. However, it is also possible to combine multiple properties using a custom shader program, in the same way that you would combine multiple volumes.

The field cellOutline enables drawing the edges of the mesh cells. BoundaryCells are cells close to an undefined value. If the boundaryCells field is set to ALWAYS, these cells must always be considered at all resolution levels to avoid artifacts. In SMART mode, the default, we don't take this into account for distant views.

Normally this node uses the OpenGL tessellation shader extension to speed up rendering and automatically adjust the number of generated triangles depending on the camera position and orientation. In this mode, to change the number of generated triangles, use an SoComplexity node. A value of 1 means a full tessellation with a maximum of 4 triangles per pixel and a value of 0.5 means a maximum of 1 triangle per pixel.

If tessellation shaders are not available, a value of 1 means full resolution data is used to generate triangles (a grid of 10x10 will then generate 10x10 x2 triangles). A value of 0 means the lower resolution will be used.

To check if tessellation shaders are supported, use the method isAvailable( "GL_ARB_tessellation_shader" ) of SoGLExtension class

When no SoHeightFieldProperty nodes are used and only an SoHeightFieldGeometry node is defined, the standard VolumeViz rules apply to the creation of a scene graph using SoHeightFieldRender. A minimal scene graph displaying a height field in this case is:

EXAMPLE

// Create nodes
SoHeightFieldGeometry* HFGeom = new SoHeightFieldGeometry;
  HFGeom->fileName = "$OIVHOME/examples/data/VolumeViz/horizon.ldm";
 
// Base color
SoMaterial* material = new SoMaterial;
  material->diffuseColor.setValue( 1, 1, 1 );
 
SoTransferFunction* TF = new SoTransferFunction;
  TF->predefColorMap = SoTransferFunction::STANDARD;
 
SoHeightFieldRender* HFRend = new SoHeightFieldRender;
 
// Limit triangles (optional)
SoComplexity* complexity = new SoComplexity();
  complexity->value = 0.25;
 
// Build scene graph
SoSeparator* volSep = new SoSeparator;
  volSep->addChild( HFGeom );
  volSep->addChild( material );
  volSep->addChild( complexity );
  volSep->addChild( TF );
  volSep->addChild( HFRend );
root->addChild( volSep );

When one or more SoHeightFieldProperty nodes are used, multidata rules apply to the creation of a scene graph using SoHeightFieldRender and an SoMultiDataSeparator node must be used instead of SoSeparator. A minimal scene graph displaying a heightfield in this case is:

EXAMPLE

// Create nodes
SoHeightFieldGeometry* HFGeom = new SoHeightFieldGeometry;
  HFGeom->fileName = "$OIVHOME/examples/data/VolumeViz/horizon.ldm";
  HFGeom->dataSetId = 1;
 
SoHeightFieldProperty* HFProp = new SoHeightFieldProperty;
  HFProp->fileName = "$OIVHOME/examples/data/VolumeViz/property1.ldm";
  HFProp->dataSetId = 2;
 
// Base color
SoMaterial* material = new SoMaterial;
  material->diffuseColor.setValue( 1, 1, 1 );
 
SoTransferFunction* TF = new SoTransferFunction;
  TF->predefColorMap = SoTransferFunction::STANDARD;
 
SoHeightFieldRender* HFRend = new SoHeightFieldRender;
 
// Limit triangles (optional)
SoComplexity* complexity = new SoComplexity();
  complexity->value = 0.25;
 
// Build scene graph
SoMultiDataSeparator* volSep = new SoMultiDataSeparator;
  volSep->addChild( HFGeom );
  volSep->addChild( HFProp );
  volSep->addChild( material );
  volSep->addChild( complexity );
  volSep->addChild( TF );
  volSep->addChild( HFRend );
root->addChild( volSep );

Shaders

When used with an SoVolumeShader, a new shader function is available to compute lighting:

vec4 VVizComputeFrontColor(vec3 normal, vec4 color)): Add lighting to the color col.

The following shader code will light a heightfield:

: vec4 VVizComputeFrontColor(vec3 n, vec4 col);

void main()

{

vec3 tCoord0 = VVizComputeCoordinates(OivFragmentTexCoord(0).xyz);

vec3 normal = normalize(VVizComputeNormal(texCoord));

float sf = VVizCombineData(tCoord0);

vec4 col = VVizComputeFragmentColor(vox, texCoord);

col = VVizComputeFrontColor(normal, col);

VVizOutputColor(col);

}

VVizOutputColor
void VVizOutputColor(vec4 color)
This function sends the final fragment color to OpenGL.

VVizComputeNormal
vec3 VVizComputeNormal(vec3 view, vec3 grad)
Returns the current normal.

VVizCombineData
VVIZ_DATATYPE VVizCombineData(in vec3 dataCoord)
SoVolumeShader::DATA_COMBINE_FUNCTION function.

VVizComputeFragmentColor
vec4 VVizComputeFragmentColor(in VVizDataSetId dataset, in vec3 rayDir, inout VVizVoxelInfo voxelInfoFront, in VVizVoxelInfo voxelInfoBack, in int mask)
SoVolumeShader::FRAGMENT_COMPUTE_COLOR function.

VVizComputeCoordinates
vec3 VVizComputeCoordinates(const vec3 dataCoord)
Compute new coordinates from input coordinates.

Multiple Data:

Using an SoMultiDataSeparator, it is possible to combine datasets that have different dimensions or tile sizes. For instance, an SoHeightFieldGeometry dataset can be used with an SoHeightFieldProperty even if they don't have the same dimensions or tile sizes.

Composition with VolumeData:

It is possible to color a height field according to the values of a volume data. To do such rendering, the HeightField datasets and the SoVolumeData nodes must be in the same SoMultiDataSeparator. A custom shader must also be defined to fetch values from the right datasets using their dataSetId. This is demonstrated in the HorizonInVolume example.

In addition, texture coordinates conversion functions are provided in the VolumeViz/vvizStructure.h shader include in order to help fetch the correct VolumeData values in custom shaders.
For instance,

vec3 VVizTextureToTextureVec(in VVizDataSetId datasetSrc, in VVizDataSetId datasetDst, in vec3 texCoord);

VVizTextureToTextureVec

vec3 VVizTextureToTextureVec(in VVizDataSetId datasetSrc, in VVizDataSetId datasetDst, in vec3 texCoord)

Converts the input vector from the texture space of one dataset to the texture space of another datas...

can be used to convert texture coordinates related to one dataset to texture coordinates related to another dataset.
The conversion is based solely on the transformations applied to each dataset, which are defined by their model matrix and their extent.
Please note that the model matrix of a dataset is defined by the SoTransformation nodes that are placed before the SoDataSet node in the order of the traversal.

Picking:

Similar to other geometry, SoPickedPoint can return an SoDetail object specific to the SoHeightFieldRender node. The specific class is SoHeightFieldDetail.

Only GPU picking is supported. This means that the SoRayPickAction used for picking must have its scene manager initialized using the method SoAction::setSceneManager(). SoHandleEventAction does this automatically, so it is not necessary for the application to take any action when using (for example) an SoEventCallback node and calling the getPickedPoint() method. However if the application creates its own SoRayPickAction then it must set the scene manager. If no scene manager is specified, a warning message is issued.

Limitations:

At least one SoHeightFieldProperty which defines a property data set associated with the grid must be in the state.
If an SoROI is in the state, SoHeightFieldRender renders only one box of the ROI (ie: correct rendering only if SoROI's flag field is set to SUB_VOLUME)
Only SoHeightFieldGeometry data sets with a depth of 1 (Z dimension = 1) can be rendered.
The SoHeightFieldProperty and SoHeightFieldPropertyMask data sets must have exactly the same dimensions as the SoHeightFieldGeometry.
Triangle orientation after GPU tessellation cannot be controlled. Undefined value rendering is indeterministic.
For low resolution, undefined values can be taken into account in the property but not in the geometry. In such cases, coloring artifacts can appear.
Lighting is limited to directional lights and base color. Other kinds of lights can be implemented manually using a custom shader.
By default, two-sided lighting is not enabled ("back" side of surface will not be lighted). Use an SoShapeHints node to enable two-sided lighting.
The enableBumpMapping field is not supported on this node
SoHeightFieldPropertyMask and cellOutline can be used only if tesselation shaders are supported. Use the SoGLExtension method isAvailable( "GL_ARB_tessellation_shader" ) to check this support.

FILE FORMAT/DEFAULT

alphaUse	ALPHA_OPAQUE
alternateRep	NULL
bumpScale	1.0
cellOutline	FALSE
enableBumpMapping	FALSE
useRGBA	FALSE
largeSliceSupport	FALSE

Member Enumeration Documentation

◆ BoundaryCells

enum SoHeightFieldRender::BoundaryCells

Boundary cells mode.

Enumerator
ALWAYS	Always compute boundary cells.
SMART	Computes boundary cells according to the distance to the view.
NONE	Never computes boundary cells.

Definition at line 477 of file SoHeightFieldRender.h.

Constructor & Destructor Documentation

◆ SoHeightFieldRender()

SoHeightFieldRender::SoHeightFieldRender ( )

Constructor.

Member Function Documentation

◆ getClassTypeId()

static SoType SoHeightFieldRender::getClassTypeId ( )

static

Returns the type identifier for this class.

◆ getTypeId()

virtual SoType SoHeightFieldRender::getTypeId ( ) const

virtual

Returns the type identifier for this specific instance.

Reimplemented from SoSlice.

◆ isSupported()

static SbBool SoHeightFieldRender::isSupported ( SoState * state = NULL )

static

Returns true if graphic card can render an SoHeightFieldRender.

GPU must support geometry shaders, floating point textures and vertex buffer objects (VBO) and tessellation shaders

Friends And Related Symbol Documentation

◆ SoVolumeStateHeightField

friend class SoVolumeStateHeightField

friend

Definition at line 597 of file SoHeightFieldRender.h.

Member Data Documentation

◆ boundaryCells

SoSFEnum SoHeightFieldRender::boundaryCells

Boundary cells mode.

Setting this field to SMART will not compute boundary cells for distant views. Use enum BoundaryCells. Default is SMART.

Definition at line 495 of file SoHeightFieldRender.h.

◆ cellOutline

SoSFBool SoHeightFieldRender::cellOutline

If true, draw outline of each heightField cell (default is false).

Definition at line 458 of file SoHeightFieldRender.h.

◆ cellOutlineColor

SoSFColor SoHeightFieldRender::cellOutlineColor

When cellOutline is TRUE, this value specifies the cell outline color.

Default is black : (0, 0, 0).

NOTE: field available since Open Inventor 9.7

Definition at line 474 of file SoHeightFieldRender.h.

◆ cellOutlineWidth

SoSFFloat SoHeightFieldRender::cellOutlineWidth

When cellOutline is TRUE, this value specifies the cell outline width in pixels.

Default is 2 pixels.

NOTE: field available since Open Inventor 9.7

Definition at line 466 of file SoHeightFieldRender.h.

The documentation for this class was generated from the following file:

VolumeViz/nodes/SoHeightFieldRender.h

Open Inventor Release 2024.2.0

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Detailed Description

EXAMPLE

EXAMPLE

FILE FORMAT/DEFAULT

SEE ALSO

Member Enumeration Documentation

◆ BoundaryCells

Constructor & Destructor Documentation

◆ SoHeightFieldRender()

Member Function Documentation

◆ getClassTypeId()

◆ getTypeId()

◆ isSupported()

Friends And Related Symbol Documentation

◆ SoVolumeStateHeightField

Member Data Documentation

◆ boundaryCells

◆ cellOutline

◆ cellOutlineColor

◆ cellOutlineWidth