Open Inventor Release 2023.2.2
 
Loading...
Searching...
No Matches
SoShapeHints Class Reference

Node that provides hints about shapes. More...

#include <Inventor/nodes/SoShapeHints.h>

+ Inheritance diagram for SoShapeHints:

Public Types

enum  VertexOrdering {
  UNKNOWN_ORDERING = SoShapeHintsElement::UNKNOWN_ORDERING ,
  CLOCKWISE = SoShapeHintsElement::CLOCKWISE ,
  COUNTERCLOCKWISE = SoShapeHintsElement::COUNTERCLOCKWISE
}
 Hints about ordering of face vertices: if ordering of all vertices of all faces is known to be consistent when viewed from "outside" shape or not. More...
 
enum  ShapeType {
  UNKNOWN_SHAPE_TYPE = SoShapeHintsElement::UNKNOWN_SHAPE_TYPE ,
  SOLID = SoShapeHintsElement::SOLID
}
 Hints about entire shape: if shape is known to be a solid object, as opposed to a surface. More...
 
enum  FaceType {
  UNKNOWN_FACE_TYPE = SoShapeHintsElement::UNKNOWN_FACE_TYPE ,
  CONVEX = SoShapeHintsElement::CONVEX
}
 Hints about faces of shape: if all faces are known to be convex or not. More...
 
enum  WindingType {
  NO_WINDING_TYPE = SoShapeHintsElement::NO_WINDING_TYPE ,
  ODD_TYPE = SoShapeHintsElement::ODD_TYPE ,
  NON_ZERO_TYPE = SoShapeHintsElement::NON_ZERO_TYPE ,
  POSITIVE_TYPE = SoShapeHintsElement::POSITIVE_TYPE ,
  NEGATIVE_TYPE = SoShapeHintsElement::NEGATIVE_TYPE ,
  ABS_GEQ_TWO_TYPE = SoShapeHintsElement::ABS_GEQ_TWO_TYPE
}
 Winding type possible values. More...
 

Public Member Functions

virtual SoType getTypeId () const
 Returns the type identifier for this specific instance.
 
 SoShapeHints ()
 Creates a shape hints node with default settings.
 
virtual void setOverride (const SbBool state)
 Set the state of the override field.
 
virtual SbBool isOverride () const
 Returns the state of the override field.
 
- Public Member Functions inherited from SoNode
virtual SoNodecopy (SbBool copyConnections=FALSE) const
 Creates and returns an exact copy of the node.
 
virtual SbBool affectsState () const
 Returns TRUE if a node has an effect on the state during traversal.
 
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 SoFieldgetField (const SbName &fieldName) const
 Returns a the field of this object whose name is fieldName.
 
virtual SoFieldgetEventIn (const SbName &fieldName) const
 Returns a the eventIn with the given name.
 
