floooh / sokol

minimal cross-platform standalone C headers
https://floooh.github.io/sokol-html5
zlib License
6.63k stars 472 forks source link

sokol_gfx.h: simplify image data specification #880

Open floooh opened 10 months ago

floooh commented 10 months ago

Image data for all image attribute combinations should be described by a single ptr/size pair and a clearly defined and documented memory layout.

Especially figure out a single memory layout for cubemaps with mipmaps that works for all backends. In DDS files, mipmap cascades for faces are packed next to each other: https://learn.microsoft.com/en-us/windows/win32/direct3ddds/dds-file-layout-for-cubic-environment-maps, while in array and 3D textures, slices for one mipmap level are next to each other.

In theory we could define 2 packing conventions:

D3D11 and Metal are flexible enough to allow both layouts, because they require a pointer to each single subsurface (so it doesn't matter how those surfaces are arranged in memory)

GL is restricted in that 2D-array and 3D-texture slices must be packed so that all slices of the same mipmap level are next to each other (because an entire mip-level is defined with a single glTexImage3D() call).

Solution: to allow referencing image data with a single ptr/size pair, and at the same time allow loading most textures directly from DDS file dumps across all backends, the expected memory layout will be the same as in DDS files with the expection of array textures:

Unlike DDS, array textures are expected to be layed out in memory like 3D textures (this is different from the convention used in DDS files - this is so that GL texture creation functions can be used to create array textures without copying data around inside sokol-gfx).