diff options
Diffstat (limited to 'libs/ode-0.16.1/include/ode/odeinit.h')
| -rw-r--r-- | libs/ode-0.16.1/include/ode/odeinit.h | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/libs/ode-0.16.1/include/ode/odeinit.h b/libs/ode-0.16.1/include/ode/odeinit.h new file mode 100644 index 0000000..645ca42 --- /dev/null +++ b/libs/ode-0.16.1/include/ode/odeinit.h @@ -0,0 +1,236 @@ +/************************************************************************* + * * + * Open Dynamics Engine, Copyright (C) 2001,2002 Russell L. Smith. * + * All rights reserved. Email: russ@q12.org Web: www.q12.org * + * * + * This library is free software; you can redistribute it and/or * + * modify it under the terms of EITHER: * + * (1) The GNU Lesser General Public License as published by the Free * + * Software Foundation; either version 2.1 of the License, or (at * + * your option) any later version. The text of the GNU Lesser * + * General Public License is included with this library in the * + * file LICENSE.TXT. * + * (2) The BSD-style license that is included with this library in * + * the file LICENSE-BSD.TXT. * + * * + * This library is distributed in the hope that it will be useful, * + * but WITHOUT ANY WARRANTY; without even the implied warranty of * + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files * + * LICENSE.TXT and LICENSE-BSD.TXT for more details. * + * * + *************************************************************************/ + +/* Library initialization/finalization functions. */ + +#ifndef _ODE_ODEINIT_H_ +#define _ODE_ODEINIT_H_ + +#include <ode/common.h> + + +#ifdef __cplusplus +extern "C" { +#endif + + +/* ************************************************************************ */ +/* Library initialization */ + +/** + * @defgroup init Library Initialization + * + * Library initialization functions prepare ODE internal data structures for use + * and release allocated resources after ODE is not needed any more. + */ + + +/** + * @brief Library initialization flags. + * + * These flags define ODE library initialization options. + * + * @c dInitFlagManualThreadCleanup indicates that resources allocated in TLS for threads + * using ODE are to be cleared by library client with explicit call to @c 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 @c dAllocateODEDataForThread. Ultimately, + * the resources are released when library is closed with @c dCloseODE. On other + * operating systems resources are always released by the thread itself on its exit + * or on library closure with @c dCloseODE. + * + * With manual thread data cleanup mode every collision space object must be + * explicitly switched to manual cleanup mode with @c dSpaceSetManualCleanup + * after creation. See description of the function for more details. + * + * If @c dInitFlagManualThreadCleanup was not specified during initialization, + * calls to @c dCleanupODEAllDataForThread are not allowed. + * + * @see dInitODE2 + * @see dAllocateODEDataForThread + * @see dSpaceSetManualCleanup + * @see dCloseODE + * @ingroup init + */ +enum dInitODEFlags { + dInitFlagManualThreadCleanup = 0x00000001 /*@< Thread local data is to be cleared explicitly on @c dCleanupODEAllDataForThread function call*/ +}; + +/** + * @brief Initializes ODE library. + * + * @c dInitODE is obsolete. @c dInitODE2 is to be used for library initialization. + * + * A call to @c dInitODE is equal to the following initialization sequence + * @code + * dInitODE2(0); + * dAllocateODEDataForThread(dAllocateMaskAll); + * @endcode + * + * @see dInitODE2 + * @see dAllocateODEDataForThread + * @ingroup init + */ +ODE_API void dInitODE(void); + +/** + * @brief Initializes ODE library. + * @param uiInitFlags Initialization options bitmask + * @return 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 @c dCloseODE. + * + * The @a uiInitFlags parameter specifies initialization options to be used. These + * can be combination of zero or more @c dInitODEFlags flags. + * + * @note + * If @c dInitFlagManualThreadCleanup flag is used for initialization, + * @c 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 dInitODEFlags + * @see dCloseODE + * @see dSpaceSetManualCleanup + * @ingroup init + */ +ODE_API int dInitODE2(unsigned int uiInitFlags/*=0*/); + + +/** + * @brief ODE data allocation flags. + * + * These flags are used to indicate which data is to be pre-allocated in call to + * @c dAllocateODEDataForThread. + * + * @c dAllocateFlagBasicData tells to allocate the basic data set required for + * normal library operation. This flag is equal to zero and is always implicitly + * included. + * + * @c 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. + * + * @c 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 dAllocateODEDataForThread + * @ingroup init + */ +enum dAllocateODEDataFlags { + dAllocateFlagBasicData = 0, /*@< Allocate basic data required for library to operate*/ + + dAllocateFlagCollisionData = 0x00000001, /*@< Allocate data for collision detection*/ + + dAllocateMaskAll = ~0 /*@< Allocate all the possible data that is currently defined or will be defined in the future.*/ +}; + +/** + * @brief Allocate thread local data to allow the thread calling ODE. + * @param uiAllocateFlags Allocation options bitmask. + * @return 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. + * + * @a uiAllocateFlags parameter can contain zero or more flags from @c 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 dAllocateODEDataFlags + * @see dCleanupODEAllDataForThread + * @ingroup init + */ +ODE_API int dAllocateODEDataForThread(unsigned int uiAllocateFlags); + +/** + * @brief Free thread local data that was allocated for current thread. + * + * If library was initialized with @c dInitFlagManualThreadCleanup flag the function + * is required to be called on exit of every thread that was calling @c dAllocateODEDataForThread. + * Failure to call @c 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 @c dAllocateODEDataForThread. The function + * may not be called before ODE is initialized with @c dInitODE2 or after library + * has been closed with @c dCloseODE. A call to @c 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 @c dInitFlagManualThreadCleanup flag + * @c dCleanupODEAllDataForThread must not be called. + * + * @see dAllocateODEDataForThread + * @see dInitODE2 + * @see dCloseODE + * @ingroup init + */ +ODE_API void dCleanupODEAllDataForThread(); + + +/** + * @brief 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 @c 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. + * + * @c dCloseODE is a paired function for @c 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 @c dCloseODE. In particular it is not allowed to call + * @c dCleanupODEAllDataForThread after @c dCloseODE. + * + * @see dInitODE2 + * @see dCleanupODEAllDataForThread + * @ingroup init + */ +ODE_API void dCloseODE(void); + + + +#ifdef __cplusplus +} /* extern "C" */ +#endif + + +#endif /* _ODE_ODEINIT_H_ */ |