virtual SoFieldgetEventOut (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 isVBOSupported ()
 Indicates if Vertex Buffer Object (VBO) is supported by your graphics board.
 
- Static Public Member Functions inherited from SoNode
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 
static SoNodegetByName (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

SoSFEnum vertexOrdering
 Indicates how the vertices of faces are ordered.
 
SoSFEnum shapeType
 Indicates whether the shape is known to enclose a volume (SOLID) or not.
 
SoSFEnum faceType
 Indicates whether each face is convex.
 
SoSFEnum windingType
 Indicates the winding rule used to define holes in a polygon.
 
SoSFBool useVBO
 This field controls whether subsequent shapes in the scene graph can use OpenGL Vertex Buffer Objects (VBO) to speed up rendering.
 
SoSFFloat creaseAngle
 Indicates the minimum angle (in radians) between two adjacent face normals required to form a sharp crease at the edge when normal vectors are computed automatically by Open Inventor.
 
SoSFFloat neighborTolerance
 Specifies the tolerance value to use when default normals are computed.
 

Detailed Description

Node that provides hints about shapes.

By default, Open Inventor assumes very little about the shapes it renders. You can use the SoShapeHints node to indicate that vertex-based shapes (those derived from SoVertexShape) are solid, contain ordered vertices, or contain convex faces. For fastest rendering, specify SOLID, COUNTERCLOCKWISE, CONVEX shapes.

These hints allow Open Inventor to optimize certain rendering features. Optimizations that may be performed include enabling back-face culling and disabling two-sided lighting. For example, if an object is solid and has ordered vertices, Open Inventor turns on backface culling and turns off two-sided lighting. If the object is not solid but has ordered vertices, it turns off backface culling and turns on two-sided lighting. In all other cases, both backface culling and two-sided lighting are off.
Summary:

  • Two-sided lighting: enabled if not solid and has ordered vertices.
    Set vertexOrdering to COUNTERCLOCKWISE (usually) or CLOCKWISE.
  • Backface culling: enabled if solid and has ordered vertices.
    Set shapeType to SOLID.

Note: Two-sided lighting is automatically enabled for VolumeViz "slice" primitives, such as SoOrthoSlice and SoVolumeSkin.

This node allows the creation of polygons with holes. See the windingType field description, SoIndexedFaceSet, and SoFaceSet for details.

The SoShapeHints node also affects how default normals are generated. When a node derived from SoVertexShape has to generate default normals, it uses the creaseAngle field to determine which edges should be smooth-shaded and which ones should have a sharp crease. The crease angle is the angle between surface normals on adjacent polygons. For example, a crease angle of .5 radians means that an edge between two adjacent polygonal faces will be smooth shaded if the normals to the two faces form an angle that is less than .5 radians (about 30 degrees). Otherwise, it will be faceted.

creaseAngle = 0
creaseAngle = 0.5 creaseAngle = PI
br

Smooth shaded means that the normal vectors of all the faces that share a vertex are averaged together to compute the normal vector for that vertex.

Normal averaging
br

Normal generation is fastest when the creaseAngle is 0 (the default), producing one normal per facet. However, if a vertex is shared by two (or more) faces that should be faceted, the result of normal generation will be multiple normal vectors (one for each face) associated with that vertex. This is in conflict with using OpenGL Vertex Buffer Objects (VBO), which usually provide the best performance. VBO rendering only allows per-vertex (not per-face) normal vectors and only one normal vector per vertex. Some high-level shapes, like SoIndexedFaceSet, will automatically reorganize the geometry data to produce the requested appearance and still use VBOs for rendering. Lower level shapes like SoBufferedShape will ignore the creaseAngle field and compute normals using a crease angle of Pi in order to use VBOs for rendering. A creaseAngle of Pi produces one averaged normal per vertex.

See SoVertexShape for more information about Vertex Buffer Objects and shape rendering.

FILE FORMAT/DEFAULT

    ShapeHints {
    vertexOrdering UNKNOWN_ORDERING
    shapeType UNKNOWN_SHAPE_TYPE
    faceType CONVEX
    windingType NO_WINDING_TYPE
    creaseAngle 0
    neighborTolerance 1e-6
    useVBO TRUE
    }

ACTION BEHAVIOR

SEE ALSO

SoVertexShape SoIndexedFaceSet SoFaceSet

Definition at line 171 of file SoShapeHints.h.

Member Enumeration Documentation

◆ FaceType

Hints about faces of shape: if all faces are known to be convex or not.

Enumerator
UNKNOWN_FACE_TYPE 

Nothing is known about faces.

CONVEX 

All faces are convex.

Definition at line 212 of file SoShapeHints.h.

◆ ShapeType

Hints about entire shape: if shape is known to be a solid object, as opposed to a surface.

Enumerator
UNKNOWN_SHAPE_TYPE 

Nothing is known about the shape.

SOLID 

The shape encloses a volume.

Definition at line 200 of file SoShapeHints.h.

◆ VertexOrdering

Hints about ordering of face vertices: if ordering of all vertices of all faces is known to be consistent when viewed from "outside" shape or not.

Enumerator
UNKNOWN_ORDERING 

Ordering of vertices is unknown.

CLOCKWISE 

Face vertices are ordered clockwise (from the outside)

COUNTERCLOCKWISE 

Face vertices are ordered counterclockwise (from the outside)

Definition at line 181 of file SoShapeHints.h.

◆ WindingType

Winding type possible values.

Enumerator
NO_WINDING_TYPE 

Draw without holes (default).

ODD_TYPE 

Regions with odd winding numbers are filled.

This is the most commonly used winding rule.

NON_ZERO_TYPE 

Regions with non-zero winding numbers are filled.


POSITIVE_TYPE 

Regions with positive winding numbers are filled.

NEGATIVE_TYPE 

Regions with negative winding numbers are filled.

ABS_GEQ_TWO_TYPE 

Regions with winding numbers whose absolute value is greater than or equal to two are filled.

Definition at line 224 of file SoShapeHints.h.

Constructor & Destructor Documentation

◆ SoShapeHints()

SoShapeHints::SoShapeHints ( )

Creates a shape hints node with default settings.

Member Function Documentation

◆ getClassTypeId()

static SoType SoShapeHints::getClassTypeId ( )
static

Returns the type identifier for this class.


◆ getTypeId()

virtual SoType SoShapeHints::getTypeId ( ) const
virtual

Returns the type identifier for this specific instance.

Reimplemented from SoNode.

◆ isOverride()

virtual SbBool SoShapeHints::isOverride ( ) const
inlinevirtual

Returns the state of the override field.

Reimplemented from SoNode.

Definition at line 388 of file SoShapeHints.h.

◆ isVBOSupported()

static SbBool SoShapeHints::isVBOSupported ( )
static

Indicates if Vertex Buffer Object (VBO) is supported by your graphics board.

◆ setOverride()

virtual void SoShapeHints::setOverride ( const SbBool  state)
inlinevirtual

Set the state of the override field.

see SoNode::setOverride doc.

Reimplemented from SoNode.

Definition at line 382 of file SoShapeHints.h.

Member Data Documentation

◆ creaseAngle

SoSFFloat SoShapeHints::creaseAngle

Indicates the minimum angle (in radians) between two adjacent face normals required to form a sharp crease at the edge when normal vectors are computed automatically by Open Inventor.

It has no effect when normal vectors are explicitly provided by the application.

Definition at line 349 of file SoShapeHints.h.

◆ faceType

SoSFEnum SoShapeHints::faceType

Indicates whether each face is convex.

Because the penalty for non-convex faces is very steep (faces must be triangulated expensively), the default assumes all faces are convex. Therefore, shapes with concave faces may not be displayed correctly unless this hint is set to UNKNOWN_FACE_TYPE. Use enum FaceType. Default is CONVEX.

Definition at line 280 of file SoShapeHints.h.

◆ neighborTolerance

SoSFFloat SoShapeHints::neighborTolerance

Specifies the tolerance value to use when default normals are computed.

The default is 1e-6.

Specifically it determines which (other) points in the shape are close enough to influence the normal at each vertex.
Setting a smaller tolerance value will select a smaller number of points and can reduce the time required for computing normals on very large, very dense geometry.

If the OIV_NORMGEN_TOLERANCE environment variable is set, the default is 1/OIV_NORMGEN_TOLERANCE.

NOTE: field available since Open Inventor 8.0

Definition at line 366 of file SoShapeHints.h.

◆ shapeType

SoSFEnum SoShapeHints::shapeType

Indicates whether the shape is known to enclose a volume (SOLID) or not.

If the inside (the side away from the surface normal) of any part of the shape is visible, the shape is not solid. Use enum ShapeType. Default is UNKNOWN_SHAPE_TYPE.

Definition at line 272 of file SoShapeHints.h.

◆ useVBO

SoSFBool SoShapeHints::useVBO

This field controls whether subsequent shapes in the scene graph can use OpenGL Vertex Buffer Objects (VBO) to speed up rendering.

Default is TRUE (since Open Inventor 8.1). The default value can be set using the OIV_FORCE_USE_VBO environment variable (see SoPreferences).

In most cases there is no reason to set this field. Open Inventor will automatically choose the best rendering strategy. For example, VBOs generally provide the best performance for large shapes (many vertices), but not necessarily for small shapes. In specific cases it may be useful to influence these decisions using this field and/or the related environment variables including OIV_MIN_VERTEX_VBO and OIV_MIN_VERTEX_VAVBO_NOCACHE. See SoVertexShape for more discussion about shape rendering strategy.

NOTE: field available since Open Inventor 5.0

Definition at line 341 of file SoShapeHints.h.

◆ vertexOrdering

SoSFEnum SoShapeHints::vertexOrdering

Indicates how the vertices of faces are ordered.

CLOCKWISE ordering means that the vertices of each face form a clockwise loop around the face, when viewed from the outside (the side toward which the normal points). Use enum VertexOrdering. Default is UNKNOWN_ORDERING.

Definition at line 265 of file SoShapeHints.h.

◆ windingType

SoSFEnum SoShapeHints::windingType

Indicates the winding rule used to define holes in a polygon.

It is used by SoIndexedFaceSet and SoFaceSet to determine which parts of the polygon are on the interior and which are on the exterior and should not be filled. By default this field value is NO_WINDING_TYPE, that is, no winding rules are used, so there are no holes. Use enum WindingType.

For a single contour, the winding number of a point is the signed number of revolutions we make around that point while traveling once around the contour (where a counterclockwise revolution is positive and a clockwise revolution is negative). When there are several contours, the individual winding numbers are summed. This procedure associates a signed integer value with each point in the plane. Note that the winding number is the same for all points in a single region.

The following figure shows three sets of contours and winding numbers for points inside those contours. In the left set, all three contours are counterclockwise, so each nested interior region adds one to the winding number. For the middle set, the two interior contours are drawn clockwise, so the winding number decreases and actually becomes negative.

br

The winding rule classifies a region as inside if its winding number belongs to the chosen category (odd, nonzero, positive, negative, or "absolute value of greater than or equal to two"). The odd and nonzero rules are common ways to define the interior. The positive, negative, and "absolute value>=2" winding rules have some limited use for polygon CSG (computational solid geometry) operations. The four sets of contours shown in the following figure are used with different winding rule properties to see their effects. For each winding rule, the dark areas represent interiors. Note the effect of clockwise and counterclockwise winding.

br

NOTE: In LINES drawing style (see SoDrawStyle), if windingType is not NO_WINDING_TYPE, or if faceType is UNKNOWN_FACE_TYPE, the edges of the tessellated triangles will be drawn.

NOTE: field available since Open Inventor 4.0

Definition at line 323 of file SoShapeHints.h.


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