From e14ba41689c2888bd0097558a5f1957dbb24dc8b Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Wed, 8 May 2024 03:52:31 -0400 Subject: [PATCH] Some minor documentation tweaks. --- include/SDL3/SDL_pixels.h | 84 +++++++++++++++++++-------------------- include/SDL3/SDL_vulkan.h | 2 +- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index 1fbd9c52c0..2b6f36f921 100644 --- a/include/SDL3/SDL_pixels.h +++ b/include/SDL3/SDL_pixels.h @@ -19,48 +19,6 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_pixels.h - * - * Header for the enumerated pixel format definitions. - * - * SDL's pixel formats have the following naming convention: - * - * * Names with a list of components and a single bit count, such as - * RGB24 and ABGR32, define a platform-independent encoding into - * bytes in the order specified. For example, in RGB24 data, each - * pixel is encoded in 3 bytes (red, green, blue) in that order, - * and in ABGR32 data, each pixel is encoded in 4 bytes - * (alpha, blue, green, red) in that order. Use these names if the - * property of a format that is important to you is the order of - * the bytes in memory or on disk. - * - * * Names with a bit count per component, such as ARGB8888 and - * XRGB1555, are "packed" into an appropriately-sized integer in - * the platform's native endianness. For example, ARGB8888 is - * a sequence of 32-bit integers; in each integer, the most - * significant bits are alpha, and the least significant bits are - * blue. On a little-endian CPU such as x86, the least significant - * bits of each integer are arranged first in memory, but on a - * big-endian CPU such as s390x, the most significant bits are - * arranged first. Use these names if the property of a format that - * is important to you is the meaning of each bit position within a - * native-endianness integer. - * - * * In indexed formats such as INDEX4LSB, each pixel is represented - * by encoding an index into the palette into the indicated number - * of bits, with multiple pixels packed into each byte if appropriate. - * In LSB formats, the first (leftmost) pixel is stored in the - * least-significant bits of the byte; in MSB formats, it's stored - * in the most-significant bits. INDEX8 does not need LSB/MSB - * variants, because each pixel exactly fills one byte. - * - * The 32-bit byte-array encodings such as RGBA32 are aliases for the - * appropriate 8888 encoding for the current platform. For example, - * RGBA32 is an alias for ABGR8888 on little-endian CPUs like x86, - * or an alias for RGBA8888 on big-endian CPUs. - */ - #ifndef SDL_pixels_h_ #define SDL_pixels_h_ @@ -211,7 +169,47 @@ typedef enum SDL_PackedLayout #define SDL_ISPIXELFORMAT_FOURCC(format) \ ((format) && (SDL_PIXELFLAG(format) != 1)) -/* Note: If you modify this list, update SDL_GetPixelFormatName() */ +/* Note: If you modify this enum, update SDL_GetPixelFormatName() */ + +/** + * All pixel formats known to SDL. + * + * SDL's pixel formats have the following naming convention: + * + * - Names with a list of components and a single bit count, such as + * RGB24 and ABGR32, define a platform-independent encoding into + * bytes in the order specified. For example, in RGB24 data, each + * pixel is encoded in 3 bytes (red, green, blue) in that order, + * and in ABGR32 data, each pixel is encoded in 4 bytes + * alpha, blue, green, red) in that order. Use these names if the + * property of a format that is important to you is the order of + * the bytes in memory or on disk. + * - Names with a bit count per component, such as ARGB8888 and + * XRGB1555, are "packed" into an appropriately-sized integer in + * the platform's native endianness. For example, ARGB8888 is + * a sequence of 32-bit integers; in each integer, the most + * significant bits are alpha, and the least significant bits are + * blue. On a little-endian CPU such as x86, the least significant + * bits of each integer are arranged first in memory, but on a + * big-endian CPU such as s390x, the most significant bits are + * arranged first. Use these names if the property of a format that + * is important to you is the meaning of each bit position within a + * native-endianness integer. + * - In indexed formats such as INDEX4LSB, each pixel is represented + * by encoding an index into the palette into the indicated number + * of bits, with multiple pixels packed into each byte if appropriate. + * In LSB formats, the first (leftmost) pixel is stored in the + * least-significant bits of the byte; in MSB formats, it's stored + * in the most-significant bits. INDEX8 does not need LSB/MSB + * variants, because each pixel exactly fills one byte. + * + * The 32-bit byte-array encodings such as RGBA32 are aliases for the + * appropriate 8888 encoding for the current platform. For example, + * RGBA32 is an alias for ABGR8888 on little-endian CPUs like x86, + * or an alias for RGBA8888 on big-endian CPUs. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_PixelFormatEnum { SDL_PIXELFORMAT_UNKNOWN, diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h index bae2e694ad..05a5c559e1 100644 --- a/include/SDL3/SDL_vulkan.h +++ b/include/SDL3/SDL_vulkan.h @@ -99,7 +99,7 @@ struct VkAllocationCallbacks; * * \since This function is available since SDL 3.0.0. * - * \sa SDL_Vulkan_GetVkInstanceProcAddr + * \sa SDL_Vulkan_GetVkGetInstanceProcAddr * \sa SDL_Vulkan_UnloadLibrary */ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);