0030886: Documentation - provide information about some changes in upgrade 7.4.0
[occt.git] / dox / dev_guides / upgrade / upgrade.md
c6f11ec0 1Upgrade from older OCCT versions {#occt_dev_guides__upgrade}
d1a67b9d 6@section upgrade_intro Introduction
c6f11ec0 7
a3305c6e 8This document provides technical details on changes made in particular versions of OCCT. It can help to upgrade user applications based on previous versions of OCCT to newer ones.
c6f11ec0 9
d1a67b9d 10@subsection upgrade_intro_precautions Precautions
c6f11ec0 11
a3305c6e 12Back-up your code before the upgrade.
13We strongly recommend using version control system during the upgrade process and saving one or several commits at each step of upgrade, until the overall result is verified.
14This will facilitate identification and correction of possible problems that can occur at the intermediate steps of upgrade.
15It is advisable to document each step carefully to be able to repeat it if necessary.
d1a67b9d 16
17@subsection upgrade_intro_disclaim Disclaimer
a3305c6e 19This document describes known issues that have been encountered during porting of OCCT and some applications and approaches that have helped to resolve these issues in known cases.
d1a67b9d 20It does not pretend to cover all possible migration issues that can appear in your application.
a3305c6e 21Take this document with discretion; apply your expertise and knowledge of your application to ensure the correct result.
d1a67b9d 22
a3305c6e 23The automatic upgrade tool is provided as is, without warranty of any kind, and we explicitly disclaim any liability for possible errors that may appear due to use of this tool.
d1a67b9d 24It is your responsibility to ensure that the changes you made in your code are correct.
a3305c6e 25When you upgrade the code by an automatic script, make sure to carefully review the introduced changes at each step before committing them.
d1a67b9d 26
14542432 27
28@section upgrade_65 Upgrade to OCCT 6.5.0
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.
37@section upgrade_651 Upgrade to OCCT 6.5.1
39Porting of user applications from an earlier OCCT version to version 6.5.1 requires taking into account the following major changes:
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:
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)
48 aGroupSet->Add (aGroupsSeq.Value (aGr));
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).
07f2b741 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). 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.
14542432 55
56@section upgrade_652 Upgrade to OCCT 6.5.2
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.
80223385 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.
14542432 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:
66Handle(BRepMesh_DiscretRoot) aMeshAlgo = BRepMesh_DiscretFactory::Get().Discret (theShape, theDeflection, theAngularToler);
67 if (!aMeshAlgo.IsNull()) {}
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*).
74@section upgrade_653 Upgrade to OCCT 6.5.3
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.
80223385 85* Map classes in *NCollection* package now receive one more argument defining a hash tool.
14542432 86
87@section upgrade_654 Upgrade to OCCT 6.5.4
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:
92#include <Image_AlienPixMap.hxx>
93void dump (Handle(V3d_View)& theView3D)
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");
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.
108@section upgrade_660 Upgrade to OCCT 6.6.0
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.
07f2b741 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. 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.
14542432 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.
07f2b741 122Refer 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.
14542432 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:
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();
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);
143 Aspect_Handle aWindowHandle = (Aspect_Handle )winId();
144 Handle(Xw_Window) aWindow =
145 new Xw_Window (aGraphicDriver->GetDisplayConnection(), aWindowHandle);
146#endif // WNT
148// setup the window for a new view
149 Handle(V3d_View) aView = aViewer->CreateView();
150 aView->SetWindow (aWindow);
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.
158@section upgrade_670 Upgrade to OCCT 6.7.0
160Porting of user applications from an earlier OCCT version to version 6.7.0 requires taking into account the following major changes.
162@subsection upgrade_670_clipping Object-level clipping and capping algorithm.
07f2b741 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. 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. Refer to CDL / Doxygen documentation to find descriptive hints and snippets.
14542432 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.
07f2b741 167* It might be necessary to revise the code of custom sensitive entities and port *Matches()* and *ComputeDepth()* methods to ensure proper selection clipping. 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.
14542432 168
169@subsection upgrade_670_markers Redesign of markers presentation
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.
175@subsection upgrade_670_views Default views are not created automatically
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()*.
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.
181@subsection upgrade_670_dimensions Improved dimensions implementation
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*.
187@subsection upgrade_670_list_collection NCollection_Set replaced by List collection
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.
192@section upgrade_680 Upgrade to OCCT 6.8.0
194Porting of user applications from an earlier OCCT version to version 6.8.0 requires taking into account the following major changes.
196@subsection upgrade_680_ncollection Changes in NCollection classes
198Method *Assign()* in *NCollection* classes does not allow any more copying between different collection types. Such copying should be done manually.
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.
202@subsection upgrade_680_view_camera 3D View Camera
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).
211The current perspective model is not fully backward compatible, so the old perspective-related functionality needs to be reviewed.
07f2b741 213Revise application-specific custom presentations to provide a proper bounding box, otherwise the object might become erroneously clipped by automatic *ZFit* or frustum culling algorithms enabled by default.
14542432 214
215@subsection upgrade_680_connected_objects Redesign of Connected Interactive Objects
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*
227@subsection upgrade_680_unicode Support of UNICODE Characters
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.
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).*
233@subsection upgrade_680_projection_shift Elimination of Projection Shift Concept
235It might be necessary to revise the application code, which deals with *Center()* method of *V3d_View*.
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.
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.
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.
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.
246@section upgrade_690 Upgrade to OCCT 6.9.0
248Porting of user applications from an earlier OCCT version to version 6.9.0 requires taking into account the following major changes.
3d370858 250@subsection upgrade_690_shaders 3D Viewer initialization
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.
ee5befae 254*Note that **CSF_ShadersDirectory** become optional since OCCT 7.1.0 release*.
14542432 255
256@subsection upgrade_690_selection Changes in Selection
258Selection 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.
260#### Standard selection
261Usage of standard OCCT selection entities would require only minor updates.
263Custom Interactive Objects should implement new virtual method *SelectMgr_SelectableObject::BoundingBox().*
265Now 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:
268Handle(SelectMgr_Selection) aSelection = anInteractiveObject->Selection (aMode);
269for (aSelection->Init(); aSelection->More(); aSelection->Next())
271 Handle(SelectBasics_SensitiveEntity) anEntity = aSelection->Sensitive()->BaseSensitive();
275#### Custom sensitive entities
277Custom sensitive entities require more complex changes, since the selection algorithm has been redesigned and requires different output from the entities.
279The method *SelectBasics_SensitiveEntity::Matches()* of the base class should be overridden following the new signature:
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.
283In 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.
285The 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.
287Here is an example of overlap/inclusion test for a box:
290if (!theMgr.IsOverlapAllowed()) // check for inclusion
292 Standard_Boolean isInside = Standard_True;
293 return theMgr.Overlaps (myBox.CornerMin(), myBox.CornerMax(), &isInside) && isInside;
296Standard_Real aDepth;
297if (!theMgr.Overlaps (myBox, aDepth)) // check for overlap
299 return Standard_False;
302thePickResult =
303SelectBasics_PickResult (aDepth, theMgr.DistToGeometryCenter (myCenter3d));
306The interface of *SelectBasics_SensitiveEntity* now contains four new pure virtual functions that should be implemented by each custom sensitive:
d3013f55 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.
14542432 311
312Each sensitive entity now has its own tolerance, which can be overridden by method *SelectBasics_SensitiveEntity::SetSensitivityFactor()* called from constructor.
315@subsection upgrade_690_adaptor3d-curve Changes in Adaptor3d_Curve class
317All 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.
319@subsection upgrade_690_v3d_view Changes in V3d_View class
321The 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.
d1a67b9d 323@section upgrade_700 Upgrade to OCCT 7.0.0
14542432 325Porting of user applications from an earlier OCCT version to version 7.0.0 requires taking into account the following major changes.
0ef598d0 327Building OCCT now requires compiler supporting some C++11 features.
328The supported compilers are:
329- MSVC: version 10 (Visual Studio 2010) or later
330- GCC: version 4.3 or later
331- CLang: version 3.6 or later
332- ICC: version XE 2013 SP 1 or later
334When compiling code that uses OCCT with GCC and CLang compilers, it is necessary to use compiler option -std=c++0x (or its siblings) to enable C++11 features.
d1a67b9d 336@subsection upgrade_700_persist Removal of legacy persistence
c6f11ec0 337
d3013f55 338Legacy 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 339The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
c6f11ec0 340
d7b19997 341@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 342
343The existing data files in standard formats can be converted using OCCT 6.9.1 or a previous version, as follows.
c6f11ec0 344
ec964372 345@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.
c6f11ec0 347#### CSFDB files
d7b19997 349Files in *CSFDB* format (usually with extension .csfdb) contain OCCT shape data that can be converted to BRep format.
c6f11ec0 350The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.0 (or earlier):
a3305c6e 352- Start ImportExport sample;
353- Select File / New;
354- Select File / Import / CSFDB... and specify the file to be converted;
355- Drag the mouse with the right button pressed across the view to select all shapes by the rectangle;
356- Select File / Export / BREP... and specify the location and name for the resulting file
c6f11ec0 357
358#### OCAF and XCAF documents
a3305c6e 360Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
d3013f55 361These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands.
d7b19997 362Note 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 363
364For that, start *DRAWEXE* and perform the following commands:
a3305c6e 366 * 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 367
368 @code
369 Draw[]> pload ALL
370 Draw[]> Open [path to *.std or *.sgd file] Doc
371 Draw[]> Format Doc BinOcaf
372 Draw[]> SaveAs Doc [path to the new file]
373 @endcode
a3305c6e 375 * 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 376
377 @code
378 Draw[]> pload ALL
379 Draw[]> XOpen [path to *.dxc file] Doc
380 Draw[]> Format Doc BinXCAF
381 Draw[]> XSave Doc [path to the new file]
382 @endcode
a3305c6e 384On Windows, it is necessary to replace back slashes in the file path by direct slashes or pairs of back slashes.
386Use *XmlOcaf* or *XmlXCAF* instead of *BinOcaf* and *BinXCAF*, respectively, to save in XML format instead of binary one.
c6f11ec0 387
d1a67b9d 388@subsection upgrade_occt700_cdl Removal of CDL and WOK
390OCCT 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 391
d1a67b9d 392C++ code previously generated by WOK from CDL declarations is now included directly in OCCT sources.
394This 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.
395However, due to redesign of basic mechanisms (CDL generic classes, Handles and RTTI) using C++ templates, some changes may be necessary in the code when porting to OCCT 7.0, as described below.
a3305c6e 397WOK 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 398The recommended method for building OCCT 7.x is CMake, see @ref occt_dev_guides__building_cmake.
72c37458 399The 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 400
401@subsubsection upgrade_occt700_cdl_auto Automatic upgrade
f5f4ebd0 403Most 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 404This tool is a Tcl script, thus Tcl should be available on your workstation to run it.
408 $ tclsh
409 % source <path_to_occt>/adm/upgrade.tcl
410 % upgrade -recurse -all -src=<path_to_your_sources>
a3305c6e 413On 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 414
416cmd> <path_to_occt>\upgrade.bat -recurse -all -inc=<path_to_occt>\inc -src=<path_to_your_sources> [options]
a3305c6e 419Run the upgrade tool without arguments to see the list of available options.
d1a67b9d 420
a3305c6e 421The upgrade tool performs the following changes in the code.
d1a67b9d 422
a3305c6e 4231. 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 424~~~~~
d1a67b9d 426~~~~~
a3305c6e 428 @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 429 The former case is used if current file is header and source file with the same name is found in the same folder.
a3305c6e 430 In this case, macro *IMPLEMENT_STANDARD_RTTI* is injected in the corresponding source file.
431 The latter variant defines all methods for RTTI as inline, and does not require *IMPLEMENT_STANDARD_RTTIEXT* macro.
f5f4ebd0 432
a3305c6e 4332. Replaces forward declarations of collection classes previously generated from CDL generics (defined in *TCollection* package) by inclusion of the corresponding header:
d1a67b9d 434~~~~~
435class TColStd_Array1OfReal; -> #include <TColStd_Array1OfReal.hxx>
a3305c6e 4383. Replaces underscored names of *Handle* classes by usage of a macro:
d1a67b9d 439~~~~~
440Handle_Class -> Handle(Class)
a3305c6e 442 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).
443 The file is considered as defining a Qt object if it contains strings *Q_OBJECT* and either *slots:* or *signals:*.
d1a67b9d 444
a3305c6e 4454. 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 446~~~~~
447class Handle(TColStd_HArray1OfReal); -> #include <TColStd_HArray1OfReal.hxx>
a3305c6e 4505. Removes <i> \#includes </i> of files <i>Handle_...hxx</i> that have disappeared in OCCT 7.0:
d1a67b9d 451~~~~~
452#include <Handle_Geom_Curve.hxx> ->
a3305c6e 4556. Removes *typedef* statements that use *Handle* macro to generate the name:
d1a67b9d 456~~~~~
457typedef NCollection_Handle<Message_Msg> Handle(Message_Msg); ->
a3305c6e 4607. Converts C-style casts applied to Handles into calls to <i>DownCast()</i> method:
d1a67b9d 461~~~~~
462 ((Handle(A)&)b) -> Handle(A)::DownCast(b)
463 (Handle(A)&)b -> Handle(A)::DownCast(b)
464 (*((Handle(A)*)&b)) -> Handle(A)::DownCast(b)
465 *((Handle(A)*)&b) -> Handle(A)::DownCast(b)
466 (*(Handle(A)*)&b) -> Handle(A)::DownCast(b)
a3305c6e 4698. Moves <i>Handle()</i> macro out of namespace scope:
d1a67b9d 470~~~~~
471Namespace::Handle(Class) -> Handle(Namespace::Class)
a3305c6e 4749. 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 475~~~~~
476 const Handle(A)& a = Handle(B)::DownCast (b); -> Handle(A) a (Handle(B)::DownCast (b));
a3305c6e 47910. Adds <i>\#include</i> for all classes used as argument to macro <i>STANDARD_TYPE()</i>, except for already included ones;
d1a67b9d 480
a3305c6e 48111. Removes uses of obsolete macros *IMPLEMENT_DOWNCAST* and *IMPLEMENT_STANDARD_*..., except *IMPLEMENT_STANDARD_RTTIEXT*.
f5f4ebd0 482
a3305c6e 483 @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 484
f5f4ebd0 485.
d1a67b9d 486
487As long as the upgrade routine runs, some information messages are sent to the standard output.
488In some cases the warnings or errors like the following may appear:
491 Error in {HEADER_FILE}: Macro DEFINE_STANDARD_RTTI used for class {CLASS_NAME} whose declaration is not found in this file, cannot fix
a3305c6e 494Be sure to check carefully all reported errors and warnings, as the corresponding code will likely require manual corrections.
495In 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 496
497@subsubsection upgrade_occt700_cdl_compiler Possible compiler errors
a3305c6e 499Some situations requiring upgrade cannot be detected and / or handled by the automatic procedure.
500If you get compiler errors or warnings when trying to build the upgraded code, you will need to fix them manually.
d1a67b9d 501The following paragraphs list known situations of this kind.
503#### Missing header files
a3305c6e 505The 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 506
a3305c6e 507For example, the following lines will fail to compile if *Geom_Line.hxx* is not included:
d1a67b9d 508
510Handle(Geom_Line) aLine = 0;
511if (aLine != aCurve) {...}
512if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
513aLine = Handle(Geom_Line)::DownCast (aCurve);
516Note that it is not necessary to include header of the class to declare Handle to it.
517However, 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*.
518This will eliminate the need to include the header *A* in each source file where class *B* is used.
520#### Ambiguity of calls to overloaded functions
80223385 522This 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.
a3305c6e 523The problem is that operator <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
d1a67b9d 524
527void func (const Handle(Geom_Curve)&);
528void func (const Handle(Geom_Surface)&);
530Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
531func (aCurve); // ambiguity error in VC++ 10
d3013f55 534Note that this problem can be avoided in many cases if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
4796758e 535
a3305c6e 536To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature.
537In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
d1a67b9d 538
540Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);
a3305c6e 543Other variants consist in assigning the argument to a local variable of the correct type and using the direct cast or constructor:
d1a67b9d 544
546const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
547func (aGCurve); // OK - argument has exact type
548func (static_cast(aCurve)); // OK - direct cast
549func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed
a3305c6e 552Another possibility consists in defining additional template variant of the overloaded function causing ambiguity, and using *SFINAE* to resolve the ambiguity.
553This technique can be illustrated by the definition of the template variant of method <i>IGESData_IGESWriter::Send()</i>.
d1a67b9d 554
555#### Lack of implicit cast to base type
a3305c6e 557As 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 558
559For example:
562Handle(Geom_Geometry) aC = GC_MakeLine (p, v); // compiler error
d7b19997 565The 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 566
a3305c6e 567To resolve this, use method <i>Value()</i>:
d1a67b9d 568
570Handle(Geom_Geometry) aC = GC_MakeLine (p, v).Value(); // ok
a3305c6e 573or use variable of the appropriate type:
d1a67b9d 574
576Handle(Geom_TrimmedCurve) aC = GC_MakeLine (p, v); // ok
d7b19997 579A 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 580
582 const Handle(Geom_Line) aLine;
583 Handle(Geom_Curve) c1 = aLine; // GCC error
584 Handle(Geom_Curve) c2 (aLine); // ok
587This problem is specific to GCC and it does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
d1a67b9d 589#### Incorrect use of STANDARD_TYPE and Handle macros
591You might need to clean your code from incorrect use of macros *STANDARD_TYPE*() and *Handle*().
a3305c6e 5931. Explicit definitions of static functions with names generated by macro *STANDARD_TYPE()*, which are artifacts of old implementation of RTTI, should be removed.
d1a67b9d 594
595 Example:
597const Handle(Standard_Type)& STANDARD_TYPE(math_GlobOptMin)
599 static Handle(Standard_Type) _atype = new Standard_Type ("math_GlobOptMin", sizeof (math_GlobOptMin));
600 return _atype;
a3305c6e 6042. 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 605
606 Example (note misplaced closing parenthesis):
608aBSpline = Handle( Geom2d_BSplineCurve::DownCast(BS->Copy()) );
611#### Use of class Standard_AncestorIterator
a3305c6e 613Class *Standard_AncestorIterator* has been removed; use method *Parent()* of *Standard_Type* class to parse the inheritance chain.
d1a67b9d 614
615#### Absence of cast to Standard_Transient*
a3305c6e 617Handles in OCCT 7.0 do not have the operator of conversion to <i>Standard_Transient*,</i> which was present in earlier versions.
d1a67b9d 618This is done to prevent possible unintended errors like this:
621Handle(Geom_Line) aLine = ...;
622Handle(Geom_Surface) aSurf = ...;
a3305c6e 624if (aLine == aSurf) {...} // will cause a compiler error in OCCT 7.0, but not OCCT 6.x
d1a67b9d 625~~~~~
a3305c6e 627The places where this implicit cast has been used should be corrected manually.
d1a67b9d 628The typical situation is when Handle is passed to stream:
631Handle(Geom_Line) aLine = ...;
632os << aLine; // in OCCT 6.9.0, resolves to operator << (void*)
a3305c6e 635Call method <i>get()</i> explicitly to output the address of the Handle.
d1a67b9d 636
a9dde4a3 637#### Method DownCast for non-base types
d7b19997 639Method *DownCast()* in OCCT 7.0 is made templated; if its argument is not a base class, "deprecated" compiler warning is generated.
a9dde4a3 640This is done to prevent possible unintended errors like this:
643Handle(Geom_Surface) aSurf = ;
644Handle(Geom_Line) aLine =
645 Handle(Geom_Line)::DownCast (aSurf); // will cause a compiler warning in OCCT 7.0, but not OCCT 6.x
648The places where this cast has been used should be corrected manually.
d7b19997 650If 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 651
653template <class T>
654bool CheckLine (const Handle(T) theArg)
656 Handle(Geom_Line) aLine = dynamic_cast<Geom_Line> (theArg.get());
657 ...
d1a67b9d 661@subsubsection upgrade_occt700_cdl_runtime Possible runtime problems
a3305c6e 663Here is the list of known possible problems at run time after the upgrade to OCCT 7.0.
d1a67b9d 664
665#### References to temporary objects
a3305c6e 667In 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 668In 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 669
4796758e 670This problem does not appear if macro *OCCT_HANDLE_NOCAST* is used during compilation, see below.
d1a67b9d 671
675// note that DownCast() returns new temporary object!
676const Handle(Geom_BoundedCurve)& aBC =
678aBC->Transform (T); // access violation in OCCT 7.0
4796758e 681@subsubsection upgrade_occt700_cdl_nocast Option to avoid cast of handle to reference to base type
d7b19997 683In OCCT 6.x and earlier versions the handle classes formed a hierarchy echoing the hierarchy of the corresponding object classes .
684This 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 685
687Standard_Boolean GetCurve (Handle(Geom_Curve)& theCurve);
689Handle(Geom_Line) aLine;
690if (GetCurve (aLine)) {
691 // use aLine, unsafe
695This feature was used in multiple places in OCCT and dependent projects.
d7b19997 696However 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.
697If an object of incompatible type (e.g. Geom_Circle) is assigned to *theCurve*, the behavior will be unpredictable.
4796758e 698
d7b19997 699For 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 700
d7b19997 701To provide a safer behavior, this feature can be disabled by a compile-time macro *OCCT_HANDLE_NOCAST*.
702When 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 703This 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.
d7b19997 705The 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 706For instance, the code from the example below can be changed as follows:
709Handle(Geom_Line) aLine;
710Handle(Geom_Curve) aCurve;
711if (GetCurve (aCure) && !(aLine = Handle(Geom_Line)::DownCast (aCurve)).IsNull()) {
712 // use aLine safely
d1a67b9d 716@subsubsection upgrade_occt700_cdl_compat Preserving compatibility with OCCT 6.x
a3305c6e 718If 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 719
a3305c6e 7201. If your code used sequences of macros *IMPLEMENT_STANDARD_*... generated by WOK, replace them by single macro *IMPLEMENT_STANDARD_RTTIEXT*
f5f4ebd0 721
a3305c6e 7222. When running automatic upgrade tool, add option <i>-compat</i>.
d1a67b9d 723
a3305c6e 7243. 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 725
726 Example:
728#if OCC_VERSION_HEX < 0x070000
d1a67b9d 731#endif
734@subsubsection upgrade_occt700_cdl_wok Applications based on CDL and WOK
a3305c6e 736If 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.
737This is a non-trivial effort; the required actions would depend strongly on the structure of the code and used CDL features.
d1a67b9d 738
a3305c6e 739The 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 740
741[Contact us](http://www.opencascade.com/contact/) if you need more help.
743@subsection upgrade_occt700_bspline Separation of BSpline cache
d7b19997 745Implementation 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 746
747The benefits of this change are:
d1a67b9d 748* Reduced memory footprint of OCCT shapes (up to 20% on some cases)
749* Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks
a3305c6e 751The 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 752
a3305c6e 753OCCT algorithms have been changed to use adaptors for B-spline calculations instead of direct methods for curves and surfaces.
754The 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 755
3554ea68 756@subsection upgrade_occt700_booleanresult Structural result of Boolean operations
758The 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.
760@subsection upgrade_occt700_brepextrema BRepExtrema_ExtCC finds one solution only
762Extrema computation between non-analytical curves in shape-shape distance calculation algorithm has been changed in order to return only one solution. So, if e.g. two edges are created on parallel b-spline curves the algorithm BRepExtrema_DistShapeShape will return only one solution instead of enormous number of solutions. There is no way to get algorithm working in old manner.
d1a67b9d 764@subsection upgrade_occt700_sorttools Removal of SortTools package
a3305c6e 766Package *SortTools* has been removed.
d1a67b9d 767The code that used the tools provided by that package should be corrected manually.
768The recommended approach is to use sorting algorithms provided by STL.
770For instance:
772#include <SortTools_StraightInsertionSortOfReal.hxx>
773#include <SortTools_ShellSortOfReal.hxx>
774#include <TCollection_CompareOfReal.hxx>
776TCollection_Array1OfReal aValues = ...;
778TCollection_CompareOfReal aCompReal;
779SortTools_StraightInsertionSortOfReal::Sort(aValues, aCompReal);
781can be replaced by:
783#include <algorithm>
785TCollection_Array1OfReal aValues = ...;
a3305c6e 787std::stable_sort (aValues.begin(), aValues.end());
d1a67b9d 788~~~~~
d3839d74 790@subsection upgrade_occt700_2dlayers On-screen objects and ColorScale
27f85086 791
a3305c6e 792The 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.
793Classes *Aspect_Clayer2d, OpenGl_GraphicDriver_Layer, Visual3d_Layer, Visual3d_LayerItem, V3d_LayerMgr* and *V3d_LayerMgrPointer* have been deleted.
39a349fd 794The following auxiliary definition have been removed as well: Aspect_TypeOfPrimitive, Aspect_TypeOfLayer, Aspect_TypeOfEdge, Aspect_TypeOfDrawMode, Aspect_TypeOfConstraint, Aspect_DriverDefinitionError, Aspect_BadAccess.
27f85086 795
a3305c6e 796General AIS interactive objects with transformation persistence flag *Graphic3d_TMF_2d* can be used as a replacement of *Visual3d_LayerItem*.
797The anchor point specified for transformation persistence defines the window corner of (or center in case of (0, 0) point).
798To keep on-screen 2D objects on top of the main screen, they can be assigned to the appropriate Z-layer.
799Predefined Z-layers *Graphic3d_ZLayerId_TopOSD* and *Graphic3d_ZLayerId_BotOSD* are intended to replace Underlay and Overlay layers within the old API.
27f85086 800
a3305c6e 801*ColorScale* object previously implemented using *Visual3d_LayerItem* has been moved to a new class *AIS_ColorScale*, with width and height specified explicitly.
802The 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*.
803Here is an example of creating *ColorScale* using the updated API:
27f85086 804
806Handle(AIS_ColorScale) aCS = new AIS_ColorScale();
807// configuring
d3839d74 808Standard_Integer aWidth, aHeight;
809aView->Window()->Size (aWidth, aHeight);
810aCS->SetSize (aWidth, aHeight);
27f85086 811aCS->SetRange (0.0, 10.0);
812aCS->SetNumberOfIntervals (10);
813// displaying
814aCS->SetZLayer (Graphic3d_ZLayerId_TopOSD);
815aCS->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0));
817theContextAIS->Display (aCS);
a3305c6e 820To see how 2d objects are implemented in OCCT you can call Draw commands *vcolorscale, vlayerline* or *vdrawtext* (with <i>-2d</i> option).
821Draw command *vcolorscale* now requires the name of *ColorScale* object as argument.
822To display this object use command *vdisplay*. For example:
27f85086 823
3f812249 827vcolorscale cs -demo
27f85086 828pload MODELING
829box b 100 100 100
830vdisplay b
831vsetdispmode 1
833vlayerline 0 300 300 300 10
834vdrawtext t "2D-TEXT" -2d -pos 0 150 0 -color red
a3305c6e 837Here is a small example in C++ illustrating how to display a custom AIS object in 2d:
27f85086 838~~~~~
d3839d74 839Handle(AIS_InteractiveContext) aContext = ...;
840Handle(AIS_InteractiveObject) anObj =...; // create an AIS object
841anObj->SetZLayer(Graphic3d_ZLayerId_TopOSD); // display object in overlay
842anObj->SetTransformPersistence (Graphic3d_TMF_2d, gp_Pnt (-1,-1,0)); // set 2d flag, coordinate origin is set to down-left corner
843aContext->Display (anObj); // display the object
846@subsection upgrade_occt700_userdraw UserDraw and Visual3d
848#### Visual3d package
a3305c6e 850Package *Visual3d* implementing the intermediate layer between high-level *V3d* classes
d3839d74 851and low-level OpenGl classes for views and graphic structures management has been dropped.
a3305c6e 853The *OpenGl_View* inherits from the new class *Graphic3d_CView*.
854*Graphic3d_CView* is an interface class that declares abstract methods for managing displayed structures,
d3839d74 855display properties and a base layer code that implements computation
856and management of HLR (or more broadly speaking view-depended) structures.
a3305c6e 858In the new implementation it takes place of the eliminated *Visual3d_View*.
859As before the instance of *Graphic3d_CView* is still completely managed by *V3d_View* classes.
860It can be accessed through *V3d_View* interface but normally it should not be required as all its methods are completely wrapped.
d3839d74 861
a3305c6e 862In more details, a concrete specialization of *Graphic3d_CView* is created and returned by the graphical driver on request.
863Right after the creation the views are directly used for setting rendering properties and adding graphical structures to be displayed.
d3839d74 864
865The rendering of graphics is possible after mapping a window and activating the view.
a3305c6e 866The direct setting of properties obsoletes the use of intermediate structures with display parameter
867like *Visual3d_ContextView*, etc. This means that the whole package *Visual3d* becomes redundant.
869The functionality previously provided by *Visual3d* package has been redesigned in the following way :
870- The management of display of structures has been moved from *Visual3d_ViewManager* into *Graphic3d_StructureManager*.
871- The class *Visual3d_View* has been removed. The management of computed structures has been moved into the base layer of *Graphi3d_CView*.
872- All intermediate structures for storing view parameters, e.g. *Visual3d_ContextView*, have been removed.
873 The settings are now kept by instances of *Graphic3d_CView*.
874- 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.
875- All necessary enumerations have been moved into *Graphic3d* package.
d3839d74 876
877#### Custom OpenGL rendering and UserDraw
a3305c6e 879Old APIs based on global callback functions for creating *UserDraw* objects and for performing custom OpenGL rendering within the view have been dropped.
880*UserDraw* callbacks are no more required since *OpenGl_Group* now inherits *Graphic3d_Group* and thus can be accessed directly from *AIS_InteractiveObject*:
d3839d74 881
883//! Class implementing custom OpenGL element.
884class UserDrawElement : public OpenGl_Element {};
886//! Implementation of virtual method AIS_InteractiveObject::Compute().
887void UserDrawObject::Compute (const Handle(PrsMgr_PresentationManager3d)& thePrsMgr,
888 const Handle(Prs3d_Presentation)& thePrs,
889 const Standard_Integer theMode)
891 Graphic3d_Vec4 aBndMin (myCoords[0], myCoords[1], myCoords[2], 1.0f);
892 Graphic3d_Vec4 aBndMax (myCoords[3], myCoords[4], myCoords[5], 1.0f);
894 // casting to OpenGl_Group should be always true as far as application uses OpenGl_GraphicDriver for rendering
895 Handle(OpenGl_Group) aGroup = Handle(OpenGl_Group)::DownCast (thePrs->NewGroup());
896 aGroup->SetMinMaxValues (aBndMin.x(), aBndMin.y(), aBndMin.z(),
897 aBndMax.x(), aBndMax.y(), aBndMax.z());
898 UserDrawElement* anElem = new UserDrawElement (this);
899 aGroup->AddElement(anElem);
901 // invalidate bounding box of the scene
cfece3ef 902 thePrsMgr->StructureManager()->Update();
d3839d74 903}
27f85086 904~~~~~
d3839d74 905
a3305c6e 906To perform a custom OpenGL code within the view, it is necessary to inherit from class *OpenGl_View*.
d3839d74 907See the following code sample:
910//! Custom view.
911class UserView : public OpenGl_View
914 //! Override rendering into the view.
915 virtual void render (Graphic3d_Camera::Projection theProjection,
916 OpenGl_FrameBuffer* theReadDrawFbo,
917 const Standard_Boolean theToDrawImmediate)
918 {
919 OpenGl_View::render (theProjection, theReadDrawFbo, theToDrawImmediate);
920 if (theToDrawImmediate)
921 {
922 return;
923 }
925 // perform custom drawing
926 const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext();
927 GLfloat aVerts[3] = { 0.0f, 0,0f, 0,0f };
928 aCtx->core20->glEnableClientState(GL_VERTEX_ARRAY);
929 aCtx->core20->glVertexPointer(3, GL_FLOAT, 0, aVerts);
930 aCtx->core20->glDrawArrays(GL_POINTS, 0, 1);
931 aCtx->core20->glDisableClientState(GL_VERTEX_ARRAY);
932 }
936//! Custom driver for creating UserView.
937class UserDriver : public OpenGl_GraphicDriver
940 //! Create instance of own view.
941 virtual Handle(Graphic3d_CView) CreateView (const Handle(Graphic3d_StructureManager)& theMgr) Standard_OVERRIDE
942 {
943 Handle(UserView) aView = new UserView (theMgr, this, myCaps, myDeviceLostFlag, &myStateCounter);
944 myMapOfView.Add (aView);
945 for (TColStd_SequenceOfInteger::Iterator aLayerIt (myLayerSeq); aLayerIt.More(); aLayerIt.Next())
946 {
947 const Graphic3d_ZLayerId aLayerID = aLayerIt.Value();
948 const Graphic3d_ZLayerSettings& aSettings = myMapOfZLayerSettings.Find (aLayerID);
949 aView->AddZLayer (aLayerID);
950 aView->SetZLayerSettings (aLayerID, aSettings);
951 }
952 return aView;
953 }
958@subsection upgrade_occt700_localcontext Deprecation of Local Context
a3305c6e 960The conception of Local Context has been deprecated.
961The related classes, e.g. *AIS_LocalContext*, and methods ( <i>AIS_InteractiveContext::OpenLocalContext()</i> and others) will be removed in a future OCCT release.
d3839d74 962
963The main functionality provided by Local Context - selection of object subparts - can be now used within Neutral Point without opening any Local Context.
f47afe53 964
b0d96eb7 965The property *SelectionMode()* has been removed from the class *AIS_InteractiveObject*.
a6994681 966This property contradicts to selection logic, since it is allowed to activate several Selection modes at once.
967Therefore keeping one selection mode as object field makes no sense.
968Applications that used this method should implement selection mode caching at application level, if it is necessary for some reason.
f47afe53 970@subsection upgrade_occt700_separate_caf_visualisation Separation of visualization part from TKCAF
14542432 972Visualization CAF attributes have been moved into a new toolkit *TKVCAF*.
973If your application uses the classes from *TPrsStd* package then add link to *TKVCAF* library.
975Version numbers of *BinOCAF* and *XmlOCAF* formats are incremented; new files cannot be read by earlier versions of OCCT.
f47afe53 976
14542432 977Before 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*.
978When 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 979
14542432 980@subsection upgrade_euler_angles Correction of interpretation of Euler angles in gp_Quaternion
4f5ad416 981
14542432 982Conversion of *gp_Quaternion* to and from intrinsic Tait-Bryan angles (including *gp_YawPitchRoll*) is fixed.
4f5ad416 983
d7b19997 984Before 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 985
d7b19997 986The 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 987
14542432 988@subsection upgrade_zoom_persistent_selection Zoom Persistent Selection
4f5ad416 989
07f2b741 990Zoom 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. Keep in mind the following:
14542432 991* *Graphic3d_Camera::ModelViewState* has been renamed to *Graphic3d_Camera::WorldViewState*.
992* Transformation matrix utilities from *OpenGl_Utils* namespace have been moved to *Graphic3d_TransformUtils* and *Graphic3d_TransformUtils.hxx* header respectively.
993* Matrix stack utilities from *OpenGl_Utils* namespace have been moved to *OpenGl_MatrixStack* class and *OpenGl_MatrixStack.hxx* header respectively.
07f2b741 994* *OpenGl_View* methods *Begin/EndTransformPersistence* have been removed. Use *Graphic3d_TransformPers::Apply()* instead to apply persistence to perspective and world-view projection matrices.
83da37b1 995
d7b19997 996@subsection upgrade_occt700_correction_of_texture Texture mapping of objects
83da37b1 997
d7b19997 998Textured objects now have the priority over the environment mapping.
1000Redundant 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.
1001Draw command *VSetTextureMode* has been deleted.
c1609fbe 1002
a6994681 1003@subsection upgrade_occt700_wfshape Shape presentation builders
1005Presentation tools for building Wireframe presentation have been refactored to eliminate duplicated code and interfaces.
1006Therefore, the following classes have been modified:
1007* *StdPrs_WFDeflectionShape* and *Prs3d_WFShape* have been removed. *StdPrs_WFShape* should be used instead.
1008* *StdPrs_ToolShadedShape* has been renamed to *StdPrs_ToolTriangulatedShape*.
c1609fbe 1010@section upgrade_occt710 Upgrade to OCCT 7.1.0
2831708b 1012@subsection upgrade_710_aspects Presentation attributes
80223385 1014This section should be considered if application defines custom presentations, i.e. inherited from *AIS_InteractiveObject*.
1015The previous versions of OCCT have three levels for defining presentation properties (e.g. colors, materials, etc.):
2831708b 1016
80223385 10171. For the entire structure - *Graphic3d_Structure* / *Prs3d_Presentation*.
10182. For a specific group of primitives - *Graphic3d_Group::SetGroupPrimitivesAspect()* overriding structure aspects.
10193. For a specific primitive array within the graphic group - *Graphic3d_Group::SetPrimitivesAspect()*.
2831708b 1020
80223385 1021The 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).
1022Within 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.
2831708b 1023
80223385 1024Note 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.
1025*Graphic3d_Group::SetGroupPrimitivesAspect()* should be the main method defining presentation attributes.
b6472664 1026
80223385 1027The implementation of *Graphic3d_Group::SetGroupPrimitivesAspect()* has been changed from copying aspect values to keeping the passed object.
1028Although it was not documented, previously it was possible to modify a single aspect instance, like *Graphic3d_AspectFillArea3d* and set it to multiple groups.
1029Now such code would produce an unexpected result and therefore should be updated to create the dedicated aspect instance.
2e5139af 1030
c885cfda 1031@subsection upgrade_710_types Typedefs
1033The following type definitions in OCCT has been modified to use C++11 types:
dde68833 1034- *Standard_Boolean* is now *bool* (previously *unsigned int*).
c885cfda 1035- *Standard_ExtCharacter* is now *char16_t* (previously *short*).
1036- *Standard_ExtString;* is now *const char16_t* (previously *const short*).
1037- *Standard_Utf16Char* is now *char16_t* (previously *uint16_t* for compatibility with old compilers).
1038- *Standard_Utf32Char* is now *char32_t* (previously *uint32_t* for compatibility with old compilers).
80223385 1040For 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*.
c885cfda 1041
60273f77 1042@subsection upgrade_710_ffp Programmable Pipeline
1044Fixed-function pipeline has been already deprecated since OCCT 7.0.0.
1045Release 7.1.0 disables this functionality by default in favor of Programmable Pipeline (based on GLSL programs).
80223385 1047Method *V3d_View::Export()*, based on *gl2ps* library, requires fixed pipeline and will return error if used with default settings.
1048Applications 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()*.
1049This method is declared as deprecated and will be removed in one of the the next OCCT releases.
1050The recommended way to generate a vector image of a 3D model or scene is to use an application-level solution independent from OpenGL.
60273f77 1051
3fe9ce0e 1052@subsection upgrade_710_trsfpers Transformation persistence
80223385 1054The behavior of transformation persistence flags *Graphic3d_TMF_ZoomPers* and *Graphic3d_TMF_TriedronPers* has been changed for consistency with a textured fixed-size 2D text.
1055An object with these flags is considered as defined in pixel units, and the presentation is no more scaled depending on the view height.
1056The applications that need to scale such objects depending on viewport size should update them manually.
3fe9ce0e 1057
80223385 1058Flags *Graphic3d_TMF_PanPers* and *Graphic3d_TMF_FullPers* have been removed.
1059*Graphic3d_TMF_TriedronPers* or *Graphic3d_TMF_2d* can be used instead depending on the context.
778cd667 1060
1061*Graphic3d_TransModeFlags* is not an integer bitmask anymore - enumeration values should be specified instead.
80223385 1062Several transformation persistence methods in *PrsMgr_PresentableObject* have been marked deprecated.
1063Transformation persistence should be defined using *Graphic3d_TransformPers* constructor directly and passed by a handle, not value.
778cd667 1064
45b9409a 1065@subsection upgrade_710_selprops Dynamic highlight and selection properties
8e5fb5ea 1066
80223385 1067Release 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:
1068- *AIS_InteractiveContext::Hilight()*;
1069- *AIS_InteractiveContext::HilightWithColor()*;
1070- *PrsMgr_PresentationManager::Color()*;
1071- *SelectMgr_EntityOwner::HilightWithColor()*;
1072have been changed to receive *Graphic3d_HighlightStyle* instead of *Quantity_Color*.
8e5fb5ea 1073
80223385 1074Method *AIS_InteractiveContext::Hilight* is now deprecated and highlights the interactive object with selection style.
8e5fb5ea 1075
80223385 1076A 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.
8e5fb5ea 1077
80223385 1078The following methods have been replaced in *AIS_InteractiveContext* class:
1079- *HilightColor* and *SetHilightColor* by *HighlightStyle* and *SetHighlightStyle*;
1080- *SelectionColor* setter and getter by *SelectionStyle* and *SetSelectionStyle*.
8e5fb5ea 1081
80223385 1082The 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.
1084@subsection upgrade_occt710_correction_of_TObj_Model Correction in TObj_Model class
1086Methods *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.
1088@subsection upgrade_710_env Redundant environment variables
1090The following environment variables have become redundant:
1092* *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.
1093* *CSF_XSMessage* and *CSF_XHMessage* are now optional.
78d5ea7a 1094 English messages (XSMessage/\*XSTEP.us* and SHMessage/\*SHAPE.us*) are now embedded into source code
80223385 1095 and automatically loaded when environment variables are not set.
1096* *CSF_ShadersDirectory* is not required any more, though it still can be used to load custom shaders.
1097 Mandatory GLSL resources are now embedded into source code.
1098* *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.
1100Other environment variables still can be used to customize behavior of relevant algorithms but are not necessary any more (all required resources are embedded).
8e5fb5ea 1101
2e5139af 1102@subsection upgrade_710_removed Removed features
1104The following obsolete features have been removed:
80223385 1105* 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*.
1106 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()*.
1107* *Prs3d_Drawer::ShadingAspectGlobal()* flag has been removed as not used. The corresponding calls can be removed safely from the application code.
1108* 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).
1109* 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.
60273f77 1110 Text resolution can be managed by rendering parameter *Graphic3d_RenderingParams::Resolution*, returned by *V3d_View::ChangeRenderingParams()*.
80223385 1111* 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.
1112* 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.
1114* 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.
1f9fb707 1115
63dbfc04 1116@subsection upgrade_710_changed_methods Other changes
1118The following classes have been changed:
80223385 1120* *BVH_Sorter* class has become abstract. The list of arguments of both *Perform* methods has been changed and the methods became pure virtual.
63dbfc04 1121* *Extrema_FuncExtPS* has been renamed to *Extrema_FuncPSNorm*.
80223385 1122* 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.
1123* 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.
1124* *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*.
1125* The second parameter *theIsOuterWire* of method *ShapeAnalysis_Wire::CheckSmallArea* has been removed.
1126* 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.
73b07edd 1127* The last optional argument *RemoveInvalidFaces* has been removed from the constructor of class *BRepOffset_MakeOffset* and method *Initialize*.
80223385 1128* The public method *BOPDS_DS::VerticesOnIn* has been renamed into *SubShapesOnIn* and the new output parameter *theCommonPB* has been added.
3c162495 1129
8013367c 1130@section upgrade_occt720 Upgrade to OCCT 7.2.0
f838dac4 1132@subsection upgrade_720_removed Removed features
1134The following obsolete features have been removed:
b0d96eb7 1135* *AIS_InteractiveContext::PreSelectionColor()*, *DefaultColor()*, *WasCurrentTouched()*, *ZDetection()*.
f838dac4 1136 These properties were unused, and therefore application should remove occurrences of these methods.
1137* *AIS_InteractiveObject::SelectionPriority()*.
1138 These property was not implemented.
f1b2eddc 1139* The class *LocOpe_HBuilder* has been removed as obsolete.
7868210d 1140* The package *TestTopOpe* has been removed;
1141* The package *TestTopOpeDraw* has been removed;
1142* The package *TestTopOpeTools* has been removed.
2d0621bf 1143* The packages *QANewModTopOpe*, *QANewBRepNaming* and *QANewDBRepNaming* have been removed as containing obsolete features.
68b07699 1144* The following methods of the *IntPolyh_Triangle* class have been removed as unused:
1145 - *CheckCommonEdge*
1146 - *SetEdgeandOrientation*
1147 - *MultipleMiddleRefinement2*.
1148* The method *IntPolyh_Triangle::TriangleDeflection* has been renamed to *IntPolyh_Triangle::ComputeDeflection*.
1149* The following methods of the *IntPolyh_MaillageAffinage* class have been removed as unused:
1150 - *LinkEdges2Triangles*;
1151 - *TriangleEdgeContact2*;
1152 - *StartingPointsResearch2*;
1153 - *NextStartingPointsResearch2*;
1154 - *TriangleComparePSP*;
1155 - *StartPointsCalcul*.
2c26a53d 1156* The method PerformAdvanced of the *ShapeConstruct_ProjectCurveOnSurface* class has been removed as unused.
1157* The method Perform of the *ShapeConstruct_ProjectCurveOnSurface* class is modified:
1158 - input arguments *continuity*, *maxdeg*, *nbinterval* have been removed as unused;
1159 - input arguments *TolFirst*, *TolLast* have been added at the end of arguments' list.
4bcc2030 1160* Typedefs Quantity_Factor, Quantity_Parameter, Quantity_Ratio, Quantity_Coefficient, Quantity_PlaneAngle, Quantity_Length, V3d_Parameter and V3d_Coordinate have been removed; Standard_Real should be used instead.
1162@subsection upgrade_occt720_reshape_oriented_removed Corrections in BRepOffset API
1164In classes *BRepTools_ReShape* and *ShapeBuild_ReShape*, the possibility to process shapes different only by orientation in different ways has been removed.
1165Thus methods *Remove()* and *Replace()* do not have any more the last argument 'oriented'; they work always as if *Standard_False* was passed before (default behavior).
1166Methods *ModeConsiderLo()* and *Apply()* with three arguments have been removed.
f838dac4 1167
8013367c 1168@subsection upgrade_occt720_correction_of_Offset_API Corrections in BRepOffset API
1170Class *BRepOffsetAPI_MakeOffsetShape*:
1171* *BRepOffsetAPI_MakeOffsetShape::BRepOffsetAPI_MakeOffsetShape()* - constructor with parameters has been deleted.
1172* *BRepOffsetAPI_MakeOffsetShape::PerformByJoin()* - method has been added. This method is old algorithm behaviour.
1174The code below shows new calling procedure:
1176 BRepOffsetAPI_MakeOffsetShape OffsetMaker;
1177 OffsetMaker.PerformByJoin(Shape, OffsetValue, Tolerance);
1178 NewShape = OffsetMaker.Shape();
1181Class *BRepOffsetAPI_MakeThickSolid*:
1182* *BRepOffsetAPI_MakeThickSolid::BRepOffsetAPI_MakeThickSolid()* - constructor with parameters has been deleted.
1183* *BRepOffsetAPI_MakeThickSolid::MakeThickSolidByJoin()* - method has been added. This method is old algorithm behaviour.
1185The code below shows new calling procedure:
1187 BRepOffsetAPI_MakeThickSolid BodyMaker;
1188 BodyMaker.MakeThickSolidByJoin(myBody, facesToRemove, -myThickness / 50, 1.e-3);
1189 myBody = BodyMaker.Shape();
f838dac4 1191
1192@subsection upgrade_720_highlight Highlight style
1194Management of highlight attributes has been revised and might require modifications from application side:
1195* New class *Graphic3d_PresentationAttributes* defining basic presentation attributes has been introduced.
1196 It's definition includes properties previously defined by class Graphic3d_HighlightStyle (*Color*, *Transparency*),
1197 and new properties (*Display mode*, *ZLayer*, optional *FillArea aspect*).
1198* Class *Prs3d_Drawer* now inherits class *Graphic3d_PresentationAttributes*.
1199 So that overall presentation attributes are now split into two parts - Basic attributes and Detailed attributes.
1200* Class *Graphic3d_HighlightStyle* has been dropped.
1201 It is now defined as a typedef to *Prs3d_Drawer*.
1202 Therefore, highlight style now also includes not only Basic presentation attributes, but also Detailed attributes
1203 which can be used by custom presentation builders.
1204* Highlighting style defined by class *Graphic3d_PresentationAttributes* now provides more options:
1205 - *Graphic3d_PresentationAttributes::BasicFillAreaAspect()* property providing complete Material definition.
1206 This option, when defined, can be used instead of the pair Object Material + Highlight Color.
1207 - *Graphic3d_PresentationAttributes::ZLayer()* property specifying the Layer where highlighted presentation should be shown.
1208 This property can be set to Graphic3d_ZLayerId_UNKNOWN, which means that ZLayer of main presentation should be used instead.
1209 - *Graphic3d_PresentationAttributes::DisplayMode()* property specifying Display Mode for highlight presentation.
1210* Since Highlight and Selection styles within *AIS_InteractiveContext* are now defined by *Prs3d_Drawer* inheriting from *Graphic3d_PresentationAttributes*,
1211 it is now possible to customize default highlight attributes like *Display Mode* and *ZLayer*, which previously could be defined only on Object level.
1212* Properties *Prs3d_Drawer::HighlightStyle()* and *Prs3d_Drawer::SelectionStyle()* have been removed.
b0d96eb7 1213 Instead, *AIS_InteractiveObject* now defines *DynamicHilightAttributes()* for dynamic highlighting in addition to *HilightAttributes()* used for highlighting in selected state.
cee2b556 1214 Note that *AIS_InteractiveObject::HilightAttributes()* and *AIS_InteractiveObject::DynamicHilightAttributes()* override highlighting properties for both - entire object and for part coming from decomposition.
1215 This includes Z-layer settings, which will be the same when overriding properties through AIS_InteractiveObject, while *AIS_InteractiveContext::HighlightStyle()* allows customizing properties for local and global selection independently
1216 (with Graphic3d_ZLayerId_Top used for dynamic highlighting of entire object and Graphic3d_ZLayerId_Topmost for dynamic highlighting of object part by default).
f838dac4 1217* The following protected fields have been removed from class *AIS_InteractiveObject*:
1218 - *myOwnColor*, replaced by *myDrawer->Color()*
1219 - *myTransparency*, replaced by *myDrawer->Transparency()*
1220 - *myZLayer*, replaced by *myDrawer->ZLayer()*
1221* The method *PrsMgr_PresentationManager::Unhighlight()* taking Display Mode as an argument has been marked deprecated.
1222 Implementation now performs unhighlighting of all highlighted presentation mode.
4bcc2030 1223* The methods taking/returning *Quantity_NameOfColor* (predefined list of colors) and duplicating methods operating with *Quantity_Color* (definition of arbitrary RGB color) in AIS have been removed.
1224 *Quantity_Color* should be now used instead.
77a11d3d 1225
0577ae8c 1226@subsection upgrade_720_implicit_viewer_update Elimination of implicit 3D Viewer updates
1228Most AIS_InteractiveContext methods are defined with a flag to update viewer immediatly or not.
1229Within previous version of OCCT, this argument had default value TRUE.
1230While immediate viewer updates are useful for beginners (the result is displayed as soon as possible),
1231this approach is inefficent for batch viewer updates, and having default value as TRUE
1232leaded to non-intended accidential updates which are difficult to find.
1234To avoid such issues, the interface has been modified and default value has been removed.
1235Therefore, old application code should be updated to set the flag theToUpdateViewer explicitly
1236to desired value (TRUE to preserve old previous behavior), if it was not already set.
4bcc2030 1238The following AIS_InteractiveContext methods have been changed:
0577ae8c 1239 Display, Erase, EraseAll, DisplayAll, EraseSelected, DisplaySelected, ClearPrs, Remove, RemoveAll, Hilight,
1240 HilightWithColor, Unhilight, Redisplay, RecomputePrsOnly, Update, SetDisplayMode, UnsetDisplayMode, SetColor,
1241 UnsetColor, SetWidth, UnsetWidth, SetMaterial, UnsetMaterial, SetTransparency, UnsetTransparency,
1242 SetLocalAttributes, UnsetLocalAttributes, SetPolygonOffsets, SetTrihedronSize, SetPlaneSize, SetPlaneSize,
1243 SetDeviationCoefficient, SetDeviationAngle, SetAngleAndDeviation, SetHLRDeviationCoefficient,
1244 SetHLRDeviationAngle, SetHLRAngleAndDeviation, SetSelectedAspect, MoveTo, Select, ShiftSelect, SetSelected,
1245 UpdateSelected, AddOrRemoveSelected, HilightSelected, UnhilightSelected, ClearSelected, ResetOriginalState,
1246 SubIntensityOn, SubIntensityOff, FitSelected, EraseGlobal, ClearGlobal, ClearGlobalPrs.
cfece3ef 1248In addition, the API for immediate viewer update has been removed from V3d_View and Graphic3d_StructureManager classes
1249(enumerations *Aspect_TypeOfUpdate* and *V3d_TypeOfUpdate*):
1250 V3d::SetUpdateMode(), V3d::UpdateMode(), Graphic3d_StructureManager::SetUpdateMode(), Graphic3d_StructureManager::UpdateMode().
97f3782b 1252The argument theUpdateMode has been removed from methods Graphic3d_CView::Display(), Erase(), Update().
cfece3ef 1253Method Graphic3d_CView::Update() does not redraw the view and does not re-compute structures anymore.
224f48fa 1255The following Grid management methods within class V3d_Viewer do not implicitly redraw the viewer:
1256 ActivateGrid, DeactivateGrid, SetRectangularGridValues, SetCircularGridValues,
1257 RectangularGridGraphicValues, CircularGridGraphicValues, SetPrivilegedPlane, DisplayPrivilegedPlane.
87432b82 1259@subsection upgrade_720_v3d_colorname Elimination of Quantity_NameOfColor from TKV3d interface classes
1261The duplicating interface methods accepting *Quantity_NameOfColor* (in addition to methods accepting *Quantity_Color*) of TKV3d toolkit have been removed.
1262In most cases this change should be transparent, however applications implementing such interface methods should also remove them
1263(compiler will automatically highlight this issue for methods marked with Standard_OVERRIDE keyword).
77a11d3d 1265@subsection upgrade_720_Result_Of_BOP_On_Containers Result of Boolean operations on containers
0577ae8c 1267* The result of Boolean operations on arguments of collection types (WIRE/SHELL/COMPSOLID) is now filtered from duplicating containers.
465e6861 1268
1269@subsection upgrade_720_changes_methods Other changes
25e59720 1271* *MMgt_TShared* class definition has been removed - Standard_Transient should be used instead (MMgt_TShared is marked as deprecated typedef of Standard_Transient for smooth migration).
465e6861 1272* Class GeomPlate_BuildPlateSurface accepts base class Adaptor3d_HCurve (instead of inherited Adaptor3d_HCurveOnSurface accepted earlier).
465e6861 1273* 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).
dc858f4c 1274* 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.
1275 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.
b18a83d4 1276 Old definitions are preserved as depreacated aliases to the new ones;
e958a649 1277* Methods *Image_PixMap::PixelColor()* and *Image_PixMap::SetPixelColor()* now take/return Quantity_ColorRGBA instead of Quantity_Color/NCollection_Vec4.
b18a83d4 1278* The method BOPAlgo_Builder::Origins() returns BOPCol_DataMapOfShapeListOfShape instead of BOPCol_DataMapOfShapeShape.
edfa30de 1279* The methods BOPDS_DS::IsToSort(const Handle(BOPDS_CommonBlock)&, Standard_Integer&) and BOPDS_DS::SortPaveBlocks(const Handle(BOPDS_CommonBlock)&) have been removed. The sorting is now performed during the addition of the Pave Blocks into Common Block.
1280* The methods BOPAlgo_Tools::MakeBlocks() and BOPAlgo_Tools::MakeBlocksCnx() have been replaced with the single template method BOPAlgo_Tools::MakeBlocks(). The chains of connected elements are now stored into the list of list instead of data map.
1281* The methods BOPAlgo_Tools::FillMap() have been replaced with the single template method BOPAlgo_Tools::FillMap().
f5b72419 1282* Package BVH now uses opencascade::handle instead of NCollection_Handle (for classes BVH_Properties, BVH_Builder, BVH_Tree, BVH_Object).
1283 Application code using BVH package directly should be updated accordingly.
a6dee93d 1284* AIS_Shape now computes UV texture coordinates for AIS_Shaded presentation in case if texture mapping is enabled within Shaded Attributes.
4bcc2030 1285 Therefore, redundant class *AIS_TexturedShape is now deprecated* - applications can use *AIS_Shape* directly (texture mapping should be defined through AIS_Shape::Attributes()).
1286* Methods for managing active texture within OpenGl_Workspace class (ActiveTexture(), DisableTexture(), EnableTexture()) have been moved to *OpenGl_Context::BindTextures()*.
25dfc507 1287
1288@subsection upgrade_720_BOP_DataStructure BOP - Pairs of interfering indices
1290* 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:
1291 - The method *BOPDS_DS::Interferences()* now returns the *BOPDS_MapOfPair*;
1292 - The method *BOPDS_Iterator::Value()* takes now only two parameters - the indices of interfering sub-shapes.
20aa0d3f 1293
e45b5ff7 1294@subsection upgrade_720_Removal_Of_Old_Boolean_Operations_Draw Removal of the Draw commands based on old Boolean operations
1296* The commands *fubl* and *cubl* have been removed. The alternative for these commands are the commands *bfuseblend* and *bcutblend* respectively.
5652dc62 1297* The command *ksection* has been removed. The alternative for this command is the command *bsection*.
1299@subsection upgrade_720_Change_Of_FaceFace_Intersection Change of Face/Face intersection in Boolean operations
1301* Previously, the intersection tolerance for all section curves between pair of faces has been calculated as the maximal tolerance among all curves.
1302 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.
1303* The methods *IntTools_FaceFace::TolReached3d()*, *IntTools_FaceFace::TolReal()* and *IntTools_FaceFace::TolReached2d()* have been removed.
1304* Intersection tolerances of the curve can be obtained from the curve itself:
1305 - *IntTools_Curve::Tolerance()* - returns the valid tolerance for the curve;
1306 - *IntTools_Curve::TangentialTolerance()* - returns the tangential tolerance, which reflects the size of the common between faces.
1307* 2d tolerance (*IntTools_FaceFace::TolReached2d()*) has been completely removed from the algorithm as unused.
ff3f0387 1308
ec964372 1310@subsection upgrade_720_persistence Restore OCCT 6.9.1 persistence
4bcc2030 1311
1312The 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.
ec964372 1313
1314One can use this functionality in two ways:
ff3f0387 1315- invoke DRAW Test Harness commands *fsdread / fsdwrite* for shapes;
1316- call *StdStorage* class *Read / Write* functions in custom code.
ec964372 1317
4bcc2030 1318The code example below demonstrates how to read shapes from a storage driver using *StdStorage* class.
ec964372 1319
1321// aDriver should be created and opened for reading
1322Handle(StdStorage_Data) aData;
1324// Read data from the driver
1325// StdStorage::Read creates aData instance automatically if it is null
1326Storage_Error anError = StdStorage::Read(*aDriver, aData);
1327if (anError != Storage_VSOk)
1329 // Error processing
1332// Get root objects
1333Handle(StdStorage_RootData) aRootData = aData->RootData();
1334Handle(StdStorage_HSequenceOfRoots) aRoots = aRootData->Roots();
1335if (!aRoots.IsNull())
1337 // Iterator over the sequence of root objects
1338 for (StdStorage_HSequenceOfRoots::Iterator anIt(*aRoots); anIt.More(); anIt.Next())
1339 {
1340 Handle(StdStorage_Root)& aRoot = anIt.ChangeValue();
1341 // Get a persistent root's object
1342 Handle(StdObjMgt_Persistent) aPObject = aRoot->Object();
1343 if (!aPObject.IsNull())
1344 {
1345 Handle(ShapePersistent_TopoDS::HShape) aHShape = Handle(ShapePersistent_TopoDS::HShape)::DownCast(aPObject);
1346 if (aHShape) // Downcast to an expected type to import transient data
1347 {
1348 TopoDS_Shape aShape = aHShape->Import();
1349 shapes.Append(aShape);
1350 }
1351 }
1352 }
1356The following code demonstrates how to write shapes in OCCT 7.2.0 using *StdStorage* class.
1359// Create a file driver
1360NCollection_Handle<Storage_BaseDriver> aFileDriver(new FSD_File());
1362// Try to open the file driver for writing
4bcc2030 1366 PCDM_ReadWriter::Open (*aFileDriver, TCollection_ExtendedString(theFilename), Storage_VSWrite);
ec964372 1367}
1368catch (Standard_Failure& e)
1370 // Error processing
1373// Create a storage data instance
4bcc2030 1374Handle(StdStorage_Data) aData = new StdStorage_Data();
ec964372 1375// Set an axiliary application name (optional)
1378// Provide a map to track sharing
1379StdObjMgt_TransientPersistentMap aMap;
1380// Iterator over a collection of shapes
1381for (Standard_Integer i = 1; i <= shapes.Length(); ++i)
1383 TopoDS_Shape aShape = shapes.Value(i);
1384 // Translate a shape to a persistent object
1385 Handle(ShapePersistent_TopoDS::HShape) aPShape =
1386 ShapePersistent_TopoDS::Translate(aShape, aMap, ShapePersistent_WithTriangle);
1387 if (aPShape.IsNull())
1388 {
1389 // Error processing
1390 }
1392 // Construct a root name
4bcc2030 1393 TCollection_AsciiString aName = TCollection_AsciiString("Shape_") + i;
ec964372 1394
1395 // Add a root to storage data
1396 Handle(StdStorage_Root) aRoot = new StdStorage_Root(aName, aPShape);
1397 aData->RootData()->AddRoot(aRoot);
1400// Write storage data to the driver
1401Storage_Error anError = StdStorage::Write(*aFileDriver, aData);
1402if (anError != Storage_VSOk)
1404 // Error processing
b608f6a5 1407
1408@subsection upgrade_720_Change_In_BRepLib_MakeFace_Algo Change in BRepLib_MakeFace algorithm
4bcc2030 1410Previously, *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 the entire face as a hole; the 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 the open wire will be located on the left side from the source wire.
b608f6a5 1411
1412@subsection upgrade_720_Change_In_BRepFill_OffsetWire Change in BRepFill_OffsetWire algorithm
4bcc2030 1414From now on, the offset will always be directed to the outer region in case of positive offset value and to the inner region in case of negative offset value.
1415Inner/Outer region for an open wire is defined by the following rule:
1416when we go along the wire (taking into account edges orientation) the outer region will be on the right side, the inner region will be on the left side.
1417In case of a closed wire, the inner region will always be inside the wire (at that, the edges orientation is not taken into account).
ff3f0387 1419@subsection upgrade_720_Change_In_GeomAdaptor_Curve Change in Geom(2d)Adaptor_Curve::IsPeriodic
4bcc2030 1420
ff3f0387 1421Since 7.2.0 version, method *IsPeriodic()* returns the corresponding status of periodicity of the basis curve regardless of closure status of the adaptor curve (see method *IsClosed()*).
1422Method *IsClosed()* for adaptor can return false even on periodic curve, in the case if its parametric range is not full period, e.g. for adaptor on circle in range [0, @f$ \pi @f$].
1423In previous versions, *IsPeriodic()* always returned false if *IsClosed()* returned false.
654c48b2 1424
896faa72 1425@subsection upgrade_720_UnifySameDomain Change in algorithm ShapeUpgrade_UnifySameDomain
654c48b2 1426
1427The history of the changing of the initial shape was corrected:
1428* all shapes created by the algorithm are considered as modified shapes instead of generated ones;
1429* method Generated was removed and its calls should be replaced by calls of method History()->Modified.
4178b353 1430
1431@subsection upgrade_720_Change_In_RWStl Changes in STL Reader / Writer
1433Class RWStl now uses class Poly_Triangulation for storing triangular mesh instead of StlMesh data classes; the latter have been removed.
a743814b 1434
1435@subsection upgrade_720_New_Error_Warning_system_in_BOA Refactoring of the Error/Warning reporting system in Boolean Component
1437The Error/Warning reporting system of the algorithms in Boolean Component (in all BOPAlgo_* and BRepAlgoAPI_* algorithms) has been refactored.
1438The methods returning the status of errors and warnings of the algorithms (ErrorStatus() and WarningStatus()) have been removed.
1439Instead use methods HasErrors() and HasWarnings() to check for presence of errors and warnings, respectively.
1440The full list of errors and warnings, with associated data such as problematic sub-shapes, can be obtained by method GetReport().
f16a6cc5 1441
1442@section upgrade_occt721 Upgrade to OCCT 7.2.1
1444@subsection upgrade_721_Changes_In_USD Changes in ShapeUpgrade_UnifySameDomain
1446The following public methods in the class ShapeUpgrade_UnifySameDomain became protected:
1447* *UnifyFaces*
1448* *UnifyEdges*
1450The following public method has been removed:
1451* *UnifyFacesAndEdges*
1453@subsection upgrade_721_Move_BuildPCurveForEdgeOnPlane Moving BuildPCurveForEdgeOnPlane from BOPTools_AlgoTools2D to BRepLib
1455The methods BuildPCurveForEdgeOnPlane and BuildPCurveForEdgesOnPlane have been moved from the class BOPTools_AlgoTools2D
1456to the more lower level class BRepLib.
1155d05a 1457
1458@subsection upgrade_721_removed Removed features
1460The following obsolete features have been removed:
1461* The package BOPCol has been fully removed:
1462 - *BOPCol_BaseAllocator* is replaced with *Handle(NCollection_BaseAllocator)*;
1463 - *BOPCol_BoxBndTree* is replaced with *BOPTools_BoxBndTree*;
1464 - *BOPCol_Box2DBndTree* is removed as unused;
1465 - *BOPCol_DataMapOfIntegerInteger* is replaced with *TColStd_DataMapOfIntegerInteger*;
1466 - *BOPCol_DataMapOfIntegerListOfInteger* is replaced with *TColStd_DataMapOfIntegerListOfInteger*;
1467 - *BOPCol_DataMapOfIntegerListOfShape* is replaced with *TopTools_DataMapOfIntegerListOfShape*;
1468 - *BOPCol_DataMapOfIntegerMapOfInteger.hxx* is removed as unused;
1469 - *BOPCol_DataMapOfIntegerReal* is replaced with *TColStd_DataMapOfIntegerReal*;
1470 - *BOPCol_DataMapOfIntegerShape* is replaced with *TopTools_DataMapOfIntegerShape*;
1471 - *BOPCol_DataMapOfShapeBox* is replaced with *TopTools_DataMapOfShapeBox*;
1472 - *BOPCol_DataMapOfShapeInteger* is replaced with *TopTools_DataMapOfShapeInteger*;
1473 - *BOPCol_DataMapOfShapeListOfShape* is replaced with *TopTools_DataMapOfShapeListOfShape*;
1474 - *BOPCol_DataMapOfShapeReal* is replaced with *TopTools_DataMapOfShapeReal*;
1475 - *BOPCol_DataMapOfShapeShape* is replaced with *TopTools_DataMapOfShapeShape*;
1476 - *BOPCol_DataMapOfTransientAddress* is removed as unused;
1477 - *BOPCol_IndexedDataMapOfIntegerListOfInteger* is removed as unused;
1478 - *BOPCol_IndexedDataMapOfShapeBox* is removed as unused;
1479 - *BOPCol_IndexedDataMapOfShapeInteger* is removed as unused;
1480 - *BOPCol_IndexedDataMapOfShapeListOfShape* is replaced with *TopTools_IndexedDataMapOfShapeListOfShape*;
1481 - *BOPCol_IndexedDataMapOfShapeReal* is removed as unused;
1482 - *BOPCol_IndexedDataMapOfShapeShape* is replaced with *TopTools_IndexedDataMapOfShapeShape*;
1483 - *BOPCol_IndexedMapOfInteger* is replaced with *TColStd_IndexedMapOfInteger*;
1484 - *BOPCol_IndexedMapOfOrientedShape* is replaced with *TopTools_IndexedMapOfOrientedShape*;
1485 - *BOPCol_IndexedMapOfShape* is replaced with *TopTools_IndexedMapOfShape*;
1486 - *BOPCol_ListOfInteger* is replaced with *TColStd_ListOfInteger*;
1487 - *BOPCol_ListOfListOfShape* is replaced with *TopTools_ListOfListOfShape*;
1488 - *BOPCol_ListOfShape* is replaced with *TopTools_ListOfShape*;
1489 - *BOPCol_MapOfInteger* is replaced with *TColStd_MapOfInteger*;
1490 - *BOPCol_MapOfOrientedShape* is replaced with *TopTools_MapOfOrientedShape*;
1491 - *BOPCol_MapOfShape* is replaced with *TopTools_MapOfShape*;
1492 - *BOPCol_PListOfInteger* is removed as unused;
1493 - *BOPCol_PInteger* is removed as unused
1494 - *BOPCol_SequenceOfPnt2d* is replaced with *TColgp_SequenceOfPnt2d*;
1495 - *BOPCol_SequenceOfReal* is replaced with *TColStd_SequenceOfReal*;
1496 - *BOPCol_SequenceOfShape* is replaced with *TopTools_SequenceOfShape*;
1497 - *BOPCol_Parallel* is replaced with *BOPTools_Parallel*;
1498 - *BOPCol_NCVector* is replaced with *NCollection_Vector*;
1499* The class *BOPDS_PassKey* and containers for it have been removed as unused.
1500* The unused containers from *IntTools* package have been removed:
1501 - *IntTools_DataMapOfShapeAddress* is removed as unused;
1502 - *IntTools_IndexedDataMapOfTransientAddress* is removed as unused;
1503* The container *BiTgte_DataMapOfShapeBox* is replaced with *TopTools_DataMapOfShapeBox*;
1504* The class *BOPTools* has been removed as duplicate of the class *TopExp*;
992ed6b3 1505* The method *BOPAlgo_Builder::Splits()* has been removed as excessive. The method *BOPAlgo_Builder::Images()* can be used instead.
80d55adf 1506* The method *BOPTools_AlgoTools::CheckSameGeom()* has been removed as excessive. The method *BOPTools_AlgoTools::AreFacesSameDomain()* can be used instead.
992ed6b3 1507
1508@section upgrade_occt730 Upgrade to OCCT 7.3.0
1510@subsection upgrade_730_lights Light sources
f841d372 1512Multiple changes have been applied to lights management within *TKV3d* and *TKOpenGl*:
1513* *V3d_Light* class is now an alias to *Graphic3d_CLight*.
1514 *Graphic3d_CLight* is now a Handle class with refactored methods for managing light source parameters.
1515 Most methods of *V3d_Light* sub-classes have been preserved to simplify porting.
1516* Obsolete debugging functionality for drawing a light source has been removed from *V3d_Light*.
1517 Methods and constructors that take parameters for debug display and do not affect the light definition itself have also been removed.
1518* Light constructors taking *V3d_Viewer* have been marked as deprecated.
1519 Use method *AddLight()* of the class *V3d_Viewer* or *V3d_View* to add new light sources to a scene or a single view, respectively.
992ed6b3 1520* The upper limit of 8 light sources has been removed.
f841d372 1521* The classes for specific light source types: *V3d_AmbientLight, V3d_DirectionalLight, V3d_PositionalLight* and *V3d_SpotLight* have been preserved, but it is now possible to define the light of any type by creating base class *Graphic3d_CLight* directly. The specific classes only hide unrelated light properties depending on the type of light source.
1522* It is no more required to call *V3d_Viewer::UpdateLights()* after modifying the properties of light sources (color, position, etc.)
803a8caf 1523
db5d29de 1524@subsection upgrade_730_shadingmodels Shading Models
f841d372 1526*Graphic3d_AspectFillArea3d* has been extended by a new property *ShadingModel()*, which previously has been defined globally for the entire View.
db5d29de 1527
f841d372 1528Previously, a triangle array without normal vertex attributes was implicitly considered as unshaded,
db5d29de 1529but now such array will be shaded using *Graphic3d_TOSM_FACET* model (e.g. by computing per-triangle normals).
f841d372 1530Therefore, *Graphic3d_TOSM_UNLIT* should be explicitly specified to disable shading of triangles array.
1531Alternatively, a material without reflectance properties can be used to disable shading (as before).
db5d29de 1532
dc89236f 1533@subsection upgrade_730_tkopengl Custom low-level OpenGL elements
f841d372 1535The following API changes should be considered while porting custom *OpenGl_Element* objects:
39a349fd 1536* *OpenGl_ShaderManager::BindFaceProgram()*, *BindLineProgram()*, *BindMarkerProgram()* now take enumeration arguments instead of Boolean flags.
dc89236f 1537
803a8caf 1538@subsection upgrade_730_BOPAlgo_Section Changes in BOPAlgo_Section
f841d372 1540The public method *BuildSection()* in the class *BOPAlgo_Section* has become protected. The methods *Perform()* or *PerformWithFiller()* should be called for construction of the result of SECTION operation.
f24150b8 1541
1542@subsection upgrade_730_BRepAdaptor_CompCurve Changes in BRepAdaptor_CompCurve
f841d372 1544The method *BRepAdaptor_CompCurve::SetPeriodic* has been eliminated.
1545Since the new version, the method *BRepAdaptor_CompCurve::IsPeriodic()* will always return FALSE. Earlier, it could return TRUE in case if the wire contained only one edge based on a periodic curve.
03cca6f7 1546
1547@subsection upgrade_730_removed Removed features
f841d372 1548* The methods *SetDeflection*, *SetEpsilonT*, *SetDiscretize* of the class *IntTools_EdgeFace* have been removed as redundant.
e52ba46e 1549* Deprecated functionality *V3d_View::Export()*, related enumerations Graphic3d_ExportFormat, Graphic3d_SortType
1550 as well as optional dependency from gl2ps library have been removed.
7797eb38 1551
7f3408c8 1552@subsection upgrade_730_BuilderSolid Boolean Operations - Solid Builder algorithm
f841d372 1554Previously, the unclassified faces of *BOPAlgo_BuilderSolid* algorithm (i.e. the faces not used for solids creation and located outside of all created solids) were used to form an additional (not closed) solid with INTERNAL orientation.
1555Since the new version, these unclassified faces are no longer added into the resulting solids. Instead, the @ref occt_algorithms_ers "warning" with a list of these faces appears.
7f3408c8 1556
f841d372 1557The following public methods of the *BOPAlgo_BuilderSolid* class have been removed as redundant:
1558* *void SetSolid(const TopoDS_Solid& theSolid);*
1559* *const TopoDS_Solid& Solid() const;*
9ce99357 1560
1561@subsection upgrade_730_BRepAlgoBO Boolean Operation classes in BRepAlgo are deprecated
1563The API classes in the package BRepAlgo providing access to old Boolean operations are marked as deprecated:
1564* BRepAlgo_Fuse
1565* BRepAlgo_Common
1566* BRepAlgo_Cut
1567* BRepAlgo_Section
1568Corresponding classes from the package BRepAlgoAPI should be used instead.
64e93ce1 1569
1570@subsection upgrade_730_replace_CDM_MessageDriver_interface_by_Message_Messenger Unification of the Error/Warning reporting system of Application Framework
1572Class *CDM_MessageDriver* and its descendants have been removed; class *Message_Messenger* is used instead in all OCAF packages.
1573By default, messenger returned by *Message::DefaultMessenger()* is used, thus all messages generated by OCAF are directed in the common message queue of OCCT.
1575In classes implementing OCAF persistence for custom attributes (those inheriting from *BinMDF_ADriver*, *XmlMDF_ADriver*), uses of method *WriteMessage()* should be replaced by call to method *Send()* of the inherited field *myMessageDriver*. Note that this method takes additional argument indicating the gravity of the message (Trace, Info, Warning, Alarm, or Fail).
1577Class *Message_PrinterOStream* can be used instead of *CDM_COutMessageDriver* to direct all messages to a stream.
1578If custom driver class is used in the application, that class shall be reimplemented inheriting from *Message_Printer* instead of *CDM_MessageDriver*.
1579Method *Send()* should be redefined instead of method *Write()* of *CDM_MessageDriver*.
1580To use the custom printer in OCAF, it can be either added to default messenger or set into the custom *Message_Messenger* object created in the method *MessageDriver()* of a class inheriting *CDF_Application*.
7e4ff648 1581
1582@section upgrade_occt740 Upgrade to OCCT 7.4.0
1584@subsection upgrade_740_BRepPrimAPI_MakeRevol Changes in BRepPrimAPI_MakeRevol algorithm
1585Previously the algorithm could create a shape with the same degenerated edge shared between some faces. Now it is prevented. The algorithm creates the different copy of this edge for each face. The method *Generated(...)* has been changed in order to apply restriction to the input shape: input shape can be only of type VERTEX, EDGE, FACE or SOLID. For input shape of another type the method always returns empty list.
638ad7f3 1586
948fe6ca 1587@subsection upgrade_740_removed Removed features
1588* The following methods of the class *BRepAlgoAPI_BooleanOperation* have been removed as obsolete or replaced:
1589 - *BuilderCanWork* can be replaced with *IsDone* or *HasErrors* method.
1590 - *FuseEdges* removed as obsolete.
1591 - *RefineEdges* replaced with new method *SimplifyResult*.
1592* The method *ImagesResult* of the class *BOPAlgo_BuilderShape* has been removed as unused. The functionality of this method can be completely replaced by the history methods *Modified* and *IsDeleted*.
1593* The method *TrackHistory* of the classes *BOPAlgo_RemoveFeatures* and *BRepAlgoAPI_Defeaturing* has been renamed to *SetToFillHistory*.
1594* The method *GetHistory* of the class *BRepAlgoAPI_Defeaturing* has been renamed to *History*.
0fdcb9c9 1595* The classes *BRepAlgo_BooleanOperations* and *BRepAlgo_DSAccess* have been removed as obsolete. Please use the BRepAlgoAPI_* classes to perform Boolean operations.
1596* *BRepAlgo_DataMapOfShapeBoolean* has been removed as unused.
1597* *BRepAlgo_DataMapOfShapeInterference* has been removed as unused.
1598* *BRepAlgo_EdgeConnector* has been removed as unused.
1599* *BRepAlgo_SequenceOfSequenceOfInteger* has been removed as unused.
948fe6ca 1600
68dcee02 1601@subsection upgrade_740_localcontext Local Context removal
1603Previously deprecated Local Context functionality has been removed from AIS package,
1604so that related methods have been removed from AIS_InteractiveContext interface:
73b07edd 1605*HasOpenedContext()*, *HighestIndex()*, *LocalContext()*, *LocalSelector()*, *OpenLocalContext()*, *CloseLocalContext()*,
1606*IndexOfCurrentLocal()*, *CloseAllContexts()*, *ResetOriginalState()*, *ClearLocalContext()*, *UseDisplayedObjects()*, *NotUseDisplayedObjects()*,
1607*SetShapeDecomposition()*, *SetTemporaryAttributes()*, *ActivateStandardMode()*, *DeactivateStandardMode()*, *KeepTemporary()*,
1608*SubIntensityOn()*, *SubIntensityOff()*, *ActivatedStandardModes()*, *IsInLocal()*, *AddOrRemoveSelected()* taking TopoDS_Shape.
68dcee02 1609
1610A set of deprecated methods previously related to Local Context and now redirecting to other methods has been preserved to simplify porting; they will be removed in next release.
7c5f7e3e 1612@subsection upgrade_740_geomconvert Changes in behavior of Convert algorithms
4a361058 1613
17017555 1614Now methods *GeomConvert::ConcatG1*, *GeomConvert::ConcatC1*, *Geom2dConvert::ConcatG1*, *Geom2dConvert::ConcatC1* modify the input argument representing the flag of closedness.
7c5f7e3e 1615
1616@subsection upgrade_740_selection Changes in selection API and picked point calculation algorithm.
17017555 1617
46478ffe 1618*SelectBasics_PickResult* structure has been extended, so that it now defines a 3D point on the detected entity in addition to Depth value along picking ray.
17017555 1619*SelectMgr_SelectingVolumeManager::Overlap()* methods have been corrected to fill in *SelectBasics_PickResult* structure (depth and 3D point) instead of only depth value, so that custom *Select3D_SensitiveEntity* implementation should be updated accordingly (including *Select3D_SensitiveSet* subclasses).
b34d86cb 1620
1621@subsection upgrade_740_ocafpersistence Document format version management improvement.
46478ffe 1623Previously Document format version restored by *DocumentRetrievalDriver* was propagated using static methods of the corresponding units (like *MDataStd* or *MNaming*) to static variables of these units and after that became accessible to Drivers of these units.
1624Now Document format version is available to drivers via *RelocationTable*. The Relocation table now keeps *HeaderData* of the document and a format version can be extracted in the following way: *theRelocTable.GetHeaderData()->StorageVersion()*.
1625Obsolete methods: *static void SetDocumentVersion (const Standard_Integer DocVersion)* and *static Standard_Integer DocumentVersion()* have been removed from *BinMDataStd*, *BinMNaming*, *XmlMDataStd* and *XmlMNaming*.
7bd071ed 1626
1627@subsection upgrade_740_changed_api_of_brepmesh BRepMesh - revision of the data model
1629The entire structure of *BRepMesh* component has been revised and separated into several logically connected classes.
1631In new version, deflection is controlled more accurately, this may be necessary to tune parameters of call of the BRepMesh algorithm on the application side to obtain the same quality of presentation and/or performance as before.
1633*BRepMesh_FastDiscret* and *BRepMesh_FastDiscretFace* classes have been removed.
1635The following changes have been introduced in the API of *BRepMesh_IncrementalMesh*, component entry point:
1636* Due to revised logic, *adaptiveMin* parameter of the constructor has been removed as meaningless;
1637* *BRepMesh_FastDiscret::Parameters* has been moved to a separate structure called *IMeshTools_Parameters*; the signatures of related methods have been changed correspondingly.
1639* Interface of *BRepMesh_Delaun* class has been changed.
1641Example of usage:
1642Case 1 (explicit parameters):
1644#include <IMeshData_Status.hxx>
1645#include <IMeshTools_Parameters.hxx>
1646#include <BRepMesh_IncrementalMesh.hxx>
1648Standard_Boolean meshing_explicit_parameters()
1650 BRepMesh_IncrementalMesh aMesher (aShape, 0.1, Standard_False, 0.5, Standard_True);
1651 const Standard_Integer aStatus = aMesher.GetStatusFlags();
1652 return !aStatus;
1655Standard_Boolean meshing_new()
1657 IMeshTools_Parameters aMeshParams;
1658 aMeshParams.Deflection = 0.1;
1659 aMeshParams.Angle = 0.5;
1660 aMeshParams.Relative = Standard_False;
1661 aMeshParams.InParallel = Standard_True;
1662 aMeshParams.MinSize = Precision::Confusion();
1663 aMeshParams.InternalVerticesMode = Standard_True;
1664 aMeshParams.ControlSurfaceDeflection = Standard_True;
1666 BRepMesh_IncrementalMesh aMesher (aShape, aMeshParams);
1667 const Standard_Integer aStatus = aMesher.GetStatusFlags();
1668 return !aStatus;
1d54b807 1671
1672@subsection upgrade_740_chamfer Changes in API of Chamfer algorithms
1674Some public methods of the class BRepFilletAPI_MakeChamfer are released from excess arguments:
1675- method Add for symmetric chamfer now takes only 2 arguments: distance and edge;
1676- method GetDistAngle now takes only 3 arguments: index of contour, distance and angle.
2a332745 1677
bf5f0ca2 1678@subsection upgrade_740_aspects Aspects unification
1680Fill Area, Line and Marker aspects (classes *Graphic3d_AspectFillArea3d*, *Graphic3d_AspectLine3d*, *Graphic3d_AspectMarker3d* and *Graphic3d_AspectText3d*)
1681have been merged into new class *Graphic3d_Aspects* providing a single state for rendering primitives of any type.
1682The old per-primitive type aspect classes have been preserved as sub-classes of *Graphic3d_Aspects* with default values close to the previous behavior.
1683All aspects except Graphic3d_AspectFillArea3d define Graphic3d_TOSM_UNLIT shading model.
1685The previous approach with dedicated aspects per primitive type was handy in simplified case, but lead to confusion otherwise.
1686In fact, drawing points or lines with lighting applied is a valid use case, but only *Graphic3d_AspectFillArea3d* previously defined necessary material properties.
1688As aspects for different primitive types have been merged, Graphic3d_Group does no more provide per-type aspect properties.
1689Existing code relying on old behavior and putting interleaved per-type aspects into single Graphic3d_Group should be updated.
1690For example, the following pseudo-code will not work anymore, because all *SetGroupPrimitivesAspect* calls will setup the same property:
1692Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
1693aGroup->SetGroupPrimitivesAspect (myDrawer->ShadingAspect()->Aspect());
1694aGroup->SetGroupPrimitivesAspect (myDrawer->LineAspect()->Aspect()); //!< overrides previous aspect
1696Handle(Graphic3d_ArrayOfSegments) aLines = new Graphic3d_ArrayOfSegments (2);
1697Handle(Graphic3d_ArrayOfTriangles) aTris = new Graphic3d_ArrayOfTriangles (3);
1698aGroup->AddPrimitiveArray (aLines); //!< both arrays will use the same aspect
1699aGroup->AddPrimitiveArray (aTris);
1702To solve the problem, the code should be modified to either put primitives into dedicated groups (preferred approach), or using *SetPrimitivesAspect* in proper order:
1704Handle(Graphic3d_Group) aGroup = thePrs->NewGroup();
1706aGroup->SetGroupPrimitivesAspect (myDrawer->ShadingAspect()->Aspect());
1707Handle(Graphic3d_ArrayOfTriangles) aTris = new Graphic3d_ArrayOfTriangles (3);
1708aGroup->AddPrimitiveArray (aTris);
1710Handle(Graphic3d_ArrayOfSegments) aLines = new Graphic3d_ArrayOfSegments (2);
1711aGroup->SetPrimitivesAspect (myDrawer->LineAspect()->Aspect()); //!< next array will use the new aspect
1712aGroup->AddPrimitiveArray (aLines);
61168418 1715@subsection upgrade_740_materials Material definition
1717Decomposition of Ambient, Diffuse, Specular and Emissive properties has been eliminated within *Graphic3d_MaterialAspect* definition.
1718As result, the following methods of *Graphic3d_MaterialAspect* class have been removed: SetReflectionMode(), SetReflectionModeOn(), Ambient(), Diffuse(), Emissive(), Specular(), SetAmbient(), SetDiffuse(), SetSpecular(), SetEmissive().
1720Previously, computation of final value required the following code:
1722Graphic3d_MaterialAspect theMaterial; Quantity_Color theInteriorColor;
1723Graphic3d_Vec3 anAmbient (0.0f);
1724if (theMaterial.ReflectionMode (Graphic3d_TOR_AMBIENT))
1726 anAmbient = theMaterial.MaterialType (Graphic3d_MATERIAL_ASPECT)
1727 ? (Graphic3d_Vec3 )theInteriorColor * theMaterial.Ambient()
1728 : (Graphic3d_Vec3 )theMaterial.AmbientColor() * theMaterial.Ambient();
1732New code looks like this:
1734Graphic3d_MaterialAspect theMaterial; Quantity_Color theInteriorColor;
1735Graphic3d_Vec3 anAmbient = theMaterial.AmbientColor();
1736if (theMaterial.MaterialType (Graphic3d_MATERIAL_ASPECT)) { anAmbient *= (Graphic3d_Vec3 )theInteriorColor; }
1739Existing code should be updated to:
1740- Replace Graphic3d_MaterialAspect::SetReflectionModeOff() with setting black color; SetReflectionModeOn() calls can be simply removed.
1741 R.g. theMaterial.SetAmbientColor(Quantity_NOC_BLACK).
1742- Replace Graphic3d_MaterialAspect::Ambient(), SetAmbient(), Diffuse(), SetDiffuse(), Specular(), SetSpecular(), Emissive(), SetEmissive() with methods working with pre-multiplied color.
1743 E.g. theMaterial.SetAmbientColor(Graphic3d_Vec3 (1.0f, 0.0f, 0.0f) * 0.2f).
1744- Avoid using Graphic3d_MaterialAspect::Color() and SetColor() with non-physical materials (Graphic3d_MATERIAL_ASPECT).
1745 These materials do not include color definition, because it is taken from Graphic3d_Aspects::InteriorColor() - this has not been changed.
1746 However, previously it was possible storing the color with SetColor() call and then fetching it with Color() by application code (the rendering ignored this value);
1747 now SetColor() explicitly ignores call for Graphic3d_MATERIAL_ASPECT materials and Color() returns DiffuseColor() multiplication coefficients.
8ed07085 1749@subsection upgrade_740_text Changes in Graphic3d_Text and OpenGl_Text API
1751Parameters of *Text* in *Graphic3d_Group* are moved into a new *Graphic3d_Text* class. *AddText* of *Graphic3d_Group* should be used instead of the previous *Text*.
1753The previous code:
1755Standard_Real x, y, z;
1757theGroup->Text (theText,
1758 Graphic3d_Vertex(x,y,z),
1759 theAspect->Height(),
1760 theAspect->Angle(),
1761 theAspect->Orientation(),
1762 theAspect->HorizontalJustification(),
1763 theAspect->VerticalJustification());
1765should be replaced by the new code:
1767Handle(Graphic3d_Text) aText = new Graphic3d_Text (theAspect->Height());
1768aText->SetText (theText.ToExtString());
1769aText->SetPosition (theAttachmentPoint);
1770aText->SetHorizontalAlignment (theAspect->HorizontalJustification());
1771aText->SetVerticalAlignment (theAspect->VerticalJustification());
1772theGroup->AddText (aText);
1775*OpenGl_Text* contains *Graphic3d_Text* field.
1777*OpenGl_TextParam* struct is removed. Constructor and *Init* of *OpenGl_Text* with *OpenGl_TextParam* are also removed.
1778Instead of using them, change *OpenGl_Text*.
1780Please, note, that after modifying *OpenGl_Text*, *Reset* of *OpenGl_Text* should be called.
1782*FormatParams* of *OpenGl_Text* is replaced by *Text*.
226fce20 1784@subsection upgrade_740_prsupdate Presentation invalidation
1786Historically AIS_InteractiveObject provided two independent mechanisms invalidating presentation (asking presentation manager to recompute specific display mode or all modes):
17881. *AIS_InteractiveObject::SetToUpdate()*, marking existing presentation for update.
1789 This is main invalidation API, which is expected to be followed by *AIS_InteractiveContext::Update()* call.
17902. *AIS_InteractiveObject::myToRecomputeModes* + *myRecomputeEveryPrs*.
1791 This is auxiliary invalidation API, used internally by AIS_InteractiveContext::SetColor()/UnsetColor() and similar modification methods.
1793The latter one has been removed to avoid confusion and unexpected behavior.
1794In addition, two methods *AIS_InteractiveObject::Update()* have been deprecated in favor of new *AIS_InteractiveObject::UpdatePresentations()* recomputing only invalidated presentations.
1796Custom presentations implementing interface methods *AIS_InteractiveObject::SetColor()* and others should be revised to use *AIS_InteractiveObject::SetToUpdate()*
1797or updating presentation without recomputation (see *AIS_InteractiveObject::SynchronizeAspects()* and *AIS_InteractiveObject::replaceAspects()*).
2a332745 1799@subsection upgrade_740_interiorstyles Interior styles
1801* *Aspect_IS_HOLLOW* is now an alias to *Aspect_IS_EMPTY* and does not implicitly enables drawing mesh edges anymore.
1802 Specify Graphic3d_AspectFillArea3d::SetDrawEdges(true) with Graphic3d_AspectFillArea3d::SetInteriorStyle(Aspect_IS_EMPTY) to get previous behavior of Aspect_IS_HOLLOW style.
1803* *Aspect_IS_HIDDENLINE* does not implicitly enables drawing mesh edges anymore.
1804 Specify Graphic3d_AspectFillArea3d::SetDrawEdges(true) with Graphic3d_AspectFillArea3d::SetInteriorStyle(Aspect_IS_HIDDENLINE) to get previous behavior of Aspect_IS_HIDDENLINE style.
d9166000 1805
0ef04197 1806@subsection upgrade_740_modedprs PrsMgr and SelectMgr hierarchy clean up
7dd7c146 1807
1808Proxy classes *Prs3d_Presentation*, *PrsMgr_ModedPresentation* and *PrsMgr_Prs* have been removed.
1809Code iterating through the list of low-level structures AIS_InteractiveObject::Presentations() should be updated to access PrsMgr_Presentation directly.
1810Forward declarations of *Prs3d_Presentation* should be corrected, since it is now a typedef to *Graphic3d_Structure*.
0ef04197 1812Proxy classes *SelectBasics_SensitiveEntity* and *SelectBasics_EntityOwner* have been removed - *Select3D_SensitiveEntity* and *SelectMgr_EntityOwner* should be now used directly instead.
8aafd5f9 1814@subsection upgrade_740_offset Polygon offset defaults
1816*Graphic3d_PolygonOffset* default constructor has been corrected to define Units=1 instead of Units=0.
1817Default polygon offset settings Mode=Aspect_POM_Fill + Factor=1 + Units=1 are intended to push triangulation
1818(Shaded presentation) a little bit behind of lines (Wireframe and Face Edges)
1819for reducing z-fighting effect of Shaded+Wireframe combination.
1820The change in defaults (Units changed from 0 to 1) is intended to cover scenario when camera direction is perpendicular to model plane (like 2D view).
1822Application observing unexpected visual difference on this change should consider customizing this property within AIS_InteractiveContext default attributes
1823or on per-presentation basis via *Graphic3d_Aspects::SetPolygonOffset()* methods.
1825@subsection upgrade_740_zlayer Adding ZLayers in given position
1827Interface of insertion ZLayer in the viewer has been improved with ability to insert new layer before or after existing one.
1828Previously undocumented behavior of *V3d_Viewer::AddZlayer()* method has been corrected to insert new layer before *Graphic3d_ZLayerId_Top*.
1829Applications might need revising their custom layers creation code and specify precisely their order with new methods *V3d_Viewer::InsertLayerBefore()* and *V3d_Viewer::InsertLayerAfter()*.
1831@subsection upgrade_740_enum_changed Modified enumerations
1833Applications using integer values of the following enumerations in persistence
1834should be corrected as these enumerations have been modified:
1836| Name |
1837| :----- |
1838| AIS_TypeOfAttribute |
1839| Aspect_InteriorStyle |
1840| Font_FontAspect |
d9166000 1842@subsection upgrade_740_geproj Custom defines within env.bat
1844*env.bat* produced by Visual Studio project generator *genproj.bat* has been modified so that *%CSF_DEFINES%* variable is reset to initial state.
1845Custom building environment relying on old behavior and setting extra macros within *%CSF_DEFINES%* before env.bat should be updated
1846to either modify custom.bat or setup new variable *%CSF_DEFINES_EXTRA%* instead.
9324aa2d 1847
1848@subsection upgrade_740_BVH_in_BOP Switching Boolean Operations algorithm to use BVH tree instead of UB tree
1850Since OCCT 7.4.0 Boolean Operations algorithm uses BVH tree instead of UBTree to find the pairs of entities with interfering bounding boxes.
1851The following API changes have been made:
1852* BOPTools_BoxBndTree and BOPTools_BoxBndTreeSelector have been removed. Use the BOPTools_BoxTree and BOPTools_BoxTreeSelector instead.
1853* BOPTools_BoxSelector::SetBox() method now accepts the BVH_Box instead of Bnd_Box.
1854* Methods BOPTools_BoxSelector::Reject and BOPTools_BoxSelector::Accept have been removed as unused.
1855* The RunParallel flag has been removed from the list of parameters of BOPAlgo_Tools::IntersectVertices method. Earlier, it performed selection from the UB tree in parallel mode. Now all interfering pairs are found in one pass, using pair traverse of the same BVH tree.
7fab82af 1857@subsection upgrade_740_stdnamespace Standard_Stream.hxx no more has "using std::" statements
1858*Standard_Stream.hxx* header, commonly included by other OCCT header files, does no more add entities from *std namespace* related to streams (like *std::cout*, *std::istream* and others) into global namespace.
1859The application code relying on this matter should be updated to either specify std namespace explicitly (like std::cout) or add "using std::" statements locally.