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 = ~0 /*@< 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_ */ 237