gim_memory.h

ODE v0.8 很好用的多平台几何物理模拟库源代码,内含多個示例

	{\
        GUINT * _pt = GIM_DYNARRAY_POINTER(GUINT,array_data);\
        _pt[bit_index >> GUINT_EXPONENT] &= ~(1 << (bit_index & (GUINT_BIT_COUNT-1)));\
	}\
}\
//! @}

/*! \defgroup MEMORY_ACCESS_CONSTANTS
\brief
Memory Access constants.
\sa BUFFERS
*/
//! @{
#define G_MA_READ_ONLY 1
#define G_MA_WRITE_ONLY 2
#define G_MA_READ_WRITE 3
//! @}

/*! \defgroup MEMORY_USAGE_CONSTANTS
\brief
Memory usage constants.
\sa BUFFERS
*/
//! @{
/// Don't care how memory is used
#define G_MU_EITHER 0
/// specified once, doesn't allow read information
#define G_MU_STATIC_WRITE 1
/// specified once, allows to read information from a shadow buffer
#define G_MU_STATIC_READ 2
/// write directly on buffer, allows to read information from a shadow buffer
#define G_MU_STATIC_READ_DYNAMIC_WRITE 3
/// upload data to buffer from the shadow buffer, allows to read information from a shadow buffer
#define G_MU_STATIC_READ_DYNAMIC_WRITE_COPY 4
/// specified once, allows to read information directly from memory
#define G_MU_STATIC_WRITE_DYNAMIC_READ 5
/// write directly on buffer, allows to read information directly from memory
#define G_MU_DYNAMIC_READ_WRITE 6
//! @}

/*! \defgroup BUFFER_ERRORS
\brief
Buffer operation errors
\sa BUFFERS
*/
//! @{
#define G_BUFFER_OP_SUCCESS 0
#define G_BUFFER_OP_INVALID 1
#define G_BUFFER_OP_STILLREFCOUNTED 2
//! @}

/*! \defgroup BUFFER_MANAGER_IDS
\brief
Buffer manager identifiers
\sa BUFFERS, BUFFER_MANAGERS
*/
//! @{
#define G_BUFFER_MANAGER_SYSTEM 0
#define G_BUFFER_MANAGER_SHARED 1
#define G_BUFFER_MANAGER_USER 2
//! @}

/*! \defgroup BUFFERS
\brief
Buffer operations and structs.
<ul>
<li> Before using buffers you must initializes GIMPACT buffer managers by calling \ref gimpact_init.
<li> For initializes a buffer, use  \ref gim_create_buffer, \ref gim_create_buffer_from_data , \ref gim_create_common_buffer, \ref gim_create_common_buffer_from_data or \ref gim_create_shared_buffer_from_data.
<li> For accessing to the buffer memory, you must call \ref gim_lock_buffer, and then \ref gim_unlock_buffer for finish the access.
<li> When a buffer is no longer needed, you must free it by calling \ref gim_buffer_free.
<li> You must call \ref gimpact_terminate when finish your application.
<li> For a safe manipulation of buffers, use \ref BUFFER_ARRAYS
</ul>
\sa BUFFER_MANAGERS, BUFFER_ARRAYS
*/
//! @{

//! Buffer handle.
struct GBUFFER_ID
{
    GUINT m_buffer_id;
    GUINT m_buffer_manager_id;
};
//typedef  struct _GBUFFER_ID GBUFFER_ID;

//! Buffer internal data
struct GBUFFER_DATA
{
    GUINT m_buffer_handle;//!< if 0, buffer doesn't exists
    GUINT m_size;
    GUINT m_usage;
    GINT m_access;
    GUINT m_lock_count;
    char * m_mapped_pointer;
    GBUFFER_ID m_shadow_buffer;
    GUINT m_refcount;//! Reference counting for safe garbage collection
};
//typedef  struct _GBUFFER_DATA GBUFFER_DATA;
//! @}

/*! \defgroup BUFFERS_MANAGER_PROTOTYPES
\brief
Function prototypes to allocate and free memory for buffers
\sa BUFFER_MANAGERS, BUFFERS
*/
//! @{

//! Returns a Buffer handle
typedef GUINT gim_buffer_alloc_function(GUINT size,int usage);

//! Returns a Buffer handle, and copies the pdata to the buffer
typedef GUINT gim_buffer_alloc_data_function(const void * pdata,GUINT size,int usage);

//! Changes the size of the buffer preserving the content, and returns the new buffer id
typedef GUINT gim_buffer_realloc_function(GUINT buffer_handle,GUINT oldsize,int old_usage,GUINT newsize,int new_usage);

