misc/builddeps/linux32/ode/include/ode/odeinit.h

   1 /*************************************************************************
   2 *                                                                       *
   3 * Open Dynamics Engine, Copyright (C) 2001,2002 Russell L. Smith.       *
   4 * All rights reserved.  Email: russ@q12.org   Web: www.q12.org          *
   5 *                                                                       *
   6 * This library is free software; you can redistribute it and/or         *
   7 * modify it under the terms of EITHER:                                  *
   8 *   (1) The GNU Lesser General Public License as published by the Free  *
   9 *       Software Foundation; either version 2.1 of the License, or (at  *
  10 *       your option) any later version. The text of the GNU Lesser      *
  11 *       General Public License is included with this library in the     *
  12 *       file LICENSE.TXT.                                               *
  13 *   (2) The BSD-style license that is included with this library in     *
  14 *       the file LICENSE-BSD.TXT.                                       *
  15 *                                                                       *
  16 * This library is distributed in the hope that it will be useful,       *
  17 * but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the files    *
  19 * LICENSE.TXT and LICENSE-BSD.TXT for more details.                     *
  20 *                                                                       *
  21 *************************************************************************/
  22
  23 /* Library initialization/finalization functions. */
  24
  25 #ifndef _ODE_ODEINIT_H_
  26 #define _ODE_ODEINIT_H_
  27
  28 #include <ode/common.h>
  29
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35
  36 /* ************************************************************************ */
  37 /* Library initialization */
  38
  39 /**
  40  * @defgroup init Library Initialization
  41  *
  42  * Library initialization functions prepare ODE internal data structures for use
  43  * and release allocated resources after ODE is not needed any more.
  44  */
  45
  46
  47 /**
  48  * @brief Library initialization flags.
  49  *
  50  * These flags define ODE library initialization options.
  51  *
  52  * @c dInitFlagManualThreadCleanup indicates that resources allocated in TLS for threads
  53  * using ODE are to be cleared by library client with explicit call to @c dCleanupODEAllDataForThread.
  54  * If this flag is not specified the automatic resource tracking algorithm is used.
  55  *
  56  * With automatic resource tracking, On Windows, memory allocated for a thread may
  57  * remain not freed for some time after the thread exits. The resources may be
  58  * released when one of other threads calls @c dAllocateODEDataForThread. Ultimately,
  59  * the resources are released when library is closed with @c dCloseODE. On other
  60  * operating systems resources are always released by the thread itself on its exit
  61  * or on library closure with @c dCloseODE.
  62  *
  63  * With manual thread data cleanup mode every collision space object must be
  64  * explicitly switched to manual cleanup mode with @c dSpaceSetManualCleanup
  65  * after creation. See description of the function for more details.
  66  *
  67  * If @c dInitFlagManualThreadCleanup was not specified during initialization,
  68  * calls to @c dCleanupODEAllDataForThread are not allowed.
  69  *
  70  * @see dInitODE2
  71  * @see dAllocateODEDataForThread
  72  * @see dSpaceSetManualCleanup
  73  * @see dCloseODE
  74  * @ingroup init
  75  */
  76 enum dInitODEFlags {
  77         dInitFlagManualThreadCleanup = 0x00000001 //@< Thread local data is to be cleared explicitly on @c dCleanupODEAllDataForThread function call
  78 };
  79
  80 /**
  81  * @brief Initializes ODE library.
  82  *
  83  * @c dInitODE is obsolete. @c dInitODE2 is to be used for library initialization.
  84  *
  85  * A call to @c dInitODE is equal to the following initialization sequence
  86  * @code
  87  *     dInitODE2(0);
  88  *     dAllocateODEDataForThread(dAllocateMaskAll);
  89  * @endcode
  90  *
  91  * @see dInitODE2
  92  * @see dAllocateODEDataForThread
  93  * @ingroup init
  94  */
  95 ODE_API void dInitODE(void);
  96
  97 /**
  98  * @brief Initializes ODE library.
  99  * @param uiInitFlags Initialization options bitmask
 100  * @return A nonzero if initialization succeeded and zero otherwise.
 101  *
 102  * This function must be called to initialize ODE library before first use. If
 103  * initialization succeeds the function may not be called again until library is
 104  * closed with a call to @c dCloseODE.
 105  *
 106  * The @a uiInitFlags parameter specifies initialization options to be used. These
 107  * can be combination of zero or more @c dInitODEFlags flags.
 108  *
 109  * @note
 110  * If @c dInitFlagManualThreadCleanup flag is used for initialization,
 111  * @c dSpaceSetManualCleanup must be called to set manual cleanup mode for every
 112  * space object right after creation. Failure to do so may lead to resource leaks.
 113  *
 114  * @see dInitODEFlags
 115  * @see dCloseODE
 116  * @see dSpaceSetManualCleanup
 117  * @ingroup init
 118  */
 119 ODE_API int dInitODE2(unsigned int uiInitFlags/*=0*/);
 120
 121
 122 /**
 123  * @brief ODE data allocation flags.
 124  *
 125  * These flags are used to indicate which data is to be pre-allocated in call to
 126  * @c dAllocateODEDataForThread.
 127  *
 128  * @c dAllocateFlagBasicData tells to allocate the basic data set required for
 129  * normal library operation. This flag is equal to zero and is always implicitly
 130  * included.
 131  *
 132  * @c dAllocateFlagCollisionData tells that collision detection data is to be allocated.
 133  * Collision detection functions may not be called if the data has not be allocated
 134  * in advance. If collision detection is not going to be used, it is not necessary
 135  * to specify this flag.
 136  *
 137  * @c dAllocateMaskAll is a mask that can be used for for allocating all possible
 138  * data in cases when it is not known what exactly features of ODE will be used.
 139  * The mask may not be used in combination with other flags. It is guaranteed to
 140  * include all the current and future legal allocation flags. However, mature
 141  * applications should use explicit flags they need rather than allocating everything.
 142  *
 143  * @see dAllocateODEDataForThread
 144  * @ingroup init
 145  */
 146 enum dAllocateODEDataFlags {
 147         dAllocateFlagBasicData = 0, //@< Allocate basic data required for library to operate
 148
 149         dAllocateFlagCollisionData = 0x00000001, //@< Allocate data for collision detection
 150
 151         dAllocateMaskAll = ~0U //@< Allocate all the possible data that is currently defined or will be defined in the future.
 152 };
 153
 154 /**
 155  * @brief Allocate thread local data to allow the thread calling ODE.
 156  * @param uiAllocateFlags Allocation options bitmask.
 157  * @return A nonzero if allocation succeeded and zero otherwise.
 158  *
 159  * The function is required to be called for every thread that is going to use
 160  * ODE. This function allocates the data that is required for accessing ODE from
 161  * current thread along with optional data required for particular ODE subsystems.
 162  *
 163  * @a uiAllocateFlags parameter can contain zero or more flags from @c dAllocateODEDataFlags
 164  * enumerated type. Multiple calls with different allocation flags are allowed.
 165  * The flags that are already allocated are ignored in subsequent calls. If zero
 166  * is passed as the parameter, it means to only allocate the set of most important
 167  * data the library can not operate without.
 168  *
 169  * If the function returns failure status it means that none of the requested
 170  * data has been allocated. The client may retry allocation attempt with the same
 171  * flags when more system resources are available.
 172  *
 173  * @see dAllocateODEDataFlags
 174  * @see dCleanupODEAllDataForThread
 175  * @ingroup init
 176  */
 177 ODE_API int dAllocateODEDataForThread(unsigned int uiAllocateFlags);
 178
 179 /**
 180  * @brief Free thread local data that was allocated for current thread.
 181  *
 182  * If library was initialized with @c dInitFlagManualThreadCleanup flag the function
 183  * is required to be called on exit of every thread that was calling @c dAllocateODEDataForThread.
 184  * Failure to call @c dCleanupODEAllDataForThread may result in some resources remaining
 185  * not freed until program exit. The function may also be called when ODE is still
 186  * being used to release resources allocated for all the current subsystems and
 187  * possibly proceed with data pre-allocation for other subsystems.
 188  *
 189  * The function can safely be called several times in a row. The function can be
 190  * called without prior invocation of @c dAllocateODEDataForThread. The function
 191  * may not be called before ODE is initialized with @c dInitODE2 or after library
 192  * has been closed with @c dCloseODE. A call to @c dCloseODE implicitly releases
 193  * all the thread local resources that might be allocated for all the threads that
 194  * were using ODE.
 195  *
 196  * If library was initialized without @c dInitFlagManualThreadCleanup flag
 197  * @c dCleanupODEAllDataForThread must not be called.
 198  *
 199  * @see dAllocateODEDataForThread
 200  * @see dInitODE2
 201  * @see dCloseODE
 202  * @ingroup init
 203  */
 204 ODE_API void dCleanupODEAllDataForThread();
 205
 206
 207 /**
 208  * @brief Close ODE after it is not needed any more.
 209  *
 210  * The function is required to be called when program does not need ODE features any more.
 211  * The call to @c dCloseODE releases all the resources allocated for library
 212  * including all the thread local data that might be allocated for all the threads
 213  * that were using ODE.
 214  *
 215  * @c dCloseODE is a paired function for @c dInitODE2 and must only be called
 216  * after successful library initialization.
 217  *
 218  * @note Important!
 219  * Make sure that all the threads that were using ODE have already terminated
 220  * before calling @c dCloseODE. In particular it is not allowed to call
 221  * @c dCleanupODEAllDataForThread after @c dCloseODE.
 222  *
 223  * @see dInitODE2
 224  * @see dCleanupODEAllDataForThread
 225  * @ingroup init
 226  */
 227 ODE_API void dCloseODE(void);
 228
 229
 230
 231 #ifdef __cplusplus
 232 } // extern "C"
 233 #endif
 234
 235
 236 #endif // _ODE_ODEINIT_H_