The Gravel v3 Physics API consists of the following functions:
| accelerateGravelObject | Accelerates an object for a specified length of time |
| addGravelObject | Adds a copy of an object to the Gravel scene |
| advanceGravelTime | Advances the simulation by a number of time units |
| calculateLocalGravelAcceleration | Calculates the acceleration at a given location |
| createGravelScene | Creates a new Gravel scene |
| createGravelSceneWithData | Creates a new Gravel scene with additional generic data |
| deleteGravelScene | Destroys a Gravel scene |
| getElapsedGravelTime | Reports how much simulated time has passed |
| getGravelConstantOfGravity | Reports the constant of gravity for the used timeframe |
| getGravelObjectCPointer | Reports the address of an object in the Gravel scene |
| getGravelSceneData | Reports the size of the generic data and/or copies the data |
| getGravelSceneIs3D | Reports whether the z-axis is being used |
| getGravelTimeframe | Reports which timeframe is used by the Gravel scene |
| getNumberOfGravelObjects | Reports how many objects are in the Gravel scene |
| resetGravelScene | Resets the Gravel scene to its initial state |
These functions are described in more detail in the Reference section.
The licence includes conditional permission to redistribute exact unmodified copies of RclsoftwareGravelv3Phy.dll.
It is strongly recommended to install the redistributed file in the system folder (i.e. "C:\Windows\System32\").
The Gravel v3 Physics API can be accessed via implicit or explicit linking.
Implicit linking
The DLL import library RclsoftwareGravelv3Phy.lib is provided for users of Visual C++ 2003/2005 and other compatible compilers.
Explicit linking
The Windows API function LoadLibrary can be used to load RclsoftwareGravelv3Phy.dll into the application's program space.
The Windows API function GetProcAddress can then be used to retrieve the addresses of the Gravel v3 Engine's API functions.
Note
The exported functions conform to the same standard function call convention that is also used by the Windows API.
Therefore, programming languages which support the standard function call convention, such as C/C++ and Delphi, can be used to access the Gravel v3 Physics API.
The Gravel v3 Physics API is described by the C/C++ header file RclsoftwareGravelv3PhyApi.h.
Before using this SDK, the path of the SDK's C/C++ header files (and the path of the DLL's .lib file) should be added to the programming environment's search paths.
An application which uses the Gravel v3 SDK should #include <RclsoftwareGravelv3Phy.h> which will include both RclsoftwareGravelv3PhyApiTypes.h and RclsoftwareGravelv3PhyApi.h.
Depending on your programming environment, you may need to #include <stddef.h> first.
RclsoftwareGravelv3PhyApiTypes.h
All C/C++ environments differ slightly in the way they define certain data types, how they declare functions exported from DLLs, and so forth. This header file may be modified by the user of the SDK in order to make certain adjustments for the chosen compiler.
If explicit linking is to be used, it is recommended that the following line be added to RclsoftwareGravelv3PhyApiTypes.h:
#define RCLSOFTWAREORGUK_GRAVELV3PHYAPI typedef GravelAPIResult __stdcall
The above #define causes function types (rather than imported functions) to be declared, which can then be used for pointer-to-function definitions.
RclsoftwareGravelv3PhyApi.h
This header file contains the actual API specification and must NOT be modified.
The types and functions declared in this header file are fully described in the reference section.