[occt.git] / dox / dev_guides / upgrade / upgrade.md

Upgrade from older OCCT versions  {#occt_dev_guides__upgrade}
================================

@tableofcontents

@section upgrade_intro Introduction

This document provides technical details on changes made in particular versions of OCCT, and is aimed to help upgrading user applications based on previous versions of OCCT to newer ones.

@subsection upgrade_intro_precautions Precautions

Back-up your code before upgrade.
We strongly recommend using version control system during upgrade process, saving one or several commits for each step of upgrade, until overall result is verified.
This will facilitate identification and correction of possible problems that can occur on intermediate steps of upgrade.
Carefully document each step to be able to repeat it if necessary.

@subsection upgrade_intro_disclaim Disclaimer

This document describes known issues that have been encountered in porting of OCCT and some applications, and approaches that helped to resolve these issues in known cases.
It does not pretend to cover all possible migration issues that can appear in your application.
Please take this document with discretion; apply your expertise and knowledge of your application to ensure correct result. 

The automatic upgrade tool is provided as-is, without warranty of any kind, and we explicitly disclaim any liability for possible errors that may appear due to use of this tool. 
It is your responsibility to ensure that the changes you made in your code are correct. 
When upgrading your code by automatic script, make sure to carefully review the changes made by it, on each step, before committing them.

@section upgrade_700 Upgrade to OCCT 7.0.0

@subsection upgrade_700_persist Removal of legacy persistence

Legacy persistence for shapes and OCAF data based on Storage_Schema (toolkits TKShapeShcema, TLStdLSchema, TKStdSchema, TKXCAFSchema) has been removed in OCCT 7.0.0.
Applications that used these persistence tools for their data need to be updated to use other persistence mechanisms.

The existing data files in standard formats can be converted using OCCT 6.9.0 or previous version, as follows.

#### CSFDB files

Files in CSFDB format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format. 
The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):

- Start ImportExport sample
- Select File / New
- Select File / Import / CSFDB... and specify the file to be converted
- Drag mouse with right button pressed across the view to select all shapes by rectangle
- Select File / Export / BREP... and specify location and name for the resulting file

#### OCAF and XCAF documents

Files containing OCAF data saved in old format usually have extensions .std or .sgd or .dxc (XDE documents).
These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands available in OCCT 6.9.0 or earlier.

For that, start *DRAWEXE* and perform the following commands: 

  * for the conversion of the "*.std" and "*.sgd" file formats to the binary format "*.cbf" (Created document should be in **BinOcaf** format instead of **MDTV-Standard**):

  @code
  Draw[]> pload ALL
  Draw[]> Open [path to *.std or *.sgd file] Doc
  Draw[]> Format Doc BinOcaf
  Draw[]> SaveAs Doc [path to the new file]
  @endcode

  * for the conversion of the "*.dxc" file format to the binary format "*.xbf" (Created document should be in **BinXCAF** format instead of **MDTV-XCAF**):

  @code
  Draw[]> pload ALL
  Draw[]> XOpen [path to *.dxc file] Doc
  Draw[]> Format Doc BinXCAF
  Draw[]> XSave Doc [path to the new file]
  @endcode

On Windows, be careful to replace back slashes in the file path by either direct slash or pairs of back slashes.
Use "XmlOcaf" or "XmlXCAF" instead of "BinOcaf" and "BinXCAF", respectively, to save in XML format instead of binary one.

@subsection upgrade_occt700_cdl Removal of CDL and WOK

OCCT code has been completely refactored in version 7.0 to get rid of obsolete technologies used since its inception: CDL (Cas.Cade Definition Language) and WOK (Workshop Organization Kit).
C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.

This modification did not change names, API, and behavior of existing OCCT classes, thus in general the code based on OCCT 6.x should compile and work fine with OCCT 7.0.
However, due to redesign of basic mechanisms (CDL generic classes, Handles and RTTI) using C++ templates, some changes may be necessary in the code when porting to OCCT 7.0, as described below.

WOK is not necessary anymore for building OCCT from sources, though it still can be used in traditional way -- auxiliary files required for that are preserved.
The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
Alternative solution is to use legacy generator of project files (extracted from WOK), see @ref occt_dev_guides__building_wok.

@subsubsection upgrade_occt700_cdl_auto Automatic upgrade

Most of typical changes required for upgrading code to use OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
This tool is a Tcl script, thus Tcl should be available on your workstation to run it.

Example:
~~~~~
 $ tclsh
 % source <path_to_occt>/adm/upgrade.tcl
 % upgrade -recurse -all -src=<path_to_your_sources>
~~~~~

