Class SoBufferedShape
- java.lang.Object
-
- com.openinventor.inventor.Inventor
-
- com.openinventor.inventor.misc.SoBase
-
- com.openinventor.inventor.fields.SoFieldContainer
-
- com.openinventor.inventor.nodes.SoNode
-
- com.openinventor.inventor.nodes.SoShape
-
- com.openinventor.inventor.nodes.SoBufferedShape
-
- All Implemented Interfaces:
SafeDisposable
- Direct Known Subclasses:
SoVolumeBufferedShape
public class SoBufferedShape extends SoShape
Node to render geometry stored inSoBufferObject
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 theSoBufferObject
classes).SoBufferedShape
provides fields for:- Vertices
- Indices (optional)
- Colors (optional)
- Normals (optional)
- Texture coordinates (optional)
In this sense it is similar to the
SoVertexProperty
node, butSoVertexProperty
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 ofSoBufferedShape
.) You specify the type of primitive in theSoSFEnum
fieldshapeType
.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 theSoMFInt32
fieldnumVertices
(similar toSoFaceSet
).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 likeSoIndexedFaceSet
, but is implemented on the GPU.
NOTE:- Primitive restart must be explicitly enabled using the
primitiveRestartEnabled
field. - Check availability of primitive restart using
SoShape.isPrimitiveRestartAvailable()
.
The geometry and its attributes must be stored in buffer objects (see
SoBufferObject
). The buffer objects can be SoGpuBufferObjects stored directly on the graphics board or SoCpuBufferObjects stored in system memory. This allows the application to control what data is stored where.In the general case, when the underlying buffer object is modified using the
SoBufferObject
API (setSize, map, memcpy, memset), the containingSoSFBufferObject
field needs to be notified usingtouch()
in order for Open Inventor to take this modification into account. Iftouch()
is not called, there is no guarantee that the modifications will be visible on the next rendering.If the application needs to frequently modify the values of an
SoBufferObject
, callingtouch()
on the field can result in an undesirable decrease in performance. Instead, it is recommended to use an instance ofSoGpuBufferObject
and set theshapeUsage
field to DYNAMIC. These settings guarantee that this buffer data will be used directly for rendering, and eliminate the need to calltouch()
on the field. It also guarantees that modifications to the buffer done by shaders will be properly taken into account.If lighting is enabled (there is no
SoLightModel
node or the model field of theSoLightModel
is set to PHONG) and thenormalBuffer
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 theSoShapeHints
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 theuseNormalsGenerator
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
- Transparency:
If there is no color buffer, making the entire shape transparent using anSoMaterial
node works as usual. However if there is a color buffer with RGBA values, note that Open Inventor does not currently check the color buffer for transparency (alpha values < 1). So in this case theSoBufferedShape
will not be considered transparent geometry (even if there are alpha values < 1) and may not be rendered correctly. You can force Open Inventor to handle the shape as transparent geometry by putting anSoMaterial
node with non-zero transparency before it in the scene graph. - Normal generation:
If lighting is enabled and the normalBuffer field is not set, then Open Inventor will automatically compute normal vectors, but only in some cases. Automatic generation of normal vectors is ONLY enabled when:- The
vertexComponentsCount
field is set to 2 or 3, - The
primitiveRestartEnabled
field is set to false (default), and - The primitives are TRIANGLES, TRIANGLE_STRIP or QUADS.
Note: The crease angle (seeSoShapeHints
) is not used by the normal generator if the vertices are indexed. 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.
- The
SoGetPrimitiveCountAction
:
When using the primitive restart feature, the triangle/line count returned by theSoGetPrimitiveCountAction
will not be accurate.- Concave polygons:
Unlike (for example)SoFaceSet
,SoBufferedShape
does NOT automatically tesselate concave or complex polygons. Such primitives may not be rendered correctly. SoWriteAction
:
SoBufferedShape
can be saved to and restored from a .iv file just like any other Open Inventor node. However, during the read operation any GPU buffer objects (SoGpuBufferObject
) in the file will be created as CPU buffers (SoCpuBufferObject
).- Material binding (etc):
SoBufferedShape
effectively only supports per-vertex and per-vertex-indexed binding of materials, normals and texture coordinates using the values found in its own buffers.
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 float[] vertices = { 1.0f, 0.5f,0.0f, 0.0f, 1.0f,0.0f, -1.0f,0.5f,0.0f, -1.0f,-1.0f,0.0f, 1.0f,-1.0f,0.0f, 1.0f,0.0f,0.0f, -1.0f,0.0f,0.0f, -1.0f,-1.5f,0.0f, 1.0f,-1.5f,0.0f }; int[] numVerts = { 3, 4, 2 }; // Create a CPU buffer object and set its size (allocate memory) SoCpuBufferObject cpuBuffer = new SoCpuBufferObject(); cpuBuffer.setSize( vertices.length * Float.SIZE/8 ); // Copy vertex data into the buffer object FloatBuffer vertData = cpuBuffer.map( SoBufferObject.AccessModes.SET ).asFloatBuffer(); vertData.put(vertices); cpuBuffer.unmap(); // Create a buffered shape to render the geometry SoBufferedShape shape = new SoBufferedShape(); shape.shapeType.setValue( "LINE_STRIP" ); shape.numVertices.setValues( 0, numVerts ); shape.vertexBuffer.setValue( cpuBuffer ); 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 float[] vertices = { 1.0f, 0.5f,0.0f, 0.0f, 1.0f,0.0f, -1.0f,0.5f,0.0f, -1.0f,-1.0f,0.0f, 1.0f,-1.0f,0.0f, 1.0f,0.0f,0.0f, -1.0f,0.0f,0.0f, -1.0f,-1.5f,0.0f, 1.0f,-1.5f,0.0f }; int[] numVerts = { 3, 4, 2 }; // Create a GPU (OpenGL) buffer and set its size (allocate memory) SoGLContext glContext = new SoGLContext( true ); glContext.bind(); SoGpuBufferObject gpuBuffer = new SoGpuBufferObject( SoGpuBufferObject.BufferAccessFrequencies.STATIC, SoGpuBufferObject.BufferAccessNatures.SHARED ); gpuBuffer.setSize( vertices.length * Float.SIZE/8 ); // Copy vertex data into the GPU buffer object FloatBuffer vertData = gpuBuffer.map( SoBufferObject.AccessModes.SET ).asFloatBuffer(); vertData.put(vertices); gpuBuffer.unmap(); glContext.unbind(); // Create a buffered shape to render the geometry SoBufferedShape shape = new SoBufferedShape(); shape.shapeType.setValue( "LINE_STRIP" ); shape.numVertices.setValues( 0, numVerts ); shape.vertexBuffer.setValue( gpuBuffer ); LIMITATIONS:
SoBufferedShape
needs a graphic card supporting vertex buffer objects, if not available shape won't be rendered.File format/default:
BufferedShape {
useNormalsGenerator true shapeType TRIANGLES numVertices 0 vertexBuffer NULL vertexComponentsCount 3 vertexComponentsType SbDataType.FLOAT
vertexStride 0 vertexOffset 0 normalBuffer NULL normalComponentsType SbDataType.FLOAT
normalStride 3 * sizeof(float) normalOffset 0 indexBuffer NULL indexType SbDataType.UNSIGNED_INT32
indexOffset 0 colorBuffer NULL colorComponentsType SbDataType.FLOAT
colorStride 0 colorOffset 0 colorComponentsCount 3 texCoordsBuffer NULL texCoordsComponentsType SbDataType.FLOAT
texCoordsStride 0 texCoordsOffset 0 texCoordsComponentsCount 2 primitiveRestartEnabled false primitiveRestartValue -1 Action behavior:
SoGLRenderAction
,SoCallbackAction
, SoBoundingBoxAction
Do the actual rendering / bounding box computation.- See Also:
SoCpuBufferObject
,SoGpuBufferObject
,SoBBox
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SoBufferedShape.Types
Type of shape that will be rendered.static class
SoBufferedShape.Usages
This enum is used to set theshapeUsage
field.-
Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoShape
SoShape.ShapeTypes
-
Nested classes/interfaces inherited from class com.openinventor.inventor.nodes.SoNode
SoNode.RenderModes
-
Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor
Inventor.ConstructorCommand
-
-
Field Summary
Fields Modifier and Type Field Description SoSFBufferObject
colorBuffer
Buffer object that contains the (optional) color values.SoSFInt32
colorComponentsCount
Number of components in each color value.SoSFEnum<SbDataType.DataTypes>
colorComponentsType
SbDataType.DataType
type for the color values.SoSFInt32
colorOffset
Offset in bytes to the first color value in the buffer.SoSFInt32
colorStride
Stride in bytes between the first component of two consecutive colors.SoSFBufferObject
indexBuffer
Buffer object that contains the (optional) indices.SoSFInt32
indexOffset
Offset in bytes to the first index in the buffer.SoSFEnum<SbDataType.DataTypes>
indexType
SbDataType.DataType
type for the indices.SoSFBufferObject
normalBuffer
Buffer object that contains the (optional) normal vectors.SoSFEnum<SbDataType.DataTypes>
normalComponentsType
SbDataType.DataType
type for the normal vectors.SoSFInt32
normalOffset
Offset in bytes to the first normal vector in the buffer.SoSFShort
normalStride
Stride in bytes between the first component of two consecutive normals.SoMFInt32
numVertices
Total number of vertices/indices or number of vertices/indices to be used per primitive.SoSFBool
primitiveRestartEnabled
Enable/disable the primitive restart feature.SoSFInt32
primitiveRestartValue
Index value for the primitive restart feature.SoSFEnum<SoBufferedShape.Types>
shapeType
Shape type to render.SoSFEnum<SoBufferedShape.Usages>
shapeUsage
Defines the usage of the shape.SoMFBufferObject
texCoordsBuffer
Buffer objects that contains the (optional) texture coordinates.SoMFInt32
texCoordsComponentsCount
Number of components in each texture coordinate.SoMFEnum<SbDataType.DataTypes>
texCoordsComponentsType
SbDataType.DataType
type for the texture coordinates.SoMFInt32
texCoordsOffset
Offset in bytes to the first texture coordinate in the buffer.SoMFInt32
texCoordsStride
Stride in bytes between the first component of two consecutive texture coordinates.SoSFBool
useNormalsGenerator
Indicates if the node should use the internal normal vector generator if no normals are defined.SoSFBufferObject
vertexBuffer
Buffer object that contains the vertex data.SoSFShort
vertexComponentsCount
Number of components in each vertex.SoSFEnum<SbDataType.DataTypes>
vertexComponentsType
SbDataType.DataType
for vertices.SoSFInt32
vertexOffset
Offset in bytes to the first vertex within the buffer.SoSFShort
vertexStride
Stride in bytes between the first component of two consecutive vertices.-
Fields inherited from class com.openinventor.inventor.nodes.SoShape
boundingBoxIgnoring
-
Fields inherited from class com.openinventor.inventor.Inventor
VERBOSE_LEVEL, ZeroHandle
-
-
Constructor Summary
Constructors Constructor Description SoBufferedShape()
Default constructor.
-
Method Summary
-
Methods inherited from class com.openinventor.inventor.nodes.SoShape
getShapeType, isPrimitiveRestartAvailable, isPrimitiveRestartAvailable
-
Methods inherited from class com.openinventor.inventor.nodes.SoNode
affectsState, callback, copy, copy, distribute, doAction, getAlternateRep, getBoundingBox, getByName, getMatrix, getPrimitiveCount, getRenderEngineMode, getRenderUnitID, GLRender, GLRenderBelowPath, GLRenderInPath, GLRenderOffPath, grabEventsCleanup, grabEventsSetup, handleEvent, isBoundingBoxIgnoring, isOverride, pick, rayPick, search, setOverride, touch, write
-
Methods inherited from class com.openinventor.inventor.fields.SoFieldContainer
copyFieldValues, copyFieldValues, enableNotify, fieldsAreEqual, get, getAllFields, getEventIn, getEventOut, getField, getFieldName, hasDefaultValues, isNotifyEnabled, set, setToDefaults
-
Methods inherited from class com.openinventor.inventor.misc.SoBase
dispose, getName, isDisposable, isSynchronizable, setName, setSynchronizable
-
Methods inherited from class com.openinventor.inventor.Inventor
getNativeResourceHandle
-
-
-
-
Field Detail
-
shapeUsage
public final SoSFEnum<SoBufferedShape.Usages> shapeUsage
Defines the usage of the shape. Some optimizations can be performed when we know the usage of the shape. Most of the time if the buffer objects attached to the shape are updated on a regular basis prefer using DYNAMIC, otherwise prefer STATIC.STATIC provides the best performance when the content of the buffer is never modified or modified infrequently.
. The default value is STATIC.
- Since:
- Open Inventor 9.2
-
primitiveRestartEnabled
public final SoSFBool primitiveRestartEnabled
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 emitted. 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 usedLimitations: Enabling primitive restart disables the normal generator.
- Since:
- Open Inventor 8.5
-
primitiveRestartValue
public final SoSFInt32 primitiveRestartValue
Index value for the primitive restart feature. Default is -1.- Since:
- Open Inventor 8.5
-
useNormalsGenerator
public final SoSFBool useNormalsGenerator
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
.
-
shapeType
public final SoSFEnum<SoBufferedShape.Types> shapeType
Shape type to render. . Default is TRIANGLES.
-
numVertices
public final SoMFInt32 numVertices
Total number of vertices/indices or number of vertices/indices to be used per 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. Specifically:- For a list of points: numVertices should be the number of points to be drawn.
- For a list of lines: numVertices should be num_lines * 2 where num_lines is the number of lines to be drawn.
- For a list of quadrangles: numVertices should be num_quads * 4 where num_quads is the number of quadrangles to be drawn.
- For a list of triangles: numVertices should be num_tri * 3 where num_tri is the number of triangles to be drawn.
- For all other types:
The number of values in this field specifies the number of primitives that will be drawn.
Each value in the field specifies the number of vertices (or indices if given) to be used for each primitive.
- For the shape types POINTS, LINES, TRIANGLES and QUADS
-
vertexBuffer
public final SoSFBufferObject vertexBuffer
Buffer object that contains the vertex data.
Default is no buffer. Note: This buffer must be anSoCpuBufferObject
orSoGpuBufferObject
. (SoGLBufferObject
with target = ARRAY_BUFFER is also allowed but not recommended.)
-
vertexComponentsCount
public final SoSFShort vertexComponentsCount
Number of components in each vertex. Default is 3 (i.e. X, Y and Z).
-
vertexComponentsType
public final SoSFEnum<SbDataType.DataTypes> vertexComponentsType
SbDataType.DataType
for vertices. . Default isSbDataType.FLOAT
.
-
vertexStride
public final SoSFShort vertexStride
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.
-
vertexOffset
public final SoSFInt32 vertexOffset
Offset in bytes to the first vertex within the buffer. Default is 0.
-
normalBuffer
public final SoSFBufferObject normalBuffer
Buffer object that contains the (optional) normal vectors.
Default is no buffer. Note: This buffer must be anSoCpuBufferObject
orSoGpuBufferObject
. (SoGLBufferObject
with target = ARRAY_BUFFER is also allowed but not recommended.)
-
normalComponentsType
public final SoSFEnum<SbDataType.DataTypes> normalComponentsType
SbDataType.DataType
type for the normal vectors. . Default isSbDataType.FLOAT
.
-
normalStride
public final SoSFShort normalStride
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.
-
normalOffset
public final SoSFInt32 normalOffset
Offset in bytes to the first normal vector in the buffer. Default is 0.
-
indexBuffer
public final SoSFBufferObject indexBuffer
Buffer object that contains the (optional) indices. Default is no buffer. Note: This buffer must be anSoCpuBufferObject
orSoGpuBufferObject
. (SoGLBufferObject
with target = ARRAY_BUFFER is also allowed but not recommended.)
-
indexType
public final SoSFEnum<SbDataType.DataTypes> indexType
SbDataType.DataType
type for the indices. . Default isSbDataType.UNSIGNED_INT32
. Note: Due to OpenGL restrictions, only 3 values are accepted here:SbDataType.UNSIGNED_INT32
,SbDataType.UNSIGNED_BYTE
orSbDataType.UNSIGNED_SHORT
.
-
indexOffset
public final SoSFInt32 indexOffset
Offset in bytes to the first index in the buffer. Default is 0.
-
colorBuffer
public final SoSFBufferObject colorBuffer
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 anSoCpuBufferObject
orSoGpuBufferObject
. (SoGLBufferObject
with target = ARRAY_BUFFER is also allowed but not recommended.)
-
colorComponentsType
public final SoSFEnum<SbDataType.DataTypes> colorComponentsType
SbDataType.DataType
type for the color values. . Default isSbDataType.FLOAT
.
-
colorStride
public final SoSFInt32 colorStride
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.
-
colorOffset
public final SoSFInt32 colorOffset
Offset in bytes to the first color value in the buffer. Default is 0.
-
colorComponentsCount
public final SoSFInt32 colorComponentsCount
Number of components in each color value. Default is 3 (i.e. red, green and blue)
-
texCoordsBuffer
public final SoMFBufferObject texCoordsBuffer
Buffer objects that contains the (optional) texture coordinates.
Default is no buffer. Note: This buffer must be anSoCpuBufferObject
orSoGpuBufferObject
. (SoGLBufferObject
with target = ARRAY_BUFFER is also allowed but not recommended.)
-
texCoordsComponentsType
public final SoMFEnum<SbDataType.DataTypes> texCoordsComponentsType
SbDataType.DataType
type for the texture coordinates. . Default isSbDataType.FLOAT
.
-
texCoordsStride
public final SoMFInt32 texCoordsStride
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.
-
texCoordsOffset
public final SoMFInt32 texCoordsOffset
Offset in bytes to the first texture coordinate in the buffer. Default is 0.
-
texCoordsComponentsCount
public final SoMFInt32 texCoordsComponentsCount
Number of components in each texture coordinate. Default is 2 (i.e. S and T)
-
-