1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
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_ */
|
