Currently, all SDL_Surfaces with an indexed pixel format have an
associated SDL_Palette. This palette either consists of entirely the
colour black, or -- in the special case of 1-bit surfaces, black and
white.
When an indexed surface is blitted to another indexed surface, a 'map'
is generated from the source surface's palette to the destination
surfaces palette, in order to preserve the look of the image if the
palettes differ.
However, in most cases, applications will want to blit the raw index
values, rather than translate to make the colours as similar as
possible. For instance, the destination surface's palette may have been
modified to fade the screen out.
This change allows an indexed surface to have no associated palette. If
either the source or destination surface of a blit do not have a
palette, then the raw indices are copied (assuming both have an indexed
format).
This mimics better what happens with most other APIs (such as
DirectDraw), where most users do not set a palette on any surface but
the screen, whose palette is implicitly used for the whole application.
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 better reflects how HDR content is actually used, e.g. most content is in the SDR range, with specular highlights and bright details beyond the SDR range, in the HDR headroom.
This more closely matches how HDR is handled on Apple platforms, as EDR.
This also greatly simplifies application code which no longer has to think about color scaling. SDR content is rendered at the appropriate brightness automatically, and HDR content is scaled to the correct range for the display HDR headroom.
These functions historically didn't set the error indicator on overflow.
Before commit 447b508a "error: SDL's allocators now call SDL_OutOfMemory
on error", their callers would call SDL_OutOfMemory() instead, which was
assumed to be close enough in meaning: "that's a silly amount of memory
that would overflow size_t" is similar to "that's more memory than
is available". Now that responsibility for calling SDL_OutOfMemory()
has been pushed down into SDL_calloc() and friends, the functions that
check for overflows might as well set more specific errors.
Signed-off-by: Simon McVittie <smcv@collabora.com>
We'll use properties for new data associated with a surface, which lets us preserve ABI compatibility with SDL2 and any surfaces created by applications and passed in to SDL functions.
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 was legal before, but the Android NDK wants to make sure we didn't mean
for this function to be marked `static` since it didn't have a formal
declaration before its definition and might only be used in the one source
file.)
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
This shares its implementation with SDLTest_ReadSurfacePixel: the same
code is compiled twice, to get it into the static test library and also
the public shared library.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The destination rectangle passed to SDL_BlitSurface() and SDL_BlitSurfaceScaled() is non-const and filled in with the final destination rectangle after clipping, and now documented as such.
Fixes https://github.com/libsdl-org/SDL/issues/7911
This takes care of the last set of void functions that could
potentially be shifted to instead return an int indicating success and
setting an error in case of an error.
