PathEngine home previous: Calling Through Abstract Base Classesnext: Linking with the PathEngine DLL
Contents, Programmers Guide, Linking with the SDK, Interface Version Numbers

Interface Version Numbers

Querying the versions of the root interfaces

Use iPathEngine::getInterfaceMajorVersion() and iPathEngine::getInterfaceMinorVersion() to obtain version numbers for the PathEngine runtime (i.e. interfaces supplied directly or indirectly through Interface iPathEngine).

Use iContentProcessing3D::getInterfaceMajorVersion() and iContentProcessing3D::getInterfaceMinorVersion() to obtain version numbers for the PathEngine 3D Content Processing library (i.e. interfaces supplied directly or indirectly through Interface iContentProcessing3D).

Use iTestBed::getInterfaceMajorVersion() and iTestBed::getInterfaceMinorVersion() to obtain version numbers for the PathEngine TestBed (i.e. interfaces supplied directly or indirectly through Interface iTestBed).

Note that these 'interface version numbers' are distinct from the major and minor release numbers for the SDK as a whole.
Interface version numbers are purely for managing binary compatibility across the API interface.

Interface changes and backwards compatibility

A release that just includes stuff like bug fixes and optimisation can be made without any change to interface version numbers.

When a public release adds methods to the end of any interface the minor version number relating to that interface is incremented.
This kind of change can be made without breaking binary compatibility between PathEngine and code compiled with old versions of the headers. In this situation executables can continue to run against the new dll, without recompilation.

If any methods are removed from the interface, or if the linkage is changed for any existing method, then the major version number is incremented and the minor version reset to 0.
After this kind of change any code calling the interface must be recompiled.

The following defines are provided by the PathEngine header file (i_pathengine.h), to identify API versions corresponding to the class definitions in the header: PATHENGINE_INTERFACE_MAJOR_VERSION
PATHENGINE_INTERFACE_MINOR_VERSION
CONTENT_PROCESSING_3D_INTERFACE_MAJOR_VERSION
CONTENT_PROCESSING_3D_INTERFACE_MINOR_VERSION
TESTBED_INTERFACE_MAJOR_VERSION
TESTBED_INTERFACE_MINOR_VERSION

The following code should be used to check for interface incompatibility before calling any other functions through the interface:

// for an interface to iPathEngine
// check if interfaces are compatible with the headers used for compilation
// pathEngine is a reference to class iPathEngine
	if(pathEngine.getInterfaceMajorVersion() != PATHENGINE_INTERFACE_MAJOR_VERSION
	 || pathEngine.getInterfaceMinorVersion() < PATHENGINE_INTERFACE_MINOR_VERSION
	 )
	{
		//.. report an error - code must be recompiled with new headers
	}
	//.. the interface is compatible with the headers used for compilation

// for an interface to iContentProcessing3D
// check if interfaces are compatible with the headers used for compilation
// cp3d is a reference to class iContentProcessing3D
	if(cp3d.getInterfaceMajorVersion() != CONTENT_PROCESSING_3D_INTERFACE_MAJOR_VERSION
	 || cp3d.getInterfaceMinorVersion() < CONTENT_PROCESSING_3D_INTERFACE_MINOR_VERSION
	 )
	{
		//.. report an error - code must be recompiled with new headers
	}
	//.. the interface is compatible with the headers used for compilation

// for an interface to iTestBed
// check if interfaces are compatible with the headers used for compilation
// testBed is a reference to class iTestBed
	if(testBed.getInterfaceMajorVersion() != TESTBED_INTERFACE_MAJOR_VERSION
	 || testBed.getInterfaceMinorVersion() < TESTBED_INTERFACE_MINOR_VERSION
	 )
	{
		//.. report an error - code must be recompiled with new headers
	}
	//.. the interface is compatible with the headers used for compilation

Documentation for PathEngine release 6.03 - Copyright © 2002-2021 PathEnginenext: Linking with the PathEngine DLL