Chapter 2. Incompatible API Changes

The 2.1 release of Open Inventor provides significant performance enhancements over previous releases. In some cases an infrequently used feature was slowing down rendering, even when the feature wasn't being used. In Open Inventor 2.1, some of those features have therefore been slightly modified and some have been removed altogether.

This chapter helps you find these incompatible changes, providing the following information:

Note: This chapter only lists incompatible API changes. For additions to the API, see Chapter 4, “New Features.”

Overview of Changes By Class Name

This section provides an overview of the incompatible API changes. If you're using the online version of this manual, you can access a change description directly by clicking on it:

Changes to Shape Hints

  • SoShapeHintscreaseAngle default value changed.

    The creaseAngle field is used when default normals are generated. The default value has been changed from 0.5 radians to 0.0 radians. As a result, default normals are generated faster and use less memory. However, objects that were smoothly shaded by default by previous versions of Inventor will have faceted normals in Inventor 2.1.

  • SoShapeHints, SoDrawStyle, SoClipPlane—Wireframe and clipped objects behavior changed.

    Drawing in wireframe mode (using the SoDrawStyle node) or clipped mode (using SoClipPlane nodes) no longer turns off SOLID SoShapeHints; clipped or wireframe objects have backfaces removed if the appropriate SoShapeHints value is specified.

  • SoShapeHints, SoCube, SoCone, SoSphere, SoCylinder—Primitive shapes behavior changed.

    The primitive shapes (SoCube, SoCone, SoSphere, SoCylinder) no longer automatically turn on shapeType = SOLID and vertexOrdering = COUNTERCLOCKWISE on SoShapeHints nodes. You must insert an SoShapeHints node at the top of your scenes to get the old primitive behavior. Note that if you don't insert an SoShapeHints node, backface culling is disabled. This may slow down the frame rate.

    On the other hand, you can now specify an SoShapeHints node of shapeType = UNKNOWN_SHAPE_TYPE and vertexOrdering = COUNTERCLOCKWISE if you want both the interior and exterior surfaces of primitive shapes to be lit. If you only want the inside of the object lit, for example if the viewer is always inside a sphere, you can specify an SoShapeHints node with shapeType = SOLID and vertexOrdering = CLOCKWISE.

Changes to Complexity

  • SoComplexity, nodes derived from SoVertexShape—Geometry is no longer dropped for complexity values smaller than 0.5.

    When you applied complexity values of less than 0.5 to triangle strips and other vertex-based shapes in Inventor 2.0, some of the geometry was dropped (for example, alternate strips were deleted from a triangle strip set). In Inventor 2.1 this no longer happens. No geometry is deleted from such shapes because this was not an effective way of speeding up the rendering of complex shapes.

  • SoComplexity, SoTexture2textureQuality field behavior changed.

    The textureQuality field of the SoComplexity node now takes effect only when the next SoTexture2 node is traversed, not immediately as in Inventor 2.0. As a result, mipmap creation for an SoTexture2 node can be avoided if the texture quality is low enough. If you arranged your scene graphs so that the textureQuality field of SoComplexity followed the SoTexture2 nodes, re-arrange them so that the SoComplexity node is traversed first.

  • SoComplexity, SoTexture2—Default texture quality is point sampling on some systems.

    On systems that do not provide hardware support for texture mapping, the default textureQuality field is interpreted to mean point sampling of the texture, and mipmaps are not used.

  • SoComplexity, SoTexture2—Textures sometimes use only 12 bits of color.

    If textureQuality is less than 0.8, only 12 bits of texture color is used (instead of 24) on systems that support the OpenGL texture extension (EXT_texture). This increases the fill rate but decreases visual quality.

