New Geometric Modeler Interfaces Layer

Technical Article

Abstract

This article lists the modifications, and their migration path for the Geometric Modeler.

The Need for GM Interfaces

One of the CAA V6 architecture goal is to minimize the code size at installation and manage to load the code which is strictly necessary for the achievement of some identified scenarios (open a model, perform measures on it ...). The new interfaces allow an application to load dynamically the dlls which are strictly needed for the execution of a given scenario.

What Has Changed?

Two interface frameworks are created:

The Tessellation, NewTopologicalObjects, GeometricOperators, TopologicalOperators, FreeFormOperators and AdvancedTopologicalOpe are no longer exposed. Their APIs are exposed through the GMModelInterfaces and GMOperatorsInterfaces frameworks.

The New CAA Frameworks

Before

Now

GMModelInterfaces contains interfaces previously contained in the GeometricOperators, NewTopologicalObjects, Tessellation and BasicTopologicalOpe frameworks. GMOperatorsInterfaces contains interfaces previously contained in NewTopologicalObjects, BasicTopologicalOpe, FreeFormOperators and AdvancedTopologicalOpe frameworks.

The frameworks below are no longer packaged in the CAA offer:

The New GM Interface Description vs. CAA V5 Operators

How to Use GM Interfaces vs. CAA V5 Operators

List of modifications

  1. The operator name: CATxxx -> CATICGMxxx
  2. The global function to create the operator:; CATCreatexxx->CATCGMCreatexxx
  3. The way to delete the operator delete pWire0->pWire0->Release()

Migration Tools

A migration tool is provided in GeometricObjects. You can run it:

The Step-by-Step Migration Procedure

Step 1

Run the tck_list command to display the list of available tck profile identifiers then run the mkmk profile:

tck_profile myProfile

Refer to Using TCKs for Accessing Tools for more information.

You can also open a command window from MsDev by using the CAA customization.

Step 2:

Set the CGMITF_WS_DIR environment variable

set CGMITF_WS_DIR=E:\MyWorkspace

Step 3:  

Run the profile below

CAAMathematics.edu\Data.d\Tools\CGMItfProfile.bat

Step 4:

Run either command below:

CGMItfMigrate MyFramework

or

CGMItfMigrate MyFramework\MyModule

or

CGMItfMigrate MyFramework\MyModule\src\MyCode.cpp

The files generated by this command have the .CGMItf_new extension and a log file is generated in the ToolsData\CGMItfMigration folder.

Step 5:

Run either command below:

CGMItfMerge [-replace_all] MyFramework

or

CGMItfMerge [-replace_all] MyFramework\MyModule

or

CGMItfMerge [-replace_all] MyFramework\MyModule\src\MyCode.cpp

The migrated files together with the CATIA Version 5 files are displayed.
Note: The vdiff32 tool is used by default to display the file differences. If need be, you can specify a different tool by using the CGMITF_DIFF environment variable.

Exit the vdiff32 application. The question below is displayed:
Do you want to get the migrated source? Y(es)/N(o)/Q(uit)

Reply:

How to Fix Compilation Errors

Once you have migrated your application, you have to re-build your code. The migration tools described here above can leave some compilation errors behind. If so,  here is a way to fix the major part of these compilation errors.

Step 1:

When re-compiling your frameworks, redirect the output in a text file. Example:

mkcpl MyFramework >c:\temp\traces.txt

Step 2:

In Visual Studio, install the CGM Interface Migration Macros. To do so, open the directory CAAMathematics.edu\Data.d\CGMItfVisualStudio in your Explorer and double-click on CAACGMItfVisualStudio.vsmacros
The CAACGMItfMacros macros are now installed. They can be viewed in the Visual Studio Macro Explorer (Alt+F8).

Visual Studio Macro Explorer

Step 3:

The FixCGMItfErrors  macro should be launched first. Double-click the FixCGMItfErrors macro in the tree view above. The dialog box below is displayed.

Compilation traces file Dialog Box

To fill in field, enter the path of your trace file. Click OK.

Step 4:

Fix the other errors by clicking the other macros in the Macro Explorer tree structure. Here are the macro descriptions:

