Compatibility Notes 9.0

Open Inventor 9.0 (January 2012) Older compatibility notes

Technical Overview

New classes

New Fields/Enums in Existing Nodes

Open Inventor

VolumeViz

MeshViz XLM

.NET API Specific

Java API Specific

Open Inventor 8.6 (July 2011)

Open Inventor 8.5 (March 2011)

Open Inventor 8.1 (February 2010)

Open Inventor 8.0 (May 2009)

Open Inventor 7.2 (October 2008)

Open Inventor 7.1 (April 2008)


Technical overview

Please at least glance through these compatibility notes so that you are not surprised by any differences in behavior between this release and the previous release.

You should always re-run CMake (if you are using it) after installing a new version of Open Inventor.
CMake generates project/make files with absolute paths that could refer to an older version of Open Inventor.

You should completely recompile existing applications after installing a new version of Open Inventor.
New versions of Open Inventor are source code compatible (unless noted in this document), but not binary compatible.

ReservoirViz is no longer supported or delivered.


New Classes

Open Inventor

SoInteractiveSwitch

SoMultiPathsSwitch

SoMultiSwitch

MeshViz XLM

MoScalarSet


New Fields/Enums in Existing Nodes

Open Inventor

  • New SoDB::processEvents() method allowing to process pending Open Inventor events.

VolumeViz

  • SoDataCompressor class now inherits from the SoTypedObject class


Open Inventor

  • Unix Static libraries are no longer delivered or supported.
  • SbColorRGBA behavior has been fixed as it used to use the alpha component as a transparency value. As this fix might change behavior of application that used to rely on this bug we have added an environement variable to revert the fix and potentially ease the transition to Open Inventor 9. To get back previous behavior set the OIV_COMPAT_COLOR_RGBA to TRUE.
  • SoStereoViewer There are new pure virtual methods that will cause build errors when compiling a new inheriting class.
  • SoBufferObject class now inherits from SoRefCounter:
    This allows applications to correctly manage data sharing and avoid data copying in many cases.
    This creates a major incompatibility in the API, because the SoBufferObject destructor is no longer accessible:
    • SoBufferObject cannot be instanciated on the stack anymore.

The following piece of code:

{
  SoCpuBufferObject cpuObj;
  cpuObj.map();
  …
  cpuObj.unmap();
}

Must be replaced by:

{
  SoRef<SoCpuBufferObject> cpuObj = new SoCpuBufferObject;
  cpuObj->map();
  …
  cpuObj->unmap();
}

  • Deletion of SoBufferObject must be done through the ref/unref mechanism

The following piece of code:

{
 SoCpuBufferObject* cpuObj = new SoCpuBufferObject;
  cpuObj->map();
  …
  cpuObj->unmap();
  delete cpuObj;
}

Must be replaced by:

{
  SoRef<SoCpuBufferObject> cpuObj = new SoCpuBufferObject;
  cpuObj->map();
  …
  cpuObj->unmap();
}

Or:

{
  SoCpuBufferObject* cpuObj = new SoCpuBufferObject;
  cpuObj->ref();
  cpuObj->map();
  …
  cpuObj->unmap();
  cpuObj->unref();
}

VolumeViz

General

  • LDM format files with border > 0 (overlapping tiles) are no longer supported!
    All LDM files with border > 0 must be re-converted with no border.
    Note that you can use the new LDM Converter option "-update" to convert directly from LDM to LDM format, for example:
    LDMConverter oldFile.ldm -o newFile.ldm –update
  • VolumeViz "Paging mode" is no longer supported.
  • 2D texture storage is no longer supported
    (you need OpenGL and GLSL 3D texture support for Volumeviz to work).
    As a side-effect, the storageHint field of SoVolumeData is now deprecated.

VolumeViz editing

  • In previous version, when doing multiple edits of the same data in the volume, undo was possible only for the last editing request. This limitation has been removed.  Therefore the following method is no longer needed and has been removed :
    SoVolumeData::setNotifyOnMultiEdit(const bool flag);
     
  • In order to provide a more consistent API and avoid misinterpretation, the following methods were renamed:
    SoVolumeData::writeTile => SoVolumeData::editTile
    SoVolumeData::writeSubVolume => SoVolumeData::editSubVolume

VolumeViz GLSL shader pipeline

The VolumeViz shader API has been significantly reorganized. There are very nice improvements as a result, including

  • On the GPU, all the data for the volume is managed as a single “virtual texture”. 
    So tile boundaries no longer exist and a shader may freely access any voxel anywhere in the volume.
  • It is now possible to write a single shader that works for both slice primitives and volume rendering.
  • “Forward declarations” to use VolumeViz shader API functions are simplified using header files and a new “//!include” directive.

