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