//! It changes the m_buffer_handle member to 0/0
typedef void gim_buffer_free_function(GUINT buffer_handle,GUINT size);

//! It maps the m_mapped_pointer. Returns a pointer
typedef char * gim_lock_buffer_function(GUINT buffer_handle,int access);

//! It sets the m_mapped_pointer to 0
typedef void gim_unlock_buffer_function(GUINT buffer_handle);

typedef void gim_download_from_buffer_function(
        GUINT source_buffer_handle,
		GUINT source_pos,
		void * destdata,
		GUINT copysize);

typedef void  gim_upload_to_buffer_function(
        GUINT dest_buffer_handle,
		GUINT dest_pos,
		void * sourcedata,
		GUINT copysize);

typedef void gim_copy_buffers_function(
		GUINT source_buffer_handle,
		GUINT source_pos,
		GUINT dest_buffer_handle,
		GUINT dest_pos,
		GUINT copysize);
//! @}


/*! \defgroup BUFFER_MANAGERS
\brief
Buffer Manager operations
*/
//! @{
//! Buffer manager prototype
struct GBUFFER_MANAGER_PROTOTYPE
{
    gim_buffer_alloc_function * alloc_fn;
    gim_buffer_alloc_data_function *alloc_data_fn;
    gim_buffer_realloc_function * realloc_fn;
    gim_buffer_free_function * free_fn;
    gim_lock_buffer_function * lock_buffer_fn;
    gim_unlock_buffer_function * unlock_buffer_fn;
    gim_download_from_buffer_function * download_from_buffer_fn;
    gim_upload_to_buffer_function * upload_to_buffer_fn;
    gim_copy_buffers_function * copy_buffers_fn;
};
//typedef  struct _GBUFFER_MANAGER_PROTOTYPE GBUFFER_MANAGER_PROTOTYPE;

//! Buffer manager
struct GBUFFER_MANAGER_DATA
{
    GDYNAMIC_ARRAY m_buffer_array;//!< Array of GBUFFER_DATA objects
    GDYNAMIC_ARRAY m_free_positions;//!< Array of GUINT elements. Free positions
    GBUFFER_MANAGER_PROTOTYPE m_prototype;//! Prototype of functions
    GUINT m_active; //!< 0 or 1
};
//typedef  struct _GBUFFER_MANAGER_DATA GBUFFER_MANAGER_DATA;

//! Adds a buffer Manager to the Memory Singleton
void gim_create_buffer_manager(GBUFFER_MANAGER_PROTOTYPE * prototype,GUINT buffer_manager_id);
//! Gets buffer manager
GUINT gim_get_buffer_manager_count();
//! Destroys a buffer manager
void gim_destroy_buffer_manager(GUINT buffer_manager_id);
void gim_get_buffer_manager_data(GUINT buffer_manager_id,GBUFFER_MANAGER_DATA ** pbm_data);
void gim_init_buffer_managers();
void gim_terminate_buffer_managers();

//! @}


/*! \addtogroup BUFFERS
*/
//! @{

//!Creates a buffer on the buffer manager specified by buffer_manager_id
/*!
\param buffer_manager_id
\param buffer_size
\param usage An usage constant. Use G_MU_DYNAMIC_READ_WRITE as default.
\param buffer_id a pointer for receive the new buffer id
\return An error code. 0 if success.
\post m_refcount = 0
*/
GUINT gim_create_buffer(
    GUINT buffer_manager_id,
    GUINT buffer_size,
    int usage,
    GBUFFER_ID * buffer_id);

//!Creates a buffer on the buffer manager specified by buffer_manager_id
/*!
\param buffer_manager_id
\param pdata Data for allocating
\param buffer_size Size of the data buffer
\param usage An usage constant. Use G_MU_DYNAMIC_READ_WRITE as default.
\param buffer_id a pointer for receive the new buffer id
\return An error code. 0 if success.
\post m_refcount = 0
*/
GUINT gim_create_buffer_from_data(
    GUINT buffer_manager_id,
    const void * pdata,
    GUINT buffer_size,
    int usage,
    GBUFFER_ID * buffer_id);

//!Allocates on the G_BUFFER_MANAGER_SYSTEM
GUINT gim_create_common_buffer(GUINT buffer_size, GBUFFER_ID * buffer_id);
//!Allocates on the G_BUFFER_MANAGER_SYSTEM, and copies the data
GUINT gim_create_common_buffer_from_data(
    const void * pdata, GUINT buffer_size, GBUFFER_ID * buffer_id);