On Windows, helper batch script upgrade.bat can be used, provided that Tcl is either available in PATH, or configured via custom.bat script (for instance, if you use OCCT installed from Windows installer package). Start it from command prompt:

~~~~~
cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
~~~~~

Run upgrade tool without arguments to see the list of available options.

Upgrade tool performs the following changes in the code.

1. Adds second argument to macro DEFINE_STANDARD_RTTI indicating base class for its argument class (if inheritance is recognized by the script):
~~~~~
DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTI(Class, Base)
~~~~~

2. Replaces forward declarations of collection classes previously generated from CDL generics (defined in TCollection package) by \#include of corresponding header:
~~~~~
class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
~~~~~

3. Replaces underscored names of Handle classes by usage of a macro:
~~~~~
Handle_Class -> Handle(Class)
~~~~~
  This change is not applied if source or header file is recognized as containing definition of Qt class with signals or slots, to avoid possible compilation errors of MOC files caused by inability of MOC to recognize macros (see http://doc.qt.io/qt-4.8/signalsandslots.html).
  The file is considered as defining Qt object if it contains strings "Q_OBJECT" and either "slots:" or "signals". 

4. Removes forward declarations of classes with names Handle(C) or Handle_C, replacing these either by forward declaration of its argument class, or (for files defining Qt objects) \#include statement for header with name of the argument class and extension .hxx:
~~~~~
class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
~~~~~

5. Removes \#includes of files Handle_...hxx disappeared in OCCT 7.0:
~~~~~
#include <Handle_Geom_Curve.hxx> ->
~~~~~

6. Removes typedef statements that use Handle macro to generate name:
~~~~~
typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
~~~~~

7. Converts C-style casts applied to Handles to calls to DownCast() method:
~~~~~
    ((Handle(A)&)b)     -> Handle(A)::DownCast(b)
    (Handle(A)&)b       -> Handle(A)::DownCast(b)
    (*((Handle(A)*)&b)) -> Handle(A)::DownCast(b)
    *((Handle(A)*)&b)   -> Handle(A)::DownCast(b)
    (*(Handle(A)*)&b)   -> Handle(A)::DownCast(b)
~~~~~

8. Moves Handle() macro out of namespace scope:
~~~~~
Namespace::Handle(Class) -> Handle(Namespace::Class)
~~~~~

9. Converts local variables of reference type initialized by temporary object returned by call to DownCast(), to non-references (to avoid using reference to destroyed memory):
~~~~~
    const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
~~~~~

10. Adds \#include for all classes used as argument to macro STANDARD_TYPE(), except of already included ones;

11. Removes uses of obsolete macros IMPLEMENT_DOWNCAST() and IMPLEMENT_STANDARD_*().

  > If you plan to keep compatibility of your code with older versions of OCCT, add option "-compat" to avoid the latter change. See also @ref upgrade_occt700_cdl_compat.

As long as the upgrade routine runs, some information messages are sent to the standard output. 
In some cases the warnings or errors like the following may appear:

~~~~~
  Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
~~~~~

Be sure to check carefully all reported errors and warnings, as corresponding places likely will require manual corrections.
In some cases these messages may help you to detect errors in your code, for instance, cases where DEFINE_STANDARD_RTTI macro passes invalid class name as an argument.

@subsubsection upgrade_occt700_cdl_compiler Possible compiler errors

Some situations requiring upgrade cannot be detected and / or handled by automatic procedure.
If you get compiler errors or warnings when trying to build upgraded code, you will need to fix them manually. 
The following paragraphs list known situations of this kind.

#### Missing header files

Use of handle objects (construction, comparison using operators == or !=, use of function STANDRAD_TYPE() and method DownCast()) now requires the type of the object pointed by Handle to be completely known at compile time. Thus it may be necessary to include header of the corresponding class to make the code compilable.

For example, the following lines will fail to compile if Geom_Line.hxx is not included:

~~~~~
Handle(Geom_Line) aLine = 0;
if (aLine != aCurve) {...} 
if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
aLine = Handle(Geom_Line)::DownCast (aCurve);
~~~~~

Note that it is not necessary to include header of the class to declare Handle to it.
However, if you define a class *B* that uses Handle(*A*) in its fields, or contains a method returning Handle(*A*), it is advisable to have header defining *A* included in the header of *B*.
This will eliminate the need to include the header *A* in each source file where class *B* is used.

#### Ambiguity of calls to overloaded functions

This issue appears in compilers that do not support default arguments in template functions (known cases are Visual C++ 10 and 11): compiler reports ambiguity error if handle is used in argument of call to function that has two or move overloaded versions, accepting handles to different types. 
The problem is that operator const handle<T2>& is defined for any type T2, thus compiler cannot make a right choice.

Example:
~~~~~
void func (const Handle(Geom_Curve)&);
void func (const Handle(Geom_Surface)&);

Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
func (aCurve); // ambiguity error in VC++ 10
~~~~~

To resolve this ambiguity, change your code so that argument type corresponds exactly to the function signature. 
In some cases this can be done by using relevant type for the corresponding variable, like in the example above:

~~~~~
Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);  
~~~~~

