SoBufferedShape Class Reference
[Shapes]

VSG extension Node to render geometry stored in SoBufferObject objects. More...

#include <Inventor/nodes/SoBufferedShape.h>

Inheritance diagram for SoBufferedShape:
SoShape SoNode SoFieldContainer SoBase SoRefCounter SoTypedObject SoVolumeBufferedShape

List of all members.

Classes

struct  InstancesInfos
 Parameters used for support of batching in multiinstance mode.

Public Types

enum  Type {
  POINTS,
  LINE_STRIP,
  LINE_LOOP,
  LINES,
  TRIANGLE_STRIP,
  TRIANGLE_FAN,
  TRIANGLES,
  QUAD_STRIP,
  QUADS,
  POLYGON
}
enum  Usage {
  STATIC,
  DYNAMIC
}

Public Member Functions

virtual SoType getTypeId () const
 SoBufferedShape ()

Static Public Member Functions

static SoType getClassTypeId ()

Public Attributes

SoSFEnum shapeUsage
SoSFBool primitiveRestartEnabled
SoSFInt32 primitiveRestartValue
SoSFBool useNormalsGenerator
SoSFEnum shapeType
SoMFInt32 numVertices
SoSFBufferObject vertexBuffer
SoSFShort vertexComponentsCount
SoSFEnum vertexComponentsType
SoSFShort vertexStride
SoSFInt32 vertexOffset
SoSFBufferObject normalBuffer
SoSFEnum normalComponentsType
SoSFShort normalStride
SoSFInt32 normalOffset
SoSFBufferObject indexBuffer
SoSFEnum indexType
SoSFInt32 indexOffset
SoSFBufferObject colorBuffer
SoSFEnum colorComponentsType
SoSFInt32 colorStride
SoSFInt32 colorOffset
SoSFInt32 colorComponentsCount
SoMFBufferObject texCoordsBuffer
SoMFEnum texCoordsComponentsType
SoMFInt32 texCoordsStride
SoMFInt32 texCoordsOffset
SoMFInt32 texCoordsComponentsCount

Detailed Description

VSG extension Node to render geometry stored in SoBufferObject objects.

SoBufferedShape is useful to manage the rendering of large geometry, provide application control over where the data is stored (CPU or GPU) and to integrate rendering with the Open Inventor computing framework (through the SoBufferObject classes).

SoBufferedShape provides fields for:

In this sense it is similar to the SoVertexProperty node, but SoVertexProperty is just a property node. SoBufferedShape also does the rendering of the shape. Properties that are not specified are taken from the traversal state (e.g. colors) or computed (e.g. normals).

SoBufferedShape can render many types of geometric primitives including points, lines, quads and triangles. (A single type must be specified per instance of SoBufferedShape.) You specify the type of primitive in the SoSFEnum field shapeType.

SoBufferedShape can render multiple primitives of the same type. You can specify the number of vertices (or indices if provided) to use for each primitive in the SoMFInt32 field numVertices (similar to SoFaceSet).

You can also use the primitive restart feature to define multiple indexed strip shapes, for example TRIANGLE_STRIP or LINE_STRIP. The end of each primitive is marked by a special index value in the index buffer and this value can be specified in the primitiveRestartValue field. The behavior is similar to the "-1" value that can be used in Open Inventor indexed shape nodes like SoIndexedFaceSet, but is implemented on the GPU.
NOTE:

The geometry and its attributes must be stored in buffer objects (see SoBufferObject). The buffer objects can be SoGLBufferObjects stored directly on the graphics board or SoCpuBufferObjects stored in system memory. This allows the application to control what data is stored where.

If lighting is enabled (there is no SoLightModel node or the model field of the SoLightModel is set to PHONG) and the normalBuffer field is not set, then Open Inventor will automatically compute normal vectors, but only in some cases (see Limitations section). Normal generation is affected by the creaseAngle field of the SoShapeHints node, but only if the vertices are NOT indexed (indexBuffer field is not set). If the vertices are indexed the creaseAngle is forced to PI, creating a smooth surface rendering. If the application needs to render sharp edges on a shape, either compute normal vectors and set the normalBuffer field or do not use the indexBuffer field. It is possible to disable normal generation (if for example the normals are generated by a geometry shader) by setting the useNormalsGenerator field to FALSE. If no normal vectors are specified or generated, and lighting is enabled, the primitive may not be rendered correctly.

