cf7142974d24dcdb9a71eba5238da9a069a840bc
[occt.git] / dox / dev_guides / upgrade / upgrade.md
1 Upgrade from older OCCT versions  {#occt_dev_guides__upgrade}
2 ================================
3
4 @tableofcontents
5
6 @section upgrade_intro Introduction
7
8 This 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.
9
10 @subsection upgrade_intro_precautions Precautions
11
12 Back-up your code before the upgrade.
13 We 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.
14 This will facilitate identification and correction of possible problems that can occur at the intermediate steps of upgrade.
15 It is advisable to document each step carefully to be able to repeat it if necessary.
16
17 @subsection upgrade_intro_disclaim Disclaimer
18
19 This 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.
20 It does not pretend to cover all possible migration issues that can appear in your application.
21 Take this document with discretion; apply your expertise and knowledge of your application to ensure the correct result. 
22
23 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. 
24 It is your responsibility to ensure that the changes you made in your code are correct. 
25 When you upgrade the code by an automatic script, make sure to carefully review the introduced changes at each step before committing them.
26
27 @section upgrade_700 Upgrade to OCCT 7.0.0
28
29 @subsection upgrade_700_persist Removal of legacy persistence
30
31 Legacy persistence for shapes and OCAF data based on *Storage_Schema* (toolkits *TKShapeShcema, TLStdLSchema, TKStdSchema* and *TKXCAFSchema*) has been removed in OCCT 7.0.0.
32 The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
33
34 The existing data files in standard formats can be converted using OCCT 6.9.0 or a previous version, as follows.
35
36 #### CSFDB files
37
38 Files in CSFDB format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format. 
39 The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):
40
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
46
47 #### OCAF and XCAF documents
48
49 Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
50 These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands available in OCCT 6.9.0 or earlier.
51
52 For that, start *DRAWEXE* and perform the following commands: 
53
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*):
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
62
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*):
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
71
72 On Windows, it is necessary to replace back slashes in the file path by  direct slashes or pairs of back slashes.
73
74 Use *XmlOcaf* or *XmlXCAF* instead of *BinOcaf* and *BinXCAF*, respectively, to save in XML format instead of binary one.
75
76 @subsection upgrade_occt700_cdl Removal of CDL and WOK
77
78 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).
79
80 C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.
81
82 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.
83 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.
84
85 WOK 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.
86 The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
87 The alternative solution is to use legacy generator of project files (extracted from WOK), see @ref occt_dev_guides__building_wok.
88
89 @subsubsection upgrade_occt700_cdl_auto Automatic upgrade
90
91 Most of typical changes required for upgrading code for OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
92 This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
93
94 Example:
95 ~~~~~
96  $ tclsh
97  % source <path_to_occt>/adm/upgrade.tcl
98  % upgrade -recurse -all -src=<path_to_your_sources>
99 ~~~~~
100
101 On 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:
102
103 ~~~~~
104 cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
105 ~~~~~
106
107 Run the upgrade tool without arguments to see the list of available options.
108
109 The upgrade tool performs the following changes in the code.
110
111 1. 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):
112 ~~~~~
113 DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTIEXT(Class, Base)
114 ~~~~~
115
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*. 
117    The former case is used if current file is header and source file with the same name is found in the same folder. 
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. 
120
121 2. Replaces forward declarations of collection classes previously generated from CDL generics (defined in *TCollection* package) by inclusion of the corresponding header:
122 ~~~~~
123 class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
124 ~~~~~
125
126 3. Replaces underscored names of *Handle* classes by usage of a macro:
127 ~~~~~
128 Handle_Class -> Handle(Class)
129 ~~~~~
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:*. 
132
133 4. 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:
134 ~~~~~
135 class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
136 ~~~~~
137
138 5. Removes <i> \#includes </i> of files <i>Handle_...hxx</i> that have disappeared in OCCT 7.0:
139 ~~~~~
140 #include <Handle_Geom_Curve.hxx> ->
141 ~~~~~
142
143 6. Removes *typedef* statements that use *Handle* macro to generate the name:
144 ~~~~~
145 typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
146 ~~~~~
147
148 7. Converts C-style casts applied to Handles into calls to <i>DownCast()</i> method:
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)
155 ~~~~~
156
157 8. Moves <i>Handle()</i> macro out of namespace scope:
158 ~~~~~
159 Namespace::Handle(Class) -> Handle(Namespace::Class)
160 ~~~~~
161
162 9. 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):
163 ~~~~~
164     const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
165 ~~~~~
166
167 10. Adds  <i>\#include</i> for all classes used as argument to macro <i>STANDARD_TYPE()</i>, except for already included ones;
168
169 11. Removes uses of obsolete macros *IMPLEMENT_DOWNCAST* and *IMPLEMENT_STANDARD_*..., except *IMPLEMENT_STANDARD_RTTIEXT*.
170
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.
172
173 .
174
175 As long as the upgrade routine runs, some information messages are sent to the standard output. 
176 In some cases the warnings or errors like the following may appear:
177
178 ~~~~~
179   Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
180 ~~~~~
181
182 Be sure to check carefully all reported errors and warnings, as the corresponding code will likely require manual corrections.
183 In 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.
184
185 @subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
186
187 Some situations requiring upgrade cannot be detected and / or handled by the automatic procedure.
188 If you get compiler errors or warnings when trying to build the upgraded code, you will need to fix them manually. 
189 The following paragraphs list known situations of this kind.
190
191 #### Missing header files
192
193 The 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.
194
195 For example, the following lines will fail to compile if *Geom_Line.hxx* is not included:
196
197 ~~~~~
198 Handle(Geom_Line) aLine = 0;
199 if (aLine != aCurve) {...} 
200 if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
201 aLine = Handle(Geom_Line)::DownCast (aCurve);
202 ~~~~~
203
204 Note that it is not necessary to include header of the class to declare Handle to it.
205 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*.
206 This will eliminate the need to include the header *A* in each source file where class *B* is used.
207
208 #### Ambiguity of calls to overloaded functions
209
210 This 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. 
211 The problem is that operator  <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
212
213 Example:
214 ~~~~~
215 void func (const Handle(Geom_Curve)&);
216 void func (const Handle(Geom_Surface)&);
217
218 Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
219 func (aCurve); // ambiguity error in VC++ 10
220 ~~~~~
221
222 To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature. 
223 In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
224
225 ~~~~~
226 Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);  
227 ~~~~~
228
229 Other variants consist in assigning the argument to a local variable of the correct type and using the direct cast or constructor:
230
231 ~~~~~
232 const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
233 func (aGCurve); // OK - argument has exact type
234 func (static_cast(aCurve)); // OK - direct cast 
235 func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
236 ~~~~~
237
238 Another possibility consists in defining additional template variant of the overloaded function causing ambiguity, and using *SFINAE* to resolve the ambiguity.
239 This technique can be illustrated by the definition of the template variant of method <i>IGESData_IGESWriter::Send()</i>.
240
241 #### Lack of implicit cast to base type
242
243 As 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.
244
245 For example:
246
247 ~~~~~
248 Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
249 ~~~~~
250
251 The 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*.
252
253 To resolve this, use method <i>Value()</i>:
254
255 ~~~~~
256 Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
257 ~~~~~
258
259 or use variable of the appropriate type:
260
261 ~~~~~
262 Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
263 ~~~~~
264
265 #### Incorrect use of STANDARD_TYPE and Handle macros
266
267 You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().
268
269 1. Explicit definitions of static functions with names generated by macro *STANDARD_TYPE()*, which are artifacts of old implementation of RTTI, should be removed.
270    
271    Example:
272 ~~~~~
273 const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
274 {
275   static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
276   return _atype;
277 }
278 ~~~~~
279
280 2. 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.
281
282    Example (note misplaced closing parenthesis):
283 ~~~~~
284 aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
285 ~~~~~
286
287 #### Use of class Standard_AncestorIterator
288
289 Class *Standard_AncestorIterator* has been removed; use method *Parent()* of *Standard_Type* class to parse the inheritance chain.
290
291 #### Absence of cast to Standard_Transient*
292
293 Handles in OCCT 7.0 do not have the operator of conversion to <i>Standard_Transient*,</i> which was present in earlier versions.
294 This is done to prevent possible unintended errors like this:
295
296 ~~~~~
297 Handle(Geom_Line) aLine = ...;
298 Handle(Geom_Surface) aSurf = ...;
299 ...
300 if (aLine == aSurf) {...} // will cause a compiler error in OCCT 7.0, but not OCCT 6.x
301 ~~~~~
302
303 The places where this implicit cast has been used should be corrected manually.
304 The typical situation is when Handle is passed to stream:
305
306 ~~~~~
307 Handle(Geom_Line) aLine = ...;
308 os << aLine; // in OCCT 6.9.0, resolves to operator << (void*) 
309 ~~~~~
310
311 Call method <i>get()</i> explicitly to output the address of the Handle.
312
313 @subsubsection upgrade_occt700_cdl_runtime Possible runtime problems
314
315 Here is the list of known possible problems at run time after the upgrade to OCCT 7.0.
316
317 #### References to temporary objects
318
319 In 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. 
320 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.
321
322 Example:
323
324 ~~~~~
325 // note that DownCast() returns new temporary object!
326 const Handle(Geom_BoundedCurve)& aBC =
327 Handle(Geom_TrimmedCurve)::DownCast(aCurve);
328 aBC->Transform (T); // access violation in OCCT 7.0
329 ~~~~~
330
331 @subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x
332
333 If 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:
334
335 1. If your code used sequences of macros *IMPLEMENT_STANDARD_*... generated by WOK, replace them by single macro *IMPLEMENT_STANDARD_RTTIEXT*
336
337 2. When running automatic upgrade tool, add option <i>-compat</i>.
338
339 3. 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 
340
341    Example:
342 ~~~~~   
343 #if OCC_VERSION_HEX < 0x070000
344   #define DEFINE_STANDARD_RTTIEXT(C1,C2) DEFINE_STANDARD_RTTI(C1)
345   #define DEFINE_STANDARD_RTTI_INLINE(C1,C2) DEFINE_STANDARD_RTTI(C1)
346 #endif
347 ~~~~~
348
349 @subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK
350
351 If 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.
352 This is a non-trivial effort; the required actions would depend strongly on the structure of the code and used CDL features.
353
354 The 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).
355
356 [Contact us](http://www.opencascade.com/contact/) if you need more help.
357
358 @subsection upgrade_occt700_bspline Separation of BSpline cache
359
360 Implementation 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*. 
361
362 The benefits of this change are:
363 * Reduced memory footprint of OCCT shapes (up to 20% on some cases)
364 * Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks 
365
366 The 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.
367
368 OCCT algorithms have been changed to use adaptors for B-spline calculations instead of direct methods for  curves and surfaces.
369 The 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.
370
371 @subsection upgrade_occt700_booleanresult Structural result of Boolean operations
372
373 The 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.
374
375 @subsection upgrade_occt700_brepextrema BRepExtrema_ExtCC finds one solution only
376
377 Extrema 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.
378
379 @subsection upgrade_occt700_sorttools Removal of SortTools package
380
381 Package *SortTools* has been removed. 
382 The code that used the tools provided by that package should be corrected manually.
383 The recommended approach is to use sorting algorithms provided by STL.
384
385 For instance:
386 ~~~~~
387 #include <SortTools_StraightInsertionSortOfReal.hxx>
388 #include <SortTools_ShellSortOfReal.hxx>
389 #include <TCollection_CompareOfReal.hxx>
390 ...
391 TCollection_Array1OfReal aValues = ...;
392 ...
393 TCollection_CompareOfReal aCompReal;
394 SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
395 ~~~~~
396 can be replaced by:
397 ~~~~~
398 #include <algorithm>
399 ...
400 TCollection_Array1OfReal aValues = ...;
401 ...
402 std::stable_sort (aValues.begin(), aValues.end());
403 ~~~~~
404
405 @subsection upgrade_occt700_2dlayers On-screen objects and ColorScale
406
407 The 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.
408 Classes *Aspect_Clayer2d, OpenGl_GraphicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr* and *V3d_LayerMgrPointer* have been deleted.
409
410 General AIS interactive objects with transformation persistence flag *Graphic3d_TMF_2d* can be used as a replacement of *Visual3d_LayerItem*.
411 The anchor point specified for transformation persistence defines the window corner of  (or center in case of (0, 0) point).
412 To keep on-screen 2D objects on top of the main screen, they can be assigned to the appropriate Z-layer.
413 Predefined Z-layers *Graphic3d_ZLayerId_TopOSD* and *Graphic3d_ZLayerId_BotOSD* are intended to replace Underlay and Overlay layers within the old API.
414
415 *ColorScale* object previously implemented using *Visual3d_LayerItem* has been moved to a new class *AIS_ColorScale*, with width and height specified explicitly.
416 The 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*.
417 Here is an example of creating *ColorScale* using the updated API:
418
419 ~~~~~
420 Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
421 // configuring
422 Standard_Integer aWidth, aHeight;
423 aView->Window()->Size (aWidth, aHeight);
424 aCS->SetSize              (aWidth, aHeight);
425 aCS->SetRange             (0.0, 10.0);
426 aCS->SetNumberOfIntervals (10);
427 // displaying
428 aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
429 aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
430 aCS->SetToUpdate();
431 theContextAIS->Display (aCS);
432 ~~~~~
433
434 To see how 2d objects are implemented in OCCT you can call Draw commands *vcolorscale, vlayerline* or *vdrawtext* (with <i>-2d</i> option).
435 Draw command *vcolorscale* now requires the name of *ColorScale* object as argument.
436 To display this object use command *vdisplay*. For example:
437
438 ~~~~~
439 pload VISUALIZATION
440 vinit
441 vcolorscale cs -demo
442 pload MODELING
443 box b 100 100 100
444 vdisplay b
445 vsetdispmode 1
446 vfit
447 vlayerline 0 300 300 300 10
448 vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
449 ~~~~~
450
451 Here is a small example in C++ illustrating how to display a custom AIS object in 2d:
452 ~~~~~
453 Handle(AIS_InteractiveContext) aContext = ...;
454 Handle(AIS_InteractiveObject) anObj =...; // create an AIS object
455 anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); // display object in overlay
456 anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); // set 2d flag, coordinate origin is set to down-left corner
457 aContext->Display (anObj); // display the object
458 ~~~~~
459
460 @subsection upgrade_occt700_userdraw UserDraw and Visual3d
461
462 #### Visual3d package
463
464 Package *Visual3d* implementing the intermediate layer between high-level *V3d* classes
465 and low-level OpenGl classes for views and graphic structures management has been dropped.
466
467 The *OpenGl_View* inherits from the new class *Graphic3d_CView*.
468 *Graphic3d_CView* is an interface class that declares abstract methods for managing displayed structures,
469 display properties and a base layer code that implements computation
470 and management of HLR (or more broadly speaking view-depended) structures.
471
472 In the new implementation it takes place of the eliminated *Visual3d_View*.
473 As before the instance of *Graphic3d_CView* is still completely managed by *V3d_View* classes.
474 It can be accessed through *V3d_View* interface but normally it should not be required as all its methods are completely wrapped.
475
476 In more details, a concrete specialization of *Graphic3d_CView* is created and returned by the graphical driver on request.
477 Right after the creation the views are directly used for setting rendering properties and adding graphical structures to be displayed.
478
479 The rendering of graphics is possible after mapping a window and activating the view.
480 The direct setting of properties obsoletes the use of intermediate structures with display parameter
481 like *Visual3d_ContextView*, etc. This means that the whole package *Visual3d* becomes redundant.
482
483 The functionality previously provided by *Visual3d* package has been redesigned in the following way :
484 - The management of display of structures has been moved from *Visual3d_ViewManager* into *Graphic3d_StructureManager*.
485 - The class *Visual3d_View* has been removed. The management of computed structures has been moved into the base layer of *Graphi3d_CView*.
486 - All intermediate structures for storing view parameters, e.g. *Visual3d_ContextView*, have been removed.
487   The settings are now kept by instances of *Graphic3d_CView*.
488 - 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.
489 - All necessary enumerations have been moved into *Graphic3d* package.
490
491 #### Custom OpenGL rendering and UserDraw
492
493 Old APIs based on global callback functions for creating *UserDraw* objects and for performing custom OpenGL rendering within the view have been dropped.
494 *UserDraw* callbacks are no more required since *OpenGl_Group* now inherits *Graphic3d_Group* and thus can be accessed directly from *AIS_InteractiveObject*:
495
496 ~~~~~
497 //! Class implementing custom OpenGL element.
498 class UserDrawElement : public OpenGl_Element {};
499
500 //! Implementation of virtual method AIS_InteractiveObject::Compute().
501 void UserDrawObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
502                               const Handle(Prs3d_Presentation)& thePrs,
503                               const Standard_Integer theMode)
504 {
505   Graphic3d_Vec4 aBndMin (myCoords[0], myCoords[1], myCoords[2], 1.0f);
506   Graphic3d_Vec4 aBndMax (myCoords[3], myCoords[4], myCoords[5], 1.0f);
507
508   // casting to OpenGl_Group should be always true as far as application uses OpenGl_GraphicDriver for rendering
509   Handle(OpenGl_Group) aGroup = Handle(OpenGl_Group)::DownCast (thePrs->NewGroup());
510   aGroup->SetMinMaxValues (aBndMin.x(), aBndMin.y(), aBndMin.z(),
511                            aBndMax.x(), aBndMax.y(), aBndMax.z());
512   UserDrawElement* anElem = new UserDrawElement (this);
513   aGroup->AddElement(anElem);
514
515   // invalidate bounding box of the scene
516   thePrsMgr->StructureManager()->Update (thePrsMgr->StructureManager()->UpdateMode());
517 }
518 ~~~~~
519
520 To perform a custom OpenGL code within the view, it is necessary to inherit from class *OpenGl_View*.
521 See the following code sample:
522
523 ~~~~~
524 //! Custom view.
525 class UserView : public OpenGl_View
526 {
527 public:
528   //! Override rendering into the view.
529   virtual void render (Graphic3d_Camera::Projection theProjection,
530                        OpenGl_FrameBuffer*          theReadDrawFbo,
531                        const Standard_Boolean       theToDrawImmediate)
532   {
533     OpenGl_View::render (theProjection, theReadDrawFbo, theToDrawImmediate);
534     if (theToDrawImmediate)
535     {
536       return;
537     }
538
539     // perform custom drawing
540     const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext();
541     GLfloat aVerts[3] = { 0.0f, 0,0f, 0,0f };
542     aCtx->core20->glEnableClientState(GL_VERTEX_ARRAY);
543     aCtx->core20->glVertexPointer(3, GL_FLOAT, 0, aVerts);
544     aCtx->core20->glDrawArrays(GL_POINTS, 0, 1);
545     aCtx->core20->glDisableClientState(GL_VERTEX_ARRAY);
546   }
547
548 };
549
550 //! Custom driver for creating UserView.
551 class UserDriver : public OpenGl_GraphicDriver
552 {
553 public:
554   //! Create instance of own view.
555   virtual Handle(Graphic3d_CView) CreateView (const Handle(Graphic3d_StructureManager)& theMgr) Standard_OVERRIDE
556   {
557     Handle(UserView) aView = new UserView (theMgr, this, myCaps, myDeviceLostFlag, &myStateCounter);
558     myMapOfView.Add (aView);
559     for (TColStd_SequenceOfInteger::Iterator aLayerIt (myLayerSeq); aLayerIt.More(); aLayerIt.Next())
560     {
561       const Graphic3d_ZLayerId        aLayerID  = aLayerIt.Value();
562       const Graphic3d_ZLayerSettings& aSettings = myMapOfZLayerSettings.Find (aLayerID);
563       aView->AddZLayer         (aLayerID);
564       aView->SetZLayerSettings (aLayerID, aSettings);
565     }
566     return aView;
567   }
568 };
569
570 ~~~~~
571
572 @subsection upgrade_occt700_localcontext Deprecation of Local Context
573
574 The conception of Local Context has been deprecated.
575 The related classes, e.g. *AIS_LocalContext*, and methods ( <i>AIS_InteractiveContext::OpenLocalContext()</i> and others) will be removed in a future OCCT release.
576
577 The main functionality provided by Local Context - selection of object subparts - can be now used within Neutral Point without opening any Local Context.
578
579 @subsection upgrade_occt700_separate_caf_visualisation Separation of visualization part from TKCAF
580
581 Visualization CAF attributes moved into new toolkit TKVCAF. 
582 If your application uses the classes from TPrsStd package then add link to TKVCAF library.
583
584 Verson numbers of BinOCAF and XmlOCAF formats are incremented; new files cannot be read by previous versions of OCCT.
585
586 For 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.
587 When 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).
588
589
590 @subsection Correction of interpretation of Euler angles in gp_Quaternion
591
592 Conversion of gp_Quaternion to and from intrinsic Tait-Bryan angles (including gp_YawPitchRoll) is fixed.
593
594 Before 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.
595 Now this is fixed, and rotations are made in correct order.
596
597 Applications 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.