060f3801d3b1b28efe823f5a50391dda900828a5
[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
28 @section upgrade_65 Upgrade to OCCT 6.5.0
29
30 Porting of user applications from an earlier OCCT version to version 6.5 requires taking into account the following major changes:
31 * If you are not comfortable with dependence on Intel TBB, FreeImage, or Gl2Ps libraries, you will need to (re)build OCCT with these dependencies disabled.
32 * The low-level format version of OCAF binary and XML persistence has been incremented. Hence, the files saved by OCCT 6.5 to OCAF binary or XML format will not be readable by previous versions of OCCT.
33 * The *BRepMesh* triangulation algorithm has been seriously revised and now tries hard to fulfill the requested deflection and angular tolerance parameters. If you experience any problems with performance or triangulation quality (in particular, display of shapes in shading mode), consider revising the values of these parameters used in your application.
34 * If you were using method *ToPixMap()* of class *V3d_View* to get a buffer for passing to Windows API functions (e.g. *BitBlt*), this will not work anymore. You will need to use method *Image_PixMap::AccessBuffer()* to get the raw buffer data that can be further passed to WinAPI functions.
35 * As the processing of message gravity parameter in *Message* package has been improved, some application messages (especially the ones generated by IGES or STEP translators) can be suppressed or new messages appear in the application. Use relevant message level parameter to tune this behavior.
36
37 @section upgrade_651 Upgrade to OCCT 6.5.1
38
39 Porting of user applications from an earlier OCCT version to version 6.5.1 requires taking into account the following major changes:
40
41 *       Method *Graphic3d_Structure::Groups()* now returns *Graphic3d_SequenceOfGroup*. If this method has been used, the application code should be updated to iterate another collection type or, if *Graphic3d_HSetOfGroup* is required, to fill its own collection:
42 ~~~~
43 const Graphic3d_SequenceOfGroup& aGroupsSeq = theStructure.Groups();
44 Handle(Graphic3d_HSetOfGroup) aGroupSet = new Graphic3d_HSetOfGroup();
45 Standard_Integer aLen = aGroupsSeq.Length();
46 for (Standard_Integer aGr = 1; aGr <= aLen; ++aGr)
47 {
48  aGroupSet->Add (aGroupsSeq.Value (aGr));
49 }
50 ~~~~
51
52 * All occurrences of *Select3D_Projector* in the application code (if any) should be replaced with *Handle(Select3D_Projector)*.
53 * The code of inheritors of *Select3D_SensitiveEntity* should be updated if they override <i>Matches()</i> (this is probable, if clipping planes are used).
54 * Constructor for *V3d_Plane* has been changed, so the extra argument should be removed if used in the application. It is necessary to add a new plane using method *V3d_Viewer::AddPlane()* if *V3d_Viewer* has been used to manage clipping planes list (this does not affect clipping planes representation). Please, have a look at the source code for new DRAWEXE *vclipplane* command in *ViewerTest_ObjectsCommands.cxx, VClipPlane* to see how clipping planes can be managed in the application.
55
56 @section upgrade_652 Upgrade to OCCT 6.5.2
57
58 Porting of user applications from an earlier OCCT version to version 6.5.2 requires taking into account the following major changes:
59 * Any code that has been generated by WOK from CDL generic classes *Tcollection_DataMap* and *Tcollection_IndexedDataMap* needs to be regenerated by WOK to take into account the change in the interface of these classes.
60 * The enumerations *CDF_StoreStatus* and *CDF_RetrievableStatus* have been replaced by the enumerations *PCDM_StoreStatus* and *PCDM_ReaderStatus*. Correspondingly, the methods *Open, Save* and *SaveAs* of the class *TDocStd_Application* have changed their return value. Any code, which uses these enumerations, needs to be updated.
61 * *BRepLib_MakeFace* has been modified to receive tolerance value for resolution of degenerated edges. This tolerance parameter has no default value to ensure that the client code takes care of passing a meaningful value, not just *Precision::Confusion*, so some porting overheads are expected. 
62 * If the callback mechanism in call_togl_redraw function was used in the application code, it is necessary to revise it to take into account the new callback execution and provide a check of reason value of Aspect_GraphicCallbackStruct in callback methods to confirm that the callback code is executed at the right moment. Now the callbacks are executed before redrawing the underlayer, before redrawing the overlayer and at the end of redrawing. The information about the moment when the callback is invoked is provided with the reason value in form of an additional bit flag <i>(OCC_PRE_REDRAW, OCC_PRE_OVERLAY)</i>. The state of OpenGl changed in callback methods will not be restored automatically, which might lead to unwanted behavior in redrawing procedure.
63 * The print method used in the application code might need to be revised to take into account the ability to choose between print algorithms: tile and stretch. The stretch algorithm will be selected by default during porting.
64 * It is recommended to *BRepMesh_DiscretFactory* users, to check *BRepMesh_DiscretFactory::SetDefault()* return value to determine plugin availability / validity. *BRepMesh_DiscretFactory::Discret()* method now returns handle instead of pointer. The code should be updated in the following manner:
65 ~~~~
66 Handle(BRepMesh_DiscretRoot) aMeshAlgo = BRepMesh_DiscretFactory::Get().Discret (theShape, theDeflection, theAngularToler);
67  if (!aMeshAlgo.IsNull())  {}
68 ~~~~
69
70 * The default state of *BRepMesh* parallelization has been turned off. The user should switch this flag explicitly:
71     *   by using methods *BRepMesh_IncrementalMesh::SetParallel(Standard_True)* for each *BRepMesh_IncrementalMesh* instance before <i>Perform()</i>;
72     *   by calling *BRepMesh_IncrementalMesh::SetParallelDefault(Standard_True)* when *BRepMesh_DiscretFactory* is used to retrieve the meshing tool (this also affects auto-triangulation in *AIS*).
73
74 @section upgrade_653 Upgrade to OCCT 6.5.3
75
76 Porting of user applications from an earlier OCCT version to version 6.5.3 requires taking into account the following major changes:
77 * As a result of code clean-up and redesign of *TKOpenGl* driver, some obsolete functions and rendering primitives <i>(TriangleMesh, TriangleSet, Bezier, Polyline, Polygon, PolygonHoles, QuadrangleMesh</i> and *QuadrangleSet*) have been removed. Instead, the application developers should use primitive arrays that provide the same functionality but are hardware-accelerated. The details can be found in OCCT Visualization User's Guide, “Primitive Arrays” chapter.
78 * Applications should not call *AIS_InteractiveObject::SetPolygonOffsets()* method for an instance of *AIS_TexturedShape* class after it has been added to *AIS_InteractiveContext*. More generally, modification of *Graphic3d_AspectFillArea3d* parameters for the computed groups of any *AIS_InteractiveObject* subclass that uses texture mapping should be avoided, because this results in broken texture mapping (see issue 23118). It is still possible to apply non-default polygon offsets to *AIS_TexturedShape* by calling *SetPolygonOffsets()* before displaying the shape.
79 * The applications that might have used internal functions provided by *TKOpenGl* or removed primitives will need to be updated.
80 * In connection with the implementation of Z-layers it might be necessary to revise the application code or revise the custom direct descendant classes of *Graphic3d_GraphicDriver* and *Graphic3d_StructureManager* to use the Z-layer feature.
81 * Global variables *Standard_PI* and *PI* have been eliminated (use macro *M_PI* instead). 
82 * Method *HashCode()* has been removed from class *Standard_Transient*. It is advisable to use global function <i>HashCode()</i> for Handle objects instead. 
83 * Declaration of operators new/delete for classes has become consistent and is encapsulated in macros.
84 * Memory management has been changed to use standard heap <i>(MMGT_OPT=0)</i> and reentrant mode <i>(MMGT_REENTRANT=1)</i> by default.
85 * Map classes in *NCollection* package now receive one more argument defining a hash tool.
86
87 @section upgrade_654 Upgrade to OCCT 6.5.4
88
89 Porting of user applications from an earlier OCCT version to version 6.5.4 requires taking into account the following major changes:
90 * The code using obsolete classes *Aspect_PixMap, Xw_PixMap* and *WNT_PixMap* should be rewritten implementing class *Image_PixMap*, which is now retrieved by *ToPixMap* methods as argument. A sample code using *ToPixMap* is given below:
91 ~~~~
92 #include <Image_AlienPixMap.hxx>
93 void dump (Handle(V3d_View)& theView3D)
94 {
95   Standard_Integer aWndSizeX = 0;
96   Standard_Integer aWndSizeY = 0;
97   theView3D->Window()->Size (aWndSizeX, aWndSizeY);
98   Image_AlienPixMap aPixMap;
99   theView3D->ToPixMap (aPixMap, aWndSizeX, aWndSizeY);
100   aPixMap.Save ("c:\\image.png");
101 }
102 ~~~~
103 * Now OpenGL resources related to Interactive Objects are automatically freed when the last view (window) is removed from graphical driver. 
104 To avoid presentation data loss, the application should replace an old view with a new one in the proper order: first the new view is created and activated and only then the old one is detached and removed. 
105 * It is recommended to use *NCollection* containers with hasher parameter (introduced in 6.5.3) instead of global definition <i>IsEqual()/HashCode()</i> as well as to use explicit namespaces to avoid name collision.
106
107
108 @section upgrade_660 Upgrade to OCCT 6.6.0
109
110 Porting of user applications from an earlier OCCT version to version 6.6.0 requires taking into account the following major changes:
111 * Due to the changes in the implementation of Boolean Operations, the order of sub-shapes resulting from the same operation performed with OCCT 6.5.x and OCCT 6.6.0 can be different. 
112 It is necessary to introduce the corresponding changes in the applications for which the order of sub-shapes resulting from a Boolean operation is important. It is strongly recommended to use identification methods not relying on the order of sub-shapes (e.g. OCAF naming).
113 * If you need to use OCCT on Mac OS X with X11 (without Cocoa), build OCCT with defined pre-processor macro *CSF_MAC_USE_GLX11*. XLib front-end (previously the only way for unofficial OCCT builds on Mac OS X) is now disabled by default on this platform. If your application has no support for Cocoa framework you may build OCCT with XLib front-end adding *MACOSX_USE_GLX* macro to compiler options (you may check the appropriate option in WOK configuration GUI and in CMake configuration). Notice that XQuartz (XLib implementation for Mac OS X) now is an optional component and does not provide a sufficient level of integrity with native (Cocoa-based) applications in the system. It is not possible to build OCCT with both XLib and Cocoa at the same time due to symbols conflict in OpenGL functions. 
114 * Animation mode and degeneration presentation mode (simplified presentation for animation) and associated methods have been removed from 3D viewer functionality.
115 Correspondingly, the code using methods *SetAnimationModeOn(), SetAnimationModeOff(), AnimationModeIsOn(), AnimationMode(), Tumble(), SetDegenerateModeOn(), SetDegenerateModeOff()* and *DegenerateModeIsOn()* of classes *V3d_View* and *Visual3d_View* will need to be removed or redesigned. Please, notice that Hidden Line Removal presentation was not affected; however, the old code that used methods *V3d_View::SetDegenerateModeOn* or *V3d_View::SetDegenerateModeOff* to control HLR presentation should be updated to use *V3d_View::SetComputedMode* method instead.
116 * Calls of *Graphic3d_Group::BeginPrimitives()* and *Graphic3d_Group::EndPrimitives()* should be removed from the application code.
117 * Application functionality for drawing 2D graphics that was formerly based on *TKV2d* API should be migrated to *TKV3d* API. The following changes are recommended for this migration:
118    * A 2D view can be implemented as a *V3d_View* instance belonging to *V3d_Viewer* managed by *AIS_InteractiveContext* instance. To turn *V3d_View* into a 2D view, the necessary view orientation should be set up at the view initialization stage using *V3d_View::SetProj()* method, and view rotation methods simply should not be called.
119    * Any 2D graphic entity (formerly represented with *AIS2D_InteractiveObject*) should become a class derived from *AIS_InteractiveObject* base. These entities should be manipulated in a view using *AIS_InteractiveContext* class API.
120    * All drawing code should be put into *Compute()* virtual method of a custom interactive object class and use API of *Graphic3d* package. In particular, all geometry should be drawn using class hierarchy derived from *Graphic3d_ArrayOfPrimitives*. Normally, the Z coordinate for 2D geometry should be constant, unless the application implements some advanced 2D drawing techniques like e.g. multiple "Z layers" of drawings.
121    * Interactive selection of 2D presentations should be set up inside *ComputeSelection()* virtual method of a custom interactive object class, using standard sensitive entities from *Select3D* package and standard or custom entity owners derived from *SelectMgr_EntityOwner* base.
122 Please refer to the Visualization User's Guide for further details concerning OCCT 3D visualization and selection classes. See also *Viewer2D* OCCT sample application, which shows how 2D drawing can be implemented using TKV3d API.
123 * Run-time graphic driver library loading mechanism based on *CSF_GraphicShr* environment variable usage has been replaced by explicit linking against *TKOpenGl* library. The code sample below shows how the graphic driver should be created and initialized in the application code: 
124 ~~~~
125 // initialize a new viewer with OpenGl graphic driver
126 Handle(Graphic3d_GraphicDriver) aGraphicDriver = 
127 new OpenGl_GraphicDriver ("TKOpenGl");
128   aGraphicDriver->Begin (new Aspect_DisplayConnection());
129   TCollection_ExtendedString aNameOfViewer ("Visu3D");
130   Handle(V3d_Viewer) aViewer 
131 = new V3d_Viewer (aGraphicDriver, aNameOfViewer.ToExtString());
132   aViewer->Init();
133
134 // create a new window or a wrapper over the existing window, 
135 // provided by a 3rd-party framework (Qt, MFC, C# or Cocoa)
136 #if defined(_WIN32) || defined(__WIN32__)
137   Aspect_Handle aWindowHandle = (Aspect_Handle )winId();
138   Handle(WNT_Window) aWindow = new WNT_Window (winId());
139 #elif defined(__APPLE__) && !defined(MACOSX_USE_GLX)
140   NSView* aViewHandle = (NSView* )winId();
141   Handle(Cocoa_Window) aWindow = new Cocoa_Window (aViewHandle);
142 #else
143  Aspect_Handle aWindowHandle = (Aspect_Handle )winId();
144   Handle(Xw_Window) aWindow = 
145      new Xw_Window (aGraphicDriver->GetDisplayConnection(), aWindowHandle);
146 #endif // WNT
147
148 // setup the window for a new view
149   Handle(V3d_View) aView = aViewer->CreateView();
150   aView->SetWindow (aWindow);
151 ~~~~
152
153 * The following changes should be made in the application-specific implementations of texture aspect:
154     * *Graphic3d_TextureRoot* inheritors now should return texture image by overloading of *Graphic3d_TextureRoot::GetImage()* method instead of the old logic.
155     * Now you can decide if the application should store the image copy as a field of property or reload it dynamically each time (to optimize the memory usage). The default implementation (which loads the image content from the provided file path) does not hold an extra copy since it will be uploaded to the graphic memory when first used.
156     * Notice that the image itself should be created within *Image_PixMap* class from *AlienImage* package, while *Image_Image* class is no more supported and will be removed in the next OCCT release.
157         
158 @section upgrade_670 Upgrade to OCCT 6.7.0
159
160 Porting of user applications from an earlier OCCT version to version 6.7.0 requires taking into account the following major changes.
161
162 @subsection upgrade_670_clipping Object-level clipping and capping algorithm. 
163
164 * It might be necessary to revise and port code related to management of view-level clipping to use *Graphic3d_ClipPlane* instead of *V3d_Plane* instances. Please note that *V3d_Plane* class has been preserved -- as previously, it can be used as plane representation. Another approach to represent *Graphic3d_ClipPlane* in a view is to use custom presentable object.
165 * The list of arguments of *Select3D_SensitiveEntity::Matches()* method for picking detection has changed. Since now, for correct selection clipping, the implementations should perform a depth clipping check and return (as output argument) minimum depth value found at the detected part of sensitive. Please refer to CDL / Doxygen documentation to find descriptive hints and snippets.
166 * *Select3D_SensitiveEntity::ComputeDepth()* abstract method has been removed. Custom implementations should provide depth checks by method *Matches()* instead -- all data required for it is available within a scope of single method.
167 * It might be necessary to revise the code of custom sensitive entities and port *Matches()* and *ComputeDepth()* methods to ensure proper selection clipping. Please note that obsolete signature of *Matches* is not used anymore by the selector. If your class inheriting *Select3D_SensitiveEntity* redefines the method with old signature the code should not compile as the return type has been changed. This is done to prevent override of removed methods.
168
169 @subsection upgrade_670_markers Redesign of markers presentation
170
171 * Due to the redesign of *Graphic3d_AspectMarker3d* class the code of custom markers initialization should be updated. Notice that you can reuse old markers definition code as *TColStd_HArray1OfByte*; however, *Image_PixMap* is now the preferred way (and supports full-color images on modern hardware).
172 * Logics and arguments of methods *AIS_InteractiveContext::Erase()* and *AIS_InteractiveContext::EraseAll()* have been changed. Now these methods do not remove resources from *Graphic3d_Structure*; they simply change the visibility flag in it. Therefore, the code that deletes and reсomputes resources should be revised.
173 * *Graphic3d_Group::MarkerSet()* has been removed. *Graphic3d_Group::AddPrimitiveArray()* should be used instead to specify marker(s) array.
174
175 @subsection upgrade_670_views Default views are not created automatically 
176
177 As the obsolete methods *Init(), DefaultOrthographicView()* and *DefaultPerspectiveView()* have been removed from *V3d_Viewer* class, the two default views are no longer created automatically. It is obligatory to create *V3d_View* instances explicitly, either directly by operator new or by calling *V3d_Viewer::CreateView()*. 
178
179 The call *V3d_Viewer::SetDefaultLights()* should also be done explicitly at the application level, if the application prefers to use the default light source configuration. Otherwise, the application itself should set up the light sources to obtain a correct 3D scene.
180
181 @subsection upgrade_670_dimensions Improved dimensions implementation
182
183 * It might be necessary to revise and port code related to management of *AIS_LengthDimension, AIS_AngleDimension* and *AIS_DiameterDimension* presentations. There is no more need to compute value of dimension and pass it as string to constructor argument. The value is computed internally. The custom value can be set with *SetCustomValue()* method.
184 * The definition of units and general aspect properties is now provided by *Prs3d_DimensionUnits* and *Prs3d_DimensionApsect* classes.
185 * It might be also necessary to revise code of your application related to usage of *AIS_DimensionDisplayMode enumeration*. If it used for specifying the selection mode, then it should be replaced by a more appropriate enumeration *AIS_DimensionSelectionMode*.
186
187 @subsection upgrade_670_list_collection NCollection_Set replaced by List collection 
188
189 It might be necessary to revise your application code, which uses non-ordered *Graphic3d_SetOfHClipPlane* collection type and replace its occurrences by ordered *Graphic3d_SequenceOfHClipPlane* collection type.
190
191
192 @section upgrade_680 Upgrade to OCCT 6.8.0
193
194 Porting of user applications from an earlier OCCT version to version 6.8.0 requires taking into account the following major changes.
195
196 @subsection upgrade_680_ncollection Changes in NCollection classes
197
198 Method *Assign()* in *NCollection* classes does not allow any more copying between different collection types. Such copying should be done manually.
199
200 List and map classes in *NCollection* package now require that their items be copy-constructible, but do not require items to have default constructor. Thus the code using *NCollection* classes for non-copy-constructible objects needs be updated. One option is to provide copy constructor; another possibility is to use Handle or other smart pointer.
201
202 @subsection upgrade_680_view_camera 3D View Camera
203
204 If *ViewMapping* and *ViewOrientation* were used directly, this functionality has to be ported to the new camera model. The following methods should be considered as an alternative to the obsolete *Visual3d* services (all points and directions are supposed to be in world coordinates):
205 * *Graphic3d_Camera::ViewDimensions()* or *V3d_View::Size()/ZSize()* -- returns view width, height and depth (or "Z size"). Since the view is symmetric now, you can easily compute top, bottom, left and right limits. *Graphic3d_Camera::ZNear()/ZFar()* can be used to obtain the near and far clipping distances with respect to the eye.
206 * *Graphic3d_Camera::Up()* or *V3d_View::Up()* -- returns Y direction of the view.
207 * *Graphic3d_Camera::Direction()* returns the reverse view normal directed from the eye, *V3d_View::Proj()* returns the old-style view normal.
208 * *Graphic3d_Camera::Eye()* or *V3d_View::Eye()* -- returns the camera position (same as projection reference point in old implementation).
209 * *Graphic3d_Camera::Center()* or *V3d_View::At()* -- returns the point the camera looks at (or view reference point according to old terminology).
210
211 The current perspective model is not fully backward compatible, so the old perspective-related functionality needs to be reviewed.
212
213 Please revise application-specific custom presentations to provide proper bounding box. Otherwise object might become erroneously clipped by automatic *ZFit* or frustum culling algorithms enabled by default.
214
215 @subsection upgrade_680_connected_objects Redesign of Connected Interactive Objects
216
217 The new implementation of connected Interactive Objects makes it necessary to take the following steps if you use connected Interactive Objects in your application.
218 * Use new *PrsMgr_PresentableObject* transformation API.
219 * Call *RemoveChild()* from the original object after connect if you need the original object and *AIS_ConnectedInteractive* to move independently.
220 * Access instances of objects connected to *AIS_MultiplyConnectedInteractive* with *Children()* method.
221 * For *PrsMgr_PresentableObject* transformation:
222    * *SetLocation (TopLoc_Location) -> SetLocalTransformation (gp_Trsf)*
223    * *Location -> LocalTransformation*
224    * *HasLocation -> HasTransformation*
225    * *ResetLocation -> ResetTransformation*
226    
227 @subsection upgrade_680_unicode Support of UNICODE Characters 
228
229 Support of UNICODE characters introduced in OCCT breaks backward compatibility with applications, which currently use filenames in extended ASCII encoding bound to the current locale. Such applications should be updated to convert such strings to UTF-8 format.
230
231 The conversion from UTF-8 to wchar_t is made using little-endian approach. Thus, this code will not work correctly on big-endian platforms. It is needed to complete this in the way similar as it is done for binary persistence (see the macro *DO_INVERSE* in *FSD_FileHeader.hxx).*
232
233 @subsection upgrade_680_projection_shift Elimination of Projection Shift Concept
234
235 It might be necessary to revise the application code, which deals with *Center()* method of *V3d_View*. 
236
237 This method was used to pan a *V3d* view by virtually moving the screen center with respect to the projection ray passed through Eye and At points. There is no more need to derive the panning from the Center parameter to get a camera-like eye position and look at the coordinates. *Eye()* and *At()* now return these coordinates directly. When porting code dealing with *Center()*, the parameters *Eye()* and *At()* can be adjusted instead. Also *V3d_View::SetCenter(Xpix, Ypix)* method can be used instead of *V3d_View::Center(X, Y)* to center the view at the given point. However, if the center coordinates X and Y come from older OCCT releases, calling *V3d_View::Panning(-X, -Y)* can be recommended to compensate missing projection shift effect.
238
239 There are several changes introduced to *Graphic3d_Camera*. The internal data structure of the camera is based on *Standard_Real* data types to avoid redundant application-level conversions and precision errors. The transformation matrices now can be evaluated both for *Standard_Real* and *Standard_ShortReal* value types. *ZNear* and *ZFar* planes can be either negative or positive for orthographic camera projection, providing a trade-off between the camera distance and the range of *ZNear* or *ZFar* to reduce difference of exponents of values composing the orientation matrix - to avoid calculation errors. The negative values can be specified to avoid Z-clipping if the reference system of camera goes inside of the model when decreasing camera distance.
240
241 The auto z fit mode, since now, has a parameter defining Z-range margin (the one which is usually passed as argument to *ZFitAll()* method). The methods *SetAutoZFitMode(), AutoZFitScaleFactor()* and *ZFitAll()* from class *V3d_View* deal with the new parameter.
242
243 The class *Select3D_Projector* now supports both orientation and projection transformation matrices, which can be naturally set for the projector. The definition of projector was revised in *StdSelect_ViewerSelector3d*: perspective and orthographic projection parameters are handled properly. Orthographic projector is based only on direction of projection - no more *Center* property. This makes it possible to avoid unnecessary re-projection of sensitive while panning, zooming or moving along the projection ray of the view. These operations do not affect the orthographic projection.
244
245
246 @section upgrade_690 Upgrade to OCCT 6.9.0
247
248 Porting of user applications from an earlier OCCT version to version 6.9.0 requires taking into account the following major changes.
249
250 @subsection upgrade_690_shaders 3D Viewer initialization
251
252 3D Viewer now uses GLSL programs for managing frame buffer and stereoscopic output.
253 For proper initialization, application should configure **CSF_ShadersDirectory** environment variable pointing to a folder with GLSL resources - files from folder **CASROOT**/src/Shaders.
254 *Note that **CSF_ShadersDirectory** become optional since OCCT 7.1.0 release*.
255
256 @subsection upgrade_690_selection Changes in Selection
257
258 Selection mechanism of 3D Viewer has been redesigned to use 3-level BVH tree traverse directly in 3D space instead of projection onto 2D screen space (updated on each rotation). This architectural redesign may require appropriate changes at application level in case if custom Interactive Objects are used.
259
260 #### Standard selection
261 Usage of standard OCCT selection entities would require only minor updates.
262
263 Custom Interactive Objects should implement new virtual method *SelectMgr_SelectableObject::BoundingBox().*
264
265 Now the method *SelectMgr_Selection::Sensitive()* does not return *SelectBasics_SensitiveEntity*. It returns an instance of *SelectMgr_SensitiveEntity*, which belongs to a different class hierarchy (thus *DownCast()* will fail). To access base sensitive it is necessary to use method *SelectMgr_SensitiveEntity::BaseSensitive()*. For example:
266
267 ~~~~
268 Handle(SelectMgr_Selection) aSelection = anInteractiveObject->Selection (aMode);
269 for (aSelection->Init(); aSelection->More(); aSelection->Next())
270 {
271    Handle(SelectBasics_SensitiveEntity) anEntity = aSelection->Sensitive()->BaseSensitive();
272 }
273 ~~~~
274
275 #### Custom sensitive entities
276
277 Custom sensitive entities require more complex changes, since the selection algorithm has been redesigned and requires different output from the entities. 
278
279 The method *SelectBasics_SensitiveEntity::Matches()* of the base class should be overridden following the new signature:
280
281 *Standard_Boolean Matches (SelectBasics_SelectingVolumeManager& theMgr, SelectBasics_PickResult& thePickResult)*, where *theMgr* contains information about the currently selected frustum or set of frustums (see *SelectMgr_RectangularFrustum, SelectMgr_TrangularFrustum, SelectMgr_TriangularFrustumSet)* and *SelectBasics_PickResult* is an output parameter, containing information about the depth of the detected entity and distance to its center of geometry.
282
283 In the overridden method it is necessary to implement an algorithm of overlap and inclusion detection (the active mode is returned by *theMgr.IsOverlapAllowed()*) with triangular and rectangular frustums.
284
285 The depth and distance to the center of geometry must be calculated for the 3D projection of user-picked screen point in the world space. You may use already implemented overlap and inclusion detection methods for different primitives from *SelectMgr_RectangularFrustum* and *SelectMgr_TriangularFrustum*, including triangle, point, axis-aligned box, line segment and planar polygon. 
286
287 Here is an example of overlap/inclusion test for a box:
288
289 ~~~~
290 if (!theMgr.IsOverlapAllowed()) // check for inclusion
291 {
292   Standard_Boolean isInside = Standard_True;
293   return theMgr.Overlaps (myBox.CornerMin(), myBox.CornerMax(), &isInside) && isInside;
294 }
295
296 Standard_Real aDepth;
297 if (!theMgr.Overlaps (myBox, aDepth)) // check for overlap
298 {
299   return Standard_False;
300 }
301
302 thePickResult =
303 SelectBasics_PickResult (aDepth, theMgr.DistToGeometryCenter (myCenter3d));
304 ~~~~
305
306 The interface of *SelectBasics_SensitiveEntity* now contains four new pure virtual functions that should be implemented by each custom sensitive:
307 * <i>BoundingBox()</i> – returns a bounding box of the entity;
308 * <i>Clear()</i> – clears up all the resources and memory allocated for complex sensitive entities;
309 * <i>BVH()</i> – builds a BVH tree for complex sensitive entities, if it is needed;
310 * <i>NbSubElements()</i> – returns atomic sub-entities of a complex sensitive entity, which will be used as primitives for BVH building. If the entity is simple and no BVH is required, this method returns 1.
311
312 Each sensitive entity now has its own tolerance, which can be overridden by method *SelectBasics_SensitiveEntity::SetSensitivityFactor()* called from constructor.
313
314
315 @subsection upgrade_690_adaptor3d-curve Changes in Adaptor3d_Curve class
316
317 All classes inheriting *Adaptor3d_Curve* (directly or indirectly) must be updated in application code to use new signature of methods *Intervals()* and *NbIntervals()*. Note that no compiler warning will be generated if this is not done.
318
319 @subsection upgrade_690_v3d_view Changes in V3d_View class
320
321 The methods *V3d_View::Convert* and *V3d_View::ConvertWithProj()* have ceased to return point on the active grid. It might be necessary to revise the code of your application so that *V3d_View::ConvertToGrid()* was called explicitly for the values returned by *V3d_View::Convert* to get analogous coordinates on the grid. The methods *V3d_View::Convert* and *V3d_View::ConvertWithProj* convert point into reference plane of the view corresponding to the intersection with the projection plane of the eye/view point vector.
322
323 @section upgrade_700 Upgrade to OCCT 7.0.0
324
325 Porting of user applications from an earlier OCCT version to version 7.0.0 requires taking into account the following major changes.
326
327 @subsection upgrade_700_persist Removal of legacy persistence
328
329 Legacy persistence for shapes and OCAF data based on *Storage_Schema* (toolkits *TKPShape*, *TKPLCAF*, *TKPCAF*, *TKShapeShcema, TLStdLSchema, TKStdSchema*, and *TKXCAFSchema*) has been removed in OCCT 7.0.0.
330 The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
331
332 @note For compatibility with previous versions, the possibility to read standard OCAF data (*TKLCAF* and *TKCAF*) from  files stored in the old format is preserved (toolkits *TKStdL* and *TKStd*).
333
334 The existing data files in standard formats can be converted using OCCT 6.9.1 or a previous version, as follows.
335
336 @note Reading / writing custom files capability from OCCT 6.9.1 is restored in OCCT 7.2.0. See details in @ref upgrade_720_persistence section.
337
338 #### CSFDB files
339
340 Files in *CSFDB* format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format. 
341 The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):
342
343 - Start ImportExport sample;
344 - Select File / New;
345 - Select File / Import / CSFDB... and specify the file to be converted;
346 - Drag the mouse with the right button pressed across the view to select all shapes by the rectangle;
347 - Select File / Export / BREP... and specify the location and name for the resulting file
348
349 #### OCAF and XCAF documents
350
351 Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
352 These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands.
353 Note that if the file contains only attributes defined in *TKLCAF* and *TKCAF*, this action can be performed in OCCT 7.0; otherwise OCCT 6.9.1 or earlier should be used.
354
355 For that, start *DRAWEXE* and perform the following commands: 
356
357   * 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*):
358
359   @code
360   Draw[]> pload ALL
361   Draw[]> Open [path to *.std or *.sgd file] Doc
362   Draw[]> Format Doc BinOcaf
363   Draw[]> SaveAs Doc [path to the new file]
364   @endcode
365
366   * 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*):
367
368   @code
369   Draw[]> pload ALL
370   Draw[]> XOpen [path to *.dxc file] Doc
371   Draw[]> Format Doc BinXCAF
372   Draw[]> XSave Doc [path to the new file]
373   @endcode
374
375 On Windows, it is necessary to replace back slashes in the file path by  direct slashes or pairs of back slashes.
376
377 Use *XmlOcaf* or *XmlXCAF* instead of *BinOcaf* and *BinXCAF*, respectively, to save in XML format instead of binary one.
378
379 @subsection upgrade_occt700_cdl Removal of CDL and WOK
380
381 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).
382
383 C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.
384
385 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.
386 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.
387
388 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.
389 The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
390 The 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.
391
392 @subsubsection upgrade_occt700_cdl_auto Automatic upgrade
393
394 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.
395 This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
396
397 Example:
398 ~~~~~
399  $ tclsh
400  % source <path_to_occt>/adm/upgrade.tcl
401  % upgrade -recurse -all -src=<path_to_your_sources>
402 ~~~~~
403
404 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:
405
406 ~~~~~
407 cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
408 ~~~~~
409
410 Run the upgrade tool without arguments to see the list of available options.
411
412 The upgrade tool performs the following changes in the code.
413
414 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):
415 ~~~~~
416 DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTIEXT(Class, Base)
417 ~~~~~
418
419    @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*. 
420    The former case is used if current file is header and source file with the same name is found in the same folder. 
421    In this case, macro *IMPLEMENT_STANDARD_RTTI* is injected in the corresponding source file.
422    The latter variant defines all methods for RTTI as inline, and does not require *IMPLEMENT_STANDARD_RTTIEXT* macro. 
423
424 2. Replaces forward declarations of collection classes previously generated from CDL generics (defined in *TCollection* package) by inclusion of the corresponding header:
425 ~~~~~
426 class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
427 ~~~~~
428
429 3. Replaces underscored names of *Handle* classes by usage of a macro:
430 ~~~~~
431 Handle_Class -> Handle(Class)
432 ~~~~~
433   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).
434   The file is considered as defining a Qt object if it contains strings *Q_OBJECT* and either *slots:* or *signals:*. 
435
436 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:
437 ~~~~~
438 class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
439 ~~~~~
440
441 5. Removes <i> \#includes </i> of files <i>Handle_...hxx</i> that have disappeared in OCCT 7.0:
442 ~~~~~
443 #include <Handle_Geom_Curve.hxx> ->
444 ~~~~~
445
446 6. Removes *typedef* statements that use *Handle* macro to generate the name:
447 ~~~~~
448 typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
449 ~~~~~
450
451 7. Converts C-style casts applied to Handles into calls to <i>DownCast()</i> method:
452 ~~~~~
453     ((Handle(A)&)b)     -> Handle(A)::DownCast(b)
454     (Handle(A)&)b       -> Handle(A)::DownCast(b)
455     (*((Handle(A)*)&b)) -> Handle(A)::DownCast(b)
456     *((Handle(A)*)&b)   -> Handle(A)::DownCast(b)
457     (*(Handle(A)*)&b)   -> Handle(A)::DownCast(b)
458 ~~~~~
459
460 8. Moves <i>Handle()</i> macro out of namespace scope:
461 ~~~~~
462 Namespace::Handle(Class) -> Handle(Namespace::Class)
463 ~~~~~
464
465 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):
466 ~~~~~
467     const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
468 ~~~~~
469
470 10. Adds  <i>\#include</i> for all classes used as argument to macro <i>STANDARD_TYPE()</i>, except for already included ones;
471
472 11. Removes uses of obsolete macros *IMPLEMENT_DOWNCAST* and *IMPLEMENT_STANDARD_*..., except *IMPLEMENT_STANDARD_RTTIEXT*.
473
474     @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.
475
476 .
477
478 As long as the upgrade routine runs, some information messages are sent to the standard output. 
479 In some cases the warnings or errors like the following may appear:
480
481 ~~~~~
482   Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
483 ~~~~~
484
485 Be sure to check carefully all reported errors and warnings, as the corresponding code will likely require manual corrections.
486 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.
487
488 @subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
489
490 Some situations requiring upgrade cannot be detected and / or handled by the automatic procedure.
491 If you get compiler errors or warnings when trying to build the upgraded code, you will need to fix them manually. 
492 The following paragraphs list known situations of this kind.
493
494 #### Missing header files
495
496 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.
497
498 For example, the following lines will fail to compile if *Geom_Line.hxx* is not included:
499
500 ~~~~~
501 Handle(Geom_Line) aLine = 0;
502 if (aLine != aCurve) {...} 
503 if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
504 aLine = Handle(Geom_Line)::DownCast (aCurve);
505 ~~~~~
506
507 Note that it is not necessary to include header of the class to declare Handle to it.
508 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*.
509 This will eliminate the need to include the header *A* in each source file where class *B* is used.
510
511 #### Ambiguity of calls to overloaded functions
512
513 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 more overloaded versions, receiving handles to different types. 
514 The problem is that operator  <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
515
516 Example:
517 ~~~~~
518 void func (const Handle(Geom_Curve)&);
519 void func (const Handle(Geom_Surface)&);
520
521 Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
522 func (aCurve); // ambiguity error in VC++ 10
523 ~~~~~
524
525 Note that this problem can be avoided in many cases if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
526
527 To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature. 
528 In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
529
530 ~~~~~
531 Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);  
532 ~~~~~
533
534 Other variants consist in assigning the argument to a local variable of the correct type and using the direct cast or constructor:
535
536 ~~~~~
537 const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
538 func (aGCurve); // OK - argument has exact type
539 func (static_cast(aCurve)); // OK - direct cast 
540 func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
541 ~~~~~
542
543 Another possibility consists in defining additional template variant of the overloaded function causing ambiguity, and using *SFINAE* to resolve the ambiguity.
544 This technique can be illustrated by the definition of the template variant of method <i>IGESData_IGESWriter::Send()</i>.
545
546 #### Lack of implicit cast to base type
547
548 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.
549
550 For example:
551
552 ~~~~~
553 Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
554 ~~~~~
555
556 The problem is that the class *GC_MakeLine* 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*.
557
558 To resolve this, use method <i>Value()</i>:
559
560 ~~~~~
561 Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
562 ~~~~~
563
564 or use variable of the appropriate type:
565
566 ~~~~~
567 Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
568 ~~~~~
569
570 A similar problem appears with GCC compiler, 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:
571
572 ~~~~~
573   const Handle(Geom_Line) aLine;
574   Handle(Geom_Curve) c1 = aLine; // GCC error 
575   Handle(Geom_Curve) c2 (aLine); // ok
576 ~~~~~
577
578 This problem is specific to GCC and it does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
579
580 #### Incorrect use of STANDARD_TYPE and Handle macros
581
582 You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().
583
584 1. Explicit definitions of static functions with names generated by macro *STANDARD_TYPE()*, which are artifacts of old implementation of RTTI, should be removed.
585    
586    Example:
587 ~~~~~
588 const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
589 {
590   static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
591   return _atype;
592 }
593 ~~~~~
594
595 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.
596
597    Example (note misplaced closing parenthesis):
598 ~~~~~
599 aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
600 ~~~~~
601
602 #### Use of class Standard_AncestorIterator
603
604 Class *Standard_AncestorIterator* has been removed; use method *Parent()* of *Standard_Type* class to parse the inheritance chain.
605
606 #### Absence of cast to Standard_Transient*
607
608 Handles in OCCT 7.0 do not have the operator of conversion to <i>Standard_Transient*,</i> which was present in earlier versions.
609 This is done to prevent possible unintended errors like this:
610
611 ~~~~~
612 Handle(Geom_Line) aLine = ...;
613 Handle(Geom_Surface) aSurf = ...;
614 ...
615 if (aLine == aSurf) {...} // will cause a compiler error in OCCT 7.0, but not OCCT 6.x
616 ~~~~~
617
618 The places where this implicit cast has been used should be corrected manually.
619 The typical situation is when Handle is passed to stream:
620
621 ~~~~~
622 Handle(Geom_Line) aLine = ...;
623 os << aLine; // in OCCT 6.9.0, resolves to operator << (void*) 
624 ~~~~~
625
626 Call method <i>get()</i> explicitly to output the address of the Handle.
627
628 #### Method DownCast for non-base types
629
630 Method *DownCast()* in OCCT 7.0 is made templated; if its argument is not a base class, "deprecated" compiler warning is generated.
631 This is done to prevent possible unintended errors like this:
632
633 ~~~~~
634 Handle(Geom_Surface) aSurf = ;
635 Handle(Geom_Line) aLine = 
636   Handle(Geom_Line)::DownCast (aSurf); // will cause a compiler warning in OCCT 7.0, but not OCCT 6.x
637 ~~~~~
638
639 The places where this cast has been used should be corrected manually.
640
641 If down casting is used in a template context where the 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.: 
642
643 ~~~~~
644 template <class T>
645 bool CheckLine (const Handle(T) theArg)
646 {
647   Handle(Geom_Line) aLine = dynamic_cast<Geom_Line> (theArg.get());
648   ...
649 }
650 ~~~~~
651
652 @subsubsection upgrade_occt700_cdl_runtime Possible runtime problems
653
654 Here is the list of known possible problems at run time after the upgrade to OCCT 7.0.
655
656 #### References to temporary objects
657
658 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. 
659 In 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.
660
661 This problem does not appear if macro *OCCT_HANDLE_NOCAST* is used during compilation, see below.
662
663 Example:
664
665 ~~~~~
666 // note that DownCast() returns new temporary object!
667 const Handle(Geom_BoundedCurve)& aBC =
668 Handle(Geom_TrimmedCurve)::DownCast(aCurve);
669 aBC->Transform (T); // access violation in OCCT 7.0
670 ~~~~~
671
672 @subsubsection upgrade_occt700_cdl_nocast Option to avoid cast of handle to reference to base type
673
674 In OCCT 6.x and earlier versions the handle classes formed a hierarchy echoing the hierarchy of the corresponding object classes .
675 This automatically enabled the possibility to use the handle to a derived class in all contexts where the handle to a base class was needed, e.g. to pass it in a function by reference without copying:
676
677 ~~~~
678 Standard_Boolean GetCurve (Handle(Geom_Curve)& theCurve);
679 ....
680 Handle(Geom_Line) aLine;
681 if (GetCurve (aLine)) {
682   // use aLine, unsafe
683 }
684 ~~~~
685
686 This feature was used in multiple places in OCCT and dependent projects.
687 However it is potentially unsafe: in the above example no checks are done at compile time or at run time to ensure that the type assigned to the argument handle is compatible with the type of the handle passed as argument. 
688 If an object of incompatible type (e.g. Geom_Circle) is assigned to *theCurve*, the behavior will be unpredictable. 
689
690 For compatibility with the existing code, OCCT 7.0 keeps this possibility by default, providing operators of type cast to the handle to a base type. However, this feature is unsafe and in specific situations it may cause compile-time or run-time errors as described above.
691
692 To provide a safer behavior, this feature can be disabled by a compile-time macro *OCCT_HANDLE_NOCAST*.
693 When it is used, constructors and assignment operators are defined (instead of type cast operators) to convert handles to a derived type into handles to a base type.
694 This 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.
695
696 The code that relies on the possibility of casting to base should be amended to always use the handle of argument type in function call and to use *DownCast()* to safely convert the result to the desired type.
697 For instance, the code from the example below can be changed as follows:
698
699 ~~~~~
700 Handle(Geom_Line) aLine;
701 Handle(Geom_Curve) aCurve;
702 if (GetCurve (aCure) && !(aLine = Handle(Geom_Line)::DownCast (aCurve)).IsNull()) {
703   // use aLine safely
704 }
705 ~~~~~
706
707 @subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x
708
709 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:
710
711 1. If your code used sequences of macros *IMPLEMENT_STANDARD_*... generated by WOK, replace them by single macro *IMPLEMENT_STANDARD_RTTIEXT*
712
713 2. When running automatic upgrade tool, add option <i>-compat</i>.
714
715 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 
716
717    Example:
718 ~~~~~   
719 #if OCC_VERSION_HEX < 0x070000
720   #define DEFINE_STANDARD_RTTIEXT(C1,C2) DEFINE_STANDARD_RTTI(C1)
721   #define DEFINE_STANDARD_RTTI_INLINE(C1,C2) DEFINE_STANDARD_RTTI(C1)
722 #endif
723 ~~~~~
724
725 @subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK
726
727 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.
728 This is a non-trivial effort; the required actions would depend strongly on the structure of the code and used CDL features.
729
730 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).
731
732 [Contact us](http://www.opencascade.com/contact/) if you need more help.
733
734 @subsection upgrade_occt700_bspline Separation of BSpline cache
735
736 Implementation of NURBS curves and surfaces has been revised: the cache of polynomial coefficients, which is used to accelerate the calculation of values of a B-spline, has been separated from data objects *Geom2d_BSplineCurve, Geom_BSplineCurve* and *Geom_BSplineSurface* into the dedicated classes *BSplCLib_Cache* and *BSplSLib_Cache*. 
737
738 The benefits of this change are:
739 * Reduced memory footprint of OCCT shapes (up to 20% on some cases)
740 * Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks 
741
742 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.
743
744 OCCT algorithms have been changed to use adaptors for B-spline calculations instead of direct methods for  curves and surfaces.
745 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.
746
747 @subsection upgrade_occt700_booleanresult Structural result of Boolean operations
748
749 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.
750
751 @subsection upgrade_occt700_brepextrema BRepExtrema_ExtCC finds one solution only
752
753 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.
754
755 @subsection upgrade_occt700_sorttools Removal of SortTools package
756
757 Package *SortTools* has been removed. 
758 The code that used the tools provided by that package should be corrected manually.
759 The recommended approach is to use sorting algorithms provided by STL.
760
761 For instance:
762 ~~~~~
763 #include <SortTools_StraightInsertionSortOfReal.hxx>
764 #include <SortTools_ShellSortOfReal.hxx>
765 #include <TCollection_CompareOfReal.hxx>
766 ...
767 TCollection_Array1OfReal aValues = ...;
768 ...
769 TCollection_CompareOfReal aCompReal;
770 SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
771 ~~~~~
772 can be replaced by:
773 ~~~~~
774 #include <algorithm>
775 ...
776 TCollection_Array1OfReal aValues = ...;
777 ...
778 std::stable_sort (aValues.begin(), aValues.end());
779 ~~~~~
780
781 @subsection upgrade_occt700_2dlayers On-screen objects and ColorScale
782
783 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.
784 Classes *Aspect_Clayer2d, OpenGl_GraphicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr* and *V3d_LayerMgrPointer* have been deleted.
785
786 General AIS interactive objects with transformation persistence flag *Graphic3d_TMF_2d* can be used as a replacement of *Visual3d_LayerItem*.
787 The anchor point specified for transformation persistence defines the window corner of  (or center in case of (0, 0) point).
788 To keep on-screen 2D objects on top of the main screen, they can be assigned to the appropriate Z-layer.
789 Predefined Z-layers *Graphic3d_ZLayerId_TopOSD* and *Graphic3d_ZLayerId_BotOSD* are intended to replace Underlay and Overlay layers within the old API.
790
791 *ColorScale* object previously implemented using *Visual3d_LayerItem* has been moved to a new class *AIS_ColorScale*, with width and height specified explicitly.
792 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*.
793 Here is an example of creating *ColorScale* using the updated API:
794
795 ~~~~~
796 Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
797 // configuring
798 Standard_Integer aWidth, aHeight;
799 aView->Window()->Size (aWidth, aHeight);
800 aCS->SetSize              (aWidth, aHeight);
801 aCS->SetRange             (0.0, 10.0);
802 aCS->SetNumberOfIntervals (10);
803 // displaying
804 aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
805 aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
806 aCS->SetToUpdate();
807 theContextAIS->Display (aCS);
808 ~~~~~
809
810 To see how 2d objects are implemented in OCCT you can call Draw commands *vcolorscale, vlayerline* or *vdrawtext* (with <i>-2d</i> option).
811 Draw command *vcolorscale* now requires the name of *ColorScale* object as argument.
812 To display this object use command *vdisplay*. For example:
813
814 ~~~~~
815 pload VISUALIZATION
816 vinit
817 vcolorscale cs -demo
818 pload MODELING
819 box b 100 100 100
820 vdisplay b
821 vsetdispmode 1
822 vfit
823 vlayerline 0 300 300 300 10
824 vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
825 ~~~~~
826
827 Here is a small example in C++ illustrating how to display a custom AIS object in 2d:
828 ~~~~~
829 Handle(AIS_InteractiveContext) aContext = ...;
830 Handle(AIS_InteractiveObject) anObj =...; // create an AIS object
831 anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); // display object in overlay
832 anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); // set 2d flag, coordinate origin is set to down-left corner
833 aContext->Display (anObj); // display the object
834 ~~~~~
835
836 @subsection upgrade_occt700_userdraw UserDraw and Visual3d
837
838 #### Visual3d package
839
840 Package *Visual3d* implementing the intermediate layer between high-level *V3d* classes
841 and low-level OpenGl classes for views and graphic structures management has been dropped.
842
843 The *OpenGl_View* inherits from the new class *Graphic3d_CView*.
844 *Graphic3d_CView* is an interface class that declares abstract methods for managing displayed structures,
845 display properties and a base layer code that implements computation
846 and management of HLR (or more broadly speaking view-depended) structures.
847
848 In the new implementation it takes place of the eliminated *Visual3d_View*.
849 As before the instance of *Graphic3d_CView* is still completely managed by *V3d_View* classes.
850 It can be accessed through *V3d_View* interface but normally it should not be required as all its methods are completely wrapped.
851
852 In more details, a concrete specialization of *Graphic3d_CView* is created and returned by the graphical driver on request.
853 Right after the creation the views are directly used for setting rendering properties and adding graphical structures to be displayed.
854
855 The rendering of graphics is possible after mapping a window and activating the view.
856 The direct setting of properties obsoletes the use of intermediate structures with display parameter
857 like *Visual3d_ContextView*, etc. This means that the whole package *Visual3d* becomes redundant.
858
859 The functionality previously provided by *Visual3d* package has been redesigned in the following way :
860 - The management of display of structures has been moved from *Visual3d_ViewManager* into *Graphic3d_StructureManager*.
861 - The class *Visual3d_View* has been removed. The management of computed structures has been moved into the base layer of *Graphi3d_CView*.
862 - All intermediate structures for storing view parameters, e.g. *Visual3d_ContextView*, have been removed.
863   The settings are now kept by instances of *Graphic3d_CView*.
864 - 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.
865 - All necessary enumerations have been moved into *Graphic3d* package.
866
867 #### Custom OpenGL rendering and UserDraw
868
869 Old APIs based on global callback functions for creating *UserDraw* objects and for performing custom OpenGL rendering within the view have been dropped.
870 *UserDraw* callbacks are no more required since *OpenGl_Group* now inherits *Graphic3d_Group* and thus can be accessed directly from *AIS_InteractiveObject*:
871
872 ~~~~~
873 //! Class implementing custom OpenGL element.
874 class UserDrawElement : public OpenGl_Element {};
875
876 //! Implementation of virtual method AIS_InteractiveObject::Compute().
877 void UserDrawObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
878                               const Handle(Prs3d_Presentation)& thePrs,
879                               const Standard_Integer theMode)
880 {
881   Graphic3d_Vec4 aBndMin (myCoords[0], myCoords[1], myCoords[2], 1.0f);
882   Graphic3d_Vec4 aBndMax (myCoords[3], myCoords[4], myCoords[5], 1.0f);
883
884   // casting to OpenGl_Group should be always true as far as application uses OpenGl_GraphicDriver for rendering
885   Handle(OpenGl_Group) aGroup = Handle(OpenGl_Group)::DownCast (thePrs->NewGroup());
886   aGroup->SetMinMaxValues (aBndMin.x(), aBndMin.y(), aBndMin.z(),
887                            aBndMax.x(), aBndMax.y(), aBndMax.z());
888   UserDrawElement* anElem = new UserDrawElement (this);
889   aGroup->AddElement(anElem);
890
891   // invalidate bounding box of the scene
892   thePrsMgr->StructureManager()->Update();
893 }
894 ~~~~~
895
896 To perform a custom OpenGL code within the view, it is necessary to inherit from class *OpenGl_View*.
897 See the following code sample:
898
899 ~~~~~
900 //! Custom view.
901 class UserView : public OpenGl_View
902 {
903 public:
904   //! Override rendering into the view.
905   virtual void render (Graphic3d_Camera::Projection theProjection,
906                        OpenGl_FrameBuffer*          theReadDrawFbo,
907                        const Standard_Boolean       theToDrawImmediate)
908   {
909     OpenGl_View::render (theProjection, theReadDrawFbo, theToDrawImmediate);
910     if (theToDrawImmediate)
911     {
912       return;
913     }
914
915     // perform custom drawing
916     const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext();
917     GLfloat aVerts[3] = { 0.0f, 0,0f, 0,0f };
918     aCtx->core20->glEnableClientState(GL_VERTEX_ARRAY);
919     aCtx->core20->glVertexPointer(3, GL_FLOAT, 0, aVerts);
920     aCtx->core20->glDrawArrays(GL_POINTS, 0, 1);
921     aCtx->core20->glDisableClientState(GL_VERTEX_ARRAY);
922   }
923
924 };
925
926 //! Custom driver for creating UserView.
927 class UserDriver : public OpenGl_GraphicDriver
928 {
929 public:
930   //! Create instance of own view.
931   virtual Handle(Graphic3d_CView) CreateView (const Handle(Graphic3d_StructureManager)& theMgr) Standard_OVERRIDE
932   {
933     Handle(UserView) aView = new UserView (theMgr, this, myCaps, myDeviceLostFlag, &myStateCounter);
934     myMapOfView.Add (aView);
935     for (TColStd_SequenceOfInteger::Iterator aLayerIt (myLayerSeq); aLayerIt.More(); aLayerIt.Next())
936     {
937       const Graphic3d_ZLayerId        aLayerID  = aLayerIt.Value();
938       const Graphic3d_ZLayerSettings& aSettings = myMapOfZLayerSettings.Find (aLayerID);
939       aView->AddZLayer         (aLayerID);
940       aView->SetZLayerSettings (aLayerID, aSettings);
941     }
942     return aView;
943   }
944 };
945
946 ~~~~~
947
948 @subsection upgrade_occt700_localcontext Deprecation of Local Context
949
950 The conception of Local Context has been deprecated.
951 The related classes, e.g. *AIS_LocalContext*, and methods ( <i>AIS_InteractiveContext::OpenLocalContext()</i> and others) will be removed in a future OCCT release.
952
953 The main functionality provided by Local Context - selection of object subparts - can be now used within Neutral Point without opening any Local Context.
954
955 The property *SelectionMode()* has been removed from the class *AIS_InteractiveObject*.
956 This property contradicts to selection logic, since it is allowed to activate several Selection modes at once.
957 Therefore keeping one selection mode as object field makes no sense.
958 Applications that used this method should implement selection mode caching at application level, if it is necessary for some reason.
959
960 @subsection upgrade_occt700_separate_caf_visualisation Separation of visualization part from TKCAF
961
962 Visualization CAF attributes have been moved into a new toolkit *TKVCAF*. 
963 If your application uses the classes from *TPrsStd* package then add link to *TKVCAF* library.
964
965 Version numbers of *BinOCAF* and *XmlOCAF* formats are incremented; new files cannot be read by earlier versions of OCCT.
966
967 Before loading the OCAF files saved by previous versions and containing *TPrsStd_AISPresentation* attribute it is necessary to define the environment variable *CSF_MIGRATION_TYPES*, pointing to file *src/StdResources/MigrationSheet.txt*.
968 When using documents loaded from a file, make sure to call method *TPrsStd_AISViewer::New()* prior to accessing *TPrsStd_AISPresentation* attributes in this document as that method creates them.
969
970 @subsection upgrade_euler_angles Correction of interpretation of Euler angles in gp_Quaternion
971
972 Conversion of *gp_Quaternion* to and from intrinsic Tait-Bryan angles (including *gp_YawPitchRoll*) is fixed.
973
974 Before that fix the sequence of rotation axes was opposite to the intended; e.g. *gp_YawPitchRoll* (equivalent to *gp_Intrinsic_ZYX*) actually  defined intrinsic rotations around X, then Y, then Z. Now the rotations are made in the correct order.
975
976 The 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.
977
978 @subsection upgrade_zoom_persistent_selection Zoom Persistent Selection
979
980 Zoom persistent selection introduces a new structure *Graphic3d_TransformPers* to transform persistence methods and parameters and a new class *Graphic3d_WorldViewProjState* to refer to the camera transformation state. You might need to update your code to deal with the new classes if you were using the related features. Please, keep in mind the following: 
981 * *Graphic3d_Camera::ModelViewState* has been renamed to *Graphic3d_Camera::WorldViewState*.
982 * Transformation matrix utilities from *OpenGl_Utils* namespace have been moved to *Graphic3d_TransformUtils* and *Graphic3d_TransformUtils.hxx* header respectively.
983 * Matrix stack utilities from *OpenGl_Utils* namespace have been moved to *OpenGl_MatrixStack* class and *OpenGl_MatrixStack.hxx* header respectively.
984 * *OpenGl_View* methods *Begin/EndTransformPersistence* have been removed. Please, use *Graphic3d_TransformPers::Apply()* instead to apply persistence to perspective and world-view projection matrices.
985
986 @subsection upgrade_occt700_correction_of_texture Texture mapping of objects
987
988 Textured objects now have the priority over the environment mapping.
989
990 Redundant enumerations *V3d_TypeOfSurface* and *Graphic3d_TypeOfSurface*, class *OpenGl_SurfaceDetailState*, the corresponding methods from *Graphic3d_CView, OpenGl_ShaderManager, OpenGl_View, V3d_View* and *V3d_Viewer* have been deleted.
991 Draw command *VSetTextureMode* has been deleted.
992
993 @subsection upgrade_occt700_wfshape Shape presentation builders
994
995 Presentation tools for building Wireframe presentation have been refactored to eliminate duplicated code and interfaces.
996 Therefore, the following classes have been modified:
997 * *StdPrs_WFDeflectionShape* and *Prs3d_WFShape* have been removed. *StdPrs_WFShape* should be used instead.
998 * *StdPrs_ToolShadedShape* has been renamed to *StdPrs_ToolTriangulatedShape*.
999
1000 @section upgrade_occt710 Upgrade to OCCT 7.1.0
1001
1002 @subsection upgrade_710_aspects Presentation attributes
1003
1004 This section should be considered if application defines custom presentations, i.e. inherited from *AIS_InteractiveObject*.
1005 The previous versions of OCCT have three levels for defining presentation properties (e.g. colors, materials, etc.):
1006
1007 1. For the entire structure - *Graphic3d_Structure* / *Prs3d_Presentation*.
1008 2. For a specific group of primitives - *Graphic3d_Group::SetGroupPrimitivesAspect()* overriding structure aspects.
1009 3. For a specific primitive array within the graphic group - *Graphic3d_Group::SetPrimitivesAspect()*.
1010
1011 The structure level has de facto not been used for a long time since OCCT presentations always define aspects at the graphic group level (overriding any structure aspects).
1012 Within this OCCT release, structure level of aspects has been completely removed. In most cases the application code should just remove missing methods. In those rare cases, when this functionality was intentionally used, the application should explicitly define aspects to the  appropriate graphic groups.
1013
1014 Note that defining several different aspects within the same graphic group should also be avoided in the application code since it is a deprecated functionality which can be removed in further releases.
1015 *Graphic3d_Group::SetGroupPrimitivesAspect()* should be the main method defining presentation attributes.
1016
1017 The implementation of *Graphic3d_Group::SetGroupPrimitivesAspect()* has been changed from copying aspect values to keeping the passed object.
1018 Although it was not documented, previously it was possible to modify a single aspect instance, like *Graphic3d_AspectFillArea3d* and set it to multiple groups.
1019 Now such code would produce an unexpected result and therefore should be updated to create the dedicated aspect instance.
1020
1021 @subsection upgrade_710_types Typedefs
1022
1023 The following type definitions in OCCT has been modified to use C++11 types:
1024 - *Standard_Boolean* is now *bool* (previously *unsigned int*).
1025 - *Standard_ExtCharacter* is now *char16_t* (previously *short*).
1026 - *Standard_ExtString;* is now *const char16_t* (previously *const short*).
1027 - *Standard_Utf16Char* is now *char16_t* (previously *uint16_t* for compatibility with old compilers).
1028 - *Standard_Utf32Char* is now *char32_t* (previously *uint32_t* for compatibility with old compilers).
1029
1030 For most applications this change should be transparent on the level of source code. Binary compatibility is not maintained, as *bool* has a different size in comparison with *unsigned int*.
1031
1032 @subsection upgrade_710_ffp Programmable Pipeline
1033
1034 Fixed-function pipeline has been already deprecated since OCCT 7.0.0.
1035 Release 7.1.0 disables this functionality by default in favor of Programmable Pipeline (based on GLSL programs).
1036
1037 Method *V3d_View::Export()*, based on *gl2ps* library, requires fixed pipeline and will return error if used with default settings.
1038 Applications should explicitly enable fixed pipeline by setting *OpenGl_Caps::ffpEnable* flag to TRUE within *OpenGl_GraphicDriver::ChangeOptions()* before creating the viewer to use *V3d_View::Export()*.
1039 This method is declared as deprecated and will be removed in one of the the next OCCT releases.
1040 The recommended way to generate a vector image of a 3D model or scene is to use an application-level solution independent from OpenGL.
1041
1042 @subsection upgrade_710_trsfpers Transformation persistence
1043
1044 The behavior of transformation persistence flags *Graphic3d_TMF_ZoomPers* and *Graphic3d_TMF_TriedronPers* has been changed for consistency with a textured fixed-size 2D text.
1045 An object with these flags is considered as defined in pixel units, and the presentation is no more scaled depending on the view height.
1046 The applications that need to scale such objects depending on viewport size should update them manually.
1047
1048 Flags *Graphic3d_TMF_PanPers* and *Graphic3d_TMF_FullPers* have been removed.
1049 *Graphic3d_TMF_TriedronPers* or *Graphic3d_TMF_2d* can be used instead depending on the context.
1050
1051 *Graphic3d_TransModeFlags* is not an integer bitmask anymore - enumeration values should be specified instead.
1052 Several transformation persistence methods in *PrsMgr_PresentableObject* have been marked deprecated.
1053 Transformation persistence should be defined using  *Graphic3d_TransformPers* constructor directly and passed by a handle, not value.
1054
1055 @subsection upgrade_710_selprops Dynamic highlight and selection properties
1056
1057 Release 7.1.0 introduces *Graphic3d_HighlightStyle* - an entity that allows flexible customization of highlighting parameters (such as highlighting method, color, and transparency). Therefore, the signatures of the following methods related to highlighting:
1058 - *AIS_InteractiveContext::Hilight()*;
1059 - *AIS_InteractiveContext::HilightWithColor()*;
1060 - *PrsMgr_PresentationManager::Color()*;
1061 - *SelectMgr_EntityOwner::HilightWithColor()*;
1062 have been changed to receive *Graphic3d_HighlightStyle* instead of *Quantity_Color*.
1063
1064 Method *AIS_InteractiveContext::Hilight* is now deprecated and highlights the interactive object with selection style.
1065
1066 A group of methods *AIS_InteractiveContext::IsHilighted* has changed its behavior - now they only check highlight flags of the object or the owner in the global status. If the highlight color is required on the application level, it is necessary to use overloaded methods *AIS_InteractiveContext::HighlightStyle* for the owner and the object.
1067
1068 The following methods have been replaced in *AIS_InteractiveContext* class:
1069 - *HilightColor* and *SetHilightColor* by *HighlightStyle* and *SetHighlightStyle*;
1070 - *SelectionColor* setter and getter by *SelectionStyle* and *SetSelectionStyle*.
1071
1072 The API of *Prs3d_Drawer* has been extended to allow setting up styles for both dynamic selection and highlighting. Therefore, it is possible to change the highlight style of a particular object on the application level via *SelectMgr_SelectableObject::HilightAttributes()* and process it in the entity owner.
1073
1074 @subsection upgrade_occt710_correction_of_TObj_Model Correction in TObj_Model class
1075
1076 Methods *TObj_Model::SaveAs* and *TObj_Model::Load* now receive *TCollection_ExtendedString* filename arguments instead of char*. UTF-16 encoding can be used to pass file names containing Unicode symbols.
1077
1078 @subsection upgrade_710_env Redundant environment variables
1079
1080 The following environment variables have become redundant:
1081
1082 * *CSF_UnitsLexicon* and *CSF_UnitsDefinition* are no more used.  Units definition (*UnitsAPI/Lexi_Expr.dat* and *UnitsAPI/Units.dat*) is now embedded into source code.
1083 * *CSF_XSMessage* and *CSF_XHMessage* are now optional.
1084   English messages (XSMessage/*XSTEP.us* and SHMessage/*SHAPE.us*) are now embedded into source code
1085   and automatically loaded when environment variables are not set.
1086 * *CSF_ShadersDirectory* is not required any more, though it still can be used to load custom shaders.
1087   Mandatory GLSL resources are now embedded into source code.
1088 * *CSF_PluginDefaults* and other variables pointing to OCAF plugin resources (*CSF_StandardDefaults*, *CSF_XCAFDefaults*, *CSF_StandardLiteDefaults* and *CSF_XmlOcafResource*) are not necessary if method *TDocStd_Application::DefineFormat()* is used to enable persistence of OCAF documents.
1089
1090 Other environment variables still can be used to customize behavior of relevant algorithms but are not necessary any more (all required resources are embedded).
1091
1092 @subsection upgrade_710_removed Removed features
1093
1094 The following obsolete features have been removed:
1095 * Anti-aliasing API *V3d_View::SetAntialiasingOn()*. This method was intended to activate deprecated OpenGL functionality *GL_POLYGON_SMOOTH, GL_LINE_SMOOTH* and *GL_POINT_SMOOTH*.
1096   Instead of the old API, the application should request MSAA buffers for anti-aliasing by assigning *Graphic3d_RenderingParams::NbMsaaSamples* property of the structure returned by *V3d_View::ChangeRenderingParams()*.
1097 * *Prs3d_Drawer::ShadingAspectGlobal()* flag has been removed as not used. The corresponding calls can be removed safely from the application code.
1098 * The methods managing ZClipping planes and ZCueing: *V3d_View::SetZClippingType()*, *V3d_View::SetZCueingOn()*, etc. have been removed.  ZClipping planes can be replaced by general-purpose clipping planes (the application should update plane definition manually).
1099 * The 3D viewer printing API *V3d_View::Print()* has been removed. This functionality was available on Windows platforms only. The applications should use the general image dump API *V3d_View::ToPixMap()* and manage printing using a platform-specific API at the application level.
1100   Text resolution can be managed by rendering parameter *Graphic3d_RenderingParams::Resolution*, returned by *V3d_View::ChangeRenderingParams()*.
1101 * Methods *PrsMgr_PresentationManager::BoundBox*, *PrsMgr_PresentationManager::Hilight* and *SelectMgr_EntityOwner::Hilight* have been removed as not used. The corresponding method in custom implementations of *SelectMgr_EntityOwner* can be removed safely. *PrsMgr_PresentationManager::Color* with the corresponding style must be used instead.
1102 * Class *NCollection_QuickSort* has been removed. The code that used the tools provided by that class should be corrected manually. The recommended approach is to use sorting algorithms provided by STL (std::sort). See also @ref upgrade_occt700_sorttools above.
1103
1104 * Package *Dico*. The code that used the tools provided by that package should be corrected manually.  The recommended approach is to use *NCollection_DataMap* and *NCollection_IndexedDataMap* classes.
1105
1106 @subsection upgrade_710_changed_methods Other changes
1107
1108 The following classes have been changed:
1109
1110 * *BVH_Sorter* class has become abstract. The list of arguments of both  *Perform* methods has been changed and the methods became pure virtual.
1111 * *Extrema_FuncExtPS* has been renamed to *Extrema_FuncPSNorm*.
1112 * The default constructor and the constructor taking a point and a surface have been removed from class *Extrema_GenLocateExtPS*. Now the only constructor takes the surface and optional tolerances in U and V directions. The new method *Perform* takes the point with the start solution and processes it. The class has become not assignable and not copy-constructable.
1113 * Constructors with arguments *(const gp_Ax22d& D, const gp_Pnt2d& F)* have been removed from *GCE2d_MakeParabola*, *gce_MakeParab2d* and *gp_Parab2d*.  The objects created with some constructors of class *gp_Parab2d*  may differ from the previous version (see the comments in *gp_Parab2d.hxx*). The result returned by *gp_Parab2d::Directrix()* method has an opposite direction in comparison with the previous OCCT versions.
1114 * *BRepTools_Modifier* class now has two modes of work. They are defined by the boolean parameter *MutableInput*, which is turned off by default. This means that the algorithm always makes a copy of a sub-shape (e.g. vertex) if its tolerance is to be increased in the output shape. The old mode corresponds to *MutableInput* turned on. This change may impact an application if it implements a class derived from *BRepTools_Modifier*.
1115 * The second parameter *theIsOuterWire* of method *ShapeAnalysis_Wire::CheckSmallArea* has been removed.
1116 * In class *GeomPlate_CurveConstraint*, two constructors taking boundary curves of different types have been replaced with one constructor taking the curve of an abstract type.
1117 *  The last optional argument *RemoveInvalidFaces* has been removed from the constructor of class  *BRepOffset_MakeOffset* and method *Initialize*.
1118 * The public method *BOPDS_DS::VerticesOnIn* has been renamed into *SubShapesOnIn* and the new output parameter *theCommonPB* has been added.
1119
1120 @section upgrade_occt720 Upgrade to OCCT 7.2.0
1121
1122 @subsection upgrade_720_removed Removed features
1123
1124 The following obsolete features have been removed:
1125 * *AIS_InteractiveContext::PreSelectionColor()*, *DefaultColor()*, *WasCurrentTouched()*, *ZDetection()*.
1126   These properties were unused, and therefore application should remove occurrences of these methods.
1127 * *AIS_InteractiveObject::SelectionPriority()*.
1128   These property was not implemented.
1129 * The class *LocOpe_HBuilder* has been removed as obsolete.
1130 * The package *TestTopOpe* has been removed;
1131 * The package *TestTopOpeDraw* has been removed;
1132 * The package *TestTopOpeTools* has been removed.
1133 * The packages *QANewModTopOpe*, *QANewBRepNaming* and *QANewDBRepNaming* have been removed as containing obsolete features.
1134 * The following methods of the *IntPolyh_Triangle* class have been removed as unused:
1135   - *CheckCommonEdge*
1136   - *SetEdgeandOrientation*
1137   - *MultipleMiddleRefinement2*.
1138 * The method *IntPolyh_Triangle::TriangleDeflection* has been renamed to *IntPolyh_Triangle::ComputeDeflection*.
1139 * The following methods of the *IntPolyh_MaillageAffinage* class have been removed as unused:
1140   - *LinkEdges2Triangles*;
1141   - *TriangleEdgeContact2*;
1142   - *StartingPointsResearch2*;
1143   - *NextStartingPointsResearch2*;
1144   - *TriangleComparePSP*;
1145   - *StartPointsCalcul*.
1146
1147 @subsection upgrade_occt720_correction_of_Offset_API Corrections in BRepOffset API
1148
1149 Class *BRepOffsetAPI_MakeOffsetShape*:
1150 * *BRepOffsetAPI_MakeOffsetShape::BRepOffsetAPI_MakeOffsetShape()* - constructor with parameters has been deleted.
1151 * *BRepOffsetAPI_MakeOffsetShape::PerformByJoin()* - method has been added. This method is old algorithm behaviour. 
1152
1153 The code below shows new calling procedure:
1154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1155     BRepOffsetAPI_MakeOffsetShape OffsetMaker;
1156     OffsetMaker.PerformByJoin(Shape, OffsetValue, Tolerance);
1157     NewShape = OffsetMaker.Shape();
1158 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1159
1160 Class *BRepOffsetAPI_MakeThickSolid*:
1161 * *BRepOffsetAPI_MakeThickSolid::BRepOffsetAPI_MakeThickSolid()* - constructor with parameters has been deleted.
1162 * *BRepOffsetAPI_MakeThickSolid::MakeThickSolidByJoin()* - method has been added. This method is old algorithm behaviour. 
1163
1164 The code below shows new calling procedure:
1165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
1166     BRepOffsetAPI_MakeThickSolid BodyMaker;
1167     BodyMaker.MakeThickSolidByJoin(myBody, facesToRemove, -myThickness / 50, 1.e-3);
1168     myBody = BodyMaker.Shape();
1169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1170
1171 @subsection upgrade_720_highlight Highlight style
1172
1173 Management of highlight attributes has been revised and might require modifications from application side:
1174 * New class *Graphic3d_PresentationAttributes* defining basic presentation attributes has been introduced.
1175   It's definition includes properties previously defined by class Graphic3d_HighlightStyle (*Color*, *Transparency*),
1176   and new properties (*Display mode*, *ZLayer*, optional *FillArea aspect*).
1177 * Class *Prs3d_Drawer* now inherits class *Graphic3d_PresentationAttributes*.
1178   So that overall presentation attributes are now split into two parts - Basic attributes and Detailed attributes.
1179 * Class *Graphic3d_HighlightStyle* has been dropped.
1180   It is now defined as a typedef to *Prs3d_Drawer*.
1181   Therefore, highlight style now also includes not only Basic presentation attributes, but also Detailed attributes
1182   which can be used by custom presentation builders.
1183 * Highlighting style defined by class *Graphic3d_PresentationAttributes* now provides more options:
1184   - *Graphic3d_PresentationAttributes::BasicFillAreaAspect()* property providing complete Material definition.
1185     This option, when defined, can be used instead of the pair Object Material + Highlight Color.
1186   - *Graphic3d_PresentationAttributes::ZLayer()* property specifying the Layer where highlighted presentation should be shown.
1187     This property can be set to Graphic3d_ZLayerId_UNKNOWN, which means that ZLayer of main presentation should be used instead.
1188   - *Graphic3d_PresentationAttributes::DisplayMode()* property specifying Display Mode for highlight presentation.
1189 * Since Highlight and Selection styles within *AIS_InteractiveContext* are now defined by *Prs3d_Drawer* inheriting from *Graphic3d_PresentationAttributes*,
1190   it is now possible to customize default highlight attributes like *Display Mode* and *ZLayer*, which previously could be defined only on Object level.
1191 * Properties *Prs3d_Drawer::HighlightStyle()* and *Prs3d_Drawer::SelectionStyle()* have been removed.
1192   Instead, *AIS_InteractiveObject* now defines *DynamicHilightAttributes()* for dynamic highlighting in addition to *HilightAttributes()* used for highlighting in selected state.
1193 * The following protected fields have been removed from class *AIS_InteractiveObject*:
1194   - *myOwnColor*, replaced by *myDrawer->Color()*
1195   - *myTransparency*, replaced by *myDrawer->Transparency()*
1196   - *myZLayer*, replaced by *myDrawer->ZLayer()*
1197 * The method *PrsMgr_PresentationManager::Unhighlight()* taking Display Mode as an argument has been marked deprecated.
1198   Implementation now performs unhighlighting of all highlighted presentation mode.
1199
1200 @subsection upgrade_720_implicit_viewer_update Elimination of implicit 3D Viewer updates
1201
1202 Most AIS_InteractiveContext methods are defined with a flag to update viewer immediatly or not.
1203 Within previous version of OCCT, this argument had default value TRUE.
1204 While immediate viewer updates are useful for beginners (the result is displayed as soon as possible),
1205 this approach is inefficent for batch viewer updates, and having default value as TRUE
1206 leaded to non-intended accidential updates which are difficult to find.
1207
1208 To avoid such issues, the interface has been modified and default value has been removed.
1209 Therefore, old application code should be updated to set the flag theToUpdateViewer explicitly
1210 to desired value (TRUE to preserve old previous behavior), if it was not already set.
1211
1212 The follow AIS_InteractiveContext methods have been changed:
1213   Display, Erase, EraseAll, DisplayAll, EraseSelected, DisplaySelected, ClearPrs, Remove, RemoveAll, Hilight,
1214   HilightWithColor, Unhilight, Redisplay, RecomputePrsOnly, Update, SetDisplayMode, UnsetDisplayMode, SetColor,
1215   UnsetColor, SetWidth, UnsetWidth, SetMaterial, UnsetMaterial, SetTransparency, UnsetTransparency,
1216   SetLocalAttributes, UnsetLocalAttributes, SetPolygonOffsets, SetTrihedronSize, SetPlaneSize, SetPlaneSize,
1217   SetDeviationCoefficient, SetDeviationAngle, SetAngleAndDeviation, SetHLRDeviationCoefficient,
1218   SetHLRDeviationAngle, SetHLRAngleAndDeviation, SetSelectedAspect, MoveTo, Select, ShiftSelect, SetSelected,
1219   UpdateSelected, AddOrRemoveSelected, HilightSelected, UnhilightSelected, ClearSelected, ResetOriginalState,
1220   SubIntensityOn, SubIntensityOff, FitSelected, EraseGlobal, ClearGlobal, ClearGlobalPrs.
1221
1222 In addition, the API for immediate viewer update has been removed from V3d_View and Graphic3d_StructureManager classes
1223 (enumerations *Aspect_TypeOfUpdate* and *V3d_TypeOfUpdate*):
1224   V3d::SetUpdateMode(), V3d::UpdateMode(), Graphic3d_StructureManager::SetUpdateMode(), Graphic3d_StructureManager::UpdateMode().
1225
1226 The argument theUpdateMode has been removed from methods Graphic3d_CView::Display(), Erase(), Update().
1227 Method Graphic3d_CView::Update() does not redraw the view and does not re-compute structures anymore.
1228
1229 The following Grid management methods within class V3d_Viewer do not implicitly redraw the viewer:
1230   ActivateGrid, DeactivateGrid, SetRectangularGridValues, SetCircularGridValues,
1231   RectangularGridGraphicValues, CircularGridGraphicValues, SetPrivilegedPlane, DisplayPrivilegedPlane.
1232
1233 @subsection upgrade_720_Result_Of_BOP_On_Containers Result of Boolean operations on containers
1234
1235 * The result of Boolean operations on arguments of collection types (WIRE/SHELL/COMPSOLID) is now filtered from duplicating containers.
1236
1237 @subsection upgrade_720_changes_methods Other changes
1238
1239 * Class GeomPlate_BuildPlateSurface accepts base class Adaptor3d_HCurve (instead of inherited Adaptor3d_HCurveOnSurface accepted earlier).
1240 * Types GeomPlate_Array1OfHCurveOnSurface and GeomPlate_HArray1OfHCurveOnSurface have been replaced with GeomPlate_Array1OfHCurve and GeomPlate_HArray1OfHCurve correspondingly (accept base class Adaptor3d_HCurve instead of Adaptor3d_HCurveOnSurface).
1241 * Enumeration *Image_PixMap::ImgFormat*, previously declared as nested enumeration within class *Image_PixMap*, has been moved to global namespace as *Image_Format* following OCCT coding rules.
1242   The enumeration values have suffix Image_Format_ and preserve previous name scheme for easy renaming of old values - e.g. Image_PixMap::ImgGray become Image_Format_Gray.
1243   Old definitions are preserved as depreacated aliases to the new ones.
1244
1245 @subsection upgrade_720_BOP_DataStructure BOP - Pairs of interfering indices
1246
1247 * The classes *BOPDS_PassKey* and *BOPDS_PassKeyBoolean* are too excessive and not used any more in Boolean Operations. To replace them the new *BOPDS_Pair* class has been implemented. Thus:
1248   - The method *BOPDS_DS::Interferences()* now returns the *BOPDS_MapOfPair*;
1249   - The method *BOPDS_Iterator::Value()* takes now only two parameters - the indices of interfering sub-shapes.
1250
1251 @subsection upgrade_720_Removal_Of_Old_Boolean_Operations_Draw Removal of the Draw commands based on old Boolean operations
1252
1253 * The commands *fubl* and *cubl* have been removed. The alternative for these commands are the commands *bfuseblend* and *bcutblend* respectively.
1254 * The command *ksection* has been removed. The alternative for this command is the command *bsection*.
1255
1256 @subsection upgrade_720_Change_Of_FaceFace_Intersection Change of Face/Face intersection in Boolean operations
1257
1258 * Previously, the intersection tolerance for all section curves between pair of faces has been calculated as the maximal tolerance among all curves.
1259   Now, each curve has its own valid tolerance calculated as the maximal deviation of the 3D curve from its 2D curves or surfaces in case there are no 2D curves.
1260 * The methods *IntTools_FaceFace::TolReached3d()*, *IntTools_FaceFace::TolReal()* and *IntTools_FaceFace::TolReached2d()* have been removed.
1261 * Intersection tolerances of the curve can be obtained from the curve itself:
1262   - *IntTools_Curve::Tolerance()* - returns the valid tolerance for the curve;
1263   - *IntTools_Curve::TangentialTolerance()* - returns the tangential tolerance, which reflects the size of the common between faces.
1264 * 2d tolerance (*IntTools_FaceFace::TolReached2d()*) has been completely removed from the algorithm as unused.
1265 @subsection upgrade_720_persistence Restore OCCT 6.9.1 persistence
1266   
1267 Capability of reading / writing files in old format using *Storage_ShapeSchema* functionality from OCCT 6.9.1 has been restored in OCCT 7.2.0. 
1268
1269 One can use this functionality in two ways:
1270 - invoke DRAW Test Harness commands fsdread / fsdwrite for shapes
1271 - call *StdStorage* class Read / Write functions in custom code
1272
1273 Code example below demonstrates how to read shapes from a storage driver using *StdStorage* class. 
1274
1275 ~~~~
1276 // aDriver should be created and opened for reading
1277 Handle(StdStorage_Data) aData;
1278
1279 // Read data from the driver
1280 // StdStorage::Read creates aData instance automatically if it is null
1281 Storage_Error anError = StdStorage::Read(*aDriver, aData);
1282 if (anError != Storage_VSOk)
1283 {
1284   // Error processing
1285 }
1286
1287 // Get root objects
1288 Handle(StdStorage_RootData) aRootData = aData->RootData();
1289 Handle(StdStorage_HSequenceOfRoots) aRoots = aRootData->Roots();
1290 if (!aRoots.IsNull())
1291 {
1292   // Iterator over the sequence of root objects
1293   for (StdStorage_HSequenceOfRoots::Iterator anIt(*aRoots); anIt.More(); anIt.Next())
1294   {
1295     Handle(StdStorage_Root)& aRoot = anIt.ChangeValue();
1296         // Get a persistent root's object
1297     Handle(StdObjMgt_Persistent) aPObject = aRoot->Object();
1298     if (!aPObject.IsNull())
1299     {
1300       Handle(ShapePersistent_TopoDS::HShape) aHShape = Handle(ShapePersistent_TopoDS::HShape)::DownCast(aPObject);
1301       if (aHShape) // Downcast to an expected type to import transient data
1302       {
1303         TopoDS_Shape aShape = aHShape->Import();
1304         shapes.Append(aShape);
1305       }
1306     }
1307   }
1308 }
1309 ~~~~
1310
1311 The following code demonstrates how to write shapes in OCCT 7.2.0 using *StdStorage* class.
1312
1313 ~~~~
1314 // Create a file driver
1315 NCollection_Handle<Storage_BaseDriver> aFileDriver(new FSD_File());
1316
1317 // Try to open the file driver for writing
1318 try
1319 {
1320   OCC_CATCH_SIGNALS
1321   PCDM_ReadWriter::Open(*aFileDriver, TCollection_ExtendedString(CStringA(filename).GetBuffer()), Storage_VSWrite);
1322 }
1323 catch (Standard_Failure& e)
1324 {
1325   // Error processing
1326 }
1327
1328 // Create a storage data instance
1329 Handle(StdStorage_Data) aData = new StdStorage_Data;
1330 // Set an axiliary application name (optional)
1331 aData->HeaderData()->SetApplicationName(TCollection_ExtendedString("Application"));
1332
1333 // Provide a map to track sharing
1334 StdObjMgt_TransientPersistentMap aMap;
1335 // Iterator over a collection of shapes
1336 for (Standard_Integer i = 1; i <= shapes.Length(); ++i)
1337 {
1338   TopoDS_Shape aShape = shapes.Value(i);
1339   // Translate a shape to a persistent object
1340   Handle(ShapePersistent_TopoDS::HShape) aPShape =
1341     ShapePersistent_TopoDS::Translate(aShape, aMap, ShapePersistent_WithTriangle);
1342   if (aPShape.IsNull())
1343   {
1344     // Error processing
1345   }
1346
1347   // Construct a root name
1348   TCollection_AsciiString aName = "Shape_";
1349   aName += i;
1350
1351   // Add a root to storage data
1352   Handle(StdStorage_Root) aRoot = new StdStorage_Root(aName, aPShape);
1353   aData->RootData()->AddRoot(aRoot);
1354 }
1355
1356 // Write storage data to the driver
1357 Storage_Error anError = StdStorage::Write(*aFileDriver, aData);
1358 if (anError != Storage_VSOk)
1359 {
1360   // Error processing
1361 }
1362 ~~~~
1363
1364 @subsection upgrade_720_Change_In_BRepLib_MakeFace_Algo Change in BRepLib_MakeFace algorithm
1365
1366   Previously, BRepLib_MakeFace algorithm changed orientation of the source wire in order to avoid creation of face as a hole (i.e. it is impossible to create single face as hole; hole can be created in context of another face only). New algorithm does not reverse the wire if it is open. Material of the face for open wire will be located on the left side from the source wire.
1367
1368 @subsection upgrade_720_Change_In_BRepFill_OffsetWire Change in BRepFill_OffsetWire algorithm
1369
1370   Now, offset direction will always be to outer region in case of positive offset value and to inner region in case of negative offset value.
1371   Inner/Outer region for open wire is defined by the following rule:
1372     when we go along the wire (taking into account edges orientation) then outer region will be on the right side, inner region will be on the left side.
1373   In case of closed wire, inner region will always be inside the wire (at that, edges orientation is not taken into account).