mirror of
https://github.com/glfw/glfw.git
synced 2024-11-10 00:51:47 +00:00
parent
a12311e596
commit
2afd57bf9b
@ -223,9 +223,9 @@ allocator.user = NULL;
|
|||||||
glfwInitAllocator(&allocator);
|
glfwInitAllocator(&allocator);
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
The allocator will be picked up at the beginning of initialization and will be
|
The allocator will be made active at the beginning of initialization and will be used by
|
||||||
used until GLFW has been fully terminated. Any allocator set after
|
GLFW until the library has been fully terminated. Any allocator set after initialization
|
||||||
initialization will be picked up only at the next initialization.
|
will be picked up only at the next initialization.
|
||||||
|
|
||||||
The allocator will only be used for allocations that would have been made with
|
The allocator will only be used for allocations that would have been made with
|
||||||
the C standard library. Memory allocations that must be made with platform
|
the C standard library. Memory allocations that must be made with platform
|
||||||
@ -242,6 +242,9 @@ void* my_malloc(size_t size, void* user)
|
|||||||
}
|
}
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
The documentation for @ref GLFWallocatefun also lists the requirements and limitations for
|
||||||
|
an allocation function. If the active one does not meet all of these, GLFW may fail.
|
||||||
|
|
||||||
The reallocation function must have a function signature matching @ref GLFWreallocatefun.
|
The reallocation function must have a function signature matching @ref GLFWreallocatefun.
|
||||||
It receives the memory block to be reallocated, the new desired size, in bytes, and the user
|
It receives the memory block to be reallocated, the new desired size, in bytes, and the user
|
||||||
pointer passed to @ref glfwInitAllocator and returns the address to the resized memory
|
pointer passed to @ref glfwInitAllocator and returns the address to the resized memory
|
||||||
@ -254,6 +257,9 @@ void* my_realloc(void* block, size_t size, void* user)
|
|||||||
}
|
}
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
The documentation for @ref GLFWreallocatefun also lists the requirements and limitations
|
||||||
|
for a reallocation function. If the active one does not meet all of these, GLFW may fail.
|
||||||
|
|
||||||
The deallocation function must have a function signature matching @ref GLFWdeallocatefun.
|
The deallocation function must have a function signature matching @ref GLFWdeallocatefun.
|
||||||
It receives the memory block to be deallocated and the user pointer passed to @ref
|
It receives the memory block to be deallocated and the user pointer passed to @ref
|
||||||
glfwInitAllocator.
|
glfwInitAllocator.
|
||||||
@ -265,6 +271,9 @@ void my_free(void* block, void* user)
|
|||||||
}
|
}
|
||||||
@endcode
|
@endcode
|
||||||
|
|
||||||
|
The documentation for @ref GLFWdeallocatefun also lists the requirements and limitations
|
||||||
|
for a deallocation function. If the active one does not meet all of these, GLFW may fail.
|
||||||
|
|
||||||
|
|
||||||
@subsection intro_init_terminate Terminating GLFW
|
@subsection intro_init_terminate Terminating GLFW
|
||||||
|
|
||||||
|
@ -1416,16 +1416,25 @@ typedef struct GLFWcursor GLFWcursor;
|
|||||||
* or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
* or `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
||||||
* failures gracefully yet.
|
* failures gracefully yet.
|
||||||
*
|
*
|
||||||
* This function may be called during @ref glfwInit but before the library is
|
* This function must support being called during @ref glfwInit but before the library is
|
||||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||||
* library is no longer flagged as initialized.
|
* longer flagged as initialized.
|
||||||
*
|
*
|
||||||
* Any memory allocated by this function will be deallocated during library
|
* Any memory allocated via this function will be deallocated via the same allocator
|
||||||
* termination or earlier.
|
* during library termination or earlier.
|
||||||
|
*
|
||||||
|
* Any memory allocated via this function must be suitably aligned for any object type.
|
||||||
|
* If you are using C99 or earlier, this alignment is platform-dependent but will be the
|
||||||
|
* same as what `malloc` provides. If you are using C11 or later, this is the value of
|
||||||
|
* `alignof(max_align_t)`.
|
||||||
*
|
*
|
||||||
* The size will always be greater than zero. Allocations of size zero are filtered out
|
* The size will always be greater than zero. Allocations of size zero are filtered out
|
||||||
* before reaching the custom allocator.
|
* before reaching the custom allocator.
|
||||||
*
|
*
|
||||||
|
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||||
|
*
|
||||||
|
* This function must not call any GLFW function.
|
||||||
|
*
|
||||||
* @param[in] size The minimum size, in bytes, of the memory block.
|
* @param[in] size The minimum size, in bytes, of the memory block.
|
||||||
* @param[in] user The user-defined pointer from the allocator.
|
* @param[in] user The user-defined pointer from the allocator.
|
||||||
* @return The address of the newly allocated memory block, or `NULL` if an
|
* @return The address of the newly allocated memory block, or `NULL` if an
|
||||||
@ -1436,7 +1445,8 @@ typedef struct GLFWcursor GLFWcursor;
|
|||||||
*
|
*
|
||||||
* @reentrancy This function should not call any GLFW function.
|
* @reentrancy This function should not call any GLFW function.
|
||||||
*
|
*
|
||||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||||
|
* functions.
|
||||||
*
|
*
|
||||||
* @sa @ref init_allocator
|
* @sa @ref init_allocator
|
||||||
* @sa @ref GLFWallocator
|
* @sa @ref GLFWallocator
|
||||||
@ -1459,16 +1469,26 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user);
|
|||||||
* `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
* `NULL` if allocation failed. Note that not all parts of GLFW handle allocation
|
||||||
* failures gracefully yet.
|
* failures gracefully yet.
|
||||||
*
|
*
|
||||||
* This function may be called during @ref glfwInit but before the library is
|
* This function must support being called during @ref glfwInit but before the library is
|
||||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||||
* library is no longer flagged as initialized.
|
* longer flagged as initialized.
|
||||||
*
|
*
|
||||||
* Any memory allocated by this function will be deallocated during library
|
* Any memory allocated via this function will be deallocated via the same allocator
|
||||||
* termination or earlier.
|
* during library termination or earlier.
|
||||||
|
*
|
||||||
|
* Any memory allocated via this function must be suitably aligned for any object type.
|
||||||
|
* If you are using C99 or earlier, this alignment is platform-dependent but will be the
|
||||||
|
* same as what `realloc` provides. If you are using C11 or later, this is the value of
|
||||||
|
* `alignof(max_align_t)`.
|
||||||
*
|
*
|
||||||
* The block address will never be `NULL` and the size will always be greater than zero.
|
* The block address will never be `NULL` and the size will always be greater than zero.
|
||||||
* Reallocations of a block to size zero are converted into deallocations. Reallocations
|
* Reallocations of a block to size zero are converted into deallocations before reaching
|
||||||
* of `NULL` to a non-zero size are converted into regular allocations.
|
* the custom allocator. Reallocations of `NULL` to a non-zero size are converted into
|
||||||
|
* regular allocations before reaching the custom allocator.
|
||||||
|
*
|
||||||
|
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||||
|
*
|
||||||
|
* This function must not call any GLFW function.
|
||||||
*
|
*
|
||||||
* @param[in] block The address of the memory block to reallocate.
|
* @param[in] block The address of the memory block to reallocate.
|
||||||
* @param[in] size The new minimum size, in bytes, of the memory block.
|
* @param[in] size The new minimum size, in bytes, of the memory block.
|
||||||
@ -1481,7 +1501,8 @@ typedef void* (* GLFWallocatefun)(size_t size, void* user);
|
|||||||
*
|
*
|
||||||
* @reentrancy This function should not call any GLFW function.
|
* @reentrancy This function should not call any GLFW function.
|
||||||
*
|
*
|
||||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||||
|
* functions.
|
||||||
*
|
*
|
||||||
* @sa @ref init_allocator
|
* @sa @ref init_allocator
|
||||||
* @sa @ref GLFWallocator
|
* @sa @ref GLFWallocator
|
||||||
@ -1503,13 +1524,17 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user);
|
|||||||
* This function may deallocate the specified memory block. This memory block
|
* This function may deallocate the specified memory block. This memory block
|
||||||
* will have been allocated with the same allocator.
|
* will have been allocated with the same allocator.
|
||||||
*
|
*
|
||||||
* This function may be called during @ref glfwInit but before the library is
|
* This function must support being called during @ref glfwInit but before the library is
|
||||||
* flagged as initialized, as well as during @ref glfwTerminate after the
|
* flagged as initialized, as well as during @ref glfwTerminate after the library is no
|
||||||
* library is no longer flagged as initialized.
|
* longer flagged as initialized.
|
||||||
*
|
*
|
||||||
* The block address will never be `NULL`. Deallocations of `NULL` are filtered out
|
* The block address will never be `NULL`. Deallocations of `NULL` are filtered out
|
||||||
* before reaching the custom allocator.
|
* before reaching the custom allocator.
|
||||||
*
|
*
|
||||||
|
* If this function returns `NULL`, GLFW will emit @ref GLFW_OUT_OF_MEMORY.
|
||||||
|
*
|
||||||
|
* This function must not call any GLFW function.
|
||||||
|
*
|
||||||
* @param[in] block The address of the memory block to deallocate.
|
* @param[in] block The address of the memory block to deallocate.
|
||||||
* @param[in] user The user-defined pointer from the allocator.
|
* @param[in] user The user-defined pointer from the allocator.
|
||||||
*
|
*
|
||||||
@ -1518,7 +1543,8 @@ typedef void* (* GLFWreallocatefun)(void* block, size_t size, void* user);
|
|||||||
*
|
*
|
||||||
* @reentrancy This function should not call any GLFW function.
|
* @reentrancy This function should not call any GLFW function.
|
||||||
*
|
*
|
||||||
* @thread_safety This function may be called from any thread that calls GLFW functions.
|
* @thread_safety This function must support being called from any thread that calls GLFW
|
||||||
|
* functions.
|
||||||
*
|
*
|
||||||
* @sa @ref init_allocator
|
* @sa @ref init_allocator
|
||||||
* @sa @ref GLFWallocator
|
* @sa @ref GLFWallocator
|
||||||
@ -2086,7 +2112,10 @@ typedef struct GLFWgamepadstate
|
|||||||
float axes[6];
|
float axes[6];
|
||||||
} GLFWgamepadstate;
|
} GLFWgamepadstate;
|
||||||
|
|
||||||
/*! @brief
|
/*! @brief Custom heap memory allocator.
|
||||||
|
*
|
||||||
|
* This describes a custom heap memory allocator for GLFW. To set an allocator, pass it
|
||||||
|
* to @ref glfwInitAllocator before initializing the library.
|
||||||
*
|
*
|
||||||
* @sa @ref init_allocator
|
* @sa @ref init_allocator
|
||||||
* @sa @ref glfwInitAllocator
|
* @sa @ref glfwInitAllocator
|
||||||
@ -2097,9 +2126,21 @@ typedef struct GLFWgamepadstate
|
|||||||
*/
|
*/
|
||||||
typedef struct GLFWallocator
|
typedef struct GLFWallocator
|
||||||
{
|
{
|
||||||
|
/*! The memory allocation function. See @ref GLFWallocatefun for details about
|
||||||
|
* allocation function.
|
||||||
|
*/
|
||||||
GLFWallocatefun allocate;
|
GLFWallocatefun allocate;
|
||||||
|
/*! The memory reallocation function. See @ref GLFWreallocatefun for details about
|
||||||
|
* reallocation function.
|
||||||
|
*/
|
||||||
GLFWreallocatefun reallocate;
|
GLFWreallocatefun reallocate;
|
||||||
|
/*! The memory deallocation function. See @ref GLFWdeallocatefun for details about
|
||||||
|
* deallocation function.
|
||||||
|
*/
|
||||||
GLFWdeallocatefun deallocate;
|
GLFWdeallocatefun deallocate;
|
||||||
|
/*! The user pointer for this custom allocator. This value will be passed to the
|
||||||
|
* allocator functions.
|
||||||
|
*/
|
||||||
void* user;
|
void* user;
|
||||||
} GLFWallocator;
|
} GLFWallocator;
|
||||||
|
|
||||||
@ -2232,8 +2273,12 @@ GLFWAPI void glfwInitHint(int hint, int value);
|
|||||||
* To use the default allocator, call this function with a `NULL` argument.
|
* To use the default allocator, call this function with a `NULL` argument.
|
||||||
*
|
*
|
||||||
* If you specify an allocator struct, every member must be a valid function
|
* If you specify an allocator struct, every member must be a valid function
|
||||||
* pointer. If any member is `NULL`, this function emits @ref
|
* pointer. If any member is `NULL`, this function will emit @ref
|
||||||
* GLFW_INVALID_VALUE and the init allocator is unchanged.
|
* GLFW_INVALID_VALUE and the init allocator will be unchanged.
|
||||||
|
*
|
||||||
|
* The functions in the allocator must fulfil a number of requirements. See the
|
||||||
|
* documentation for @ref GLFWallocatefun, @ref GLFWreallocatefun and @ref
|
||||||
|
* GLFWdeallocatefun for details.
|
||||||
*
|
*
|
||||||
* @param[in] allocator The allocator to use at the next initialization, or
|
* @param[in] allocator The allocator to use at the next initialization, or
|
||||||
* `NULL` to use the default one.
|
* `NULL` to use the default one.
|
||||||
|
Loading…
Reference in New Issue
Block a user