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