textures, surfaces, pixels

[bottle2]

hi,

I'm a very wary person.

suppose this snippet runs infallibly:

void example(SDL_Renderer *r, SDL_TextureAccess ta) {
    SDL_assert(ta & SDL_TEXTUREACCESS_STREAMING);
    SDL_PixelFormat pf = *SDL_GetPointerProperty(SDL_GetRendererProperties(r), SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER, NULL);
    SDL_PixelFormatDetails *pfd = SDL_GetPixelFormatDetails(pf);
    int w = 400;
    SDL_Texture t = SDL_CreateTexture(r, pf, ta, w, 300);
    void *pixels;
    int pitch;
    SDL_LockTexture(t, NULL, &pixels, &pitch);
}

referring to the variables present in the previous snippet, please detail the following in the documentation:

1. Assert the range of pfd->bytes_per_pixel: is it always one of 1, 2 and 4, or could it also be 0, 3 or 5?
   • I suppose it is always <= 4 because SDL_{Get,Set}RGB works with Uint32
   • Consequently, the range of pfd->bits_per_pixel is always <= 32 right?
2. pixels is never packed, right? that is, when pfd->bits_per_pixel is a non-multiple of 8, such as 15, can I be assured a sequence of pixels is NOT a sequence of 15 bits one after another? that there is some padding separating pixels, such that they are aligned with some byte boundary?
   • I have no experience with packed arrays. I have no idea how byte order interacts nor how to retrieve and set values at all
3. Say pfd->bytes_per_pixel is 3. Is the stride actually 4 bytes, or must I do some hackery using unsigned char * or some special-purpose struct {char a[3]; } in order to index in multiples of 3 bytes? Since uint24_t doesn't exist (unless using C23 _BitInt(24)). How painful is setting and retrieving pixels, also considering byte-order issues? Specially without overwriting neighbor pixels. Please, document
4. The following always holds, right? pitch >= w * next_highest_power_of_2(pfd->bytes_per_pixel)
   • 1 == next_highest_power_of_2(1)
   • 2 == next_highest_power_of_2(2)
   • 4 == next_highest_power_of_2(3)
   • 4 == next_highest_power_of_2(4)
   • Otherwise, detail one or more cases where pitch could be longer or smaller
     • Could it be related to some kind of padding? such as alluded in https://wiki.libsdl.org/SDL3/SDL_UpdateTexture?
     • If so, is the remainder of the SDL API prepared to behave correctly given such unusual pitches?
5. How all this pixel indexing interacts with C strict aliasing rules? Assert whether -fno-strict-aliasing is mandatory to compile translation units that deal with textures and surfaces

furthermore, I'm coming from SDL2. as I was writing this, I struggled to understand the replacement for https://wiki.libsdl.org/SDL2/SDL_RendererInfo. I now understand the new API using SDL_{Get,Set}{Pointer,String,Number,Float,Boolean}Property.

for each of the following pages:

• https://wiki.libsdl.org/SDL3/SDL_GetRendererProperties
• https://wiki.libsdl.org/SDL3/SDL_GetWindowProperties
• https://wiki.libsdl.org/SDL3/SDL_GetDisplayProperties
• https://wiki.libsdl.org/SDL3/SDL_GetAudioStreamProperties
• https://wiki.libsdl.org/SDL3/SDL_GetCameraProperties
• https://wiki.libsdl.org/SDL3/SDL_GetGamepadProperties
• https://wiki.libsdl.org/SDL3/SDL_GetGlobalProperties
• https://wiki.libsdl.org/SDL3/SDL_GetIOProperties
• https://wiki.libsdl.org/SDL3/SDL_GetJoystickProperties
• https://wiki.libsdl.org/SDL3/SDL_GetProcessProperties
• https://wiki.libsdl.org/SDL3/SDL_GetSensorProperties
• https://wiki.libsdl.org/SDL3/SDL_GetSurfaceProperties
• https://wiki.libsdl.org/SDL3/SDL_GetTextureProperties

please:

1. link the page https://wiki.libsdl.org/SDL3/CategoryProperties in each of the pages above
2. tell that the returned Uint32 of each of the functions above must be the first parameter to this family of property functions
3. tell explicitly that each of the constants of each Remarks section are strings
4. tell that each such constants are the second parameter of any of the property functions

quick links:

• https://wiki.libsdl.org/SDL3/SDL_CreateTexture
• https://wiki.libsdl.org/SDL3/SDL_PixelFormat
• https://wiki.libsdl.org/SDL3/SDL_GetPixelFormatDetails
• https://wiki.libsdl.org/SDL3/SDL_PixelFormatDetails
• https://github.com/libsdl-org/SDL/blob/main/test/testcustomcursor.c#L124
• https://github.com/libsdl-org/SDL/blob/main/test/testutils.c#L101
• https://stackoverflow.com/questions/55107529/how-to-create-a-1-bit-per-pixel-surface-with-sdl2

final thoughts

I think some information from surface stuff helps understand texture stuff, but I can never be sure every knowledge translates 1:1
my main worries can be summarized: packing, byte order, indexing and strict aliasing
I don't even want to think CHAR_BIT