ODE  0.13.1
 All Data Structures Functions Variables Typedefs Enumerations Groups
Library Initialization

Data Structures

struct  dWorldStepMemoryFunctionsInfo
 World stepping memory manager descriptor structure. More...
 

Enumerations

enum  dInitODEFlags { dInitFlagManualThreadCleanup = 0x00000001 }
 Library initialization flags. More...
 
enum  dAllocateODEDataFlags { dAllocateFlagBasicData = 0, dAllocateFlagCollisionData = 0x00000001, dAllocateMaskAll = ~0 }
 ODE data allocation flags. More...
 

Functions

void dInitODE (void)
 Initializes ODE library. More...
 
int dInitODE2 (unsigned int uiInitFlags)
 Initializes ODE library. More...
 
int dAllocateODEDataForThread (unsigned int uiAllocateFlags)
 Allocate thread local data to allow the thread calling ODE. More...
 
void dCleanupODEAllDataForThread ()
 Free thread local data that was allocated for current thread. More...
 
void dCloseODE (void)
 Close ODE after it is not needed any more. More...
 

Detailed Description

Library initialization functions prepare ODE internal data structures for use and release allocated resources after ODE is not needed any more.

Enumeration Type Documentation

ODE data allocation flags.

These flags are used to indicate which data is to be pre-allocated in call to dAllocateODEDataForThread.

dAllocateFlagBasicData tells to allocate the basic data set required for normal library operation. This flag is equal to zero and is always implicitly included.

dAllocateFlagCollisionData tells that collision detection data is to be allocated. Collision detection functions may not be called if the data has not be allocated in advance. If collision detection is not going to be used, it is not necessary to specify this flag.

dAllocateMaskAll is a mask that can be used for for allocating all possible data in cases when it is not known what exactly features of ODE will be used. The mask may not be used in combination with other flags. It is guaranteed to include all the current and future legal allocation flags. However, mature applications should use explicit flags they need rather than allocating everything.

See Also
dAllocateODEDataForThread

Library initialization flags.

These flags define ODE library initialization options.

dInitFlagManualThreadCleanup indicates that resources allocated in TLS for threads using ODE are to be cleared by library client with explicit call to dCleanupODEAllDataForThread. If this flag is not specified the automatic resource tracking algorithm is used.

With automatic resource tracking, On Windows, memory allocated for a thread may remain not freed for some time after the thread exits. The resources may be released when one of other threads calls dAllocateODEDataForThread. Ultimately, the resources are released when library is closed with dCloseODE. On other operating systems resources are always released by the thread itself on its exit or on library closure with dCloseODE.

With manual thread data cleanup mode every collision space object must be explicitly switched to manual cleanup mode with dSpaceSetManualCleanup after creation. See description of the function for more details.

If dInitFlagManualThreadCleanup was not specified during initialization, calls to dCleanupODEAllDataForThread are not allowed.

See Also
dInitODE2
dAllocateODEDataForThread
dSpaceSetManualCleanup
dCloseODE

Function Documentation

int dAllocateODEDataForThread ( unsigned int  uiAllocateFlags)

Allocate thread local data to allow the thread calling ODE.

Parameters
uiAllocateFlagsAllocation options bitmask.
Returns
A nonzero if allocation succeeded and zero otherwise.

The function is required to be called for every thread that is going to use ODE. This function allocates the data that is required for accessing ODE from current thread along with optional data required for particular ODE subsystems.

uiAllocateFlags parameter can contain zero or more flags from dAllocateODEDataFlags enumerated type. Multiple calls with different allocation flags are allowed. The flags that are already allocated are ignored in subsequent calls. If zero is passed as the parameter, it means to only allocate the set of most important data the library can not operate without.

If the function returns failure status it means that none of the requested data has been allocated. The client may retry allocation attempt with the same flags when more system resources are available.

See Also
dAllocateODEDataFlags
dCleanupODEAllDataForThread
void dCleanupODEAllDataForThread ( )

Free thread local data that was allocated for current thread.

If library was initialized with dInitFlagManualThreadCleanup flag the function is required to be called on exit of every thread that was calling dAllocateODEDataForThread. Failure to call dCleanupODEAllDataForThread may result in some resources remaining not freed until program exit. The function may also be called when ODE is still being used to release resources allocated for all the current subsystems and possibly proceed with data pre-allocation for other subsystems.

The function can safely be called several times in a row. The function can be called without prior invocation of dAllocateODEDataForThread. The function may not be called before ODE is initialized with dInitODE2 or after library has been closed with dCloseODE. A call to dCloseODE implicitly releases all the thread local resources that might be allocated for all the threads that were using ODE.

If library was initialized without dInitFlagManualThreadCleanup flag dCleanupODEAllDataForThread must not be called.

See Also
dAllocateODEDataForThread
dInitODE2
dCloseODE
void dCloseODE ( void  )

Close ODE after it is not needed any more.

The function is required to be called when program does not need ODE features any more. The call to dCloseODE releases all the resources allocated for library including all the thread local data that might be allocated for all the threads that were using ODE.

dCloseODE is a paired function for dInitODE2 and must only be called after successful library initialization.

Note
Important! Make sure that all the threads that were using ODE have already terminated before calling dCloseODE. In particular it is not allowed to call dCleanupODEAllDataForThread after dCloseODE.
See Also
dInitODE2
dCleanupODEAllDataForThread
void dInitODE ( void  )

Initializes ODE library.

dInitODE is obsolete. dInitODE2 is to be used for library initialization.

A call to dInitODE is equal to the following initialization sequence

* dInitODE2(0);
* dAllocateODEDataForThread(dAllocateMaskAll);
*
See Also
dInitODE2
dAllocateODEDataForThread
int dInitODE2 ( unsigned int  uiInitFlags)

Initializes ODE library.

Parameters
uiInitFlagsInitialization options bitmask
Returns
A nonzero if initialization succeeded and zero otherwise.

This function must be called to initialize ODE library before first use. If initialization succeeds the function may not be called again until library is closed with a call to dCloseODE.

The uiInitFlags parameter specifies initialization options to be used. These can be combination of zero or more dInitODEFlags flags.

Note
If dInitFlagManualThreadCleanup flag is used for initialization, dSpaceSetManualCleanup must be called to set manual cleanup mode for every space object right after creation. Failure to do so may lead to resource leaks.
See Also
dInitODEFlags
dCloseODE
dSpaceSetManualCleanup