+++ /dev/null
-/*************************************************************************
-* *
-* 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 = ~0U //@< 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_
projects / xonotic / xonotic.git / blobdiff