像素管理子系统（CategoryPixels）

SDL 提供一套完整的像素管理工具集，核心聚焦于像素格式的处理——即解析一组二进制位具体代表的颜色含义。

如果你仅需将像素理解为红、绿、蓝（RGB）及透明度（Alpha）的组合，相关操作会非常直观，且这种程度的认知足以满足多数游戏开发需求。

但像素的实际定义远比这复杂：

颜色空间：像素是特定颜色空间中颜色的表示形式，SDL 主要支持两种颜色类型：
- RGB：由红、绿、蓝三色通道叠加形成屏幕显示的颜色（参考：https://en.wikipedia.org/wiki/RGB_color_model）；
- YCbCr（也称 YUV）：由亮度分量 Y、红色色度偏移 Cb、蓝色色度偏移 Cr 组成，利用人眼对亮度更敏感的特性，Cb/Cr 分量常被压缩且分辨率低于 Y 分量（参考：https://en.wikipedia.org/wiki/YCbCr）。
色度位置：YCbCr 压缩时，Y 分量保持全分辨率，单个 Cb/Cr 像素代表一块 Y 像素的平均色度，色度位置定义了该色度信息在像素块中的来源位置；
颜色范围：定义像素值转换为显示颜色时的有效数值范围——全范围使用像素位的完整数值区间，窄范围因历史原因仅使用部分区间；
原色与白点：基于标准 XYZ 色彩空间定义当前颜色空间的颜色基准（参考：https://en.wikipedia.org/wiki/CIE_1931_color_space）；
传输特性（OETF）：将线性数学空间的颜色转换为非线性输出信号的方式（参考：https://en.wikipedia.org/wiki/Rec._709#Transfer_characteristics）；
矩阵系数：用于 YCbCr 与 RGB 颜色空间的相互转换。

函数

SDL_CreatePalette：创建调色板对象（用于索引色像素格式）
SDL_DestroyPalette：销毁调色板对象（释放资源）
SDL_GetMasksForPixelFormat：根据像素格式获取 RGBA 掩码（解析像素各通道的二进制位）
SDL_GetPixelFormatDetails：获取像素格式的详细信息（包含颜色空间、位深等）
SDL_GetPixelFormatForMasks：根据 RGBA 掩码反查对应的像素格式
SDL_GetPixelFormatName：获取像素格式的名称字符串（如 "SDL_PIXELFORMAT_RGBA8888"）
SDL_GetRGB：从像素值中提取 RGB 分量（无 Alpha）
SDL_GetRGBA：从像素值中提取 RGBA 全部分量
SDL_MapRGB：将 RGB 颜色值转换为指定像素格式的像素值（无 Alpha）
SDL_MapRGBA：将 RGBA 颜色值转换为指定像素格式的像素值
SDL_MapSurfaceRGB：将 RGB 颜色值转换为 SDL_Surface 对应格式的像素值（无 Alpha）
SDL_MapSurfaceRGBA：将 RGBA 颜色值转换为 SDL_Surface 对应格式的像素值
SDL_SetPaletteColors：设置调色板中的颜色数组（批量更新索引色）

数据类型

（无）

结构体

SDL_Color：颜色结构体（整数格式，RGBA 各分量 0-255）
SDL_FColor：浮点颜色结构体（浮点格式，RGBA 各分量 0.0-1.0）
SDL_Palette：调色板结构体（存储索引色对应的颜色数组）
SDL_PixelFormatDetails：像素格式详情结构体（包含颜色类型、位深、掩码等）

枚举

SDL_ArrayOrder：数组型像素格式的通道顺序（如 RGB、BGR）
SDL_BitmapOrder：位图像素的位序（高位优先/低位优先）
SDL_ChromaLocation：YCbCr 色度位置枚举（定义色度采样点）
SDL_ColorPrimaries：颜色原色枚举（如 BT.709、BT.2020）
SDL_ColorRange：颜色范围枚举（全范围/窄范围）
SDL_Colorspace：颜色空间枚举（包含颜色类型、范围、原色等组合）
SDL_ColorType：颜色类型枚举（RGB/YCbCr）
SDL_MatrixCoefficients：颜色转换矩阵系数枚举（YCbCr↔RGB 转换用）
SDL_PackedLayout：打包像素格式的布局枚举（如 32 位 RGBA 各通道位分配）
SDL_PackedOrder：打包像素格式的通道顺序枚举
SDL_PixelFormat：像素格式枚举（如 RGBA8888、YV12 等）
SDL_PixelType：像素类型枚举（整型/浮点型/索引色等）
SDL_TransferCharacteristics：传输特性枚举（如 BT.709、sRGB）

宏

