API to get (and maybe set?) individual pixels in a surface

[smcv]

When writing regression tests or assertions, particularly around image endianness, it's useful to be able to say things like "the pixel at (15,13) should have value rgba(1, 2, 3, 4)".

However, it's not at all obvious how to do this correctly for formats that are not 32 bits per pixel, as evidenced by SDLTest_CompareSurfaces() having been wrong for RGB24 on big-endian platforms ever since it was added (fixed in #8317). As seen in #8317, you have to memcpy the right number of bytes into the low-order bits of a Uint32 (which do not necessarily start at byte 0!), and then pass that to SDL_GetRGBA() to decode it into its colour channels.

I think it might be useful to have something like:

SDL_bool SDL_ReadSurfacePixel(SDL_Surface *, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

which would do the rowstride arithmetic internally, and let you do something like:

SDL_assert_always (SDL_ReadSurfacePixel(surface, 15, 13, &r, &g, &b, &a));
SDL_assert_always (r == 1);
SDL_assert_always (g == 2);
...

This would have to lock the surface if it's in a non-trivial format, so it could be slow, but that's fine for something testing-oriented. (Because locking is refcounted, interfaces that iterate through an image, like SDLTest_CompareSurfaces(), could speed this up considerably by locking before iteration and unlocking afterwards.)

For completeness we could also have

SDL_bool SDL_WriteSurfacePixel(SDL_Surface *, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

but that seems less useful in practice.

[smcv]

See also #8320 and particularly #8320 (comment). It would probably be useful to have this as an internal function to be shared by SDLTest_CompareSurfaces and the shape stuff, even if it isn't public API.

[sulix]

See also: #4867

IIRC, there was some pushback to making this function/macro public (as it could be very slow), but we've clearly implemented this incorrectly often enough that having some helper would make sense (even if callers are later optimised to avoid using it).

[smcv]

On #4867, @slouken wrote:

We don't want the overhead of a function call for each pixel

... but Standard C says memcpy() is the only valid way to do potentially-unaligned accesses, and a decent compiler will optimize memcpy() into whatever is the best way to do a potentially-unaligned access (on x86, it usually ends up being the same machine code as the pointer cast).

I think part of the problem here is that SDL carefully avoids using memcpy() because it doesn't want a C runtime library dependency, and instead uses SDL_memcpy(), but compilers don't know that they can optimize away SDL_memcpy() and turn it into inlined machine code.

[icculus]

I would rather this not end up in the public API, but we can add it to libSDL_test.