0027793: Visualization - object drifts at zoom within Graphic3d_TMF_TriedronPers...
[occt.git] / dox / dev_guides / upgrade / upgrade.md
CommitLineData
c6f11ec0 1Upgrade from older OCCT versions {#occt_dev_guides__upgrade}
2================================
3
4@tableofcontents
5
d1a67b9d 6@section upgrade_intro Introduction
c6f11ec0 7
a3305c6e 8This document provides technical details on changes made in particular versions of OCCT. It can help to upgrade user applications based on previous versions of OCCT to newer ones.
c6f11ec0 9
d1a67b9d 10@subsection upgrade_intro_precautions Precautions
c6f11ec0 11
a3305c6e 12Back-up your code before the upgrade.
13We strongly recommend using version control system during the upgrade process and saving one or several commits at each step of upgrade, until the overall result is verified.
14This will facilitate identification and correction of possible problems that can occur at the intermediate steps of upgrade.
15It is advisable to document each step carefully to be able to repeat it if necessary.
d1a67b9d 16
17@subsection upgrade_intro_disclaim Disclaimer
18
a3305c6e 19This document describes known issues that have been encountered during porting of OCCT and some applications and approaches that have helped to resolve these issues in known cases.
d1a67b9d 20It does not pretend to cover all possible migration issues that can appear in your application.
a3305c6e 21Take this document with discretion; apply your expertise and knowledge of your application to ensure the correct result.
d1a67b9d 22
a3305c6e 23The automatic upgrade tool is provided as is, without warranty of any kind, and we explicitly disclaim any liability for possible errors that may appear due to use of this tool.
d1a67b9d 24It is your responsibility to ensure that the changes you made in your code are correct.
a3305c6e 25When you upgrade the code by an automatic script, make sure to carefully review the introduced changes at each step before committing them.
d1a67b9d 26
14542432 27
28@section upgrade_65 Upgrade to OCCT 6.5.0
29
30Porting 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
39Porting 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~~~~
43const Graphic3d_SequenceOfGroup& aGroupsSeq = theStructure.Groups();
44Handle(Graphic3d_HSetOfGroup) aGroupSet = new Graphic3d_HSetOfGroup();
45Standard_Integer aLen = aGroupsSeq.Length();
46for (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)*.
d3013f55 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).
14542432 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
58Porting 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 accept 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~~~~
66Handle(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:
d3013f55 71 * by using methods *BRepMesh_IncrementalMesh::SetParallel(Standard_True)* for each *BRepMesh_IncrementalMesh* instance before <i>Perform()</i>;
14542432 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
76Porting 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).
d3013f55 82* Method *HashCode()* has been removed from class *Standard_Transient*. It is advisable to use global function <i>HashCode()</i> for Handle objects instead.
14542432 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 accept one more argument defining a hash tool.
86
87@section upgrade_654 Upgrade to OCCT 6.5.4
88
89Porting 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>
93void 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.
104To 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
110Porting 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.
112It 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.
115Correspondingly, 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.
122Please 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
126Handle(Graphic3d_GraphicDriver) aGraphicDriver =
127new 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
160Porting 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
177As 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
179The 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
189It 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
194Porting 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
198Method *Assign()* in *NCollection* classes does not allow any more copying between different collection types. Such copying should be done manually.
199
200List 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
204If *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
211The current perspective model is not fully backward compatible, so the old perspective-related functionality needs to be reviewed.
212
213Please 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
217The 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
229Support 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
231The 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
235It might be necessary to revise the application code, which deals with *Center()* method of *V3d_View*.
236
237This 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
239There 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
241The 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
243The 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
248Porting of user applications from an earlier OCCT version to version 6.9.0 requires taking into account the following major changes.
249
3d370858 250@subsection upgrade_690_shaders 3D Viewer initialization
251
2523D Viewer now uses GLSL programs for managing frame buffer and stereoscopic output.
253For proper initialization, application should configure **CSF_ShadersDirectory** environment variable pointing to a folder with GLSL resources - files from folder **CASROOT**/src/Shaders.
14542432 254
255@subsection upgrade_690_selection Changes in Selection
256
257Selection 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.
258
259#### Standard selection
260Usage of standard OCCT selection entities would require only minor updates.
261
262Custom Interactive Objects should implement new virtual method *SelectMgr_SelectableObject::BoundingBox().*
263
264Now 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:
265
266~~~~
267Handle(SelectMgr_Selection) aSelection = anInteractiveObject->Selection (aMode);
268for (aSelection->Init(); aSelection->More(); aSelection->Next())
269{
270 Handle(SelectBasics_SensitiveEntity) anEntity = aSelection->Sensitive()->BaseSensitive();
271}
272~~~~
273
274#### Custom sensitive entities
275
276Custom sensitive entities require more complex changes, since the selection algorithm has been redesigned and requires different output from the entities.
277
278The method *SelectBasics_SensitiveEntity::Matches()* of the base class should be overridden following the new signature:
279
280*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.
281
282In 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.
283
284The 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.
285
286Here is an example of overlap/inclusion test for a box:
287
288~~~~
289if (!theMgr.IsOverlapAllowed()) // check for inclusion
290{
291 Standard_Boolean isInside = Standard_True;
292 return theMgr.Overlaps (myBox.CornerMin(), myBox.CornerMax(), &isInside) && isInside;
293}
294
295Standard_Real aDepth;
296if (!theMgr.Overlaps (myBox, aDepth)) // check for overlap
297{
298 return Standard_False;
299}
300
301thePickResult =
302SelectBasics_PickResult (aDepth, theMgr.DistToGeometryCenter (myCenter3d));
303~~~~
304
305The interface of *SelectBasics_SensitiveEntity* now contains four new pure virtual functions that should be implemented by each custom sensitive:
d3013f55 306* <i>BoundingBox()</i> – returns a bounding box of the entity;
307* <i>Clear()</i> – clears up all the resources and memory allocated for complex sensitive entities;
308* <i>BVH()</i> – builds a BVH tree for complex sensitive entities, if it is needed;
309* <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.
14542432 310
311Each sensitive entity now has its own tolerance, which can be overridden by method *SelectBasics_SensitiveEntity::SetSensitivityFactor()* called from constructor.
312
313
314@subsection upgrade_690_adaptor3d-curve Changes in Adaptor3d_Curve class
315
316All 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.
317
318@subsection upgrade_690_v3d_view Changes in V3d_View class
319
320The 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.
321
d1a67b9d 322@section upgrade_700 Upgrade to OCCT 7.0.0
323
14542432 324Porting of user applications from an earlier OCCT version to version 7.0.0 requires taking into account the following major changes.
325
d1a67b9d 326@subsection upgrade_700_persist Removal of legacy persistence
c6f11ec0 327
d3013f55 328Legacy 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.
a3305c6e 329The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
c6f11ec0 330
d7b19997 331@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*).
d3013f55 332
333The existing data files in standard formats can be converted using OCCT 6.9.1 or a previous version, as follows.
c6f11ec0 334
335#### CSFDB files
336
d7b19997 337Files in *CSFDB* format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format.
c6f11ec0 338The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):
339
a3305c6e 340- Start ImportExport sample;
341- Select File / New;
342- Select File / Import / CSFDB... and specify the file to be converted;
343- Drag the mouse with the right button pressed across the view to select all shapes by the rectangle;
344- Select File / Export / BREP... and specify the location and name for the resulting file
c6f11ec0 345
346#### OCAF and XCAF documents
347
a3305c6e 348Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
d3013f55 349These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands.
d7b19997 350Note 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.
c6f11ec0 351
352For that, start *DRAWEXE* and perform the following commands:
353
a3305c6e 354 * To convert <i>*.std</i> and <i>*.sgd</i> file formats to binary format <i>*.cbf</i> (The created document should be in *BinOcaf* format instead of *MDTV-Standard*):
c6f11ec0 355
356 @code
357 Draw[]> pload ALL
358 Draw[]> Open [path to *.std or *.sgd file] Doc
359 Draw[]> Format Doc BinOcaf
360 Draw[]> SaveAs Doc [path to the new file]
361 @endcode
362
a3305c6e 363 * To convert <i>*.dxc</i> file format to binary format <i>*.xbf</i> (The created document should be in *BinXCAF* format instead of *MDTV-XCAF*):
c6f11ec0 364
365 @code
366 Draw[]> pload ALL
367 Draw[]> XOpen [path to *.dxc file] Doc
368 Draw[]> Format Doc BinXCAF
369 Draw[]> XSave Doc [path to the new file]
370 @endcode
371
a3305c6e 372On Windows, it is necessary to replace back slashes in the file path by direct slashes or pairs of back slashes.
373
374Use *XmlOcaf* or *XmlXCAF* instead of *BinOcaf* and *BinXCAF*, respectively, to save in XML format instead of binary one.
c6f11ec0 375
d1a67b9d 376@subsection upgrade_occt700_cdl Removal of CDL and WOK
377
378OCCT code has been completely refactored in version 7.0 to get rid of obsolete technologies used since its inception: CDL (Cas.Cade Definition Language) and WOK (Workshop Organization Kit).
a3305c6e 379
d1a67b9d 380C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.
381
382This 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.
383However, 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.
384
a3305c6e 385WOK is not necessary anymore for building OCCT from sources, though it still can be used in a traditional way -- auxiliary files required for that are preserved.
d1a67b9d 386The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
72c37458 387The alternative solution is to use project files generated by OCCT legacy tool **genproj**, see @ref occt_dev_guides__building_msvc, @ref occt_dev_guides__building_code_blocks, and @ref occt_dev_guides__building_xcode.
d1a67b9d 388
389@subsubsection upgrade_occt700_cdl_auto Automatic upgrade
390
f5f4ebd0 391Most of typical changes required for upgrading code for OCCT 7.0 can be done automatically using the *upgrade* tool included in OCCT 7.0.
d1a67b9d 392This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
393
394Example:
395~~~~~
396 $ tclsh
397 % source <path_to_occt>/adm/upgrade.tcl
398 % upgrade -recurse -all -src=<path_to_your_sources>
399~~~~~
400
a3305c6e 401On Windows, the helper batch script *upgrade.bat* can be used, provided that Tcl is either available in *PATH*, or configured via *custom.bat* script (for instance, if you use OCCT installed from Windows installer package). Start it from the command prompt:
d1a67b9d 402
403~~~~~
404cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
405~~~~~
406
a3305c6e 407Run the upgrade tool without arguments to see the list of available options.
d1a67b9d 408
a3305c6e 409The upgrade tool performs the following changes in the code.
d1a67b9d 410
a3305c6e 4111. Replaces macro *DEFINE_STANDARD_RTTI* by *DEFINE_STANDARD_RTTIEXT*, with second argument indicating base class for the main argument class (if inheritance is recognized by the script):
d1a67b9d 412~~~~~
f5f4ebd0 413DEFINE_STANDARD_RTTI(Class) -> DEFINE_STANDARD_RTTIEXT(Class, Base)
d1a67b9d 414~~~~~
415
a3305c6e 416 @note If macro *DEFINE_STANDARD_RTTI* with two arguments (used in intermediate development versions of OCCT 7.0) is found, the script will convert it to either *DEFINE_STANDARD_RTTIEXT* or *DEFINE_STANDARD_RTTI_INLINE*.
f5f4ebd0 417 The former case is used if current file is header and source file with the same name is found in the same folder.
a3305c6e 418 In this case, macro *IMPLEMENT_STANDARD_RTTI* is injected in the corresponding source file.
419 The latter variant defines all methods for RTTI as inline, and does not require *IMPLEMENT_STANDARD_RTTIEXT* macro.
f5f4ebd0 420
a3305c6e 4212. Replaces forward declarations of collection classes previously generated from CDL generics (defined in *TCollection* package) by inclusion of the corresponding header:
d1a67b9d 422~~~~~
423class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
424~~~~~
425
a3305c6e 4263. Replaces underscored names of *Handle* classes by usage of a macro:
d1a67b9d 427~~~~~
428Handle_Class -> Handle(Class)
429~~~~~
a3305c6e 430 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).
431 The file is considered as defining a Qt object if it contains strings *Q_OBJECT* and either *slots:* or *signals:*.
d1a67b9d 432
a3305c6e 4334. Removes forward declarations of classes with names <i>Handle(C)</i> or *Handle_C*, replacing them either by forward declaration of its argument class, or (for files defining Qt objects) <i>\#include</i> statement for a header with the name of the argument class and extension .hxx:
d1a67b9d 434~~~~~
435class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
436~~~~~
437
a3305c6e 4385. Removes <i> \#includes </i> of files <i>Handle_...hxx</i> that have disappeared in OCCT 7.0:
d1a67b9d 439~~~~~
440#include <Handle_Geom_Curve.hxx> ->
441~~~~~
442
a3305c6e 4436. Removes *typedef* statements that use *Handle* macro to generate the name:
d1a67b9d 444~~~~~
445typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
446~~~~~
447
a3305c6e 4487. Converts C-style casts applied to Handles into calls to <i>DownCast()</i> method:
d1a67b9d 449~~~~~
450 ((Handle(A)&)b) -> Handle(A)::DownCast(b)
451 (Handle(A)&)b -> Handle(A)::DownCast(b)
452 (*((Handle(A)*)&b)) -> Handle(A)::DownCast(b)
453 *((Handle(A)*)&b) -> Handle(A)::DownCast(b)
454 (*(Handle(A)*)&b) -> Handle(A)::DownCast(b)
455~~~~~
456
a3305c6e 4578. Moves <i>Handle()</i> macro out of namespace scope:
d1a67b9d 458~~~~~
459Namespace::Handle(Class) -> Handle(Namespace::Class)
460~~~~~
461
a3305c6e 4629. Converts local variables of reference type, which are initialized by a temporary object returned by call to <i>DownCast()</i>, to the variables of non-reference type (to avoid using references to destroyed memory):
d1a67b9d 463~~~~~
464 const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
465~~~~~
466
a3305c6e 46710. Adds <i>\#include</i> for all classes used as argument to macro <i>STANDARD_TYPE()</i>, except for already included ones;
d1a67b9d 468
a3305c6e 46911. Removes uses of obsolete macros *IMPLEMENT_DOWNCAST* and *IMPLEMENT_STANDARD_*..., except *IMPLEMENT_STANDARD_RTTIEXT*.
f5f4ebd0 470
a3305c6e 471 @note If you plan to keep compatibility of your code with older versions of OCCT, add option <i>-compat</i> to avoid this change. See also @ref upgrade_occt700_cdl_compat.
d1a67b9d 472
f5f4ebd0 473.
d1a67b9d 474
475As long as the upgrade routine runs, some information messages are sent to the standard output.
476In some cases the warnings or errors like the following may appear:
477
478~~~~~
479 Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
480~~~~~
481
a3305c6e 482Be sure to check carefully all reported errors and warnings, as the corresponding code will likely require manual corrections.
483In some cases these messages may help you to detect errors in your code, for instance, cases where *DEFINE_STANDARD_RTTI* macro is used with incorrect class name as an argument.
d1a67b9d 484
485@subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
486
a3305c6e 487Some situations requiring upgrade cannot be detected and / or handled by the automatic procedure.
488If you get compiler errors or warnings when trying to build the upgraded code, you will need to fix them manually.
d1a67b9d 489The following paragraphs list known situations of this kind.
490
491#### Missing header files
492
a3305c6e 493The use of handle objects (construction, comparison using operators == or !=, use of function <i>STANDRAD_TYPE()</i> and method <i>DownCast()</i>) now requires the type of the object pointed by Handle to be completely known at compile time. Thus it may be necessary to include header of the corresponding class to make the code compilable.
d1a67b9d 494
a3305c6e 495For example, the following lines will fail to compile if *Geom_Line.hxx* is not included:
d1a67b9d 496
497~~~~~
498Handle(Geom_Line) aLine = 0;
499if (aLine != aCurve) {...}
500if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
501aLine = Handle(Geom_Line)::DownCast (aCurve);
502~~~~~
503
504Note that it is not necessary to include header of the class to declare Handle to it.
505However, 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*.
506This will eliminate the need to include the header *A* in each source file where class *B* is used.
507
508#### Ambiguity of calls to overloaded functions
509
d7b19997 510This 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, accepting handles to different types.
a3305c6e 511The problem is that operator <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
d1a67b9d 512
513Example:
514~~~~~
515void func (const Handle(Geom_Curve)&);
516void func (const Handle(Geom_Surface)&);
517
518Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
519func (aCurve); // ambiguity error in VC++ 10
520~~~~~
521
d3013f55 522Note that this problem can be avoided in many cases if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
4796758e 523
a3305c6e 524To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature.
525In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
d1a67b9d 526
527~~~~~
528Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);
529~~~~~
530
a3305c6e 531Other variants consist in assigning the argument to a local variable of the correct type and using the direct cast or constructor:
d1a67b9d 532
533~~~~~
534const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
535func (aGCurve); // OK - argument has exact type
536func (static_cast(aCurve)); // OK - direct cast
537func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
538~~~~~
539
a3305c6e 540Another possibility consists in defining additional template variant of the overloaded function causing ambiguity, and using *SFINAE* to resolve the ambiguity.
541This technique can be illustrated by the definition of the template variant of method <i>IGESData_IGESWriter::Send()</i>.
d1a67b9d 542
543#### Lack of implicit cast to base type
544
a3305c6e 545As the cast of a handle to the reference to another handle to the base type has become a user-defined operation, the conversions that require this cast together with another user-defined cast will not be resolved automatically by the compiler.
d1a67b9d 546
547For example:
548
549~~~~~
550Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
551~~~~~
552
d7b19997 553The 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*.
d1a67b9d 554
a3305c6e 555To resolve this, use method <i>Value()</i>:
d1a67b9d 556
557~~~~~
558Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
559~~~~~
560
a3305c6e 561or use variable of the appropriate type:
d1a67b9d 562
563~~~~~
564Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
565~~~~~
566
d7b19997 567A 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:
4796758e 568
569~~~~~
570 const Handle(Geom_Line) aLine;
571 Handle(Geom_Curve) c1 = aLine; // GCC error
572 Handle(Geom_Curve) c2 (aLine); // ok
573~~~~~
574
575This problem is specific to GCC and it does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
576
d1a67b9d 577#### Incorrect use of STANDARD_TYPE and Handle macros
578
579You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().
580
a3305c6e 5811. Explicit definitions of static functions with names generated by macro *STANDARD_TYPE()*, which are artifacts of old implementation of RTTI, should be removed.
d1a67b9d 582
583 Example:
584~~~~~
585const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
586{
587 static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
588 return _atype;
589}
590~~~~~
591
a3305c6e 5922. Incorrect location of closing parenthesis of *Handle()* macro that was not detectable in OCCT 6.x will cause a compiler error and must be corrected.
d1a67b9d 593
594 Example (note misplaced closing parenthesis):
595~~~~~
596aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
597~~~~~
598
599#### Use of class Standard_AncestorIterator
600
a3305c6e 601Class *Standard_AncestorIterator* has been removed; use method *Parent()* of *Standard_Type* class to parse the inheritance chain.
d1a67b9d 602
603#### Absence of cast to Standard_Transient*
604
a3305c6e 605Handles in OCCT 7.0 do not have the operator of conversion to <i>Standard_Transient*,</i> which was present in earlier versions.
d1a67b9d 606This is done to prevent possible unintended errors like this:
607
608~~~~~
609Handle(Geom_Line) aLine = ...;
610Handle(Geom_Surface) aSurf = ...;
611...
a3305c6e 612if (aLine == aSurf) {...} // will cause a compiler error in OCCT 7.0, but not OCCT 6.x
d1a67b9d 613~~~~~
614
a3305c6e 615The places where this implicit cast has been used should be corrected manually.
d1a67b9d 616The typical situation is when Handle is passed to stream:
617
618~~~~~
619Handle(Geom_Line) aLine = ...;
620os << aLine; // in OCCT 6.9.0, resolves to operator << (void*)
621~~~~~
622
a3305c6e 623Call method <i>get()</i> explicitly to output the address of the Handle.
d1a67b9d 624
a9dde4a3 625#### Method DownCast for non-base types
626
d7b19997 627Method *DownCast()* in OCCT 7.0 is made templated; if its argument is not a base class, "deprecated" compiler warning is generated.
a9dde4a3 628This is done to prevent possible unintended errors like this:
629
630~~~~~
631Handle(Geom_Surface) aSurf = ;
632Handle(Geom_Line) aLine =
633 Handle(Geom_Line)::DownCast (aSurf); // will cause a compiler warning in OCCT 7.0, but not OCCT 6.x
634~~~~~
635
636The places where this cast has been used should be corrected manually.
637
d7b19997 638If 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.:
a9dde4a3 639
640~~~~~
641template <class T>
642bool CheckLine (const Handle(T) theArg)
643{
644 Handle(Geom_Line) aLine = dynamic_cast<Geom_Line> (theArg.get());
645 ...
646}
647~~~~~
648
d1a67b9d 649@subsubsection upgrade_occt700_cdl_runtime Possible runtime problems
650
a3305c6e 651Here is the list of known possible problems at run time after the upgrade to OCCT 7.0.
d1a67b9d 652
653#### References to temporary objects
654
a3305c6e 655In previous versions, the compiler was able to detect the situation when a local variable of a "reference to a Handle" type is initialized by temporary object, and ensured that lifetime of that object is longer than that of the variable.
4796758e 656In OCCT 7.0 with default options, it will not work if types of the temporary object and variable are different (due to involvement of user-defined type cast), thus such temporary object will be destroyed immediately.
a9dde4a3 657
4796758e 658This problem does not appear if macro *OCCT_HANDLE_NOCAST* is used during compilation, see below.
d1a67b9d 659
660Example:
661
662~~~~~
663// note that DownCast() returns new temporary object!
664const Handle(Geom_BoundedCurve)& aBC =
665Handle(Geom_TrimmedCurve)::DownCast(aCurve);
666aBC->Transform (T); // access violation in OCCT 7.0
667~~~~~
668
4796758e 669@subsubsection upgrade_occt700_cdl_nocast Option to avoid cast of handle to reference to base type
670
d7b19997 671In OCCT 6.x and earlier versions the handle classes formed a hierarchy echoing the hierarchy of the corresponding object classes .
672This 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:
4796758e 673
674~~~~
675Standard_Boolean GetCurve (Handle(Geom_Curve)& theCurve);
676....
677Handle(Geom_Line) aLine;
678if (GetCurve (aLine)) {
679 // use aLine, unsafe
680}
681~~~~
682
683This feature was used in multiple places in OCCT and dependent projects.
d7b19997 684However 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.
685If an object of incompatible type (e.g. Geom_Circle) is assigned to *theCurve*, the behavior will be unpredictable.
4796758e 686
d7b19997 687For 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.
4796758e 688
d7b19997 689To provide a safer behavior, this feature can be disabled by a compile-time macro *OCCT_HANDLE_NOCAST*.
690When 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.
4796758e 691This 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.
692
d7b19997 693The 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.
4796758e 694For instance, the code from the example below can be changed as follows:
695
696~~~~~
697Handle(Geom_Line) aLine;
698Handle(Geom_Curve) aCurve;
699if (GetCurve (aCure) && !(aLine = Handle(Geom_Line)::DownCast (aCurve)).IsNull()) {
700 // use aLine safely
701}
702~~~~~
703
d1a67b9d 704@subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x
705
a3305c6e 706If you like to preserve the compatibility of your application code with OCCT versions 6.x even after the upgrade to 7.0, consider the following suggestions:
d1a67b9d 707
a3305c6e 7081. If your code used sequences of macros *IMPLEMENT_STANDARD_*... generated by WOK, replace them by single macro *IMPLEMENT_STANDARD_RTTIEXT*
f5f4ebd0 709
a3305c6e 7102. When running automatic upgrade tool, add option <i>-compat</i>.
d1a67b9d 711
a3305c6e 7123. Define macros *DEFINE_STANDARD_RTTIEXT* and *DEFINE_STANDARD_RTTI_INLINE* when building with previous versions of OCCT, resolving to *DEFINE_STANDARD_RTTI* with single argument
d1a67b9d 713
714 Example:
715~~~~~
716#if OCC_VERSION_HEX < 0x070000
f5f4ebd0 717 #define DEFINE_STANDARD_RTTIEXT(C1,C2) DEFINE_STANDARD_RTTI(C1)
718 #define DEFINE_STANDARD_RTTI_INLINE(C1,C2) DEFINE_STANDARD_RTTI(C1)
d1a67b9d 719#endif
720~~~~~
721
722@subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK
723
a3305c6e 724If 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.
725This is a non-trivial effort; the required actions would depend strongly on the structure of the code and used CDL features.
d1a67b9d 726
a3305c6e 727The upgrade script and sources of a specialized WOK version used for OCCT code upgrade can be found in WOK Git repository in branch [CR0_700_2](http://git.dev.opencascade.org/gitweb/?p=occt-wok.git;a=log;h=refs/heads/CR0_700_2).
d1a67b9d 728
729[Contact us](http://www.opencascade.com/contact/) if you need more help.
730
731@subsection upgrade_occt700_bspline Separation of BSpline cache
732
d7b19997 733Implementation 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*.
d1a67b9d 734
735The benefits of this change are:
d1a67b9d 736* Reduced memory footprint of OCCT shapes (up to 20% on some cases)
737* Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks
738
a3305c6e 739The drawback is that direct evaluation of B-Splines using methods of curves and surfaces becomes slower due to the absence of cache. The slow-down can be avoided by using adaptor classes *Geom2dAdaptor_Curve, GeomAdaptor_Curve* and *GeomAdaptor_Surface*, which now use cache when the curve or surface is a B-spline.
d1a67b9d 740
a3305c6e 741OCCT algorithms have been changed to use adaptors for B-spline calculations instead of direct methods for curves and surfaces.
742The same changes (use of adaptors instead of direct call to curve and surface methods) should be implemented in relevant places in the applications based on OCCT to get the maximum performance.
d1a67b9d 743
3554ea68 744@subsection upgrade_occt700_booleanresult Structural result of Boolean operations
745
746The 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.
747
748@subsection upgrade_occt700_brepextrema BRepExtrema_ExtCC finds one solution only
749
750Extrema 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.
751
d1a67b9d 752@subsection upgrade_occt700_sorttools Removal of SortTools package
753
a3305c6e 754Package *SortTools* has been removed.
d1a67b9d 755The code that used the tools provided by that package should be corrected manually.
756The recommended approach is to use sorting algorithms provided by STL.
757
758For instance:
759~~~~~
760#include <SortTools_StraightInsertionSortOfReal.hxx>
761#include <SortTools_ShellSortOfReal.hxx>
762#include <TCollection_CompareOfReal.hxx>
763...
764TCollection_Array1OfReal aValues = ...;
765...
766TCollection_CompareOfReal aCompReal;
767SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
768~~~~~
769can be replaced by:
770~~~~~
771#include <algorithm>
772...
773TCollection_Array1OfReal aValues = ...;
774...
a3305c6e 775std::stable_sort (aValues.begin(), aValues.end());
d1a67b9d 776~~~~~
777
d3839d74 778@subsection upgrade_occt700_2dlayers On-screen objects and ColorScale
27f85086 779
a3305c6e 780The 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.
781Classes *Aspect_Clayer2d, OpenGl_GraphicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr* and *V3d_LayerMgrPointer* have been deleted.
27f85086 782
a3305c6e 783General AIS interactive objects with transformation persistence flag *Graphic3d_TMF_2d* can be used as a replacement of *Visual3d_LayerItem*.
784The anchor point specified for transformation persistence defines the window corner of (or center in case of (0, 0) point).
785To keep on-screen 2D objects on top of the main screen, they can be assigned to the appropriate Z-layer.
786Predefined Z-layers *Graphic3d_ZLayerId_TopOSD* and *Graphic3d_ZLayerId_BotOSD* are intended to replace Underlay and Overlay layers within the old API.
27f85086 787
a3305c6e 788*ColorScale* object previously implemented using *Visual3d_LayerItem* has been moved to a new class *AIS_ColorScale*, with width and height specified explicitly.
789The 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*.
790Here is an example of creating *ColorScale* using the updated API:
27f85086 791
792~~~~~
793Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
794// configuring
d3839d74 795Standard_Integer aWidth, aHeight;
796aView->Window()->Size (aWidth, aHeight);
797aCS->SetSize (aWidth, aHeight);
27f85086 798aCS->SetRange (0.0, 10.0);
799aCS->SetNumberOfIntervals (10);
800// displaying
801aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
802aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
803aCS->SetToUpdate();
804theContextAIS->Display (aCS);
805~~~~~
806
a3305c6e 807To see how 2d objects are implemented in OCCT you can call Draw commands *vcolorscale, vlayerline* or *vdrawtext* (with <i>-2d</i> option).
808Draw command *vcolorscale* now requires the name of *ColorScale* object as argument.
809To display this object use command *vdisplay*. For example:
27f85086 810
811~~~~~
812pload VISUALIZATION
813vinit
3f812249 814vcolorscale cs -demo
27f85086 815pload MODELING
816box b 100 100 100
817vdisplay b
818vsetdispmode 1
819vfit
820vlayerline 0 300 300 300 10
821vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
822~~~~~
823
a3305c6e 824Here is a small example in C++ illustrating how to display a custom AIS object in 2d:
27f85086 825~~~~~
d3839d74 826Handle(AIS_InteractiveContext) aContext = ...;
827Handle(AIS_InteractiveObject) anObj =...; // create an AIS object
828anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); // display object in overlay
829anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); // set 2d flag, coordinate origin is set to down-left corner
830aContext->Display (anObj); // display the object
831~~~~~
832
833@subsection upgrade_occt700_userdraw UserDraw and Visual3d
834
835#### Visual3d package
836
a3305c6e 837Package *Visual3d* implementing the intermediate layer between high-level *V3d* classes
d3839d74 838and low-level OpenGl classes for views and graphic structures management has been dropped.
839
a3305c6e 840The *OpenGl_View* inherits from the new class *Graphic3d_CView*.
841*Graphic3d_CView* is an interface class that declares abstract methods for managing displayed structures,
d3839d74 842display properties and a base layer code that implements computation
843and management of HLR (or more broadly speaking view-depended) structures.
844
a3305c6e 845In the new implementation it takes place of the eliminated *Visual3d_View*.
846As before the instance of *Graphic3d_CView* is still completely managed by *V3d_View* classes.
847It can be accessed through *V3d_View* interface but normally it should not be required as all its methods are completely wrapped.
d3839d74 848
a3305c6e 849In more details, a concrete specialization of *Graphic3d_CView* is created and returned by the graphical driver on request.
850Right after the creation the views are directly used for setting rendering properties and adding graphical structures to be displayed.
d3839d74 851
852The rendering of graphics is possible after mapping a window and activating the view.
a3305c6e 853The direct setting of properties obsoletes the use of intermediate structures with display parameter
854like *Visual3d_ContextView*, etc. This means that the whole package *Visual3d* becomes redundant.
855
856The functionality previously provided by *Visual3d* package has been redesigned in the following way :
857- The management of display of structures has been moved from *Visual3d_ViewManager* into *Graphic3d_StructureManager*.
858- The class *Visual3d_View* has been removed. The management of computed structures has been moved into the base layer of *Graphi3d_CView*.
859- All intermediate structures for storing view parameters, e.g. *Visual3d_ContextView*, have been removed.
860 The settings are now kept by instances of *Graphic3d_CView*.
861- 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.
862- All necessary enumerations have been moved into *Graphic3d* package.
d3839d74 863
864#### Custom OpenGL rendering and UserDraw
865
a3305c6e 866Old APIs based on global callback functions for creating *UserDraw* objects and for performing custom OpenGL rendering within the view have been dropped.
867*UserDraw* callbacks are no more required since *OpenGl_Group* now inherits *Graphic3d_Group* and thus can be accessed directly from *AIS_InteractiveObject*:
d3839d74 868
869~~~~~
870//! Class implementing custom OpenGL element.
871class UserDrawElement : public OpenGl_Element {};
872
873//! Implementation of virtual method AIS_InteractiveObject::Compute().
874void UserDrawObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
875 const Handle(Prs3d_Presentation)& thePrs,
876 const Standard_Integer theMode)
877{
878 Graphic3d_Vec4 aBndMin (myCoords[0], myCoords[1], myCoords[2], 1.0f);
879 Graphic3d_Vec4 aBndMax (myCoords[3], myCoords[4], myCoords[5], 1.0f);
880
881 // casting to OpenGl_Group should be always true as far as application uses OpenGl_GraphicDriver for rendering
882 Handle(OpenGl_Group) aGroup = Handle(OpenGl_Group)::DownCast (thePrs->NewGroup());
883 aGroup->SetMinMaxValues (aBndMin.x(), aBndMin.y(), aBndMin.z(),
884 aBndMax.x(), aBndMax.y(), aBndMax.z());
885 UserDrawElement* anElem = new UserDrawElement (this);
886 aGroup->AddElement(anElem);
887
888 // invalidate bounding box of the scene
889 thePrsMgr->StructureManager()->Update (thePrsMgr->StructureManager()->UpdateMode());
890}
27f85086 891~~~~~
d3839d74 892
a3305c6e 893To perform a custom OpenGL code within the view, it is necessary to inherit from class *OpenGl_View*.
d3839d74 894See the following code sample:
895
896~~~~~
897//! Custom view.
898class UserView : public OpenGl_View
899{
900public:
901 //! Override rendering into the view.
902 virtual void render (Graphic3d_Camera::Projection theProjection,
903 OpenGl_FrameBuffer* theReadDrawFbo,
904 const Standard_Boolean theToDrawImmediate)
905 {
906 OpenGl_View::render (theProjection, theReadDrawFbo, theToDrawImmediate);
907 if (theToDrawImmediate)
908 {
909 return;
910 }
911
912 // perform custom drawing
913 const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext();
914 GLfloat aVerts[3] = { 0.0f, 0,0f, 0,0f };
915 aCtx->core20->glEnableClientState(GL_VERTEX_ARRAY);
916 aCtx->core20->glVertexPointer(3, GL_FLOAT, 0, aVerts);
917 aCtx->core20->glDrawArrays(GL_POINTS, 0, 1);
918 aCtx->core20->glDisableClientState(GL_VERTEX_ARRAY);
919 }
920
921};
922
923//! Custom driver for creating UserView.
924class UserDriver : public OpenGl_GraphicDriver
925{
926public:
927 //! Create instance of own view.
928 virtual Handle(Graphic3d_CView) CreateView (const Handle(Graphic3d_StructureManager)& theMgr) Standard_OVERRIDE
929 {
930 Handle(UserView) aView = new UserView (theMgr, this, myCaps, myDeviceLostFlag, &myStateCounter);
931 myMapOfView.Add (aView);
932 for (TColStd_SequenceOfInteger::Iterator aLayerIt (myLayerSeq); aLayerIt.More(); aLayerIt.Next())
933 {
934 const Graphic3d_ZLayerId aLayerID = aLayerIt.Value();
935 const Graphic3d_ZLayerSettings& aSettings = myMapOfZLayerSettings.Find (aLayerID);
936 aView->AddZLayer (aLayerID);
937 aView->SetZLayerSettings (aLayerID, aSettings);
938 }
939 return aView;
940 }
941};
942
943~~~~~
944
945@subsection upgrade_occt700_localcontext Deprecation of Local Context
946
a3305c6e 947The conception of Local Context has been deprecated.
948The related classes, e.g. *AIS_LocalContext*, and methods ( <i>AIS_InteractiveContext::OpenLocalContext()</i> and others) will be removed in a future OCCT release.
d3839d74 949
950The main functionality provided by Local Context - selection of object subparts - can be now used within Neutral Point without opening any Local Context.
f47afe53 951
952@subsection upgrade_occt700_separate_caf_visualisation Separation of visualization part from TKCAF
953
14542432 954Visualization CAF attributes have been moved into a new toolkit *TKVCAF*.
955If your application uses the classes from *TPrsStd* package then add link to *TKVCAF* library.
956
957Version numbers of *BinOCAF* and *XmlOCAF* formats are incremented; new files cannot be read by earlier versions of OCCT.
f47afe53 958
14542432 959Before 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*.
960When 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.
f47afe53 961
14542432 962@subsection upgrade_euler_angles Correction of interpretation of Euler angles in gp_Quaternion
4f5ad416 963
14542432 964Conversion of *gp_Quaternion* to and from intrinsic Tait-Bryan angles (including *gp_YawPitchRoll*) is fixed.
4f5ad416 965
d7b19997 966Before 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.
4f5ad416 967
d7b19997 968The 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.
4f5ad416 969
14542432 970@subsection upgrade_zoom_persistent_selection Zoom Persistent Selection
4f5ad416 971
d7b19997 972Zoom 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:
14542432 973* *Graphic3d_Camera::ModelViewState* has been renamed to *Graphic3d_Camera::WorldViewState*.
974* Transformation matrix utilities from *OpenGl_Utils* namespace have been moved to *Graphic3d_TransformUtils* and *Graphic3d_TransformUtils.hxx* header respectively.
975* Matrix stack utilities from *OpenGl_Utils* namespace have been moved to *OpenGl_MatrixStack* class and *OpenGl_MatrixStack.hxx* header respectively.
976* *OpenGl_View* methods *Begin/EndTransformPersistence* have been removed. Please, use *Graphic3d_TransformPers::Apply()* instead to apply persistence to perspective and world-view projection matrices.
83da37b1 977
d7b19997 978@subsection upgrade_occt700_correction_of_texture Texture mapping of objects
83da37b1 979
d7b19997 980Textured objects now have the priority over the environment mapping.
981
982Redundant 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.
983Draw command *VSetTextureMode* has been deleted.
c1609fbe 984
985@section upgrade_occt710 Upgrade to OCCT 7.1.0
986
d7b19997 987@subsection upgrade_occt710_correction_of_Parab2d Correction in *gp_Parab2d, gce_MakeParab2d* and *GCE2d_MakeParabola* classes:
c1609fbe 988
d7b19997 9891. Constructors *GCE2d_MakeParabola(const gp_Ax22d& D, const gp_Pnt2d& F)*, *gce_MakeParab2d(const gp_Ax22d& D, const gp_Pnt2d& F)* and *gp_Parab2d(const gp_Ax22d& D, const gp_Pnt2d& F)* have been deleted.
c1609fbe 990
d7b19997 9912. Objects created with some constructors of *gp_Parab2d* class may differ from the previous version. Please see the updated documentation for *gp_Parab2d* class (file *gp_Parab2d.hxx*).
c1609fbe 992
2831708b 9933. Result returned by gp_Parab2d::Directrix() method has another direction in compare with previous OCCT-version.
994
995@subsection upgrade_710_aspects Presentation attributes
996
997This section should be considered if application defines custom presentations (inherited from AIS_InteractiveObject).
998Previous versions of OCCT have three levels for defining presentation properties (e.g. colors, materials):
999
10001. For entire structure (Graphic3d_Structure / Prs3d_Presentation).
10012. For specific group of primitives (Graphic3d_Group::SetGroupPrimitivesAspect()) overriding structure aspects.
10023. For specific primitive array within graphic group (Graphic3d_Group::SetPrimitivesAspect()).
1003
1004The first one is de facto not used for a long time since OCCT presentations always define aspects at graphic group level (overriding any structure aspects).
1005Within this OCCT release, this first level of aspects has been completely removed. In most cases application code should just remove missing methods; in rare cases where this functionality was intentionally used - application should explicitly define aspects to appropriate graphic groups.
1006
1007Note that the 3rd level (defining several different aspects within the same graphic group) is also should be avoided in application code since it is deprecated functionality which can be removed in further releases.
1008Graphic3d_Group::SetGroupPrimitivesAspect() should be the main method defining presentation attributes.
b6472664 1009
1010The implementation of Graphic3d_Group::SetGroupPrimitivesAspect() has been changed from copying aspect values to keeping passed object.
1011Although it was not documented, previosly it was possible to modify single aspects instance (like Graphic3d_AspectFillArea3d) and set it to multiple groups.
1012Now such code would produce unexpected result and therefore should be updated to create dedicated aspect instance.
2e5139af 1013
c885cfda 1014@subsection upgrade_710_types Typedefs
1015
1016The following type definitions in OCCT has been modified to use C++11 types:
1017- *Standard_ExtCharacter* is now *char16_t* (previously *short*).
1018- *Standard_ExtString;* is now *const char16_t* (previously *const short*).
1019- *Standard_Utf16Char* is now *char16_t* (previously *uint16_t* for compatibility with old compilers).
1020- *Standard_Utf32Char* is now *char32_t* (previously *uint32_t* for compatibility with old compilers).
1021
1022For most applications this change should be transparent, since the size of types have not been changed.
1023
60273f77 1024@subsection upgrade_710_ffp Programmable Pipeline
1025
1026Fixed-function pipeline has been already deprecated since OCCT 7.0.0.
1027Release 7.1.0 disables this functionality by default in favor of Programmable Pipeline (based on GLSL programs).
1028
1029This also means that method *V3d_View::Export()* based on gl2ps library and requiring disabled by default functionality has been deprecated as well.
1030Applications should explicitly enable deprecated functionality by setting OpenGl_Caps::ffpEnable flag to TRUE within OpenGl_GraphicDriver::ChangeOptions() before creating the viewer to use V3d_View::Export(),
1031but being aware that this functionality is likely to be removed in a next OCCT release.
1032Thus the recommended way to generate vector image of a 3D model or scene is to use application-level solution independent from OpenGL.
1033
3fe9ce0e 1034@subsection upgrade_710_trsfpers Transformation persistence
1035
1036The behavior of transformation persistence flags Graphic3d_TMF_ZoomPers and Graphic3d_TMF_TriedronPers have been changed to be consistent with textured fixed-size 2D text.
1037Object with these flags is considered to be defined in pixel units, and presentation is no more scaled depending on view height.
1038Applications that need to scale such objects depending on viewport size should update them manually.
1039
2e5139af 1040@subsection upgrade_710_removed Removed features
1041
1042The following obsolete features have been removed:
1043
60273f77 1044* Obsolete Antialiasing API *V3d_View::SetAntialiasingOn()*. This method was intended to activate deprecated OpenGL functionality (GL_POLYGON_SMOOTH, GL_LINE_SMOOTH, GL_POINT_SMOOTH).
1045 Instead of old API, application should request MSAA buffers for antialiasing by assigning *Graphic3d_RenderingParams::NbMsaaSamples* property of structure returned by *V3d_View::ChangeRenderingParams()*.
1046* *Prs3d_Drawer::ShadingAspectGlobal()* flag has been removed as not used. Corresponding calls can be removed safely from the application code.
1047* ZClipping planes and ZCueing (methods *V3d_View::SetZClippingType()*, *::SetZCueingOn()* and V3d_View::others).
89a929ea 1048 ZClipping planes can be replaced by general-purpose clipping planes (application should update plane definion manually).
60273f77 1049* 3D viewer printing API *V3d_View::Print()* has been removed. This functionality was available on Windows platforms only.
1050 Applications should use general image dump API *V3d_View::ToPixMap()* and manage printing using platform-specific API at application level.
1051 Text resolution can be managed by rendering parameter *Graphic3d_RenderingParams::Resolution*, returned by *V3d_View::ChangeRenderingParams()*.