This was intended to make the API public, so SDL_hashtable.h got an extreme
documentation makeover, but for now this remains a private header.
This makes several significant interface changes to SDL_HashTable, and
improves code that makes use of it in various ways.
- The ability to make "stackable" tables is removed. Apparently this still
worked with the current implementation, but I could see a future
implementation struggle mightily to support this. It'll be better for
something external to build on top of the table if it needs it, inserting a
linked list of stacked items as the hash values and managing them separately.
There was only one place in SDL using this, unnecessarily, and that has also
been cleaned up to not need it.
- You no longer specify "buckets" when creating a table, but rather an
estimated number of items the table is meant to hold. The bucket count was
crucial to our classic hashtable implementation, but meant less once we
moved to an Open Addressing implementation anyhow, since the bucket count
isn't static (and they aren't really "buckets" anymore either). Now you
can just report how many items you think the hash will hold and SDL will
allocate a reasonable default for you...or 0 to not guess, and SDL will
start small and grow as necessary, which is often the correct thing to do.
- There's no more SDL_IterateHashTableKey because there's no more "stackable"
hash tables.
- SDL_IterateHashTable() now uses a callback, which matches other parts of SDL,
and also lets us hold the read-lock for the entire iteration and get rid of
the goofy iterator state variable.
- SDL_InsertIntoHashTable() now lets you specify whether to replace existing
keys or fail if the key already exists.
- Callbacks now use SDL conventions (userdata as the first param).
- Other naming convention fixes.
I discovered we use a lot of hash tables in SDL3 internally. :) So the bulk
of this work is fixing up that code to use the new interfaces, and simplifying
things (like checking for an item to remove it if it already exists before
inserting a replacement...just do the insert atomically, it'll do all that
for you!).
Read-write locks are not recursive and can't be upgraded from one type to another, so it's not safe to lock the hash table and then call functions that operate on it. If you really want this functionality, we'd need to create unlocked versions of the hashtable functions and you would call those once you've taken a lock on the hashtable, and we'd have to assert that the operations you're doing are compatible with the type of lock you've taken.
All of that complicates working with hashtables, so if you need that type of access, you should probably just use external locking.
Also marked the existing functions as unsafe, as they can cause crashes if used in multi-threaded applications.
As a bonus, since the new functions are hashtable based, hint environment lookups are much faster.
SDL_Surface has been simplified and internal details are no longer in the public structure.
The `format` member of SDL_Surface is now an enumerated pixel format value. You can get the full details of the pixel format by calling `SDL_GetPixelFormatDetails(surface->format)`. You can get the palette associated with the surface by calling SDL_GetSurfacePalette(). You can get the clip rectangle by calling SDL_GetSurfaceClipRect().
SDL_PixelFormat has been renamed SDL_PixelFormatDetails and just describes the pixel format, it does not include a palette for indexed pixel types.
SDL_PixelFormatEnum has been renamed SDL_PixelFormat and is used instead of Uint32 for API functions that refer to pixel format by enumerated value.
SDL_MapRGB(), SDL_MapRGBA(), SDL_GetRGB(), and SDL_GetRGBA() take an optional palette parameter for indexed color lookups.
This means the allocator's caller doesn't need to use SDL_OutOfMemory directly
if the allocation fails.
This applies to the usual allocators: SDL_malloc, SDL_calloc, SDL_realloc
(all of these regardless of if the app supplied a custom allocator or we're
using system malloc() or an internal copy of dlmalloc under the hood),
SDL_aligned_alloc, SDL_small_alloc, SDL_strdup, SDL_asprintf, SDL_wcsdup...
probably others. If it returns something you can pass to SDL_free, it should
work.
The caller might still need to use SDL_OutOfMemory if something that wasn't
SDL allocated the memory: operator new in C++ code, Objective-C's alloc
message, win32 GlobalAlloc, etc.
Fixes#8642.
This is a race condition if the hashtable isn't protected by a mutex, and it
makes a read/write operation out of something what appears to be read-only,
which is dangerously surprising from an interface viewpoint.
The downside is that if you have an item that is frequently accessed that
isn't in the first slot of a bucket, each find operation will take longer
instead of common items bubbling to the front of the bucket. Then again,
if you have several common things being looked up in rotation, they'll just
be doing unnecessary shuffling here. In this case, it might be better to
just use a larger hashtable or a better hashing function (or just look up the
thing you need once instead of multiple times).
Fixes#8391.
And SDL_IterateHashTableKey is only necessary for stackable hashtables, since
non-stackable ones can either iterate each unique key/value pair with
SDL_IterateHashTable, or get a specific key/value pair by using
SDL_FindInHashTable.