SoBufferedShape provides fields to describe the content of each buffer, e.g. the data type and number of components in each buffer, as well as how to access the buffers, e.g. the offset into the buffer and "stride" separating data values in the buffer. The default values for offset and stride assume that the vertices, normals, etc are each in a separate buffer. However setting appropriate offset and stride allows, for example, vertices and normals to be interleaved in a single buffer. In this case the same buffer would be set into both the vertexBuffer and normalBuffer fields.

To disable computing the bounding box, which can take a long time with very large geometry, use the SoBBox node to specify a pre-computed bounding box.

Limitations

Example using CPU buffer:

   // Result should be similar to SoLineSet example in PG-GettingStarted.pdf.
   // This example does not show any of the advantages of using SoBufferedShape,
   // just the simplest possible setup and usage.
   // Coordinate data
   const float vertices[][3] = { 1,0.5,0, 0,1,0, -1,0.5,0,
                              -1,-1,0, 1,-1,0, 1,0,0, -1,0,0,
                              -1,-1.5,0, 1,-1.5,0 };
   const int numVerts[] = {3, 4, 2};
   const int NUM_COORDS = sizeof(vertices) / sizeof(SbVec3f);
   const int NUM_COUNTS = sizeof(numVerts) / sizeof(int);

   // Wrap coordinate array in a CPU buffer object
   SoRef<SoCpuBufferObject> vertBuf = 
       new SoCpuBufferObject( (void*)vertices, NUM_COORDS * sizeof(SbVec3f) );

   // Create a buffered shape to render the geometry
   SoBufferedShape *pShape = new SoBufferedShape;
   pShape->shapeType = SoBufferedShape::LINE_STRIP;
   pShape->numVertices.setValues( 0, NUM_COUNTS, numVerts );
   pShape->vertexBuffer.setValue( vertBuf );

Example using GPU buffer:

   // Result should be similar to SoLineSet example in PG-GettingStarted.pdf.
   // This example does not show any of the advantages of using SoBufferedShape,
   // just the simplest possible setup and usage.
   // Coordinate data
   const float coords[][3] = { 1,0.5,0, 0,1,0, -1,0.5,0,
                              -1,-1,0, 1,-1,0, 1,0,0, -1,0,0,
                              -1,-1.5,0, 1,-1.5,0 };
   const int numVerts[] = {3, 4, 2};
   const int NUM_COORDS = sizeof(coords) / sizeof(SbVec3f);
   const int NUM_COUNTS = sizeof(numVerts) / sizeof(int);

   // Wrap coordinate array in a CPU buffer object
   SoRef<SoCpuBufferObject> cpuBuffer = 
       new SoCpuBufferObject( (void*)coords, NUM_COORDS * sizeof(SbVec3f) );

   // Create a GPU (OpenGL) buffer and load data from CPU buffer
   SoGLContext* glContext = new SoGLContext(true);
   glContext->bind();
     SoRef<SoGLBufferObject> gpuBuffer = new SoGLBufferObject( SoGLBufferObject::STATIC_DRAW );
     gpuBuffer->setTarget( SoGLBufferObject::ARRAY_BUFFER );
     gpuBuffer->setSize  ( cpuBuffer->getSize() ); // Set the buffer size (allocate memory)
     gpuBuffer->memcpy   ( cpuBuffer.ptr() );      // Copy data into the buffer
   glContext->unbind();
   glContext->unref(); // See ref counting rules for SoGLContext
   cpuBuffer->unref(); // Clean up this buffer

   // Create a buffered shape node to render the geometry
   SoBufferedShape *pShape = new SoBufferedShape;
   pShape->shapeType = SoBufferedShape::LINE_STRIP;
   pShape->numVertices.setValues( 0, NUM_COUNTS, numVerts );
   pShape->vertexBuffer.setValue( gpuBuffer );

LIMITATIONS: SoBufferedShape needs a graphic card supporting vertex buffer objects, if not available shape won't be rendered.

FILE FORMAT/DEFAULT

ACTION BEHAVIOR

SEE ALSO

