Sam Lantinga
4f55271571
Removed temporary memory from the API
...
It was intended to make the API easier to use, but various automatic garbage collection all had flaws, and making the application periodically clean up temporary memory added cognitive load to using the API, and in many cases was it was difficult to restructure threaded code to handle this.
So, we're largely going back to the original system, where the API returns allocated results and you free them.
In addition, to solve the problems we originally wanted temporary memory for:
* Short strings with a finite count, like device names, get stored in a per-thread string pool.
* Events continue to use temporary memory internally, which is cleaned up on the next event processing cycle.
2024-07-26 20:59:14 -07:00
Sam Lantinga
5e513ecc7f
Don't automatically free temporary memory, let the application call SDL_FreeTemporaryMemory() when it's ready.
...
Also mark up all functions that return temporary memory with SDL_DECLSPEC_TEMP, to help people implementing language bindings.
Fixes https://github.com/libsdl-org/SDL/issues/10378
2024-07-26 10:05:03 -07:00
SDL Wiki Bot
975457cfb6
Sync SDL3 wiki -> header
2024-07-19 19:23:24 +00:00
Sam Lantinga
71a60d4c0e
Updated documentation for functions that return temporary memory
2024-07-19 12:22:03 -07:00
Sam Lantinga
637e9700dd
Standardize placement of '*' in function declarations
...
Implemented using these sed commands on the headers:
sed -E -i'' '/SDLCALL|;/ s,([a-z])\* ,\1 *,g' *
sed -E -i'' 's,(\(.*[^\*])\* ([a-z])(.*\)),\1*\2\3,g' *
sed -E -i'' 's,\*const,* const,g' *
sed -E -i'' 's,\*SDLCALL,* SDLCALL,g' *
sed -E -i'' 's,void\(,void (,g' *
git checkout *gl*
2024-07-19 12:22:03 -07:00
Sam Lantinga
217330a7b3
Made return value descriptions more consistent across the API
2024-07-19 12:22:03 -07:00
Sam Lantinga
d73c7311d5
Clarify that the SDL_GetStringRule means that SDL will automatically free the memory later.
2024-07-19 12:22:03 -07:00
SDL Wiki Bot
d949673bc9
Sync SDL3 wiki -> header
2024-07-12 18:25:57 +00:00
Sam Lantinga
4c88ddf86d
More property documentation clarification
2024-07-12 11:24:40 -07:00
SDL Wiki Bot
cf441332c4
Sync SDL3 wiki -> header
2024-07-12 18:21:05 +00:00
Sam Lantinga
0e56f6a3ca
Clarify property group documentation
...
Fixes https://github.com/libsdl-org/SDL/issues/10241
2024-07-12 11:20:15 -07:00
SDL Wiki Bot
d6fe06bb5d
Sync SDL3 wiki -> header
2024-07-12 17:42:22 +00:00
Sam Lantinga
5bf6bc4d7d
Renamed SDL_Get/SetProperty() to SDL_Get/SetPointerProperty()
...
This is consistent with the naming for the functions that affect other data types
Fixes https://github.com/libsdl-org/SDL/issues/10241
2024-07-12 10:41:02 -07:00
SDL Wiki Bot
f531003776
Sync SDL3 wiki -> header
2024-07-12 15:37:23 +00:00
SDL Wiki Bot
68dfae1322
Sync SDL3 wiki -> header
2024-07-12 15:35:05 +00:00
Ryan C. Gordon
51902d4ac5
Updated headers with latest wikiheaders tweaks.
2024-06-14 02:09:55 -04:00
Ryan C. Gordon
e23257307e
Introduce formal policy for APIs that return strings.
...
This declares that any `const char *` returned from SDL is owned by SDL, and
promises to be valid _at least_ until the next time the event queue runs, or
SDL_Quit() is called, even if the thing that owns the string gets destroyed
or changed before then.
This is noted in the headers as "the SDL_GetStringRule", so this will both be
greppable to find a detailed explaination in docs/README-strings.md and
wikiheaders will automatically turn it into a link we can point at the
appropriate documentation.
Fixes #9902 .
(and several FIXMEs, both known and yet-undocumented.)
2024-06-03 14:20:49 -04:00
SDL Wiki Bot
a6da2e6f8b
Sync SDL3 wiki -> header
2024-05-26 16:19:32 +00:00
Ryan C. Gordon
2626304e70
properties: add formal SDL_CleanupPropertyCallback type, improve docs.
2024-05-26 12:17:34 -04:00
Sam Lantinga
6f2621438a
Renamed DECLSPEC to SDL_DECLSPEC
2024-05-17 17:09:09 -07:00
Ryan C. Gordon
5e6d85b8f0
wikiheaders: bridge wiki Category docs to the headers!
...
Did an initial cleanup on the headers and wrote a few pieces of documentation,
but this needs more work to fill out the documentation.
2024-05-16 11:48:23 -04:00
Petar Popovic
b98116a996
Removing trailing commas in enums in SDL headers
...
Trailing commas in enums is a C99 feature.
This commit removes them in SDL headers for ANSI compatibility.
2024-04-24 09:44:41 -04:00
Ryan C. Gordon
0df988389c
include: Add \since to all documentation that was missing it.
2024-04-11 13:34:29 -04:00
Ryan C. Gordon
ad090d2444
include: A ton of little documentation tweaks, fixes, and improvements.
...
This is just stuff I noticed while working on the wikiheaders updates. A
thorough pass over all the docs would not be terrible, and maybe a simple
script to check for consistency (does everything have a `\since` on it? etc)
might be nice, too.
2024-04-09 00:50:02 -04:00
Petar Popovic
3f8dba3713
Including SD_error.h into headers with error-returning functions
2024-04-04 11:12:58 -07:00
Sam Lantinga
d8a54cd4f8
Updated "see also" references to be more consistent
...
Fixes https://github.com/libsdl-org/SDL/issues/9282
2024-03-17 12:28:11 -07:00
Susko3
86d36a2dc2
Add missing include
2024-03-03 09:37:59 -08:00
Ryan C. Gordon
8db2a3b27a
camera: Add an optional property that reports if a camera is back or front.
...
This is useful for iOS and Android, so an app can find the camera it cares
about in the list of devices.
2024-02-20 15:56:26 -05:00
Sam Lantinga
8ce786d2b6
Property query functions don't set an error if they return the default value
...
You can call SDL_HasProperty() if you want to check to see if a property exists.
Fixes https://github.com/libsdl-org/SDL/issues/9067
2024-02-17 07:59:04 -08:00
SDL Wiki Bot
9ff8df932a
Sync SDL3 wiki -> header
2024-02-10 00:05:26 +00:00
Sam Lantinga
f6b92c9b88
Re-added a simplified version of SDL_SetWindowShape()
...
In order to handle mouse click transparency this needs to be implemented inside SDL
2024-02-09 16:04:46 -08:00
SDL Wiki Bot
943ab983cb
Sync SDL3 wiki -> header
2024-02-02 23:10:26 +00:00
Sam Lantinga
5d48f9a63a
Added SDL_CopyProperties()
2024-02-02 15:09:12 -08:00
Sam Lantinga
5b3ee51c6c
Updated copyright for 2024
2024-01-01 13:15:26 -08:00
Ryan C. Gordon
8766aa39d6
Sync wiki -> headers.
2023-11-13 13:03:42 -05:00
Sam Lantinga
bd269b0f41
Added SDL_SetBooleanProperty() and SDL_GetBooleanProperty()
2023-11-12 21:58:58 -08:00
Sam Lantinga
0907f345cb
Added property types: pointer, string, number, float
2023-11-12 10:48:38 -08:00
Ryan C. Gordon
aa7baf63aa
Sync wiki -> headers.
2023-11-09 20:11:23 -05:00
Sam Lantinga
979214363f
Added SDL_GetGlobalProperties()
...
We'll undoubtedly want to have global properties available
2023-11-08 12:01:48 -08:00
Sam Lantinga
aea6e6de6f
Simplified SDL_SetProperty() and added SDL_SetPropertyWithCleanup()
...
Most of the time people won't need to set a cleanup callback, so we can simplify the more commonly used API.
2023-11-08 12:01:48 -08:00
Sam Lantinga
8668943746
Standardized property names for internal SDL properties
2023-11-08 12:01:48 -08:00
Ryan C. Gordon
c53843a961
docs: Remove Doxygen \brief tags.
...
Doxygen and the wiki bridge don't need them; they'll both just use the first
line/sentence instead.
Fixes #8446 .
2023-11-06 10:26:06 -05:00
Sam Lantinga
1f8f82b379
Removed redundant thread-safety information
2023-10-18 22:19:50 -07:00
SDL Wiki Bot
a6edc75fe7
Sync SDL3 wiki -> header
2023-10-19 05:18:12 +00:00
Sam Lantinga
3c8edeb79b
Clarified SDL property thread-safety information
2023-10-18 22:17:02 -07:00
SDL Wiki Bot
4fa821cb3e
Sync SDL3 wiki -> header
2023-10-19 05:14:13 +00:00
Sam Lantinga
1c70760c0b
Added thread-safety information for the new SDL properties API
2023-10-18 22:13:33 -07:00
Ryan C. Gordon
ac71831350
Sync wiki -> headers
2023-10-12 15:20:53 -04:00
Sam Lantinga
4368f70ff9
Added properties to various SDL objects
...
The following objects now have properties that can be user modified:
* SDL_AudioStream
* SDL_Gamepad
* SDL_Joystick
* SDL_RWops
* SDL_Renderer
* SDL_Sensor
* SDL_Surface
* SDL_Texture
* SDL_Window
2023-10-11 22:38:00 -07:00
Sam Lantinga
973c8b3273
Added SDL properties API
...
Fixes https://github.com/libsdl-org/SDL/issues/7799
2023-10-11 22:38:00 -07:00
