From 685e381735f22801ccfe028496af0e6cba7a073a Mon Sep 17 00:00:00 2001 From: Sam Lantinga Date: Mon, 22 Jul 2024 05:58:19 -0700 Subject: [PATCH] Add an overview of how to handle temporary memory --- include/SDL3/SDL_events.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index d5624aa0c..9f581058d 100644 --- a/include/SDL3/SDL_events.h +++ b/include/SDL3/SDL_events.h @@ -1443,6 +1443,16 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size); * will return NULL, and the application does not have ownership of the * memory. * + * Essentially you have 3 options for handling temporary memory: + * + * 1. After calling a function that returns temporary memory, pass that pointer to SDL_FreeTemporaryMemory(). This gives you full control over the management of allocations. + * + * 2. On your main thread, temporary memory is automatically cleaned up when processing events. On other threads, you can periodically call SDL_FreeTemporaryMemory(NULL) to clean up any temporary memory that has accumulated. + * + * 3. After calling a function that returns temporary memory, pass that pointer to SDL_ClaimTemporaryMemory(). This transfers ownership of the memory to your application and you can pass it to other threads or save it indefinitely, calling SDL_free() to free it when you're ready. + * + * Any of the three options are valid, and you can mix and match them to suit your application. + * * \param mem a pointer allocated with SDL_AllocateTemporaryMemory(). * \returns a pointer to the memory now owned by the application, which must * be freed using SDL_free(), or NULL if the memory is not temporary