Open CASCADE Technology 7.0 preview

Dear All,

We have finalized development of several major new features for Open CASCADE Technology 7.0.
The most essential changes -- removal of CDL and WOK -- have been raised to master branch of the OCCT Git repository last Friday, and we propose this version for public review, as "alpha" version of OCCT 7.0.

This article is aimed to give overview of the major changes already integrated, and give idea of the effort required to port existing code on the new version.

Preface

As a reminder, CDL (Cas.Cade Declaration Language) and WOK (OCCT build environment) are legacy technologies used since the first days of Cas.Cade to organize its development. They provided features not-yet well supported by C++ compilers at that time (1990x), such as smart pointers (OCCT Handles), run-time type identification, and templates (CDL generics). The problem is that CDL and WOK require extra effort for their maintaining and restrict possibilities of OCCT developers; as well, the need to learn and use these tools impedes adoption of OCCT by new users and developers. The goal of the refactoring project started in 2013 is reimplementing features of OCCT, based on CDL and WOK, via use of modern technologies and tools - C++ templates metaprogramming for code generation, and CMake for build system. This development has been driven by ambitions to:

• Reduce amount of OCCT source code due to elimination of trivial code generated by WOK.
• Keep all useful documentation comments contained in CDL files, by translating them to Doxygen-style comments in C++ headers.
• Preserve high level of compatibility with previous versions, making no change in architecture, and minimal possible changes in interfaces and behavior.
• Facilitate upgrade of applications to OCCT 7.0 by automation of necessary changes, and providing detailed description of known possible issues and ways to resolve these.

This work took considerable time, and now we are happy to share the result with the community. The following paragraphs provide detailed description of the major changes already done and in progress (including those not related to CDL and WOK).

Elimination of CDL

Related issue: #24002. All classes previously defined using CDL language have been converted into pure C++ format (defined in C++ header files). This enables use of modern C++ features in whole OCCT code, and makes WOK unnecessary. As before, all sources are contained in src subfolder. Subfolder inc is populated by header files automatically during building and installation. Code previously generated in subfolder drv, as well as header files with names starting with "Handle_.." (containing definition of Handle classes), has been removed or merged into sources. This reduces number of source files in OCCT source archive by about 19.000, and saves ~22 MB of disk space:

Version	Number of files			Disk space, MB
	src	inc	drv	src	inc	drv
6.9.0	12 918	12 952	15 458	85.6	33.9	17.5
7.0.0	14 321	8 189	0	86.6	28.4	0

Use of CMake build system

Related issue: #25114. WOK is not necessary anymore for building OCCT from bare sources (though it still can be used in traditional way -- auxiliary files required for that are preserved). CMake is now considered as main build system for OCCT. As compared to CMake build scripts in OCCT 6.9.0, it introduces the following improvements (mostly useful for Windows developers):

• Does not require generation of CMake scripts by WOK: all CMake files are included with OCCT sources.
• Subfolder inc in build directory is populated not by copies of header files, by but short-cuts, redirecting to same-named header located in src. This allows having single inc directory without duplication of header files, thus reducing chance of losing modifications made to wrong copy of the header.
• When only part of OCCT is configured for building, only relevant includes will be installed.
• Header files are included in Visual Studio projects.
• Several build configurations can coexist in the same Visual Studio projects (Release, Debug, and others - as supported by CMake).
• Launch of DRAWEXE is possible directly from Visual Studio.
• Project for generation of overview documentation is added, making documentation sources easily accessible from Visual Studio IDE.

As a fallback solution for users not wishing to use CMake, we extracted generator of Visual Studio project files from WOK so it is available in OCCT code repository (genproj.bat), and are going to include traditionally organized project files in source deliveries of OCCT releases.

Conversion of TCollection classes

Related issue: #24750. Instantiations of generic classes from TCollection package have been converted into equivalent instances of NCollection templates. The names of the affected classes (such as TColgp_Array1OfPnt) are preserved, thus the code that used these classes should work as before. However, that code might need to be amended to take into account the following:

