Reference
The types and functions described here can be found in the ANSI C header files
RclsoftwareGravelv3PhyApiTypes.h and RclsoftwareGravelv3PhyApi.h.
Type definitions
Standard built-in type definitions
Return value enumeration
Timeframe enumeration
Gravel handle type definition
Gravel 3D vector definition
Gravel object definition
API functions
- accelerateGravelObject
- addGravelObject
- advanceGravelTime
- calculateLocalGravelAcceleration
- createGravelScene
- createGravelSceneWithData
- deleteGravelScene
- getElapsedGravelTime
- getGravelConstantOfGravity
- getGravelObjectCPointer
- getGravelSceneData
- getGravelSceneIs3D
- getGravelTimeframe
- getNumberOfGravelObjects
- resetGravelScene
Type definitions
Standard built-in type definitions
| bool8_t | 8-bit boolean (1 == true, 0 == false) |
| uint8_t | 8-bit unsigned byte |
| uint64_t | 64-bit unsigned integer |
| float64_t | 64-bit IEEE 754 floating point number |
| size_t | 32-bit unsigned integer (same size as a pointer) |
Return value enumeration
/***********************
GravelAPIResult
***********************/
typedef enum GravelAPIResultTAG
{
gravelResultOk = 0x0000,
gravelResultInsideObject = 0x0001,
gravelResultException = 0x0101,
gravelResultNullPointer = 0x0102,
gravelResultInvalidHandle = 0x0103,
gravelResultInvalidParameter = 0x0104,
gravelResultMemoryAllocationFailure = 0x0105,
gravelResultErrorMask = 0x7fffFF00,
gravelResultForce32BitEnum = 0x7fffFFFF
}
GravelAPIResult;
|
A 32bit enumeration describing the possible return values of the API's functions.
| gravelResultOk | The function completed successfully. |
| gravelResultInsideObject | Warning: The specified location is inside an object. |
| gravelResultException | Error: An exception occured. |
| gravelResultNullPointer | Error: One of the parameters is a null pointer. |
| gravelResultInvalidHandle | Error: One of the parameters is a null handle. |
| gravelResultInvalidParameter | Error: One of the parameters is invalid. |
| gravelResultMemoryAllocationFailure | Error: The required memory could not be allocated. |
Note:
- gravelResultInsideObject is a warning and will only be returned by calculateLocalGravelAcceleration.
- Neither gravelResultErrorMask nor gravelResultForce32BitEnum is returned by any function.
Timeframe enumeration
/**************************
GravelAPITimeframe
**************************/
typedef enum GravelAPITimeframeTAG
{
gravelTimeframeSeconds = 0,
gravelTimeframeMinutes = 1,
gravelTimeframeHours = 2,
gravelTimeframeForce32BitEnum = 0x7fffFFFF
}
GravelAPITimeframe;
|
A 32bit enumeration describing the timeframes supported by Gravel v3.
The timeframe specifies the timeunit of the simulation:
| Timeframe | Velocity | Acceleration |
| gravelTimeframeSeconds | Meters per second | Meters per second per second |
| gravelTimeframeMinutes | Meters per minute | Meters per minute per minute |
| gravelTimeframeHours | Meters per hour | Meters per hour per hour |
Gravel Handle type definition
/***************************
GravelAPISceneHandle
***************************/
struct GravelAPISceneTAG;
typedef struct GravelAPISceneTAG* GravelAPISceneHandle;
|
The GravelAPISceneHandle identifies an individual Gravel scene.
It is obtained by calling createGravelScene or createGravelSceneWithData, and is a required parameter for all other API functions.
Gravel 3D vector definition
/**********************
GravelAPIVector
**********************/
typedef struct GravelAPIVectorTAG /* win32: 24 bytes */
{
float64_t x;
float64_t y;
float64_t z;
}
GravelAPIVector;
|
This structure describes a 3D vector in Gravel.
Gravel object definition
/**********************
GravelAPIObject
**********************/
typedef struct GravelAPIObjectTAG /* win32: 80 bytes */
{
float64_t mass; /* kilograms */
float64_t equatorialRadius; /* meters */
float64_t polarDiameter; /* meters */
GravelAPIVector location; /* meters */
GravelAPIVector velocity; /* meters per timeunit */
const uint8_t* data; /* Generic data */
size_t dataLength; /* Data length */
}
GravelAPIObject;
typedef const GravelAPIObject* GravelAPIObjectCPointer;
|
This structure describes all the information about an astronomical object that Gravel needs in order to simulate its behaviour:
| mass |
The mass of the object, in kilo-grams. |
equatorialRadius
polarDiameter |
The size of the object, in meters.
For the purpose of collision detection, Gravel v3 uses these two values to calculate the size of a sphere which fully encloses the object. |
| location | A vector describing the location of the object, in meters. |
| velocity | A vector describing the velocity of the object, in meters per timeunit. |
data
dataLength | Generic data which is stored with the object.
This could for instance be graphics information used for rendering the object in a 3D view. |
API function declarations
|
accelerateGravelObject
RCLSOFTWAREORGUK_GRAVELV3PHYAPI accelerateGravelObject
(
GravelAPISceneHandle inGravelScene,
size_t inGravelObjectIndex,
const GravelAPIVector* inAcceleration,
uint64_t inDuration
);
|
Description:
Accelerates an object for a specified length of time.
Parameters:
| inGravelScene | | A GravelAPISceneHandle obtained by a call to createGravelScene or createGravelSceneWithData. |
| inGravelObjectIndex | | Specifies the zero-based index of the object which is to be accelerated (must be less than the number of objects in the Gravel scene). |
| inAcceleration | | Specifies the acceleration, in meters per timeunit per timeunit, which is to be applied. |
| inDuration | | Specifies the duration, in timeunits, of the acceleration (must be greater than zero). |
|
|
addGravelObject
RCLSOFTWAREORGUK_GRAVELV3PHYAPI addGravelObject
(
GravelAPISceneHandle inGravelScene,
GravelAPIObjectCPointer inGravelObject
);
|
Description:
Adds an astronomical object to the Gravel scene.
Parameters:
Remarks:
If inGravelScene has already been used in a call to advanceGravelTime then gravelResultInvalidParameter is returned.
|
|
advanceGravelTime
RCLSOFTWAREORGUK_GRAVELV3PHYAPI advanceGravelTime
(
GravelAPISceneHandle inGravelScene,
uint64_t inTime,
bool8_t* outCollisions
);
|
Description:
Advances the simulation by the given number of timeunits.
Parameters:
Remarks:
If two objects are colliding (their distance is less than their combined radii) then the acceleration which these two objects exert on each other is ignored.
|
|
calculateLocalGravelAcceleration
RCLSOFTWAREORGUK_GRAVELV3PHYAPI calculateLocalGravelAcceleration
(
GravelAPISceneHandle inGravelScene,
const GravelAPIVector* inLocation,
GravelAPIVector* outAcceleration
);
|
Description:
Calculates the acceleration at a given location.
Parameters:
| inGravelScene | | A GravelAPISceneHandle obtained by a call to createGravelScene or createGravelSceneWithData. |
| inLocation | | A vector describing the location at which the acceleration should be measured, in 'meters'. |
| outAcceleration | | A vector describing the acceleration at the given location, in 'meters per timeunit per timeunit'. |
Remarks:
If inLocation is inside a GravelAPIObject then outAcceleration describes the acceleration experienced by that object and gravelResultInsideObject is returned.
|
|
createGravelScene
RCLSOFTWAREORGUK_GRAVELV3PHYAPI createGravelScene
(
GravelAPITimeframe inTimeframe,
GravelAPISceneHandle* outGravelScene
);
|
Description:
Creates a new Gravel scene.
Parameters:
| inTimeframe | | Specifies the timeframe used by the Gravel scene. |
| outGravelScene | | Specifies the address of the Gravel handle which is to be initialised. |
|
|
createGravelSceneWithData
RCLSOFTWAREORGUK_GRAVELV3PHYAPI createGravelSceneWithData
(
GravelAPITimeframe inTimeframe,
const uint8_t* inDataBuffer,
size_t inDataBufferSize,
GravelAPISceneHandle* outGravelScene
);
|
Description:
Creates a new Gravel scene with additional generic data.
Parameters:
| inTimeframe | | Specifies the timeframe used by the Gravel scene. |
| inDataBuffer | | Specifies the generic data which is to be stored with the Gravel scene. |
| inDataBufferSize | | Specifies the length (in bytes) of the generic data. |
| outGravelScene | | Specifies the address of the Gravel handle which is to be initialised. |
Remarks:
If inDataBuffer is NULL then inDataBufferSize must be zero.
|
|
deleteGravelScene
RCLSOFTWAREORGUK_GRAVELV3PHYAPI deleteGravelScene
(
GravelAPISceneHandle inGravelScene
);
|
Description:
Deletes the Gravel scene.
Parameters:
|
|
getElapsedGravelTime
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getElapsedGravelTime
(
GravelAPISceneHandle inGravelScene,
uint64_t* outElapsedTime
);
|
Description:
Reports how much simulated time has passed.
Parameters:
|
|
getGravelConstantOfGravity
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getGravelConstantOfGravity
(
GravelAPISceneHandle inGravelScene,
float64_t* outConstantOfGravity
);
|
Description:
Reports Newton's constant of gravity.
Parameters:
|
|
getGravelObjectCPointer
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getGravelObjectCPointer
(
GravelAPISceneHandle inGravelScene,
size_t inGravelObjectIndex,
GravelAPIObjectCPointer* outGravelObjectCPointer
);
|
Description:
Reports the address of an object in the Gravel scene.
Parameters:
Remarks:
The address of the astronomical object will remain valid until addGravelObject or deleteGravelScene is called.
|
|
getGravelSceneData
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getGravelSceneData
(
GravelAPISceneHandle inGravelScene,
uint8_t* inDataBuffer,
size_t* inoutDataBufferSize
);
|
Description:
Reports the size of the generic data and/or copies the data.
Parameters:
Remarks:
If inDataBuffer is NULL then no data is copied; instead inoutDataBufferSize points to a variable which receives the size of the generic data.
If inDataBuffer is not NULL then inoutDataBufferSize points to a variable which specifies the size of the buffer which inDataBuffer points to.
|
|
getGravelSceneIs3D
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getGravelSceneIs3D
(
GravelAPISceneHandle inGravelScene,
bool8_t* outGravelSceneIs3D
);
|
Description:
Reports whether the z-axis is being used.
Parameters:
|
|
getGravelTimeframe
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getGravelTimeframe
(
GravelAPISceneHandle inGravelScene,
GravelAPITimeframe* outTimeframe
);
|
Description:
Reports which timeframe is used by the Gravel scene.
Parameters:
|
|
getNumberOfGravelObjects
RCLSOFTWAREORGUK_GRAVELV3PHYAPI getNumberOfGravelObjects
(
GravelAPISceneHandle inGravelScene,
size_t* outNumberOfGravelObjects
);
|
Description:
Reports how many objects are in the Gravel scene.
Parameters:
|
|
resetGravelScene
RCLSOFTWAREORGUK_GRAVELV3PHYAPI resetGravelScene
(
GravelAPISceneHandle inGravelScene
);
|
Description:
Resets the Gravel scene to its initial state.
Parameters:
Remarks:
Resetting a Gravel scene does not make it possible to add new objects to the scene (see addGravelObject remarks).
|