However, as a result most existing shaders must be updated:

  • Fragment “main” should not be replaced
  • Shaders must not access data textures directly
  • Shaders must not make any assumptions about how data is stored on the GPU
  • Some shader API uniforms are removed (details below)
  • Some shader API functions are replaced (details below)

Changes regarding the custom shader slots that are customizable:

  • SoVolumeShader::shaderPosition::VERTEX_MAIN
    We strongly recommend not to redefine this method.
    For computing specific varying attributes to pass to the fragment shader you should use the new pipeline slot named: SoVolumeShader::shaderPosition::VERTEX_POSTPROCESSING.
    Note: Defining a custom GEOMETRY_MAIN slot is only supported for compatibility. It is not compatible with the raycasting volume rendering technique that is now the default for SoVolumeRender. If you must use this slot, set the raycasting field to FALSE.
     
  • SoVolumeShader::shaderPosition::FRAGMENT_MAIN
    We strongly recommend not to redefine this method.
    For computing specific color effect or to create a co-blending effect you should use the new pipeline slot named SoVolumeShader::shaderPosition::FRAGMENT_COMPUTE_COLOR.
    Note: Defining a custom FRAGMENT_MAIN slot is only supported for compatibility. It is not compatible with the raycasting volume rendering technique that is now the default for SoVolumeRender. If you must use this slot, set the raycasting field to FALSE.
     
  • Custom shaders can be set in any slot starting at the CUSTOM_SHADER position.
    Previously the documentation said that they started at FRAGMENT_MAIN+1 position.
     
  • Shader filenames with "vviz" prefix are reserved for VolumeViz.
    If an application sets a public slot with such a name, the file will be ignored.
     

The following fragment shader methods are changed:

  • VVizGetData method
    • VVIZ_DATATYPE VVizGetData(sampler3D tex, vec3 tcoord)
      This method does not exist anymore.
      This method retrieved the voxel at the given coordinates.
      It may apply interpolation (cubic, linear...) according to the settings of the SoVolumeRenderingQuality and SoVolumeRender nodes.
       
    • VVIZ_DATATYPE VVizGetData(sampler2D tex, vec2 tcoord)
      This method does not exist anymore.
      This was the 2D version of VVizGetData for slices and volume skin nodes.
       
    • The new prototype is now common to 2D and 3D shapes, and the storage is opaque by using VVizDataSetID. dataCoord is the uniform coordinates in Volume space:
      VVIZ_DATATYPE VVizGetData(in VVizDataSetId dataset, in vec3 dataCoord);
       
  • VVizCombineData method
    • VVIZ_DATATYPE VVizCombineData(vec2 tcoord)
      This method does not exist anymore.
       
    • Only VVIZ_DATATYPE VVizCombineData(vec3 dataCoord) is available taking datacoord in uniform volume space for 2D as well as 3D shapes.
       
  • VVizComputeCoordinates method
    • vec2 VVizComputeCoordinates(const vec2)
      This method does not exist anymore.
      This method computed voxel coordinates for 2D shapes (slices, volume skin...) and had to be used instead of gl_TexCoord[0].xy.
       
    • Only vec3 VVizComputeCoordinates(in vec3 dataCoord) is available taking datacoord in uniform volume space for 2D as well as 3D shapes and returning coordinates in same space.
       

The following uniforms are no longer provided:

  • VVizVolumeDimensions: vec3 containing volume dimensions in voxels.
    This information is now available by calling the method vec3 VVizGetVolumeDimensions(in VVizDataSetId);
     
  • VVizTileDimensions: vec3 containing tile dimensions in voxels.
    This information is now available by calling method vec3 VVizGetTileDimensions (in VVizDataSetId);
     
  • VVizTileMinIJK: vec3 containing tile minimum coordinate in voxels.
  • VVizTileMaxIJK: vec3 containing tile maximum coordinate in voxels.
    This information can be retrieved by the following piece of code:
vec3 tileMinIJK;
vec3 tileMaxIJK;
 VVizGetTileIJKBox(in VVizDataSetId, in vec3 dataCoord, out vec3 tileMinIJK, out vec3 tileMaxIJK);

  • VvizDu: vec3 containing the minimum value to add to texture coordinates in order to move to the next voxel along X.
  • VvizDv: vec3 containing the minimum value to add to texture coordinates in order to move to the next voxel along Y.
  • VvizDw: vec3 containing the minimum value to add to texture coordinates in order to move to the next voxel along Z.
    This information can be retrieved by the following piece of code:
 vec3 vox elDim = VVizGetVoxelDimensions(dataset);
vec3 VVizDu = vec3(voxe lDim[0], 0.0, 0.0);
vec3 VVizDv = vec3(0.0, voxelDim[1], 0.0);
vec3 VVizDw = vec3(0.0, 0.0, voxelDim[2]);

DICOM Data

  • SoVRDicomData::getDicomInfo() now returns SbString instead of char*.
    This change simplifies the memory management. The string is owned by the application.