SoCPUBufferObject, SoGLBufferObject, SoBBox

See related examples:

AnimatedShape, BufferedShapePicking, GPUGeometry, InterleavedVertexAttribFeedback, PrimitiveRestart, SimpleVertexAttribFeedback, SoBufferedShape, SoVertexShaderPrameter, VertexAttribFeedback, CudaMarchingCubes


Member Enumeration Documentation

Type of shape that will be rendered.

Enumerator:
POINTS 

Draws each vertex as a single point.

LINE_STRIP 

Connects all the vertices to form a polyline.

Given vertices A B C D, it draws the line segments AB, BC and CD.

LINE_LOOP 

Like LINE_STRIP, but an extra line segment is drawn connecting the last vertex to the first vertex.

LINES 

Connects every other pair of vertices with a line.

Given vertices A B C D, it draws the line segments AB and CD.

TRIANGLE_STRIP 

Draws a strip of connected triangles.

Given vertices A B C D E F, it draws the triangles ABC, CBD, CDE and EDF.

TRIANGLE_FAN 

Draws a fan of triangles.

Given vertices A B C D E F, it draws the triangles ABC, ACD, ADE and AEF.

TRIANGLES 

Draws unconnected triangles.

Given vertices A B C D E F, it draws the triangles ABC and DEF.

QUAD_STRIP 

Draws a strip of connected quadrilaterals.

Given vertices A B C D E F, it draws the quadrilaterals ABDC and DCEF.

QUADS 

Draws unconnected quadrilaterals.

Given vertices A B C D E F G H, it draws the quadrilaterals ABCD and EFGH.

POLYGON 

Draws a single polygon using all the vertices (in each primitive).

This enum is used to set the shapeUsage field.

It is used to optimize the location of the data in GPU memory.

Enumerator:
STATIC 

The shape is static or when updated the buffers are fully modified (contents replaced).

This is the default mode since most of the time this gives the best performances.

DYNAMIC 

The buffers are partially modified when a modification occurs.

In this case the frame rate could be lower but transfer time will be better. This mode should only be used in specific cases.


Constructor & Destructor Documentation

SoBufferedShape::SoBufferedShape (  ) 

Default constructor.


Member Function Documentation

static SoType SoBufferedShape::getClassTypeId (  )  [static]

Returns the type identifier for this class.

Reimplemented from SoShape.

Reimplemented in SoVolumeBufferedShape.

virtual SoType SoBufferedShape::getTypeId (  )  const [virtual]

Returns the type identifier for this specific instance.

Reimplemented from SoShape.

Reimplemented in SoVolumeBufferedShape.


Member Data Documentation

Buffer object that contains the (optional) color values.

Default is no buffer. Colors are always per-vertex or per-vertex-indexed. Note: This buffer must be an SoCpuBufferObject or an SoGLBufferObject with target = ARRAY_BUFFER.

Number of components in each color value.

Default is 3 (i.e. red, green and blue)

SbDataType::DataType type for the color values.

Use enum SbDataType::DataType. Default is SbDataType::FLOAT.

Offset in bytes to the first color value in the buffer.

Default is 0.

Stride in bytes between the first component of two consecutive colors.


Default is 0. e.g: If the colors are composed of 3 float components the stride should be 3 * sizeof(float). If vertices are packed in the same buffer the stride should be 3 * sizeof(float) + 3 * sizeof(float), the second part stands for the extra data padding.

Note: When the values are packed (only color values in the buffer) the value 0 can be used and OpenGL will compute the stride value.

Buffer object that contains the (optional) indices.

Default is no buffer. Note: This buffer must be an SoCpuBufferObject or an SoGLBufferObject with target = ELEMENT_ARRAY_BUFFER.

Offset in bytes to the first index in the buffer.

Default is 0.

SbDataType::DataType type for the indices.

Use enum SbDataType::DataType. Default is SbDataType::UNSIGNED_INT32.

Buffer object that contains the (optional) normal vectors.


Default is no buffer. Note: This buffer must be an SoCpuBufferObject or an SoGLBufferObject with target = ARRAY_BUFFER.

SbDataType::DataType type for the normal vectors.

Use enum SbDataType::DataType. Default is SbDataType::FLOAT.

Offset in bytes to the first normal vector in the buffer.

