0027193: Describe building OCCT with genproj tool
[occt.git] / dox / dev_guides / upgrade / upgrade.md
c6f11ec0 1Upgrade from older OCCT versions {#occt_dev_guides__upgrade}
d1a67b9d 6@section upgrade_intro Introduction
c6f11ec0 7
a3305c6e 8This document provides technical details on changes made in particular versions of OCCT. It can help to upgrade user applications based on previous versions of OCCT to newer ones.
c6f11ec0 9
d1a67b9d 10@subsection upgrade_intro_precautions Precautions
c6f11ec0 11
a3305c6e 12Back-up your code before the upgrade.
13We strongly recommend using version control system during the upgrade process and saving one or several commits at each step of upgrade, until the overall result is verified.
14This will facilitate identification and correction of possible problems that can occur at the intermediate steps of upgrade.
15It is advisable to document each step carefully to be able to repeat it if necessary.
d1a67b9d 16
17@subsection upgrade_intro_disclaim Disclaimer
a3305c6e 19This document describes known issues that have been encountered during porting of OCCT and some applications and approaches that have helped to resolve these issues in known cases.
d1a67b9d 20It does not pretend to cover all possible migration issues that can appear in your application.
a3305c6e 21Take this document with discretion; apply your expertise and knowledge of your application to ensure the correct result.
d1a67b9d 22
a3305c6e 23The 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.
d1a67b9d 24It is your responsibility to ensure that the changes you made in your code are correct.
a3305c6e 25When you upgrade the code by an automatic script, make sure to carefully review the introduced changes at each step before committing them.
d1a67b9d 26
27@section upgrade_700 Upgrade to OCCT 7.0.0
29@subsection upgrade_700_persist Removal of legacy persistence
c6f11ec0 30
a3305c6e 31Legacy persistence for shapes and OCAF data based on *Storage_Schema* (toolkits *TKShapeShcema, TLStdLSchema, TKStdSchema* and *TKXCAFSchema*) has been removed in OCCT 7.0.0.
32The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
c6f11ec0 33
a3305c6e 34The existing data files in standard formats can be converted using OCCT 6.9.0 or a previous version, as follows.
c6f11ec0 35
36#### CSFDB files
38Files in CSFDB format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format.
39The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):
a3305c6e 41- Start ImportExport sample;
42- Select File / New;
43- Select File / Import / CSFDB... and specify the file to be converted;
44- Drag the mouse with the right button pressed across the view to select all shapes by the rectangle;
45- Select File / Export / BREP... and specify the location and name for the resulting file
c6f11ec0 46
47#### OCAF and XCAF documents
a3305c6e 49Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
c6f11ec0 50These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands available in OCCT 6.9.0 or earlier.
52For that, start *DRAWEXE* and perform the following commands:
a3305c6e 54 * To convert <i>*.std</i> and <i>*.sgd</i> file formats to binary format <i>*.cbf</i> (The created document should be in *BinOcaf* format instead of *MDTV-Standard*):
c6f11ec0 55
56 @code
57 Draw[]> pload ALL
58 Draw[]> Open [path to *.std or *.sgd file] Doc
59 Draw[]> Format Doc BinOcaf
60 Draw[]> SaveAs Doc [path to the new file]
61 @endcode
a3305c6e 63 * To convert <i>*.dxc</i> file format to binary format <i>*.xbf</i> (The created document should be in *BinXCAF* format instead of *MDTV-XCAF*):
c6f11ec0 64
65 @code
66 Draw[]> pload ALL
67 Draw[]> XOpen [path to *.dxc file] Doc
68 Draw[]> Format Doc BinXCAF
69 Draw[]> XSave Doc [path to the new file]
70 @endcode
a3305c6e 72On Windows, it is necessary to replace back slashes in the file path by direct slashes or pairs of back slashes.
74Use *XmlOcaf* or *XmlXCAF* instead of *BinOcaf* and *BinXCAF*, respectively, to save in XML format instead of binary one.
c6f11ec0 75
d1a67b9d 76@subsection upgrade_occt700_cdl Removal of CDL and WOK
78OCCT 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).
a3305c6e 79
d1a67b9d 80C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.
82This 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.
83However, 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.
a3305c6e 85WOK is not necessary anymore for building OCCT from sources, though it still can be used in a traditional way -- auxiliary files required for that are preserved.
d1a67b9d 86The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
72c37458 87The alternative solution is to use project files generated by OCCT legacy tool **genproj**, see @ref occt_dev_guides__building_msvc, @ref occt_dev_guides__building_code_blocks, and @ref occt_dev_guides__building_xcode.
d1a67b9d 88
89@subsubsection upgrade_occt700_cdl_auto Automatic upgrade
f5f4ebd0 91Most of typical changes required for upgrading code for OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
d1a67b9d 92This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
96 $ tclsh
97 % source <path_to_occt>/adm/upgrade.tcl
98 % upgrade -recurse -all -src=<path_to_your_sources>
a3305c6e 101On Windows, the 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 the command prompt:
d1a67b9d 102
104cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
a3305c6e 107Run the upgrade tool without arguments to see the list of available options.
d1a67b9d 108
a3305c6e 109The upgrade tool performs the following changes in the code.
d1a67b9d 110
a3305c6e 1111. Replaces macro *DEFINE_STANDARD_RTTI* by *DEFINE_STANDARD_RTTIEXT*, with second argument indicating base class for the main argument class (if inheritance is recognized by the script):
d1a67b9d 112~~~~~
d1a67b9d 114~~~~~
a3305c6e 116 @note If macro *DEFINE_STANDARD_RTTI* with two arguments (used in intermediate development versions of OCCT 7.0) is found, the script will convert it to either *DEFINE_STANDARD_RTTIEXT* or *DEFINE_STANDARD_RTTI_INLINE*.
f5f4ebd0 117 The former case is used if current file is header and source file with the same name is found in the same folder.
a3305c6e 118 In this case, macro *IMPLEMENT_STANDARD_RTTI* is injected in the corresponding source file.
119 The latter variant defines all methods for RTTI as inline, and does not require *IMPLEMENT_STANDARD_RTTIEXT* macro.
f5f4ebd0 120
a3305c6e 1212. Replaces forward declarations of collection classes previously generated from CDL generics (defined in *TCollection* package) by inclusion of the corresponding header:
d1a67b9d 122~~~~~
123class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
a3305c6e 1263. Replaces underscored names of *Handle* classes by usage of a macro:
d1a67b9d 127~~~~~
128Handle_Class -> Handle(Class)
a3305c6e 130 This change is not applied if the source or header file is recognized as containing the 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).
131 The file is considered as defining a Qt object if it contains strings *Q_OBJECT* and either *slots:* or *signals:*.
d1a67b9d 132
a3305c6e 1334. Removes forward declarations of classes with names <i>Handle(C)</i> or *Handle_C*, replacing them either by forward declaration of its argument class, or (for files defining Qt objects) <i>\#include</i> statement for a header with the name of the argument class and extension .hxx:
d1a67b9d 134~~~~~
135class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
a3305c6e 1385. Removes <i> \#includes </i> of files <i>Handle_...hxx</i> that have disappeared in OCCT 7.0:
d1a67b9d 139~~~~~
140#include <Handle_Geom_Curve.hxx> ->
a3305c6e 1436. Removes *typedef* statements that use *Handle* macro to generate the name:
d1a67b9d 144~~~~~
145typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
a3305c6e 1487. Converts C-style casts applied to Handles into calls to <i>DownCast()</i> method:
d1a67b9d 149~~~~~
150 ((Handle(A)&)b) -> Handle(A)::DownCast(b)
151 (Handle(A)&)b -> Handle(A)::DownCast(b)
152 (*((Handle(A)*)&b)) -> Handle(A)::DownCast(b)
153 *((Handle(A)*)&b) -> Handle(A)::DownCast(b)
154 (*(Handle(A)*)&b) -> Handle(A)::DownCast(b)
a3305c6e 1578. Moves <i>Handle()</i> macro out of namespace scope:
d1a67b9d 158~~~~~
159Namespace::Handle(Class) -> Handle(Namespace::Class)
a3305c6e 1629. Converts local variables of reference type, which are initialized by a temporary object returned by call to <i>DownCast()</i>, to the variables of non-reference type (to avoid using references to destroyed memory):
d1a67b9d 163~~~~~
164 const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
a3305c6e 16710. Adds <i>\#include</i> for all classes used as argument to macro <i>STANDARD_TYPE()</i>, except for already included ones;
d1a67b9d 168
a3305c6e 16911. Removes uses of obsolete macros *IMPLEMENT_DOWNCAST* and *IMPLEMENT_STANDARD_*..., except *IMPLEMENT_STANDARD_RTTIEXT*.
f5f4ebd0 170
a3305c6e 171 @note If you plan to keep compatibility of your code with older versions of OCCT, add option <i>-compat</i> to avoid this change. See also @ref upgrade_occt700_cdl_compat.
d1a67b9d 172
f5f4ebd0 173.
d1a67b9d 174
175As long as the upgrade routine runs, some information messages are sent to the standard output.
176In some cases the warnings or errors like the following may appear:
179 Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
a3305c6e 182Be sure to check carefully all reported errors and warnings, as the corresponding code will likely require manual corrections.
183In some cases these messages may help you to detect errors in your code, for instance, cases where *DEFINE_STANDARD_RTTI* macro is used with incorrect class name as an argument.
d1a67b9d 184
185@subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
a3305c6e 187Some situations requiring upgrade cannot be detected and / or handled by the automatic procedure.
188If you get compiler errors or warnings when trying to build the upgraded code, you will need to fix them manually.
d1a67b9d 189The following paragraphs list known situations of this kind.
191#### Missing header files
a3305c6e 193The use of handle objects (construction, comparison using operators == or !=, use of function <i>STANDRAD_TYPE()</i> and method <i>DownCast()</i>) 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.
d1a67b9d 194
a3305c6e 195For example, the following lines will fail to compile if *Geom_Line.hxx* is not included:
d1a67b9d 196
198Handle(Geom_Line) aLine = 0;
199if (aLine != aCurve) {...}
200if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
201aLine = Handle(Geom_Line)::DownCast (aCurve);
204Note that it is not necessary to include header of the class to declare Handle to it.
205However, 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*.
206This will eliminate the need to include the header *A* in each source file where class *B* is used.
208#### Ambiguity of calls to overloaded functions
a3305c6e 210This issue appears in the compilers that do not support default arguments in template functions (known cases are Visual C++ 10 and 11): the compiler reports an ambiguity error if a handle is used in the argument of a call to the function that has two or move overloaded versions, accepting handles to different types.
211The problem is that operator <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
d1a67b9d 212
215void func (const Handle(Geom_Curve)&);
216void func (const Handle(Geom_Surface)&);
218Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
219func (aCurve); // ambiguity error in VC++ 10
4796758e 222Note that this problem does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
a3305c6e 224To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature.
225In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
d1a67b9d 226
228Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);
a3305c6e 231Other variants consist in assigning the argument to a local variable of the correct type and using the direct cast or constructor:
d1a67b9d 232
234const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
235func (aGCurve); // OK - argument has exact type
236func (static_cast(aCurve)); // OK - direct cast
237func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
a3305c6e 240Another possibility consists in defining additional template variant of the overloaded function causing ambiguity, and using *SFINAE* to resolve the ambiguity.
241This technique can be illustrated by the definition of the template variant of method <i>IGESData_IGESWriter::Send()</i>.
d1a67b9d 242
243#### Lack of implicit cast to base type
a3305c6e 245As the cast of a handle to the reference to another handle to the base type has become a user-defined operation, the conversions that require this cast together with another user-defined cast will not be resolved automatically by the compiler.
d1a67b9d 246
247For example:
250Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
a3305c6e 253The problem is that the class *GCE2d_MakeSegment* has a user-defined conversion to <i>const Handle(Geom_TrimmedCurve)&,</i> which is not the same as the type of the local variable *aC*.
d1a67b9d 254
a3305c6e 255To resolve this, use method <i>Value()</i>:
d1a67b9d 256
258Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
a3305c6e 261or use variable of the appropriate type:
d1a67b9d 262
264Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
4796758e 267With GCC compiler, similar problem appears when const handle to derived type is used to construct handle to base type via assignment (and in some cases in return statement), for instance:
270 const Handle(Geom_Line) aLine;
271 Handle(Geom_Curve) c1 = aLine; // GCC error
272 Handle(Geom_Curve) c2 (aLine); // ok
275This problem is specific to GCC and it does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
d1a67b9d 277#### Incorrect use of STANDARD_TYPE and Handle macros
279You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().
a3305c6e 2811. Explicit definitions of static functions with names generated by macro *STANDARD_TYPE()*, which are artifacts of old implementation of RTTI, should be removed.
d1a67b9d 282
283 Example:
285const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
287 static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
288 return _atype;
a3305c6e 2922. Incorrect location of closing parenthesis of *Handle()* macro that was not detectable in OCCT 6.x will cause a compiler error and must be corrected.
d1a67b9d 293
294 Example (note misplaced closing parenthesis):
296aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
299#### Use of class Standard_AncestorIterator
a3305c6e 301Class *Standard_AncestorIterator* has been removed; use method *Parent()* of *Standard_Type* class to parse the inheritance chain.
d1a67b9d 302
303#### Absence of cast to Standard_Transient*
a3305c6e 305Handles in OCCT 7.0 do not have the operator of conversion to <i>Standard_Transient*,</i> which was present in earlier versions.
d1a67b9d 306This is done to prevent possible unintended errors like this:
309Handle(Geom_Line) aLine = ...;
310Handle(Geom_Surface) aSurf = ...;
a3305c6e 312if (aLine == aSurf) {...} // will cause a compiler error in OCCT 7.0, but not OCCT 6.x
d1a67b9d 313~~~~~
a3305c6e 315The places where this implicit cast has been used should be corrected manually.
d1a67b9d 316The typical situation is when Handle is passed to stream:
319Handle(Geom_Line) aLine = ...;
320os << aLine; // in OCCT 6.9.0, resolves to operator << (void*)
a3305c6e 323Call method <i>get()</i> explicitly to output the address of the Handle.
d1a67b9d 324
a9dde4a3 325#### Method DownCast for non-base types
327Method *DownCast()* in OCCT 7.0 is made templated; if it is used with argument which is not a base class, "deprecated" compiler warning is generated.
328This is done to prevent possible unintended errors like this:
331Handle(Geom_Surface) aSurf = ;
332Handle(Geom_Line) aLine =
333 Handle(Geom_Line)::DownCast (aSurf); // will cause a compiler warning in OCCT 7.0, but not OCCT 6.x
336The places where this cast has been used should be corrected manually.
338If down casting is used in a template context where argument can have the same or unrelated type so that *DownCast()* may be not available in all cases, use C++ *dynamic_cast<>* instead, e.g.:
341template <class T>
342bool CheckLine (const Handle(T) theArg)
344 Handle(Geom_Line) aLine = dynamic_cast<Geom_Line> (theArg.get());
345 ...
d1a67b9d 349@subsubsection upgrade_occt700_cdl_runtime Possible runtime problems
a3305c6e 351Here is the list of known possible problems at run time after the upgrade to OCCT 7.0.
d1a67b9d 352
353#### References to temporary objects
a3305c6e 355In previous versions, the compiler was able to detect the situation when a local variable of a "reference to a Handle" type is initialized by temporary object, and ensured that lifetime of that object is longer than that of the variable.
4796758e 356In OCCT 7.0 with default options, 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.
a9dde4a3 357
4796758e 358This problem does not appear if macro *OCCT_HANDLE_NOCAST* is used during compilation, see below.
d1a67b9d 359
363// note that DownCast() returns new temporary object!
364const Handle(Geom_BoundedCurve)& aBC =
366aBC->Transform (T); // access violation in OCCT 7.0
4796758e 369@subsubsection upgrade_occt700_cdl_nocast Option to avoid cast of handle to reference to base type
371In OCCT 6.x and earlier versions the handle classes formed a hierarchy echoing hierarchy of corresponding object classes.
372This automatically enabled possibility to use handle to derived class in all contexts where handle to base class was needed, e.g. pass it in function by reference without copying:
375Standard_Boolean GetCurve (Handle(Geom_Curve)& theCurve);
377Handle(Geom_Line) aLine;
378if (GetCurve (aLine)) {
379 // use aLine, unsafe
383This feature was used in multiple places in OCCT and dependent projects.
384However it is potentially unsafe: in the above example no checks are done at compile time or at run time to ensure that argument handle is assigned a type compatible with the type of handle passed as argument.
385If object of incompatible type (e.g. Geom_Circle) is assigned to *theCurve*, the behavior will be unpredictable.
387For compatibility with existing code, by default OCCT 7.0 keeps this possibility, providing operators of type cast to handle to base type.
388Besides being unsafe, in specific situations this feature may cause compile-time or run-time errors as described above.
390In order to provide safer behavior, this feature can be disabled by defining a compile-time macro *OCCT_HANDLE_NOCAST*.
391When it is defined, constructors and assignment operators are defined (instead of type cast operators) to convert from handle to defived type to handle to base type.
392This implies creation of temporary objects and hence may be more expensive at run time in some circumstances, however this way is more standard, safer, and in general recommended.
394The code that relies on possibility of casting to base should be amended so that handle of argument type is always used in function call, and to use DownCast() to safely convert the result to desired type.
395For instance, the code from the example below can be changed as follows:
398Handle(Geom_Line) aLine;
399Handle(Geom_Curve) aCurve;
400if (GetCurve (aCure) && !(aLine = Handle(Geom_Line)::DownCast (aCurve)).IsNull()) {
401 // use aLine safely
d1a67b9d 405@subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x
a3305c6e 407If you like to preserve the compatibility of your application code with OCCT versions 6.x even after the upgrade to 7.0, consider the following suggestions:
d1a67b9d 408
a3305c6e 4091. If your code used sequences of macros *IMPLEMENT_STANDARD_*... generated by WOK, replace them by single macro *IMPLEMENT_STANDARD_RTTIEXT*
f5f4ebd0 410
a3305c6e 4112. When running automatic upgrade tool, add option <i>-compat</i>.
d1a67b9d 412
a3305c6e 4133. Define macros *DEFINE_STANDARD_RTTIEXT* and *DEFINE_STANDARD_RTTI_INLINE* when building with previous versions of OCCT, resolving to *DEFINE_STANDARD_RTTI* with single argument
d1a67b9d 414
415 Example:
417#if OCC_VERSION_HEX < 0x070000
d1a67b9d 420#endif
423@subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK
a3305c6e 425If your application is essentially based on CDL, and you need to upgrade it to OCCT 7.0, you will very likely need to convert your application code to non-CDL form.
426This is a non-trivial effort; the required actions would depend strongly on the structure of the code and used CDL features.
d1a67b9d 427
a3305c6e 428The upgrade script and sources of a specialized WOK version used for OCCT code upgrade 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).
d1a67b9d 429
430[Contact us](http://www.opencascade.com/contact/) if you need more help.
432@subsection upgrade_occt700_bspline Separation of BSpline cache
a3305c6e 434Implementation of NURBS curves and surfaces has been revised: the cache of polynomial coefficients, which is used to accelerate calculate values of B-spline, has been separated from data objects *Geom2d_BSplineCurve, Geom_BSplineCurve* and *Geom_BSplineSurface* into the dedicated classes *BSplCLib_Cache* and *BSplSLib_Cache*.
d1a67b9d 435
436The benefits of this change are:
d1a67b9d 437* Reduced memory footprint of OCCT shapes (up to 20% on some cases)
438* Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks
a3305c6e 440The drawback is that direct evaluation of B-Splines using methods of curves and surfaces becomes slower due to the absence of cache. The slow-down can be avoided by using adaptor classes *Geom2dAdaptor_Curve, GeomAdaptor_Curve* and *GeomAdaptor_Surface*, which now use cache when the curve or surface is a B-spline.
d1a67b9d 441
a3305c6e 442OCCT algorithms have been changed to use adaptors for B-spline calculations instead of direct methods for curves and surfaces.
443The same changes (use of adaptors instead of direct call to curve and surface methods) should be implemented in relevant places in the applications based on OCCT to get the maximum performance.
d1a67b9d 444
3554ea68 445@subsection upgrade_occt700_booleanresult Structural result of Boolean operations
447The result of Boolean operations became structured according to the structure of the input shapes. Therefore it may impact old applications that always iterate on direct children of the result compound assuming to obtain solids as iteration items, regardless of the structure of the input shapes. In order to get always solids as iteration items it is recommended to use TopExp_Explorer instead of TopoDS_Iterator.
449@subsection upgrade_occt700_brepextrema BRepExtrema_ExtCC finds one solution only
451Extrema computation between non-analytical curves in shape-shape distance calculation algorithm has been changed in order to return only one solution. So, if e.g. two edges are created on parallel b-spline curves the algorithm BRepExtrema_DistShapeShape will return only one solution instead of enormous number of solutions. There is no way to get algorithm working in old manner.
d1a67b9d 453@subsection upgrade_occt700_sorttools Removal of SortTools package
a3305c6e 455Package *SortTools* has been removed.
d1a67b9d 456The code that used the tools provided by that package should be corrected manually.
457The recommended approach is to use sorting algorithms provided by STL.
459For instance:
461#include <SortTools_StraightInsertionSortOfReal.hxx>
462#include <SortTools_ShellSortOfReal.hxx>
463#include <TCollection_CompareOfReal.hxx>
465TCollection_Array1OfReal aValues = ...;
467TCollection_CompareOfReal aCompReal;
468SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
470can be replaced by:
472#include <algorithm>
474TCollection_Array1OfReal aValues = ...;
a3305c6e 476std::stable_sort (aValues.begin(), aValues.end());
d1a67b9d 477~~~~~
d3839d74 479@subsection upgrade_occt700_2dlayers On-screen objects and ColorScale
27f85086 480
a3305c6e 481The old mechanism for rendering Underlay and Overlay on-screen 2D objects based on *Visual3d_Layer* and immediate drawing model (uncached and thus slow) has been removed.
482Classes *Aspect_Clayer2d, OpenGl_GraphicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr* and *V3d_LayerMgrPointer* have been deleted.
27f85086 483
a3305c6e 484General AIS interactive objects with transformation persistence flag *Graphic3d_TMF_2d* can be used as a replacement of *Visual3d_LayerItem*.
485The anchor point specified for transformation persistence defines the window corner of (or center in case of (0, 0) point).
486To keep on-screen 2D objects on top of the main screen, they can be assigned to the appropriate Z-layer.
487Predefined Z-layers *Graphic3d_ZLayerId_TopOSD* and *Graphic3d_ZLayerId_BotOSD* are intended to replace Underlay and Overlay layers within the old API.
27f85086 488
a3305c6e 489*ColorScale* object previously implemented using *Visual3d_LayerItem* has been moved to a new class *AIS_ColorScale*, with width and height specified explicitly.
490The property of *V3d_View* storing the global *ColorScale* object has been removed with associated methods *V3d_View::ColorScaleDisplay(), V3d_View::ColorScaleErase(), V3d_View::ColorScaleIsDisplayed()* and *V3d_View::ColorScale()* as well as the classes *V3d_ColorScale, V3d_ColorScaleLayerItem* and *Aspect_ColorScale*.
491Here is an example of creating *ColorScale* using the updated API:
27f85086 492
494Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
495// configuring
d3839d74 496Standard_Integer aWidth, aHeight;
497aView->Window()->Size (aWidth, aHeight);
498aCS->SetSize (aWidth, aHeight);
27f85086 499aCS->SetRange (0.0, 10.0);
500aCS->SetNumberOfIntervals (10);
501// displaying
502aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
503aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
505theContextAIS->Display (aCS);
a3305c6e 508To see how 2d objects are implemented in OCCT you can call Draw commands *vcolorscale, vlayerline* or *vdrawtext* (with <i>-2d</i> option).
509Draw command *vcolorscale* now requires the name of *ColorScale* object as argument.
510To display this object use command *vdisplay*. For example:
27f85086 511
3f812249 515vcolorscale cs -demo
27f85086 516pload MODELING
517box b 100 100 100
518vdisplay b
519vsetdispmode 1
521vlayerline 0 300 300 300 10
522vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
a3305c6e 525Here is a small example in C++ illustrating how to display a custom AIS object in 2d:
27f85086 526~~~~~
d3839d74 527Handle(AIS_InteractiveContext) aContext = ...;
528Handle(AIS_InteractiveObject) anObj =...; // create an AIS object
529anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); // display object in overlay
530anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); // set 2d flag, coordinate origin is set to down-left corner
531aContext->Display (anObj); // display the object
534@subsection upgrade_occt700_userdraw UserDraw and Visual3d
536#### Visual3d package
a3305c6e 538Package *Visual3d* implementing the intermediate layer between high-level *V3d* classes
d3839d74 539and low-level OpenGl classes for views and graphic structures management has been dropped.
a3305c6e 541The *OpenGl_View* inherits from the new class *Graphic3d_CView*.
542*Graphic3d_CView* is an interface class that declares abstract methods for managing displayed structures,
d3839d74 543display properties and a base layer code that implements computation
544and management of HLR (or more broadly speaking view-depended) structures.
a3305c6e 546In the new implementation it takes place of the eliminated *Visual3d_View*.
547As before the instance of *Graphic3d_CView* is still completely managed by *V3d_View* classes.
548It can be accessed through *V3d_View* interface but normally it should not be required as all its methods are completely wrapped.
d3839d74 549
a3305c6e 550In more details, a concrete specialization of *Graphic3d_CView* is created and returned by the graphical driver on request.
551Right after the creation the views are directly used for setting rendering properties and adding graphical structures to be displayed.
d3839d74 552
553The rendering of graphics is possible after mapping a window and activating the view.
a3305c6e 554The direct setting of properties obsoletes the use of intermediate structures with display parameter
555like *Visual3d_ContextView*, etc. This means that the whole package *Visual3d* becomes redundant.
557The functionality previously provided by *Visual3d* package has been redesigned in the following way :
558- The management of display of structures has been moved from *Visual3d_ViewManager* into *Graphic3d_StructureManager*.
559- The class *Visual3d_View* has been removed. The management of computed structures has been moved into the base layer of *Graphi3d_CView*.
560- All intermediate structures for storing view parameters, e.g. *Visual3d_ContextView*, have been removed.
561 The settings are now kept by instances of *Graphic3d_CView*.
562- The intermediate class *Visual3d_Light* has been removed. All light properties are stored in *Graphic3d_CLight* structure, which is directly accessed by instances of *V3d_Light* classes.
563- All necessary enumerations have been moved into *Graphic3d* package.
d3839d74 564
565#### Custom OpenGL rendering and UserDraw
a3305c6e 567Old APIs based on global callback functions for creating *UserDraw* objects and for performing custom OpenGL rendering within the view have been dropped.
568*UserDraw* callbacks are no more required since *OpenGl_Group* now inherits *Graphic3d_Group* and thus can be accessed directly from *AIS_InteractiveObject*:
d3839d74 569
571//! Class implementing custom OpenGL element.
572class UserDrawElement : public OpenGl_Element {};
574//! Implementation of virtual method AIS_InteractiveObject::Compute().
575void UserDrawObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
576 const Handle(Prs3d_Presentation)& thePrs,
577 const Standard_Integer theMode)
579 Graphic3d_Vec4 aBndMin (myCoords[0], myCoords[1], myCoords[2], 1.0f);
580 Graphic3d_Vec4 aBndMax (myCoords[3], myCoords[4], myCoords[5], 1.0f);
582 // casting to OpenGl_Group should be always true as far as application uses OpenGl_GraphicDriver for rendering
583 Handle(OpenGl_Group) aGroup = Handle(OpenGl_Group)::DownCast (thePrs->NewGroup());
584 aGroup->SetMinMaxValues (aBndMin.x(), aBndMin.y(), aBndMin.z(),
585 aBndMax.x(), aBndMax.y(), aBndMax.z());
586 UserDrawElement* anElem = new UserDrawElement (this);
587 aGroup->AddElement(anElem);
589 // invalidate bounding box of the scene
590 thePrsMgr->StructureManager()->Update (thePrsMgr->StructureManager()->UpdateMode());
27f85086 592~~~~~
d3839d74 593
a3305c6e 594To perform a custom OpenGL code within the view, it is necessary to inherit from class *OpenGl_View*.
d3839d74 595See the following code sample:
598//! Custom view.
599class UserView : public OpenGl_View
602 //! Override rendering into the view.
603 virtual void render (Graphic3d_Camera::Projection theProjection,
604 OpenGl_FrameBuffer* theReadDrawFbo,
605 const Standard_Boolean theToDrawImmediate)
606 {
607 OpenGl_View::render (theProjection, theReadDrawFbo, theToDrawImmediate);
608 if (theToDrawImmediate)
609 {
610 return;
611 }
613 // perform custom drawing
614 const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext();
615 GLfloat aVerts[3] = { 0.0f, 0,0f, 0,0f };
616 aCtx->core20->glEnableClientState(GL_VERTEX_ARRAY);
617 aCtx->core20->glVertexPointer(3, GL_FLOAT, 0, aVerts);
618 aCtx->core20->glDrawArrays(GL_POINTS, 0, 1);
619 aCtx->core20->glDisableClientState(GL_VERTEX_ARRAY);
620 }
624//! Custom driver for creating UserView.
625class UserDriver : public OpenGl_GraphicDriver
628 //! Create instance of own view.
629 virtual Handle(Graphic3d_CView) CreateView (const Handle(Graphic3d_StructureManager)& theMgr) Standard_OVERRIDE
630 {
631 Handle(UserView) aView = new UserView (theMgr, this, myCaps, myDeviceLostFlag, &myStateCounter);
632 myMapOfView.Add (aView);
633 for (TColStd_SequenceOfInteger::Iterator aLayerIt (myLayerSeq); aLayerIt.More(); aLayerIt.Next())
634 {
635 const Graphic3d_ZLayerId aLayerID = aLayerIt.Value();
636 const Graphic3d_ZLayerSettings& aSettings = myMapOfZLayerSettings.Find (aLayerID);
637 aView->AddZLayer (aLayerID);
638 aView->SetZLayerSettings (aLayerID, aSettings);
639 }
640 return aView;
641 }
646@subsection upgrade_occt700_localcontext Deprecation of Local Context
a3305c6e 648The conception of Local Context has been deprecated.
649The related classes, e.g. *AIS_LocalContext*, and methods ( <i>AIS_InteractiveContext::OpenLocalContext()</i> and others) will be removed in a future OCCT release.
d3839d74 650
651The main functionality provided by Local Context - selection of object subparts - can be now used within Neutral Point without opening any Local Context.
f47afe53 652
653@subsection upgrade_occt700_separate_caf_visualisation Separation of visualization part from TKCAF
655Visualization CAF attributes moved into new toolkit TKVCAF.
656If your application uses the classes from TPrsStd package then add link to TKVCAF library.
658Verson numbers of BinOCAF and XmlOCAF formats are incremented; new files cannot be read by previous versions of OCCT.
660For loading OCAF files saved by previous versions and containing attribute TPrsStd_AISPresentation it is necessary that environment variable CSF_MIGRATION_TYPES should be defined, pointing to file src/StdResources/MigrationSheet.txt.
661When using documents loaded from a file, make sure to call method TPrsStd_AISViewer::New() prior to accessing TPrsStd_AISPresentation attributes in this document (that method will create them).
4f5ad416 662
664@subsection Correction of interpretation of Euler angles in gp_Quaternion
666Conversion of gp_Quaternion to and from intrinsic Tait-Bryan angles (including gp_YawPitchRoll) is fixed.
668Before that fix the sequence of rotation axes was opposite to intended; e.g. gp_YawPitchRoll (equivalent to gp_Intrinsic_ZYX) actually was defining intrinsic rotations around X, then Y, then Z.
669Now this is fixed, and rotations are made in correct order.
671Applications that use gp_Quaternion to convert Yaw-Pitch-Roll angles (or other intrinsic Tait-Bryan sequences) may need to be updated to take this change into account.