Changes to Materials and Colors

  • SoMaterial—Multiple materials support changed.

    Open Inventor 2.1 no longer supports multiple values for the following properties specified in an SoMaterial node:

    • ambientColor

    • specularColor

    • emissiveColor

    • shininess

    Open Inventor 2.1 continues to support multiple values for:

    • diffuseColor

    • transparency

    If you provide multiple transparencies, you must provide as many transparencies as diffuse colors. If you provide just one transparency, it applies to all materials in the shape.

    For backward compatibility, the field types for ambientColor, specularColor, emissiveColor, and shininess, have not changed. They are still SoMF- fields.

    Note that the new SoVertexProperty node provides explicit support (and accelerated performance) for changing diffuse color and transparency within a shape.

  • SoMaterialIndex—Obsolete.

    The SoMaterialIndex node is no longer supported. For indexed color rendering, use the SoColorIndex node instead.

  • SoColorIndex, SoLightModel—Indexed colors with PHONG light model no longer supported.

    The PHONG light model is no longer supported with indexed colors. Indexed colors can still be used with BASE_COLOR lighting.

  • SoPackedColor—Field for storing packed colors changed.

    The field for storing packed colors in the SoPackedColor node has been changed to be more compatible with OpenGL. The field name is now orderedRGBA, and the packing order is 0xrrggbbaa, where aa represents the alpha value, and rr, gg, and bb represent the red, green, and blue components of the color, respectively. In previous releases, the field name was rgba and the packing order was 0xaabbggrr.

  • SoPackedColorgetPackedValue(), setPackedValue() methods changed.

    The getPackedValue() and setPackedValue() methods on the SbColor class have changed.

    • getPackedValue() now takes a transparency value to pack with the color.

    • setPackedValue() returns a transparency value along with the SbColor. The transparency value, like the transparency field in SoMaterial, ranges from 0.0 to 1.0, where 0.0 is fully opaque, and 1.0 is fully transparent.

  • SoMaterialBinding, SoMaterial—Correct number of diffuse colors required.

    Open Inventor 2.1 assumes the correct number of diffuse colors is specified. When the material binding of a vertex-based shape is not OVERALL, provide one diffuse color for each vertex, face, or part, depending on whether PER_VERTEX, PER_FACE, or PER_PART binding is used. If you don't provide enough diffuse colors, you may see unexpected results. Note that in previous releases, Inventor cyclically reused the colors provided.

  • SoMaterialBinding, SoMaterial—Correct number of transparencies required.

    If not enough transparencies are provided, the first one is used.

  • SoMaterialBinding—DEFAULT and NONE bindings obsolete.

    The DEFAULT and NONE material bindings are obsolete. Files containing these bindings are transparently upgraded as if they specified OVERALL materials. Applications that use DEFAULT or NONE continue to work, unless they are compiled with -DIV_STRICT.

Changes to Normals

  • SoNormal—Default normal no longer provided.

    In previous releases, an SoNormal node contained one normal by default. In Open Inventor 2.1 the default is not to provide any normals.

  • SoNormalBinding, SoNormal—Correct number of normals required.

    If any normals are provided in a scene, Open Inventor 2.1 assumes the correct number is specified. There should be one normal for each shape, part, face, or vertex, depending on whether the normal binding is specified as OVERALL, PER_PART, PER_FACE, or PER_VERTEX.

  • SoNormalBinding, SoNormal—Normals generated automatically.

    In previous releases, normals were automatically generated only if the normal binding was DEFAULT. In Open Inventor 2.1, normals are always automatically generated if they are needed and if the user does not provide any normals in the scene. The correct number of normals is generated, depending on the normal binding.

  • SoNormalBinding—DEFAULT and NONE bindings obsolete.

    The DEFAULT and NONE normal bindings are obsolete. Files containing these bindings are transparently upgraded as if they specified PER_VERTEX_INDEXED normals. Applications that use the DEFAULT or NONE enums continue to work, unless they are compiled with -DIV_STRICT.

Changes to Texture Coordinates

  • SoTextureCoordinate2—Default texture coordinate no longer provided.

    In previous releases, an SoTextureCoordinate2 node contained one texture coordinate by default. In Open Inventor 2.1 the default is not to provide any texture coordinates at all.

  • SoTextureCoordinate2—Automatic generation of texture coordinates as needed.

    In Open Inventor 2.1, texture coordinates are always automatically generated if they are needed and no texture coordinates are provided in the scene.

  • SoTextureCoordinate2—Correct number of texture coordinates required.

    If any texture coordinates are provided in a scene, Open Inventor 2.1 assumes there is one for each vertex. You will see unexpected results if there are fewer texture coordinates than Inventor expected.

  • SoTextureCoordinateBinding—DEFAULT binding obsolete.

    The DEFAULT for the SoTextureCoordinateBinding node is obsolete. You can still specify PER_VERTEX or PER_VERTEX_INDEXED.

