Added some content from the bugtracker to porting notes.
Reviewed some other recent changes.
@section build_cmake_intro General
-This article describes the **CMake**-based build process which is now suggested as a standard way to produce the binaries of Open CASCADE Technology from sources. *OCCT requires CMake version 2.8.12 or later*.
+This article describes the **CMake**-based build process, which is now suggested as a standard way to produce the binaries of Open CASCADE Technology from sources. *OCCT requires CMake version 2.8.12 or later*.
-@note Comparing to the previous (6.x) releases of Open CASCADE Technology, OCCT 7.0 comes with a complete set of CMake scripts and projects, so that there is no need to use WOK anymore. Moreover, CMake gives you a powerful configuration tool which allows to control many aspects of OCCT deployment. At the same time this tool is quite intuitive which is a significant advantage over the legacy WOK utilities.
+@note Compared to the previous (6.x) releases of Open CASCADE Technology, OCCT 7.x has a complete set of CMake scripts and projects, so that there is no need to use WOK anymore. Moreover, CMake gives you a powerful configuration tool, which allows to control many aspects of OCCT deployment. At the same time this tool is quite intuitive, which is a significant advantage over the legacy WOK utilities.
-Here we describe the build procedure on example of Windows platform with Visual Studio 2010.
+Here we describe the build procedure on the example of Windows platform with Visual Studio 2010.
However, CMake is cross-platform and can be used to build OCCT on Linux and OS X in essentially the same way.
-@note Before you start, make sure to have installed all the 3-rd party products that you are going to use with OCCT; see @ref occt_dev_guides__building.
+@note Before you start, make sure to have installed all 3-rd party products that you are going to use with OCCT; see @ref occt_dev_guides__building.
@section build_cmake_start Start CMake
CMake is a tool that generates the actual project files for the selected target build system (e.g. Unix makefiles) or IDE (e.g. Visual Studio 2010).
-For unexpericnced users we recommend to start with *cmake-gui* -- cross-platform GUI tool provided by CMake on Windows, Mac and Linux.
-A command-line alternative, *ccmake* also can be used.
+For unexperienced users we recommend to start with *cmake-gui* -- a cross-platform GUI tool provided by CMake on Windows, Mac and Linux.
+A command-line alternative, *ccmake* can also be used.
-CMake deals with three directories: source, build or binary and install.
+CMake deals with three directories: source, build or binary and installation.
-* The source directory is where the sources of OCCT are located in your filesystem
-* The build or binary directory is where all the files created during CMake configuration and generation process will be located. The mentioned process will be described below.
+* The source directory is where the sources of OCCT are located in your file system;
+* The build or binary directory is where all files created during CMake configuration and generation process will be located. The mentioned process will be described below.
* The installation directory is where binaries will be installed after building the *INSTALL* project that is created by CMake generation process, along with header files and resources required for OCCT use in applications.
The good practice is not to use the source directory as a build one.
Press *c* to configure.
-All required actions in the configuration process will be described with using the GUI tool below.
+All actions required in the configuration process with the GUI tool will be described below.
-If the gui-tool is used, run the tool without additional arguments and after that specify the source directory by clicking **Browse Source** and the build (binary) one by clicking **Browse Build**.
+If the GUI tool is used, run this tool without additional arguments and after that specify the source directory by clicking **Browse Source** and the build (binary) one by clicking **Browse Build**.
@figure{/dev_guides/building/cmake/images/cmake_image001.png}
@figure{/dev_guides/building/cmake/images/cmake_image002.png}
-To build OCCT with using Universal Windows Platform (UWP) specify path to toolchain file for cross-compiling <i>d:/occt/adm/templates/uwp.toolchain.config.cmake</i>.
+To build OCCT for Universal Windows Platform (UWP) specify the path to toolchain file for cross-compiling <i>d:/occt/adm/templates/uwp.toolchain.config.cmake</i>.
-**Note**: Universal Windows Platform (UWP) is supported only on "Visual Studio 14 2015". File <i>d:/occt/samples/xaml/ReadMe.md</i> desribes building procedure of XAML (UWP) sample.
+**Note**: Universal Windows Platform (UWP) is supported only on "Visual Studio 14 2015". File <i>d:/occt/samples/xaml/ReadMe.md</i> describes the building procedure of XAML (UWP) sample.
-Once "Finish" button is pressed, the first pass of the configuration process is executed. At the end of the process, CMake outputs the list of environment variables which have to be properly specified for successful configuration.
+Once "Finish" button is pressed, the first pass of the configuration process is executed. At the end of the process, CMake outputs the list of environment variables, which have to be properly specified for successful configuration.
@figure{/dev_guides/building/cmake/images/cmake_image003.png}
-The error message provides an information about these variables. This message will appear after each pass of the process until all required variables are specified correctly.
+The error message provides some information about these variables. This message will appear after each pass of the process until all required variables are specified correctly.
-The change of the state of some variables can lead to the appearance of new variables. The new variables appeared after the pass of the configuration process is notified with red color by CMake GUI tool.
+The change of the state of some variables can lead to the appearance of new variables. The new variables appeared after the pass of the configuration process are highlighted with red color by CMake GUI tool.
-Note: There is "grouped" option which groups variables with a common prefix.
+Note: There is "grouped" option, which groups variables with a common prefix.
-The following table enumerates the full list of environment variables used at configuration stage:
+The following table gives the full list of environment variables used at the configuration stage:
| Variable | Type | Purpose |
|----------|------|---------|
-| CMAKE_BUILD_TYPE | String | Specifies the build type on single-configuration generators (sush as make). Possible values are Debug, Release and RelWithDebInfo |
-| USE_FREEIMAGE | Boolean flag | Indicates whether Freeimage product should be used in OCCT visualization module for support of popular graphics image formats (PNG, BMP etc) |
-| USE_GL2PS | Boolean flag | Indicates whether GL2PS product should be used in OCCT visualization module for support of vector image formats (PS, EPS etc) |
+| CMAKE_BUILD_TYPE | String | Specifies the build type on single-configuration generators (such as make). Possible values are Debug, Release and RelWithDebInfo |
+| USE_FREEIMAGE | Boolean flag | Indicates whether FreeImage product should be used in OCCT visualization module for support of popular graphics image formats (PNG, BMP, etc.) |
+| USE_GL2PS | Boolean flag | Indicates whether GL2PS product should be used in OCCT visualization module for support of vector image formats (PS, EPS, etc.) |
| USE_TBB | Boolean flag | Indicates whether TBB 3rd party is used or not. TBB stands for Threading Building Blocks, the technology of Intel Corp, which comes with different mechanisms and patterns for injecting parallelism into your application. OCCT remains parallel even without TBB product |
-| USE_VTK | Boolean flag | Indicates whether VTK 3rd party is used or not. VTK stands for Visualization ToolKit, the technology of Kitware Inc intended for general-purpose scientific visualization. OCCT comes with a bridge between CAD data representation and VTK by means of its dedicated VIS component (VTK Integration Services). You may skip this 3rd party unless you are planning to use VTK visualization for OCCT geometry. The official documentation @ref occt_user_guides__vis for the details on VIS |
+| USE_VTK | Boolean flag | Indicates whether VTK 3rd party is used or not. VTK stands for Visualization ToolKit, the technology of Kitware Inc intended for general-purpose scientific visualization. OCCT comes with a bridge between CAD data representation and VTK by means of its dedicated VIS component (VTK Integration Services). You may skip this 3rd party unless you are planning to use VTK visualization for OCCT geometry. See the official documentation @ref occt_user_guides__vis for the details on VIS |
| 3RDPARTY_DIR | Path | Defines the root directory where all required 3rd party products will be searched. Once you define this path it is very convenient to click "Configure" button in order to let CMake automatically detect all necessary products|
| 3RDPARTY_FREETYPE_* | Path | Path to Freetype binaries |
| 3RDPARTY_TCL_* 3RDPARTY_TK_* | Path | Path to Tcl/Tk binaries |
| 3RDPARTY_TBB* | Path | Path to TBB binaries |
| 3RDPARTY_VTK_* | Path | Path to VTK binaries |
| BUILD_MODULE_<MODULE>| Boolean flag | Indicates whether the corresponding OCCT module should be built or not. It should be noted that some toolkits of a module can be built even if this module is not checked (this happens if some other modules depend on these toolkits). The main modules and their descriptions can be found in @ref user_guides |
-| BUILD_LIBRARY_TYPE | String | Specifies the type of library to be created. "Shared" libraries are linked dynamically and loaded at runtime. "Static" libraries are archives of object files for use when linking other targets |
+| BUILD_LIBRARY_TYPE | String | Specifies the type of library to be created. "Shared" libraries are linked dynamically and loaded at runtime. "Static" libraries are archives of object files used when linking other targets |
| BUILD_ADDITIONAL_TOOLKITS | String | Semicolon-separated individual toolkits to include into build process. If you want to build some particular libraries (toolkits) only, then you may uncheck all modules in the corresponding *BUILD_MODUE_\<MODULE\>* options and provide the list of necessary libraries here. Of course, all dependencies will be resolved automatically |
-| BUILD_YACCLEX | Boolean flag | Enables Flex/Bison lexical analyzers. OCCT source files relating to STEP reader and ExprIntrp functionality are generated automatically with Flex/Bison. Checking this options leads to automatic search of Flex/Bison binaries and regeneration of the mentioned files |
+| BUILD_YACCLEX | Boolean flag | Enables Flex/Bison lexical analyzers. OCCT source files relating to STEP reader and ExprIntrp functionality are generated automatically with Flex/Bison. Checking this option leads to automatic search of Flex/Bison binaries and regeneration of the mentioned files |
| BUILD_MODULE_MfcSamples | Boolean flag | Indicates whether MFC samples should be built together with OCCT. This option is only relevant to Windows platforms |
-| BUILD_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation project should be created together with OCCT. It is not built together with OCCT. Checking this options leads to automatic search of Doxygen binaries. Building of it will be call Doxygen command to generate the documentation in HTML format |
+| BUILD_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation project should be created together with OCCT. It is not built together with OCCT. Checking this option leads to automatic search of Doxygen binaries. Its building calls Doxygen command to generate the documentation in HTML format |
| BUILD_PATCH | Path | Points to the directory recognized as a "patch" for OCCT. If specified, the files from this directory take precedence over the corresponding native OCCT sources. This way you are able to introduce patches to Open CASCADE Technology not affecting the original source distribution |
-| BUILD_WITH_DEBUG | Boolean flag | Enables extended messages of many OCCT algorithms, usually printed to cout. These include messages on internal errors and special cases encountered, timing etc |
+| BUILD_WITH_DEBUG | Boolean flag | Enables extended messages of many OCCT algorithms, usually printed to cout. These include messages on internal errors and special cases encountered, timing, etc. |
| CMAKE_CONFIGURATION_TYPES | String | Semicolon-separated CMake configurations |
-| INSTALL_DIR | Path | Points to the installation directory. INSTALL_DIR is synonym of CMAKE_INSTALL_PREFIX . User can specify both INSTALL_DIR or CMAKE_INSTALL_PREFIX |
+| INSTALL_DIR | Path | Points to the installation directory. *INSTALL_DIR* is a synonym of *CMAKE_INSTALL_PREFIX*. The user can specify both *INSTALL_DIR* or *CMAKE_INSTALL_PREFIX* |
| INSTALL_DIR_BIN | Path | Relative path to the binaries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_BIN}) |
| INSTALL_DIR_SCRIPT | Path | Relative path to the scripts installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SCRIPT}) |
| INSTALL_DIR_LIB | Path | Relative path to the libraries installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_LIB}) |
| INSTALL_DIR_INCLUDE | Path | Relative path to the includes installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_INCLUDE}) |
| INSTALL_DIR_RESOURCE | Path | Relative path to the resources installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_RESOURCE}) |
-| INSTALL_DIR_LAYOUT | String | Defines structure of OCCT files (binaries, resources, headers, etc) for the install directory. Two variants are predefined: for Windows (standard OCCT layout) and for Unix operating systems (standard Linux layout). If needed, layout can be customized with INSTALL_DIR_* variables |
+| INSTALL_DIR_LAYOUT | String | Defines the structure of OCCT files (binaries, resources, headers, etc.) for the install directory. Two variants are predefined: for Windows (standard OCCT layout) and for Unix operating systems (standard Linux layout). If needed, the layout can be customized with INSTALL_DIR_* variables |
| INSTALL_DIR_DATA | Path | Relative path to the data files installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_DATA}) |
| INSTALL_DIR_SAMPLES | Path | Relative path to the samples installation directory. Note that only "samples/tcl" folder will be installed. (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_SAMPLES}) |
| INSTALL_DIR_TESTS | Path | Relative path to the tests installation directory (absolute path is ${INSTALL_DIR}/${INSTALL_DIR_TESTS}) |
| INSTALL_TEST_CASES | Boolean flag | Indicates whether non-regression OCCT test scripts should be installed into the installation directory |
| INSTALL_DOC_Overview | Boolean flag | Indicates whether OCCT overview documentation should be installed into the installation directory |
-**Note:** In those CMake options defining paths only the forward slashes ("/") are acceptable.
+**Note:** Only the forward slashes ("/") are acceptable in the CMake options defining paths.
@section build_cmake_3rdparty 3rd party search mechanism
The procedure expects to find binary and header files of each 3rd party product in its own sub-directory: *bin*, *lib* and *include*.
-The results of the search (achived on the next pass of the configuration process) are recorded in the corresponding variables:
+The results of the search (achieved on the next pass of the configuration process) are recorded in the corresponding variables:
* *3RDPARTY_\<PRODUCT\>_DIR* -- path to the 3rdparty directory (with directory name) (e.g. <i>D:/3rdparty/tcltk-86-32</i>)
* *3RDPARTY_\<PRODUCT\>_LIBRARY_DIR* -- path to the directory containing a library (e.g. <i>D:/3rdparty/tcltk-86-32/lib</i>).
Porting of user applications from an earlier OCCT version to version 6.5.2 requires taking into account the following major changes:
* 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.
* 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.
-* *BRepLib_MakeFace* has been modified to accept tolerance value for resolution of degenerated edges. This tolerance parameter has no default value to ensure that the client code takes care of passing a meaningful value, not just *Precision::Confusion*, so some porting overheads are expected.
+* *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.
* 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.
* 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.
* 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:
* Method *HashCode()* has been removed from class *Standard_Transient*. It is advisable to use global function <i>HashCode()</i> for Handle objects instead.
* Declaration of operators new/delete for classes has become consistent and is encapsulated in macros.
* Memory management has been changed to use standard heap <i>(MMGT_OPT=0)</i> and reentrant mode <i>(MMGT_REENTRANT=1)</i> by default.
-* Map classes in *NCollection* package now accept one more argument defining a hash tool.
+* Map classes in *NCollection* package now receive one more argument defining a hash tool.
@section upgrade_654 Upgrade to OCCT 6.5.4
#### Ambiguity of calls to overloaded functions
-This issue appears in the compilers that do not support default arguments in template functions (known cases are Visual C++ 10 and 11): the compiler reports an ambiguity error if a handle is used in the argument of a call to the function that has two or more overloaded versions, accepting handles to different types.
+This issue appears in the compilers that do not support default arguments in template functions (known cases are Visual C++ 10 and 11): the compiler reports an ambiguity error if a handle is used in the argument of a call to the function that has two or more overloaded versions, receiving handles to different types.
The problem is that operator <i> const handle<T2>& </i> is defined for any type *T2*, thus the compiler cannot make the right choice.
Example:
@subsection upgrade_710_aspects Presentation attributes
-This section should be considered if application defines custom presentations (inherited from AIS_InteractiveObject).
-Previous versions of OCCT have three levels for defining presentation properties (e.g. colors, materials):
+This section should be considered if application defines custom presentations, i.e. inherited from *AIS_InteractiveObject*.
+The previous versions of OCCT have three levels for defining presentation properties (e.g. colors, materials, etc.):
-1. For entire structure (Graphic3d_Structure / Prs3d_Presentation).
-2. For specific group of primitives (Graphic3d_Group::SetGroupPrimitivesAspect()) overriding structure aspects.
-3. For specific primitive array within graphic group (Graphic3d_Group::SetPrimitivesAspect()).
+1. For the entire structure - *Graphic3d_Structure* / *Prs3d_Presentation*.
+2. For a specific group of primitives - *Graphic3d_Group::SetGroupPrimitivesAspect()* overriding structure aspects.
+3. For a specific primitive array within the graphic group - *Graphic3d_Group::SetPrimitivesAspect()*.
-The first one is de facto not used for a long time since OCCT presentations always define aspects at graphic group level (overriding any structure aspects).
-Within this OCCT release, this first level of aspects has been completely removed. In most cases application code should just remove missing methods; in rare cases where this functionality was intentionally used - application should explicitly define aspects to appropriate graphic groups.
+The structure level has de facto not been used for a long time since OCCT presentations always define aspects at the graphic group level (overriding any structure aspects).
+Within this OCCT release, structure level of aspects has been completely removed. In most cases the application code should just remove missing methods. In those rare cases, when this functionality was intentionally used, the application should explicitly define aspects to the appropriate graphic groups.
-Note that the 3rd level (defining several different aspects within the same graphic group) is also should be avoided in application code since it is deprecated functionality which can be removed in further releases.
-Graphic3d_Group::SetGroupPrimitivesAspect() should be the main method defining presentation attributes.
+Note that defining several different aspects within the same graphic group should also be avoided in the application code since it is a deprecated functionality which can be removed in further releases.
+*Graphic3d_Group::SetGroupPrimitivesAspect()* should be the main method defining presentation attributes.
-The implementation of Graphic3d_Group::SetGroupPrimitivesAspect() has been changed from copying aspect values to keeping passed object.
-Although it was not documented, previosly it was possible to modify single aspects instance (like Graphic3d_AspectFillArea3d) and set it to multiple groups.
-Now such code would produce unexpected result and therefore should be updated to create dedicated aspect instance.
+The implementation of *Graphic3d_Group::SetGroupPrimitivesAspect()* has been changed from copying aspect values to keeping the passed object.
+Although it was not documented, previously it was possible to modify a single aspect instance, like *Graphic3d_AspectFillArea3d* and set it to multiple groups.
+Now such code would produce an unexpected result and therefore should be updated to create the dedicated aspect instance.
@subsection upgrade_710_types Typedefs
- *Standard_Utf16Char* is now *char16_t* (previously *uint16_t* for compatibility with old compilers).
- *Standard_Utf32Char* is now *char32_t* (previously *uint32_t* for compatibility with old compilers).
-For most applications this change should be transparent on the level of source code. Binary compatibility is not maintained, as *bool* has different size in comparison with *unsigned int*.
+For most applications this change should be transparent on the level of source code. Binary compatibility is not maintained, as *bool* has a different size in comparison with *unsigned int*.
@subsection upgrade_710_ffp Programmable Pipeline
Fixed-function pipeline has been already deprecated since OCCT 7.0.0.
Release 7.1.0 disables this functionality by default in favor of Programmable Pipeline (based on GLSL programs).
-This also means that method *V3d_View::Export()* based on gl2ps library and requiring disabled by default functionality has been deprecated as well.
-Applications should explicitly enable deprecated functionality by setting OpenGl_Caps::ffpEnable flag to TRUE within OpenGl_GraphicDriver::ChangeOptions() before creating the viewer to use V3d_View::Export(),
-but being aware that this functionality is likely to be removed in a next OCCT release.
-Thus the recommended way to generate vector image of a 3D model or scene is to use application-level solution independent from OpenGL.
+Method *V3d_View::Export()*, based on *gl2ps* library, requires fixed pipeline and will return error if used with default settings.
+Applications should explicitly enable fixed pipeline by setting *OpenGl_Caps::ffpEnable* flag to TRUE within *OpenGl_GraphicDriver::ChangeOptions()* before creating the viewer to use *V3d_View::Export()*.
+This method is declared as deprecated and will be removed in one of the the next OCCT releases.
+The recommended way to generate a vector image of a 3D model or scene is to use an application-level solution independent from OpenGL.
@subsection upgrade_710_trsfpers Transformation persistence
-The behavior of transformation persistence flags *Graphic3d_TMF_ZoomPers* and *Graphic3d_TMF_TriedronPers* have been changed to be consistent with textured fixed-size 2D text.
-Object with these flags is considered to be defined in pixel units, and presentation is no more scaled depending on view height.
-Applications that need to scale such objects depending on viewport size should update them manually.
+The behavior of transformation persistence flags *Graphic3d_TMF_ZoomPers* and *Graphic3d_TMF_TriedronPers* has been changed for consistency with a textured fixed-size 2D text.
+An object with these flags is considered as defined in pixel units, and the presentation is no more scaled depending on the view height.
+The applications that need to scale such objects depending on viewport size should update them manually.
-Flags *Graphic3d_TMF_PanPers* and *Graphic3d_TMF_FullPers* has been removed.
-*Graphic3d_TMF_TriedronPers* or *Graphic3d_TMF_2d* can be used instead depending on context.
+Flags *Graphic3d_TMF_PanPers* and *Graphic3d_TMF_FullPers* have been removed.
+*Graphic3d_TMF_TriedronPers* or *Graphic3d_TMF_2d* can be used instead depending on the context.
*Graphic3d_TransModeFlags* is not an integer bitmask anymore - enumeration values should be specified instead.
-Several transformation persistence methods in PrsMgr_PresentableObject have been marked deprecated.
-Transformation persistence should be defined using directly Graphic3d_TransformPers constructor and passed by a handle, not value.
+Several transformation persistence methods in *PrsMgr_PresentableObject* have been marked deprecated.
+Transformation persistence should be defined using *Graphic3d_TransformPers* constructor directly and passed by a handle, not value.
@subsection_upgrade_710_selprops Dynamic highlight and selection properties
-Release 7.1.0 introduces *Graphic3d_HighlightStyle* - an entity that allows flexible customization of highlighting parameters (such as method, highlight color and transparency). Therefore, API of methods related to highlighting in the following core classes:
-- *AIS_InteractiveContext* (methods HilightWithColor(), Hilight());
-- *PrsMgr_PresentationManager* (method Color());
-- *SelectMgr_EntityOwner* (method HilightWithColor())
-was changed to process Graphic3d_HighlightStyle instead of Quantity_Color.
+Release 7.1.0 introduces *Graphic3d_HighlightStyle* - an entity that allows flexible customization of highlighting parameters (such as highlighting method, color, and transparency). Therefore, the signatures of the following methods related to highlighting:
+- *AIS_InteractiveContext::Hilight()*;
+- *AIS_InteractiveContext::HilightWithColor()*;
+- *PrsMgr_PresentationManager::Color()*;
+- *SelectMgr_EntityOwner::HilightWithColor()*;
+have been changed to receive *Graphic3d_HighlightStyle* instead of *Quantity_Color*.
-Method AIS_InteractiveContext::Hilight is now deprecated and highlights interactive object with selection style.
+Method *AIS_InteractiveContext::Hilight* is now deprecated and highlights the interactive object with selection style.
-Group of methods AIS_InteractiveContext::IsHilighted changed behavior - now they only check object's or owner's highlight flags in global status. If highlight color is required on application level, overloaded methods AIS_InteractiveContext::HighlightStyle for owner and object must be used instead.
+A group of methods *AIS_InteractiveContext::IsHilighted* has changed its behavior - now they only check highlight flags of the object or the owner in the global status. If the highlight color is required on the application level, it is necessary to use overloaded methods *AIS_InteractiveContext::HighlightStyle* for the owner and the object.
-The following methods were replaced in AIS_InteractiveContext API:
-- *HilightColor*, *SetHilightColor* were replaced by *HighlightStyle*, *SetHighlightStyle*;
-- *SelectionColor* setter and getter were replaced by *SelectionStyle*, *SetSelectionStyle*.
+The following methods have been replaced in *AIS_InteractiveContext* class:
+- *HilightColor* and *SetHilightColor* by *HighlightStyle* and *SetHighlightStyle*;
+- *SelectionColor* setter and getter by *SelectionStyle* and *SetSelectionStyle*.
-API of Prs3d_Drawer was extended to allow setting up styles for both dynamic selection and highlighting. Therefore, on application level changing highlight style for particular object must be implemented via SelectMgr_SelectableObject::HilightAttributes() and processed in entity owner.
+The API of *Prs3d_Drawer* has been extended to allow setting up styles for both dynamic selection and highlighting. Therefore, it is possible to change the highlight style of a particular object on the application level via *SelectMgr_SelectableObject::HilightAttributes()* and process it in the entity owner.
+
+@subsection upgrade_occt710_correction_of_TObj_Model Correction in TObj_Model class
+
+Methods *TObj_Model::SaveAs* and *TObj_Model::Load* now receive *TCollection_ExtendedString* filename arguments instead of char*. UTF-16 encoding can be used to pass file names containing Unicode symbols.
+
+@subsection upgrade_710_env Redundant environment variables
+
+The following environment variables have become redundant:
+
+* *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.
+* *CSF_XSMessage* and *CSF_XHMessage* are now optional.
+ English messages (XSMessage/*XSTEP.us* and SHMessage/*SHAPE.us*) are now embedded into source code
+ and automatically loaded when environment variables are not set.
+* *CSF_ShadersDirectory* is not required any more, though it still can be used to load custom shaders.
+ Mandatory GLSL resources are now embedded into source code.
+* *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.
+
+Other environment variables still can be used to customize behavior of relevant algorithms but are not necessary any more (all required resources are embedded).
@subsection upgrade_710_removed Removed features
The following obsolete features have been removed:
-
-* Obsolete Antialiasing API *V3d_View::SetAntialiasingOn()*. This method was intended to activate deprecated OpenGL functionality (GL_POLYGON_SMOOTH, GL_LINE_SMOOTH, GL_POINT_SMOOTH).
- Instead of old API, application should request MSAA buffers for antialiasing by assigning *Graphic3d_RenderingParams::NbMsaaSamples* property of structure returned by *V3d_View::ChangeRenderingParams()*.
-* *Prs3d_Drawer::ShadingAspectGlobal()* flag has been removed as not used. Corresponding calls can be removed safely from the application code.
-* ZClipping planes and ZCueing (methods *V3d_View::SetZClippingType()*, *::SetZCueingOn()* and V3d_View::others).
- ZClipping planes can be replaced by general-purpose clipping planes (application should update plane definion manually).
-* 3D viewer printing API *V3d_View::Print()* has been removed. This functionality was available on Windows platforms only.
- Applications should use general image dump API *V3d_View::ToPixMap()* and manage printing using platform-specific API at application level.
+* 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*.
+ 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()*.
+* *Prs3d_Drawer::ShadingAspectGlobal()* flag has been removed as not used. The corresponding calls can be removed safely from the application code.
+* 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).
+* 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.
Text resolution can be managed by rendering parameter *Graphic3d_RenderingParams::Resolution*, returned by *V3d_View::ChangeRenderingParams()*.
-* Methods PrsMgr_PresentationManager::BoundBox, PrsMgr_PresentationManager::Hilight and SelectMgr_EntityOwner::Hilight were removed as not used.
- Corresponding method in custom implementations of SelectMgr_EntityOwner can be removed safely. PrsMgr_PresentationManager::Color with corresponding style must be used instead of removed presentation manager's methods.
-* 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. See also @ref upgrade_occt700_sorttools above.
-* The obsolete class *BOPCol_VectorOfInteger* has been removed.
-* Package *Dico* has been removed.
- 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.
+* 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.
+* 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.
+
+* 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.
@subsection upgrade_710_changed_methods Other changes
The following classes have been changed:
-* *BVH_Sorter*. This class has become abstract. The list of arguments of both methods *Perform* has been changed and the methods became pure virtual.
+* *BVH_Sorter* class has become abstract. The list of arguments of both *Perform* methods has been changed and the methods became pure virtual.
* *Extrema_FuncExtPS* has been renamed to *Extrema_FuncPSNorm*.
-* *Extrema_GenLocateExtPS*. Default constructor and constructor taking point and surface have been removed. Now the only constructor takes the surface and optional tolerances in U and V directions. The new method *Perform* takes the point with start solution and does the job. The class has become non-assignable nor copy-constructable.
-* *GCE2d_MakeParabola*, *gce_MakeParab2d*, *gp_Parab2d*. Constructors with arguments *(const gp_Ax22d& D, const gp_Pnt2d& F)* have been removed. Objects created with some constructors of *gp_Parab2d* class may differ from the previous version(see comments in *gp_Parab2d.hxx*). Result returned by gp_Parab2d::Directrix() method has opposite direction in comparison with previous OCCT versions.
-* *BRepTools_Modifier*. This 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*.
-* *ShapeAnalysis_Wire*. The second parameter *theIsOuterWire* of the method *CheckSmallArea* has been removed.
-* *GeomPlate_CurveConstraint*. Two constructors taking boundary curve of different type have been replaced with one constructor taking curve of abstract type.
-* *BRepOffset_MakeOffset*. The last optional argument *RemoveInvalidFaces* has been removed from the constructor and the method *Initialize*.
-* The public method BOPDS_DS::VerticesOnIn has been renamed to SubShapesOnIn, and the new output parameter theCommonPB has been added.
-
-@subsection upgrade_occt710_correction_of_TObj_Model Correction in TObj_Model class
-
-Methods *TObj_Model::SaveAs* and *TObj_Model::Load* receive *TCollection_ExtendedString* filename arguments instead of char*. UTF-16 encoding can be used to pass file names containing Unicode symbols.
-
-@subsection upgrade_710_env Removed environment variables
+* 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.
+* 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.
+* *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*.
+* The second parameter *theIsOuterWire* of method *ShapeAnalysis_Wire::CheckSmallArea* has been removed.
+* 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.
+* The last optional argument *RemoveInvalidFaces* has been removed from the constructor of class *BRepOffset_MakeOffset* and method *Initialize*.
+* The public method *BOPDS_DS::VerticesOnIn* has been renamed into *SubShapesOnIn* and the new output parameter *theCommonPB* has been added.
-The following environment variables now either become optional or have been removed:
-
-* *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.
-* *CSF_XSMessage* and *CSF_XHMessage* are now optional.
- English messages (XSMessage/*XSTEP.us* and SHMessage/*SHAPE.us*) are now embedded into source code
- and automatically loaded when environment variables are not set.
-* *CSF_ShadersDirectory* is not required any more, though it still can be used to load custom shaders.
- Mandatory GLSL resources are now embedded into source code.
-* *CSF_PluginDefaults* and other variables pointing to OCAF plugin resources (*CSF_StandardDefaults*, *CSF_XCAFDefaults*, *CSF_StandardLiteDefaults*, *CSF_XmlOcafResource*) are not necessary if method TDocStd_Application::DefineFormat() is used to enable persistence of OCAF documents.
a148e300-5740-11d1-a904-080036aaa103.Location: libFWOSPlugin.so
~~~~~
-Then the *Load* method loads the library according to the rules of the operating system of the host machine (for example, by using environment variables such as *LD_LIBRARY_PATH* with Unix and *PATH* with Windows). After that it invokes the *PLUGINFACTORY* method to return the object which supports the required service.
+Then the *Load* method loads the library according to the rules of the operating system of the host machine (for example, by using environment variables such as *LD_LIBRARY_PATH* with Unix and *PATH* with Windows). After that it invokes the *PLUGINFACTORY* method to return the object, which supports the required service.
The client may then call the functions supported by this object.
#### C++ Client Plug-In Implementation
PLUGIN(FAFactory)
~~~~~
-Application might also instantiate a factory by linking to the library and calling FAFactory::Factory() directly.
+Application might also instantiate a factory by linking to the library and calling *FAFactory::Factory()* directly.
@section occt_fcug_3 Collections, Strings, Quantities and Unit Conversion
### Extrema between Curves
The *Geom2dAPI_ExtremaCurveCurve* class allows calculation of all minimal distances between two 2D geometric curves.
-The *GeomAPI_ExtremaCurveCurve* class allows calculation of all minimal distances two 3D geometric curves.
+The *GeomAPI_ExtremaCurveCurve* class allows calculation of all minimal distances between two 3D geometric curves.
These classes use Euclidean distance as the criteria for optimization.
### Extrema between Curve and Surface
The *GeomAPI_ExtremaCurveSurface* class allows calculation of one extrema between a 3D curve and a surface. Extrema are the lengths of the segments orthogonal to the curve and the surface.
-This class use the "Projection" criteria for optimization.
+This class uses the "Projection" criteria for optimization.
### Extrema between Surfaces
The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of one minimal and one maximal distance between two surfaces.
-This class use Euclidean distance to compute minimum and "Projection" criteria to compute maximum.
+This class uses Euclidean distance to compute the minimum, and "Projection" criteria to compute the maximum.
@section occt_modat_2 2D Geometry
@subsection occt_modat_5_6 Storage of shapes
-**BRepTools** and **BinTools** packages contain methods *Read* and *Write* allowing to read and write a Shape to/from a stream or a file.
-The methods provided by **BRepTools** package use ASCII storage format; **BinTools** package use binary format.
+*BRepTools* and *BinTools* packages contain methods *Read* and *Write* allowing to read and write a Shape to/from a stream or a file.
+The methods provided by *BRepTools* package use ASCII storage format; *BinTools* package uses binary format.
Each of these methods has two arguments:
- a *TopoDS_Shape* object to be read/written;
- a stream object or a file name to read from/write to.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here "NewDocumentFormat" is identifier of the format of your document.
-OCCT defines several standard formats, distinguishing by a set of OCAF attributes supported, and method of encoding (e.g. binary data or XML), described below.
+OCCT defines several standard formats, distinguishing by a set of supported OCAF attributes, and method of encoding (e.g. binary data or XML), described below.
If your application defines specific OCAF attributes, you need to define your own format for it.
@subsubsection occt_ocaf_4_2_3 Retrieving the application to which the document belongs
@subsubsection occt_ocaf_4_3_format Defining storage format
-OCAF uses customizable mechanism for storage of the documents.
+OCAF uses a customizable mechanism for storage of the documents.
In order to use OCAF persistence to save and read your documents to / from the file, you need to define one or several formats in your application.
For that, use method TDocStd_Application::DefineFormat(), for instance:
new NewDocumentFormat_StorageDriver());
~~~~~
-Here format "NewDocumentFormat" is defined, with default file extension "ndf", and drivers for reading and storing documents from and to that format are instantiated.
-Either of the drivers can be null, in this case corresponding action will not be supported for that format.
+This example defines format "NewDocumentFormat" with a default file extension "ndf", and instantiates drivers for reading and storing documents from and to that format.
+Either of the drivers can be null, in this case the corresponding action will not be supported for that format.
OCAF provides several standard formats, each covering some set of OCAF attributes:
<tr><td>TObjXml </td><td> TKXmlTObj </td><td> TKLCAF + TKTObj </td></tr>
</table>
-For convenience, these toolkits provide static methods DefineFormat() accepting handle to application.
+For convenience, these toolkits provide static methods *DefineFormat()* accepting handle to application.
These methods allow defining corresponding formats easily, e.g.:
~~~~~
BinDrivers::DefineFormat (app); // define format "BinOcaf"
~~~~~
-Use these toolkits as example for implementation of persistence drivers for custom attributes, or new persistence formats.
+Use these toolkits as an example for implementation of persistence drivers for custom attributes, or new persistence formats.
The application can define several storage formats.
-On save, the format specified in the document (see TDocStd_Document::StorageFormat()) will be used (it will fail if that format is not defined in the application).
-On reading, format identifier stored in the file is used, and recorded in the document.
+On save, the format specified in the document (see *TDocStd_Document::StorageFormat()*) will be used (save will fail if that format is not defined in the application).
+On reading, the format identifier stored in the file is used and recorded in the document.
@subsubsection occt_ocaf_4_3_plugins Defining storage format by resource files
-Alternative (legacy, used in earlier versions of OCCT) method to define formats is via usage of resource files.
+The alternative method to define formats is via usage of resource files.
+This method was used in earlier versions of OCCT and is considered as deprecated since version 7.1.0.
This method allows loading persistence drivers on demand, using plugin mechanism.
-To use this method, create your own application class inheriting from *TDocStd_Application*, and override method ResourcesName().
-That method should return a string with a name of resource file, e.g. "NewDocumentFormat", which will contain description of the format.
+To use this method, create your own application class inheriting from *TDocStd_Application*, and override method *ResourcesName()*.
+That method should return a string with a name of resource file, e.g. "NewDocumentFormat", which will contain a description of the format.
-Then create that resource file and define parameters of your format:
+Then create that resource file and define the parameters of your format:
~~~~~
ndf.FileFormat: NewDocumentFormat
NewDocumentFormat.RetrievalPlugin: 76fb4c04-ea9a-46aa-88a2-25f6a228d902
~~~~~
-Here GUIDs should be unique and correspond to the GUIDs supported by relevant plugin.
-You can use either one of existing plugins (see the table above) or create your own.
+The GUIDs should be unique and correspond to the GUIDs supported by relevant plugin.
+You can use an existing plugins (see the table above) or create your own.
-Finally, make a copy of the resource file "Plugin" from $CASROOT/src/StdResource, and, if necessary, add definition of your plugin in it, for instance:
+Finally, make a copy of the resource file "Plugin" from *$CASROOT/src/StdResource* and, if necessary, add the definition of your plugin in it, for instance:
~~~~~
bb5aa176-c65c-4c84-862e-6b7c1fe16921.Location: TKNewFormat
@subsubsection occt_ocaf_4_3_3 Saving a document
-To save the document, make sure that its parameter StorageFormat() corresponds to one of formats defined in the application, and use method *TDocStd_Application::SaveAs*, for instance:
+To save the document, make sure that its parameter *StorageFormat()* corresponds to one of the formats defined in the application, and use method *TDocStd_Application::SaveAs*, for instance:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
app->SaveAs(doc, "/tmp/example.caf");
projects / occt.git / commitdiff