SDL_ALPHA_OPAQUE：不透明 Alpha 值（整数，255）
SDL_ALPHA_OPAQUE_FLOAT：不透明 Alpha 值（浮点，1.0）
SDL_ALPHA_TRANSPARENT：完全透明 Alpha 值（整数，0）
SDL_ALPHA_TRANSPARENT_FLOAT：完全透明 Alpha 值（浮点，0.0）
SDL_BITSPERPIXEL：计算像素格式的每像素位数（如 RGBA8888 为 32）
SDL_BYTESPERPIXEL：计算像素格式的每像素字节数（如 RGBA8888 为 4）
SDL_COLORSPACECHROMA：从颜色空间枚举中提取色度位置
SDL_COLORSPACEMATRIX：从颜色空间枚举中提取矩阵系数
SDL_COLORSPACEPRIMARIES：从颜色空间枚举中提取颜色原色
SDL_COLORSPACERANGE：从颜色空间枚举中提取颜色范围
SDL_COLORSPACETRANSFER：从颜色空间枚举中提取传输特性
SDL_COLORSPACETYPE：从颜色空间枚举中提取颜色类型
SDL_DEFINE_COLORSPACE：定义自定义颜色空间枚举值
SDL_DEFINE_PIXELFORMAT：定义自定义像素格式枚举值
SDL_DEFINE_PIXELFOURCC：通过 FOURCC 码定义像素格式
SDL_ISCOLORSPACE_FULL_RANGE：判断颜色空间是否为全范围
SDL_ISCOLORSPACE_LIMITED_RANGE：判断颜色空间是否为窄范围
SDL_ISCOLORSPACE_MATRIX_BT2020_NCL：判断颜色空间矩阵是否为 BT.2020 NCL
SDL_ISCOLORSPACE_MATRIX_BT601：判断颜色空间矩阵是否为 BT.601
SDL_ISCOLORSPACE_MATRIX_BT709：判断颜色空间矩阵是否为 BT.709
SDL_ISPIXELFORMAT_10BIT：判断像素格式是否为 10 位深度
SDL_ISPIXELFORMAT_ALPHA：判断像素格式是否包含 Alpha 通道
SDL_ISPIXELFORMAT_ARRAY：判断像素格式是否为数组型（如 planar YUV）
SDL_ISPIXELFORMAT_FLOAT：判断像素格式是否为浮点型
SDL_ISPIXELFORMAT_FOURCC：判断像素格式是否为 FOURCC 定义
SDL_ISPIXELFORMAT_INDEXED：判断像素格式是否为索引色（调色板）
SDL_ISPIXELFORMAT_PACKED：判断像素格式是否为打包型（如 RGBA8888）
SDL_PIXELFLAG：像素格式标志位（内部宏）
SDL_PIXELLAYOUT：提取像素格式的布局信息
SDL_PIXELORDER：提取像素格式的通道顺序
SDL_PIXELTYPE：提取像素格式的类型（整型/浮点型等）

FreeBASIC 示例代码

' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL 库）
#Include "SDL.bi"

' 主程序示例
Dim As SDL_Palette Ptr palette = NULL  ' 调色板
Dim As SDL_Color colors(0 To 1)        ' 调色板颜色数组
Dim As UInteger pixelValue             ' 转换后的像素值
Dim As UByte r, g, b, a                ' 提取的 RGBA 分量
Dim As SDL_PixelFormatDetails fmtInfo  ' 像素格式详情

' 1. 创建并设置调色板（索引色示例）
colors(0) = Type<SDL_Color>(0, 0, 0, 255)   ' 索引 0：黑色
colors(1) = Type<SDL_Color>(255, 255, 255, 255) ' 索引 1：白色
palette = SDL_CreatePalette(2, @colors(0))
If (palette = NULL) Then
    SDL_LogError(SDL_LOG_CATEGORY_VIDEO, "创建调色板失败：%s", SDL_GetError())
    End 1
End If

' 2. 像素格式转换示例（RGBA8888 格式）
' 将 RGBA(255, 0, 0, 128) 转换为 RGBA8888 像素值
pixelValue = SDL_MapRGBA(SDL_PIXELFORMAT_RGBA8888, 255, 0, 0, 128)
SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "RGBA(255,0,0,128) 转换为 RGBA8888 像素值：0x%X", pixelValue)

' 从像素值反解 RGBA 分量
SDL_GetRGBA(pixelValue, SDL_PIXELFORMAT_RGBA8888, @r, @g, @b, @a)
SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "反解像素值得到：R=%d, G=%d, B=%d, A=%d", r, g, b, a)

' 3. 获取像素格式详情
If (SDL_GetPixelFormatDetails(SDL_PIXELFORMAT_RGBA8888, @fmtInfo)) Then
    SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "RGBA8888 位深：%d 位", fmtInfo.bits_per_pixel)
    SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "RGBA8888 字节数：%d 字节", fmtInfo.bytes_per_pixel)
    SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "是否含 Alpha：%s", IIf(SDL_ISPIXELFORMAT_ALPHA(SDL_PIXELFORMAT_RGBA8888), "是", "否"))
End If

' 4. 获取像素格式掩码
Dim As UInteger rmask, gmask, bmask, amask
SDL_GetMasksForPixelFormat(SDL_PIXELFORMAT_RGBA8888, @rmask, @gmask, @bmask, @amask)
SDL_LogInfo(SDL_LOG_CATEGORY_VIDEO, "RGBA8888 掩码：R=0x%X, G=0x%X, B=0x%X, A=0x%X", rmask, gmask, bmask, amask)

' 5. 清理资源
If (palette <> NULL) Then SDL_DestroyPalette(palette)

End 0

总结

SDL 像素管理子系统核心是像素格式的转换与解析，SDL_MapRGBA/SDL_GetRGBA 是最常用的函数，用于 RGB 颜色与像素值的双向转换；
FreeBASIC 中使用时，需明确目标像素格式（如 SDL_PIXELFORMAT_RGBA8888），宏 SDL_BITSPERPIXEL/SDL_BYTESPERPIXEL 可快速计算像素位深/字节数；
调色板（SDL_Palette）仅用于索引色像素格式，RGB/YCbCr 等真彩色格式无需调色板，需注意不同颜色空间（RGB/YCbCr）的转换依赖矩阵系数。