Other variants are assigning the argument to local variable of correct type, using direct cast or constructor:

~~~~~
const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
func (aGCurve); // OK - argument has exact type
func (static_cast(aCurve)); // OK - direct cast 
func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
~~~~~

Another possibility is defining additional templated variant of the overloaded function causing ambiguity, and use SFINAE to resolve the ambiguity.
For example of this technique, see definition of the template variant of the method IGESData_IGESWriter::Send().

#### Lack of implicit cast to base type

Due to the fact that now cast of handle to reference to handle to the base type is user-defined operation, conversions that require this cast combined with other user-defined cast will not be resolved automatically by compiler.

For example:

~~~~~
Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
~~~~~

The problem here is that class GCE2d_MakeSegment has user-defined conversion to const Handle(Geom_TrimmedCurve)&, which is not the same as type of the local variable aC.

To resolve this, use method Value():

~~~~~
Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
~~~~~

or use variable of appropriate type:

~~~~~
Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
~~~~~

#### Incorrect use of STANDARD_TYPE and Handle macros

You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().

1. Explicit definitions of static functions with names generated by macro STANDARD_TYPE(), which are artifacts of old implementation of RTTI, should be removed.
   
   Example:
~~~~~
const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
{
  static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
  return _atype;
}
~~~~~

2. Incorrect location of closing parenthesis of Handle() macro that was not detectable in OCCT 6.x will cause compiler error and must be corrected.

   Example (note misplaced closing parenthesis):
~~~~~
aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
~~~~~

#### Use of class Standard_AncestorIterator

Class Standard_AncestorIterator has been removed; use method Parent() of Standard_Type class to parse inheritance chain.

#### Absence of cast to Standard_Transient*

Handles in OCCT 7.0 do not have operator of conversion to Standard_Transient*, which was present in earlier versions.
This is done to prevent possible unintended errors like this:

~~~~~
Handle(Geom_Line) aLine = ...;
Handle(Geom_Surface) aSurf = ...;
...
if (aLine == aSurf) {...} // will cause compiler error in OCCT 7.0, but not OCCT 6.x
~~~~~

Places where this implicit cast has been used should be corrected manually.
The typical situation is when Handle is passed to stream:

~~~~~
Handle(Geom_Line) aLine = ...;
os << aLine; // in OCCT 6.9.0, resolves to operator << (void*) 
~~~~~

Call method get() explicitly to output address of the Handle.

@subsubsection upgrade_occt700_cdl_runtime Possible runtime problems

Known situations when problems are possible at run time after upgrade to OCCT 7.0 are listed here.

#### References to temporary objects

In previous versions, compiler was able to detect situation when local variable of reference type to Handle is initialized by temporary object, and ensured that lifetime of that object is longer than that of the variable. 
Since OCCT 7.0, it will not work if types of the temporary object and variable are different (due to involvement of user-defined type cast), thus such temporary object will be destroyed immediately.

Example:

~~~~~
// note that DownCast() returns new temporary object!
const Handle(Geom_BoundedCurve)& aBC =
Handle(Geom_TrimmedCurve)::DownCast(aCurve);
aBC->Transform (T); // access violation in OCCT 7.0
~~~~~

@subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x

If you like to preserve compatibility of your application code with OCCT versions 6.x even after upgrade to 7.0, consider the following suggestions:

1. When running automatic upgrade tool, add option *-compat*.

2. In order to overcome incompatibility of macro DEFINE_STANDARD_RTTI which has additional argument in OCCT 7.0, you can replace (after upgrade) its use in your code by your own version-dependent macro, which resolves to either 6.x or 7.x version.

   Example:
~~~~~   
#if OCC_VERSION_HEX < 0x070000
  #define DEFINE_STANDARD_RTTI_COMPAT(C1,C2) DEFINE_STANDARD_RTTI(C1) 
#else
  #define DEFINE_STANDARD_RTTI_COMPAT(C1,C2) DEFINE_STANDARD_RTTI(C1,C2) 
#endif
~~~~~

@subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK

If you have application essentially based on CDL, and need to upgrade it to OCCT 7.0, you will very likely need to convert your application code to non-CDL form.
This is non-trivial effort; the required actions would depend strongly on the structure of the code and used features of CDL.