Changes to Vertex-Based Shapes

  • Shapes derived from SoNonIndexedShapestartIndex field obsolete.

    The startIndex field of a vertex-based shape is replaced by the new SoVertexProperty node.

    Previously you could specify the vertex properties for multiple shape nodes with one set of property nodes by having a different startIndex for each shape. However, a nonzero startIndex field may not work as expected when used with coordinates in an SoVertexProperty node. Furthermore, confusion arises if some of the vertex properties come from the vertexProperty field of the shape and others are inherited from nodes in the scene.

    To facilitate transition from Inventor 2.0, Inventor 2.1 continues to support use of startIndex when all vertex properties are specified in the state. You are urged to remove dependencies on this capability.

  • Shapes derived from SoNonIndexedShape—USE_REST_OF_VERTICES not fully supported.

    In previous releases, when a value of -1 was found in the numVertices field of non-indexed shapes—for example, SoTriangleStripSet—all the remaining values in the current coordinates were used. In Inventor 2.1, this is not supported when the coordinates are specified through the new vertexProperty field of the shape. Inventor 2.1 continues to support the use of -1 for numVertices when the coordinates are specified in the inherited state. You are urged to remove dependencies on the old behavior.

Changes to Viewers

The following changes to viewers were made in Inventor 2.1:

  • SoXtViewer—Texture mapping interactive draw style change.

    On systems that do not have hardware support for texture mapping, the viewers now by default set the interactive draw style to move without textures. In other words, by default, the viewers show the texture on these systems when the camera is not moving, but when you interact with the camera, the texture is disabled. Use the setDrawStyle() method of the SoXtViewer class to change the viewer draw style. End users of the viewer can change the draw style using the right-mouse popup menu.

  • SoXtPlaneViewer, SoXtExamineViewer, SoXtWalkViewer—Key bindings changed.

    The key bindings for the three viewers have changed to make them more consistent with each other and to match WebSpace Navigator Viewers.

The new bindings for SoXtPlaneViewer are the following:



Left mouse

Zoom in and out.

Ctrl + left mouse
Middle mouse

Translate up, down, left, right.

Ctrl + middle mouse

Rotate around the viewer in forward direction (roll action).

<s> click

