Applying these changes to external code doesn't actually improve anything, and within the context of the other Get* functions for renderers and surfaces, these stand out as outliers, so I'm going to back this change out.
It also now caches at the higher level, so the platform-specific bits don't
change their interface much.
A little code hygiene work was applied to some of the platform bits on top of
this.
Reference Issue #10229.
While it makes sense to get an object pointer from an object ID, you want to get object attributes for an ID, otherwise e.g. GetNameFromID() sounds like it's a name ID, not an object ID. This is also consistent with the function naming convention in SDL2.
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.
Turns out that there isn't a strong OpenGL naming convention for "Delete" ...
WGL offers "wglDeleteContext" but the GLX equivalent is "glxDestroyContext"
and then EGL sealed the deal by going with Destroy as well! Since it matches
SDL3 naming conventions (Create/Destroy), we're renaming it.
Fixes#10197.
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 was added by the Unreal Engine to handle the input focus for popups and dialogs, window types for which SDL3 has built-in, cross-platform support.
This was only ever implemented in X11, and the only purpose was to hint that a client application may want to call the SDL_SetWindowInputFocus() function, which has since been removed, rendering it pointless now.
This was added to SDL2 for the Unreal Engine's implementation of menus and dialogs on X11, window types for which SDL3 has added built-in, cross-platform support.
Remove this function, as it was only ever implemented for X11 and is now basically useless aside from allowing annoying or malicious client apps to discretely steal focus. As the documentation states: "You almost certainly want SDL_RaiseWindow() instead of this function."
The new function includes the cursor position so IME UI elements can be placed relative to the cursor, as well as having the whole text area available so on-screen keyboards can avoid it.
SDL_StartTextInput(), SDL_StopTextInput(), SDL_TextInputActive(), SDL_ClearComposition(), and SDL_SetTextInputRect() all now take a window parameter.
This change also fixes IME candidate positioning when SDL_SetTextInputRect() is called before SDL_StartTextInput(), as is recommended in the documentation.
These are integer values internally, but the API has been changed to make it easier to mix other render code with querying those values.
Fixes https://github.com/libsdl-org/SDL/issues/7519