The upgrade script and sources of specialized version of WOK used for upgrading OCCT code can be found in WOK Git repository in branch [CR0_700_2](http://git.dev.opencascade.org/gitweb/?p=occt-wok.git;a=log;h=refs/heads/CR0_700_2).

[Contact us](http://www.opencascade.com/contact/) if you need more help.

@subsection upgrade_occt700_bspline Separation of BSpline cache

Implementation of NURBS curves and surfaces has been revised: cache of polynomial coefficients, used to accelerate calculate values of B-spline, is separated from data objects (Geom2d_BSplineCurve, Geom_BSplineCurve, Geom_BSplineSurface), into dedicated classes (BSplCLib_Cache and BSplSLib_Cache). 

The benefits of this change are:

* Reduced memory footprint of OCCT shapes (up to 20% on some cases)
* Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks 

The drawback is that direct evaluation of B-Splines using methods of curves and surfaces becomes slower, due to absence of cache. The way to avoid slow down is to use adaptor classes (Geom2dAdaptor_Curve, GeomAdaptor_Curve and GeomAdaptor_Surface): they now use cache when the curve or surface is a B-spline.

OCCT algorithms are changed to use adaptors for B-spline calculations instead of direct methods of curves and surfaces.
The same changes (use of adaptors instead of direct call to curve and surface methods) should be implemented in relevant places in applications based on OCCT in order to get maximum performance.

@subsection upgrade_occt700_sorttools Removal of SortTools package

Package SortTools has been removed. 
The code that used the tools provided by that package should be corrected manually.
The recommended approach is to use sorting algorithms provided by STL.

For instance:
~~~~~
#include <SortTools_StraightInsertionSortOfReal.hxx>
#include <SortTools_ShellSortOfReal.hxx>
#include <TCollection_CompareOfReal.hxx>
...
TCollection_Array1OfReal aValues = ...;
...
TCollection_CompareOfReal aCompReal;
SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
~~~~~
can be replaced by:
~~~~~
#include <algorithm>
...
TCollection_Array1OfReal aValues = ...;
...
std::stable_sort (aValues->begin(), aValues->end());
~~~~~

@subsection upgrade_occt700_2dlayers New implementation of 2d-layers

In latest OCCT version API that provided old implementation of 2d-layers was removed. Classes Aspect_Clayer2d, OpenGl_GrahpicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr, V3d_LayerMgrPointer were deleted.

Now 2d-layers are implemented through Z-layers. In order to create a 2d-object it is necessary to follow several steps:
1. Create an AIS interactive object
2. Set a Z-layer for it to determine in which layer this object will be displayed (layer system provides order of displaying objects, ones in the lower layer will be displayed behind the others in the higher layer)
3. Set transform persistence (flag Graphic3d_TMF_2d or Graphic3d_TMF_2d_IsTopDown and a gp_Pnt point, where X and Y are used to set the coordinates’ origin in 2d space of the view and Z coordinate defines the gap from border of view window, except center position)

One more feature of new 2d-layers imlementation is a ColorScale based on  a new class AIS_ColorScale. Old implementation of ColorScale as a global property of V3d_View has been removed with associated methods V3d_View::ColorScaleDisplay(), V3d_View::ColorScaleErase(), V3d_View::ColorScaleIsDisplayed(), V3d_View::ColorScale() and classes V3d_ColorScale, V3d_ColorScaleLayerItem, Aspect_ColorScale.

New interactive object AIS_ColorScale provides the same configuration API as previously Aspect_ColorScale and V3d_ColorScale. It should be used in the following way to display a 2D presentation of ColorScale:

~~~~~
Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
// configuring
aCS->SetHeight            (0.95);
aCS->SetRange             (0.0, 10.0);
aCS->SetNumberOfIntervals (10);
// displaying
aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
aCS->SetToUpdate();
theContextAIS->Display (aCS);
~~~~~

To see how 2d objects are realized in OCCT you can call draw commands vcolorscale, vlayerline or vdrawtext (with -2d option). Draw command vcolorscale now requires a name of ColorScale object as an argument. To display this object use command vdisplay. Example:

~~~~~
pload VISUALIZATION
vinit
vcolorscale cs –demo
pload MODELING
box b 100 100 100
vdisplay b
vsetdispmode 1
vfit
vlayerline 0 300 300 300 10
vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
~~~~~

Here is a small example in c++ how to display a custom AIS object in 2d:
~~~~~
Handle(AIS_InteractiveContext) aContext = ...; //get AIS context
Handle(AIS_InteractiveObject) anObj =...; //create an AIS object
anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); //display object in overlay
anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); //set 2d flag, coordinate origin is set to down-left corner
aContext->Display (anObj); //display the object
~~~~~