MeshViz XLM (C++ api only)

The interface MiExtractorCallback has been changed and is no longer compatible.

It has been changed to allow an application to implement a progress bar during the extraction process. Any application that calls MoMeshRepresentation::setExtractorCallback(MiExtractorCallback &extractorCallback) must change the implementation of this interface. Compile errors will occur on new methods added to the interface:
  • beginExtract() => replaces the method beginCallback()
  • endExtract() => replaces the method endCallback()
  • beginPhase()
  • endPhase()
  • endStep()
  • getEndStepCallPeriod ()

The following method has been removed: that will not produce any compile error but the implementation in the application will never be called.

  • beginCallback(): the implementation in the application should be renamed beginExtract
  • endCallback():  the implementation in the application should be renamed endExtract

Any application using either MoCustomColorMapping, MoLevelColorMapping or MoLinearColorMapping may be impacted by fix of SbColorRGBA from bug 3999. As a result the transparency property of every MeshViz shape using contouring is reverted. Setting the OIV_COMPAT_COLOR_RGBA environment variable to TRUE restores the previous behaviour.


.NET API Specific

New Fields/Enums in existing nodes.

  • SoSFEnum
  • SoMFEnum
  • SoSFBitMask
  • SoMFBitMask

These fields are now generic and typed with the relevant enum type. That enables the auto completion mechanism in Visual Studio and automatic links to the reference manual between a field and its possible enumerated values. Setting or getting the field value using the Set/GetValue() methods is now deprecated.

So the following deprecated code:

mySep.renderCaching.SetValue((int)SoSeparator.Cachings.AUTO);
SoSeparator.Cachings renderCaching = (SoSeparator.Cachings)mySep.renderCaching.GetValue();

Should be replaced by:

mySep.renderCaching.Value = SoSeparator.Cachings.AUTO;
SoSeparator.Cachings renderCaching = mySep.renderCaching.Value;

The new Extension class OIV.Inventor.EnumerationExtensions defines convenient methods HasFlag(), IsFlag(), AddFlag() and RemoveFlag() for bitmask enums.

New methods/properties in existing classes.

  • New method ToString() in SbXXX classes, SoMField classes and SoBase classes.
    For SbBox, SbColor, SbCylinder, SbLine, SbPlane, SbRotation, SbSphere and SbVecXXX, ToString() returns each component as string.
    For SoMField ToString() returns the number of elements as string.
    For SoBase ToString() returns the native getName() as string.
  • New method CanGetBuffer() in SbNativeArray<T>:
    CanGetBuffer() indicates whether the buffer can be get or not.
    Indexer may now throw the NotSupportedException if the array cannot be read or written.
  • New property Value in SoSFfield to set/get its value.
    This is equivalent to the Set/GetValue() methods that are now deprecated.
    So the following deprecated code:
 mySoFFloat.SetValue(myOtherField.GetValue());

Should be replaced by:

mySoFFloat.Value  = myOtherField.Value;
  • New ArgumentOutOfRange checking for some methods having invalid index argument as input.
    A method having an integer argument defined in a limited range throws the exception System::ArgumentOutOfRangeException if the given argument is out of this range. See for instance methods GetChild, RemoveChild, InsertChild, ReplaceChild of SoGroup or methods SetValues, Set1Values of SoMField.
    Example:
SoGroup myGroup = new SoGroup(); // new empty group
myGroup.AddChild(new SoCone());  // myGroup has one child
myGroup.RemoveChild(1);          // throws ArgumentOutOfRangeException as myGroup contains only one child

Removed methods.

  • Previous unsafe Dispose() methods have been removed.
    The Dispose method is now only available in classes derived from the new class SoDisposable that implements ISafeDisposable.
    Each class derived from new SoDisposable is associated to a native class derived from the C++ SoRefCounter class.

IvTune

  • To be able to start IvTune from a viewer with the Shift+F12 shortcut, you need to reference the OIV.IvTune assembly.

Java API Specific

  • Native distribution on Windows.
    The native dlls of OpenInventor are built and linked with Microsoft Visual C++ 2010.
    The corresponding redistributable exec (vcredist_86|vcredist_x64.exe) is delivered in $OIVJHOME/jre/bin.
    Any application that includes native code using the OpenInventor C++ API, should re-compile it with Microsoft Visual C++ 2010.
  • ReservoirViz is removed.
    packages com.openinventor.reservoirviz.* are no longer available
  • Packages com.mc.* are now deprecated.
    We strongly recommand to use com.openinventor.* packages.
  • The method com.openinventor.inventor.dispose() is now deprecated.
    This method should not be used anymore and will be removed in a future version. Calling dispose() should be reserved on classes implementing the new interface com.openinventor.inventor.SafeDisposable.
  • See API Compatibility for details