AddReleasePtr
Adds a Release() operation onto an operator pointer.
{ if (MyOperatorPointer) { MyOperatorPointer->Release(); MyOperatorPointer= 0; }

See Creating, Running and Releasing a GM Operator in CAA V6

FindInInterfaces
Searches for a pattern in the GM interface frameworks.
FixCGMItfErrors
Specifies your trace file and initializes the error fixing.
ProtectRelease
Checks the operator pointer validity prior to releasing it.
Example:
// CAA V5
MyOperatorPointer->Release();

is modified in:

// CAA V6
			{ if (MyOperatorPointer) { MyOperatorPointer->Release(); MyOperatorPointer= 0; }
ReplaceAutoVarByCreate
Replaces an automatic variable (incorrect use in CATIA version 5) by an appropriate pointer.
Example:
// CAA V5
{
  CATSolidCylinder cylinder1 (factory, topdata, ..., ...)
  ...
}

which is converted into

// CAA V6 right after migration { CATIPGMSolidCylinder cylinder1 (factory, topdata, ..., ...) ... }

			

does not build because the CATIPGMSolidCylinder class is virtual.
The ReplaceAutoVarByCreate adds the appropriate creation fonctions, as well as the Release() statement:

// CAA V6 after ReplaceAutoVarByCreate is activated
{
  CATIPGMSolidCylinder *pcylinder1 = CATPGMCreateSolidCylinder(Factory, TopData,p1, p2, p3);
  // ### CGMInterfaces AddRef()/Release() - BEGIN
  pcylinder1->Release(); pcylinder1 = NULL;
  // ### CGMInterfaces AddRef()/Release() - END
}
ReplaceDeleteByRelease
Replaces the previous operator delete by a Release().

Example:

// CAA V5
delete MyOperatorPointer;

is modified in:

// CAA V6
MyOperatorPointer->Release();

The macro takes into account CATSysDeletePtr, CATShDelete, CATPrt_DELETE, SAFE_DELETE, Remove, RemoveMapping.

SetPrereqWsPath
Sets the directory which contains the CGM interface frameworks.
SetWSPath
Not to be used
ValidateEndOfLife
Should be launched prior to using VerifyEndOfLifeInFiles. Select a line containing // ### CGMInterfaces AddRef()/Release() - END.
and run the macro. The  // ### CGMInterfaces string is replaced by // CGMInterfaces so that it can no longer be treated by the VerifyEndOfLifeInFiles macro.
VerifyEndOfLifeInFiles
Searches for the // ### CGMInterfaces AddRef()/Release() - END and // ### CGMInterfaces new/delete - END
These statements may have been inserted after a return! Running the macro helps you to find these statements and relocate them properly if need be (i.e before the return).  Another point to be checked: The CATCatchs block in which these statements should be duplicated.
VerifyItfInCastInFiles
Searches for the prohibited cast operations.

Example:

// CAA V5
  _GSDOperator = (CATTopBlendInt*)CATCreateTopBlend (_Factory,...);

which is converted into

// CAA V6 right after migration
			_GSDOperator = (CATIPGMTopBlendInt*)CATPGMCreateTopBlend (_Factory,...);

The CAA V5 code is not correct because the CATCreateTopBlend function  returns a CATTopBlend pointer. Casting it as a derived class CATTopBlendInt is not recommended as nothing guarantees that the returned object type matches. It is a potential source of crash.
This is how it should be coded:

// CAA V6 right after migration
CATIPGMTopBlend *pTopBlend = CATPGMCreateTopBlend (_Factory, ...);
if (pTopBlend != NULL)
{
  HRESULT hr = pTopBlend->QueryInterface(IID_CATIPGMTopBlendInt, (void **)&_GSDOperator);
  pTopBlend->Release();
  pTopBlend = NULL;
}

Recommendation:

Run the VerifyItfInCastInFiles.

For each cast, verify the class hierarchy:

  • If the target class is a derived class, the cast should be replaced by a QueryInterface.
  • Detail Of Interfaces Mapping

    Frameworks Replaced APIs
    AdvancedTopologicalOpe Replaced Interfaces
    BasicTopologicalOpe Replaced Interfaces
    FreeFormOperators Replaced Interfaces
    GeometricObjects Replaced Interfaces
    GeometricOperators Replaced Interfaces
    NewTopologicalObjects Replaced Interfaces
    Tessellation Replaced Interfaces
    TopologicalOperators Replaced Interfaces

    Some .h files have also been moved into other frameworks, the complete list is available here.


    History

    Version: 1 [Oct 2006] Document created