//!Creates a buffer with shared data
GUINT gim_create_shared_buffer_from_data(
    const void * pdata, GUINT buffer_size, GBUFFER_ID * buffer_id);


//! Add reference counting to buffer.
GINT gim_buffer_add_ref(GBUFFER_ID * buffer_id);

//! Function for resize buffer, preserving the content
/*!
\param buffer_id
\param newsize
\return An error code. 0 if success.
\post If m_refcount>0 then it decrements it.
*/
GINT gim_buffer_realloc(GBUFFER_ID * buffer_id,GUINT newsize);

//! Eliminates the buffer.
/*!
If the buffer reference counting is <= 1 and is unlocked, then it eliminates the buffer.
*/
GINT gim_buffer_free(GBUFFER_ID * buffer_id);

//! Locks the buffer for memory access.
/*!
\param buffer_id Id from buffer.
\param access Must have the following values: G_MA_READ_ONLY,G_MA_WRITE_ONLY or G_MA_READ_WRITE.
\param map_pointer Dest Pointer of the memory address from buffer.
\post m_lock_count increases.
*/
GINT gim_lock_buffer(GBUFFER_ID * buffer_id,int access,char ** map_pointer);

//! Unlocks the buffer for memory access.
GINT gim_unlock_buffer(GBUFFER_ID * buffer_id);

//! Gets the buffer size in bytes
GINT gim_get_buffer_size(GBUFFER_ID * buffer_id,GUINT * buffer_size);

//! Determines if the buffer is locked
GINT gim_get_buffer_is_locked(GBUFFER_ID * buffer_id,GUINT * lock_count);

//! Copies the content of the buffer to a dest pointer
GINT gim_download_from_buffer(
        GBUFFER_ID * buffer_id,
		GUINT source_pos,
		void * destdata,
		GUINT copysize);

//! Copies the content of a memory pointer to the buffer
GINT  gim_upload_to_buffer(
		GBUFFER_ID * buffer_id,
		GUINT dest_pos,
		void * sourcedata,
		GUINT copysize);

//! Copies two buffers.
GINT  gim_copy_buffers(
		GBUFFER_ID * source_buffer_id,
		GUINT source_pos,
		GBUFFER_ID * dest_buffer_id,
		GUINT dest_pos,
		GUINT copysize);
//! @}


/*! \defgroup BUFFER_ARRAYS

\brief
Buffered Arrays, for manip elements on a buffer and treat it as an array.
<ul>
<li> Before using buffer arrays you must initializes GIMPACT buffer managers by calling gimpact_init.
<li> Before creating buffer arrays, you must create a buffer. see \ref BUFFERS.
<li> Create a buffer narray by calling \ref GIM_BUFFER_ARRAY_INIT_TYPE, \ref GIM_BUFFER_ARRAY_INIT_TYPE_OFFSET or \ref GIM_BUFFER_ARRAY_INIT_OFFSET_STRIDE.
<li> For accessing to the array elements, you must call \ref gim_buffer_array_lock, and then \ref gim_buffer_array_unlock for finish the access.
<li> When a buffer array is no longer needed, you must free it by calling \ref GIM_BUFFER_ARRAY_DESTROY.
</ul>
The following example shows how Buffer arrays can be used:

\code
int main()
{
    //init gimpact
    gimpact_init();

    //Buffer handle to use
    GBUFFER_ID bufferhandle;

    //Create a memory buffer of 100 float numbers
    gim_create_common_buffer(100*sizeof(float), &bufferhandle);

    //Create a buffer array from the bufferhandle
    GBUFFER_ARRAY buffer_float_array;
    GIM_BUFFER_ARRAY_INIT_TYPE(float,buffer_float_array,bufferhandle,100);

    ////Access to the buffer data, set all elements of the array

    int i, count;
    count = buffer_float_array.m_element_count;
    //Locks the array
    gim_buffer_array_lock(&buffer_float_array,G_MA_READ_WRITE);
    float  * pelements = GIM_BUFFER_ARRAY_POINTER(float, buffer_float_array, 0); // A pointer to the buffer memory

    //fill the array with random numbers
    for (i = 0;i < count;i++ )
    {
        pelements[i] = gim_unit_random();
    }
    //unlock buffer
    gim_buffer_array_unlock(&buffer_float_array);

    //Program code
        ....
        ....

    //Destroy array
    GIM_BUFFER_ARRAY_DESTROY(buffer_float_array);