Default is 0.

Stride in bytes between the first component of two consecutive normals.

Default is 0. e.g: If the normals are composed of 3 float components the stride should be 3 * sizeof(float). If RGB colors are packed in the same buffer the stride should be 3 * sizeof(float) + 3 * sizeof(float), the second part stands for the extra data padding.

Note: When the values are packed (only normals in the buffer) the value 0 can be used and OpenGL will compute the stride value.

Number of vertices/indices to be used for each primitive.


Specifically:

  • For the shape types POINTS, LINES, TRIANGLES and QUADS only the first value is meaningful and it specifies the number of vertices to be used for rendering.
  • For all other types the number of values in this field specifies the number of primitives that will be drawn and each value in the field specifies the number of vertices (or indices if given) to be used for each primitive.

Enable/disable the primitive restart feature.

Default is FALSE. Primitive restart allows you to define multiple indexed strip shapes using only one index buffer. Each time the primitive restart index is reached a new strip or loop of primitives is emited. This feature is similar to the "-1" that can be used in the OIV indexed shapes This also means that the availability must be checked before being used

Limitations: Enabling primitive restart disables the normal generator.

NOTE: field available since Open Inventor 8.5

Index value for the primitive restart feature.

Default is -1.

NOTE: field available since Open Inventor 8.5

Shape type to render.

Use enum Type. Default is TRIANGLES.

Defines the usage of the shape.

The graphics driver can make some optimizations if it knows the usage of the shape. Most of the time if we update only a small part of the buffer objects attached to the shape on a regular basis we prefer DYNAMIC, otherwise we prefer STATIC.

STATIC provides the best performance even if we update the buffers on a per frame basis, as long as we are replacing the contents of the buffer using the SET access mode.

This field does not have any effect if the specified buffer objects are SoGLBufferObjects, because the static/dynamic behaviour is set on each buffer object.

Use enum Usage. The default value is STATIC.

NOTE: field available since Open Inventor 9.2

Buffer objects that contains the (optional) texture coordinates.


Default is no buffer. Note: The buffers must be an SoCpuBufferObject or an SoGLBufferObject with target = ARRAY_BUFFER.

Number of components in each texture coordinate.

Default is 2 (i.e. S and T)

SbDataType::DataType type for the texture coordinates.

Use enum SbDataType::DataType. Default is SbDataType::FLOAT.

Offset in bytes to the first texture coordinate in the buffer.

Default is 0.

Stride in bytes between the first component of two consecutive texture coordinates.


Default is 0. e.g: If each element is composed of 2 float components the stride should be 2 * sizeof(float). If vertices are packed in the same buffer the stride should be 2 * sizeof(float) + 3 * sizeof(float), the second part stands for the extra data padding.

Note: When the values are packed (only texture coordinates in the buffer) the value 0 can be used and OpenGL will compute the stride value.

Indicates if the node should use the internal normal vector generator if no normals are defined.

Default is TRUE.

This mode is only supported for shapes with float coordinates and 3 components per vertex. It is not supported for the points and the lines.

Disabling the normal generator can be useful if the normals are computed in a shader or if the shaders don't need any normal at all.

Normal generation is affected by the creaseAngle field of SoShapeHints.

Buffer object that contains the vertex data.


Default is no buffer. Note: This buffer must be an SoCpuBufferObject or an SoGLBufferObject with target = ARRAY_BUFFER.

Number of components in each vertex.

Default is 3 (i.e. X, Y and Z).

SbDataType::DataType for vertices.

Use enum SbDataType::DataType. Default is SbDataType::FLOAT.

Offset in bytes to the first vertex within the buffer.

Default is 0.

Stride in bytes between the first component of two consecutive vertices.


Default is 0. e.g: If the vertices are composed of 3 float components the stride should be 3 * sizeof(float). If RGB colors are packed in the same buffer the stride should be 3 * sizeof(float) + 3 * sizeof(float), the second part stands for the extra data padding.

Note: When the values are packed (only vertices in the buffer) the value 0 can be used and OpenGL will compute the stride value.


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

Open Inventor by FEI reference manual, generated on 21 Sep 2015
Copyright © FEI S.A.S. All rights reserved.
http://www.vsg3d.com