• Forward declarations of collection classes such as class TColgp_Array1OfIPnt; are not valid anymore; they should be replaced by inclusion of corresponding header (#include <TColgp_Array1OfPnt.hxx>).
• Equivalents of methods Find1() and ChangeFind1() in TCollection_DataMap have different names in NCollection_DataMap: Seek() and ChangeSeek(), respectively.
• Overloaded functions differing only by accepting equivalent TCollection and NCollection classes now become equal. Such code should be corrected to keep only one definition.

New type system

Related issue: #24947. OCCT legacy type system has been re-implemented using C++ templates. Macro STANDARD_TYPE() previously expanding to a call to a global function now expands to call to template method of the Standard_Type class. Use of templates eliminates necessity of explicit instantiation of type definition in C++ code, thus macros IMPLEMENT_DOWNCAST, IMPLEMENT_STANDARD_* are not necessary anymore. Note that these macros are still defined (as empty) for compatibility reasons. It is still necessary to include macro DEFINE_STANDARD_RTTI(Class,Base) in definition of the class to make it known to the OCCT type system. That macro defines method DynamicType(), returning its type descriptor, and auxiliary method get_type_name() returning bare name of the class. Note second argument to the macro, name of the base class, which was was not present in previous versions. Note that OCCT RTTI is not limited to classes inheriting Standard_Transient, and can be applied to any class; void should be used as second argument to DEFINE_STANDARD_RTTI macro if parent class is absent or does not provide OCCT RTTI. Example:

  struct ClassA
  {
    DEFINE_STANDARD_RTTI(ClassA, void)
  };

  struct ClassB : public ClassA
  {
    DEFINE_STANDARD_RTTI(ClassB, ClassA)
  }; 

  ClassA* aPtr = …;
  if (aPtr->DynamicType()->Parent() == STANDARD_TYPE(ClassA))
  {
    // object pointed by aPtr is first descendant of ClassA
  }

As before, OCCT RTTI does not support multiple inheritance. For iteration by class hierarchy now method Standard_Type::Parent() should be used; class Standard_AncestorIterator has been removed. This change leads to slight increase of memory allocated by OCCT at load time (by ~450 KB in total for all modules).

Template handles

Related issue: #24023. Handles are now implemented as template class opencascade::handle<>. Macro Handle() is still defined for compatibility, it expands to opencascade::handle<arg>. New implementation provides the following benefits:

• There is no need to use macro DEFINE_STANDARD_HANDLE to define a handle: it can be used without any additional declarations. Note however that macro DEFINE_STANDARD_HANDLE is still present and used in OCCT headers; it defines typedef to handle with the name corresponding to name of the class prefixed by "Handle_". This is done with hope to have better compatibility with existing code.
• There is no need to use OCCT type system for the class to use handle with it; you can use Handle() for any class inheriting Standard_Transient (method DownCast() is implemented using standard C++ RTTI).

In result, the code builds in less time, produces binaries of less size, and runs faster:

Version	Build time	Binaries size	All tests execution time (sequential)
master	30 min	67 MB	7 hours 7 min
new handles	28 min	62 MB	6 hours 59 min

The implementation of opencascade::handle<> is similar to boost::intrusive_ptr<>, with interface adapted to keep existing code using OCCT handles working. In particular, methods to cast Handle object to reference to Handle to base class are provided. This allows passing Handles to functions accepting such references without copying, as before. Current implementation requires that compiler provides support of some C++11 features. It is tested to work with:

• GCC 4.3 and above; compiler option -std=c++11 should be used (-std=c++0x in GCC 4.3-4.6).
• Visual C++ 10 (Visual Studio 2010) and above; lower versions of VC++ are not supported.
• CLang 3.4, compiler option -std=c++11 should be used.

New implementation of Handle has some implications affecting their usage in existing code. The following issues have been encountered during porting OCCT and other projects, and can be faced in porting other applications designed to work with previous versions of OCCT:

Forward declarations of Handle classes

Forward declarations of Handle classes as class are not valid anymore, and should be removed. In most cases, forward declaration of argument class is sufficient. Example:

class Handle(Geom_Curve); // compiler error: opencascade::handle<> is a template

class Geom_Curve; // sufficient for using Handle(Geom_Curve)

More #include statements may be required

Use of handle objects (construction, comparison using operators == or !=, use of method DownCast()) now requires that type of the object pointed by Handle is completely known at compile time. Thus it may be necessary to include header of the corresponding class to make the code compilable. For example, the following lines will fail to compile if Geom_Line.hxx is not included:

Handle(Geom_Line) aLine = 0;
if (aLine != aCurve) {...} 
if (aCurve->IsKind(STANDARD_TYPE(Geom_Line)) {...}
aLine = Handle(Geom_Line)::DownCast (aCurve);

Note that comparison of handles of incompatible types will now cause compile-time error:

Handle(Geom_Curve) aCurve;
Handle(Geom_Surface) aSurface;
if (aCurve == aSurf) {...} // compiler error

Misuse of Handle() macro

In OCCT versions before 7.0, Handle(C) macro was expanded to Handle_C. Sometimes this was used to generate names for typedefs, and now such code becomes not compilable, e.g.:

typedef NCollection_Handle Handle(Message_Msg);

Another case when macro Handle() is not properly used is when it's argument is not just a class name, but longer expression, for instance (note misplaced closing parenthesis):

aBSpline = Handle(Geom2d_BSplineCurve::DownCast(BS->Copy()));

This code will not compile anymore; it should be manually corrected.

Use of Handle in conditional expression

Edit 21.08.2015: this paragraph is not relevant anymore; operator of cast of Handle to bool is provided

Handle does not provide cast operator to pointer or to bool, thus cannot be used in conditional expressions. Method IsNull() should be used for checking Handle to be non-zero. Example:

Handle(Geom_Curve) aCurve = …;
if (aCurve) {...} // compiler error
if (! aCurve.IsNull()) {...} // ok

Ambiguity of calls to overloaded functions

This issue appears in compilers that do not support default arguments in template functions (known cases are MSVC++ 11 and below): compiler reports ambiguity error if handle is used in argument of call to function that has two or move overloaded versions, accepting handles to different types. The problem is that operator const handle<T2>& is defined for any type T2, thus compiler cannot make a right choice. Example:

void func (const Handle(Geom_Curve)&);
void func (const Handle(Geom_Surface)&);

Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
func (aCurve); // ambiguity error in VC++ 10

To resolve this ambiguity, change your code so that argument type correspond exactly to the function signature. In some cases this can be done by using relevant type for the corresponding variable, like in the example above:

Handle(Geom_Curve) aCurve = new Geom_TrimmedCurve (...);  

Other variants are assigning the argument to local variable of correct type, using direct cast or constructor:

const Handle(Geom_Curve)& aGCurve (aTrimmedCurve);
func (aGCurve); // OK - argument has exact type
func (static_cast(aCurve)); // OK - direct cast 
func (Handle(Geom_Curve)(aCurve)); // OK - temporary handle is constructed

Another possibility is defining additional templated variant of the overloaded function causing ambiguity, and use SFINAE to resolve the ambiguity. For example of this technique, see definition of the template variant of the method IGESData_IGESWriter::Send().

Lack of implicit cast to base type

Due to the fact that now cast of handle to reference to handle to the base type is user-defined operation, conversions that require this cast combined with other user-defined cast will not be resolved automatically by compiler. For example:

Handle(Geom_Curve) aC = GCE2d_MakeSegment(p1, p2); // compiler error

The problem here is that class GCE2d_MakeSegment has user-defined conversion to const Handle(Geom_TrimmedCurve)&, which is not the same as type of the local variable aC. To resolve this, use method Value():

Handle(Geom_Curve) aC = GCE2d_MakeSegment(p1, p2).Value(); // ok

or use variable of appropriate type:

Handle(Geom_TrimmedCurve) aC = GCE2d_MakeSegment(p1, p2); // ok

C-style casts of pointers and references to Handle objects

C-style cast of Handle object to reference or pointer to handle of derived type are not allowed anymore; cast to base type is possible but will cause compiler warnings in GCC ("use of type punned pointer breaks C strict aliasing rules"). Such casts should be replaced by calls to DownCast() method. Example:

Handle(Geom_Curve) aCurve = …;
const Handle(Geom_Line)& aLine = (Handle(Geom_Line)&)aCurve; // compiler error
const Handle(Geom_Line)& aLine = *((Handle(Geom_Line)*)&aCurve); // GCC warning

Handle(Geom_Line) aLine = Handle(Geom_Line)::DownCast (aCurve); // OK

References to temporary objects

In previous versions, compiler was able to detect situation when local variable of reference type to Handle is initialized by temporary object, and ensured that lifetime of that object is longer than that of the variable. Since OCCT 7.0, it will not work if types of the temporary object and variable are different (due to involvement of user-defined type cast), thus such temporary object will be destroyed immediately. Example:

// note that DownCast() returns new temporary object!
const Handle(Geom_BoundedCurve)& aBC =
Handle(Geom_TrimmedCurve)::DownCast(aCurve);
aBC->Transform (T); // access violation in OCCT 7.0

This kind of errors can be detected only at run-time.

Separation of BSpline cache

Related issue: #24682. Implementation of NURBS curves and surfaces has been revised: cache of polynomial coefficients, used to accelerate calculate values of B-spline, is separated from data objects (Geom2d_BSplineCurve, Geom_BSplineCurve, Geom_BSplineSurface), into dedicated classes (BSplCLib_Cache and BSplSLib_Cache). The benefits of this change are:

• Reduced memory footprint of OCCT shapes (up to 20% on some cases)
• Possibility to evaluate the same B-Spline concurrently in parallel threads without data races and mutex locks

The drawback is that direct evaluation of B-Splines using methods of curves and surfaces becomes slower, due to absence of cache. The way to avoid slow down is to use adaptor classes (Geom2dAdaptor_Curve, GeomAdaptor_Curve and GeomAdaptor_Surface): they now use cache when the curve or surface is a B-spline. OCCT algorithms are changed to use adaptors for B-spline calculations instead of direct methods of curves and surfaces. This process is not yet completely finalized, and some operations in current version of OCCT master branch are still slower than in OCCT 6.9.0 for this reason. This should be corrected before OCCT 7.0 release. The same changes (use of adaptors instead of direct call to curve and surface methods) should be implemented in relevant places in applications based on OCCT in order to get maximum performance.

Removal of obsolete functionality

Related issues: #24927, #25148. Some obsolete code will be removed in OCCT 7.0. As previously announced, already removed components are old persistence schemas and TKNIS visualization toolkit. Other candidates for removal are old Boolean operations (ones provided by TKBool toolkit).

Use direct link instead of plugin mechanism for OCAF persistence

Related issue: #25812. This change is not yet included in master branch, it should be completed in the coming month. The goal is to change current complicated mechanism of loading OCAF persistence toolkits as plugins, that requires setting of numerous environment variables, depends on resource files, and can be broken easily, by direct linking of the necessary library on application level.

Upgrade tools

Related issue: #24816. To facilitate porting existing code on OCCT 7.0, an automatic upgrade tool (Tcl script) is being developed. The detailed description of this script and recommendations on its usage to upgrade applications based on OCCT will be available soon, as part of the Upgrade Guide

Further steps

Current version of code is considered as ready for review and trial, and we will be happy to get feedback from the community regarding these changes. Further we are going to upgrade several existing applications of the new version, to verify the upgrade process and elaborate more detailed documentation. In September we are going to make a check point to consolidate obtained experience and community inputs, and define the next steps. We are looking forward for your feedback!