Alternative to Seek button. Press (but don't hold) the <s> key, then click on a target object.

Left mouse

Zoom in and out.

Ctrl + left mouse,
Middle mouse

Translate up, down, left, right.

Right mouse

Open pop-up menu.

The key bindings for SoXtExaminerViewer have changed to be the following:



Left mouse

Tumbles the virtual trackball.

Middle mouse

Ctrl + left mouse

Translate up, down, left, and right

Ctrl + middle mouse
Left and middle mouse

Zoom in and out.

<s> click

Alternative to Seek button. Press (but don't hold) the <s> key, then click on a target object.

Right mouse

Open pop-up menu.

The key bindings for SoXtWalkViewer have changed to be the following:



Left mouse

Walk mode. Hold the mouse button and move up/down for forward/backward motion. Move right and left for turning. Speed increases exponentially with the distance from the mouse-down origin.

Ctrl + left mouse
Middle mouse

Translate up, down, left, right.

Ctrl + middle mouse

Tilt the camera up/down and right/left. This lets you look around while stopped.

<s> click

Alternative to Seek button. Press (but don't hold) the <s> key, then click on a target object.

<u> click

Press (but don't hold) the <u> key, then click on a target object to set the up direction to the surface normal. By default, positive y is the up direction.

Right mouse

Open pop-up menu.

Miscellaneous Changes

  • All nodes—Limited support for Override flag.

    In Open Inventor 2.1, not all of the nodes support the Override flag. The following nodes do support override:

    • SoColorIndex

    • SoComplexity

    • SoDrawStyle

    • SoFont

    • SoLightModel

    • SoMaterial

    • SoMaterialBinding

    • SoPackedColor

    • SoPickStyle

    • SoShapeHints

    • SoTexture2

    Other node classes ignore the Override flag. Note that you can still set the flag for those classes, but it has no effect.

    An Override flag on an SoMaterial node also overrides the diffuseColor and transparency fields of SoVertexProperty nodes (in the scene graph or in the vertexProperty field of shapes). Likewise an Override flag in a SoMaterialBinding node overrides the materialBinding field in a vertex property node. However, you cannot override just the diffuse color or just the transparency. If you override one, the other is obtained from the state when the override occurs.

  • SoOutputisASCIIHeader() and isBinaryHeader() no longer supported.

    The SoOutput methods isASCIIHeader() and isBinaryHeader() are no longer supported. Use SoDB::isValidHeader() to verify that a header is valid, or SoDB::getHeaderData() to see if a particular header is for ASCII or binary files.

  • SoCallback, SoEventCallback—Reset required after making direct OpenGL calls.

    You must notify the Inventor material state management mechanism by calling SoGLLazyElement::reset() if you directly make any of the following OpenGL calls from a callback node:

    • glColor()

    • glMaterial()

    • glColorMaterial()

    • glEnable() or glDisable(), with a GL_COLOR_MATERIAL, GL_BLEND, GL_LIGHTING, or GL_POLYGON_STIPPLE argument.


    After the last OpenGL call in your callback node, you must call SoGLLazyElement::reset(state, bitmask). The value of the bitmask depends on which of the above OpenGL calls you made.

    If you invoke glColor() or glMaterial(), logical-OR one or more of the following bitmasks as argument to SoGLLazyElement::reset() (depending on which components of the OpenGL material state you are altering):

    • SoLazyElement::DIFFUSE_MASK

    • SoLazyElement::EMISSIVE_MASK

    • SoLazyElement::SPECULAR_MASK

    • SoLazyElement::SHININESS_MASK

    • SoLazyElement::AMBIENT_MASK

    If you invoke glColorMaterial(), or enable or disable GL_COLOR_MATERIAL, the corresponding mask is SoLazyElement::COLOR_MATERIAL_MASK.

    If you enable or disable GL_BLEND, use SoLazyElement::BLENDING_MASK.

    If you alter the GL stipple transparency, either with glEnable(), glDisable(), glPushAttrib(), or glPopAttrib(), use SoLazyElement::TRANSPARENCY_MASK.

    If you alter lighting, either with glEnable(), glDisable(), glPushAttrib(), or glPopAttrib(), use SoLazyElement::LIGHT_MODEL_MASK

  • SoLineHighlightRenderAction, SoBoxHighlightRenderAction, SoGLRenderAction—Constructor arguments changed.

    The constructor argument no longer takes useCurrentGLValues as an argument.

  • SoSFLong, SoMFLong, SoSFULong, SoMFULong—long changed to int32.

    The So*Long fields have been changed to So*Int32 fields as follows:

    • SoSFLong -> SoSFInt32

    • SoSFULong -> SoSFUInt32

    • SoMFLong -> SoMFInt32

    • SoMFULong -> SoMFUInt32

    You need to change your program to use the new fields, and to use the types int32_t and uint32_t, defined in inttypes.h in place of long and unsigned long. Use the longToInt32 utility program provided in the inventor_dev.src.sample subsystem to help you do this.

    To ease the transition, a typedef links the So*Long fields to SoInt32 fields and, where possible and feasible, methods taking arguments of type long are supported.

    Since the C++ compiler cannot distinguish overloaded functions by return type alone, some methods are no longer supported. If you compile your program with -DIV_STRICT, the So*Long fields cause a compile time error.

  • All draggers and manipulators—Control key change.

    All draggers and manipulators now use the <Ctrl><Meta> key where they used the <Alt> key in Inventor 2.0.