2D渲染子系统（CategoryRender）

SDL 2D 渲染功能的头文件，该 API 专为简化 2D 图形绘制设计，核心特性如下：

支持绘制基础图元：单点像素、单像素线条、填充矩形、纹理图像、2D 多边形；
图元绘制模式：不透明、混合、叠加（加法）模式；
纹理绘制能力：支持不透明/混合/叠加模式，可添加颜色色调、透明度调制，也支持线性插值拉伸；
设计目标：专注加速简单 2D 操作；若需 3D 多边形、粒子特效等高级功能，建议使用 SDL 的 OpenGL/Direct3D 支持、SDL3 GPU API 或第三方 3D 引擎。

⚠️ 注意：所有渲染函数必须在主线程调用，详情参考：https://github.com/libsdl-org/SDL/issues/986

函数

SDL_AddVulkanRenderSemaphores：为 Vulkan 渲染添加信号量同步
SDL_ConvertEventToRenderCoordinates：将事件中的坐标转换为渲染坐标系
SDL_CreateGPURenderer：创建基于 GPU 的渲染器（高性能渲染）
SDL_CreateGPURenderState：创建 GPU 渲染状态（配置渲染管线）
SDL_CreateRenderer：创建默认渲染器（自动选择硬件/软件渲染）
SDL_CreateRendererWithProperties：按自定义属性创建渲染器
SDL_CreateSoftwareRenderer：创建纯软件渲染器（无硬件加速）
SDL_CreateTexture：创建纹理对象（存储图像数据）
SDL_CreateTextureFromSurface：从 SDL_Surface 创建纹理（常用图像加载后转换）
SDL_CreateTextureWithProperties：按自定义属性创建纹理
SDL_CreateWindowAndRenderer：一键创建窗口和渲染器（简化初始化）
SDL_DestroyGPURenderState：销毁 GPU 渲染状态
SDL_DestroyRenderer：销毁渲染器（释放资源）
SDL_DestroyTexture：销毁纹理（释放图像资源）
SDL_FlushRenderer：刷新渲染器队列（强制执行待渲染命令）
SDL_GetCurrentRenderOutputSize：获取当前渲染输出的像素尺寸
SDL_GetDefaultTextureScaleMode：获取默认的纹理缩放模式
SDL_GetGPURendererDevice：获取 GPU 渲染器关联的设备句柄
SDL_GetNumRenderDrivers：获取系统支持的渲染驱动数量
SDL_GetRenderClipRect：获取渲染裁剪矩形（仅绘制矩形内区域）
SDL_GetRenderColorScale：获取渲染颜色缩放系数
SDL_GetRenderDrawBlendMode：获取当前渲染绘制的混合模式
SDL_GetRenderDrawColor：获取当前渲染绘制的颜色（整数格式，0-255）
SDL_GetRenderDrawColorFloat：获取当前渲染绘制的颜色（浮点格式，0.0-1.0）
SDL_GetRenderDriver：获取指定索引的渲染驱动信息
SDL_GetRenderer：获取窗口关联的渲染器
SDL_GetRendererFromTexture：获取纹理所属的渲染器
SDL_GetRendererName：获取渲染器名称（如 "direct3d11"、"opengl"）
SDL_GetRendererProperties：获取渲染器的属性集合
SDL_GetRenderLogicalPresentation：获取渲染逻辑显示模式（适配不同分辨率）
SDL_GetRenderLogicalPresentationRect：获取渲染逻辑显示矩形
SDL_GetRenderMetalCommandEncoder：获取 Metal 渲染的命令编码器（macOS/iOS）
SDL_GetRenderMetalLayer：获取 Metal 渲染层（macOS/iOS）
SDL_GetRenderOutputSize：获取渲染器输出的尺寸
SDL_GetRenderSafeArea：获取渲染安全区域（避免屏幕刘海/圆角遮挡）
SDL_GetRenderScale：获取渲染缩放比例
SDL_GetRenderTarget：获取当前渲染目标（默认是窗口，也可设为纹理）
SDL_GetRenderTextureAddressMode：获取纹理寻址模式（如重复、 clamp）
SDL_GetRenderViewport：获取当前渲染视口
SDL_GetRenderVSync：获取垂直同步（VSync）状态
SDL_GetRenderWindow：获取渲染器关联的窗口
SDL_GetTextureAlphaMod：获取纹理透明度调制值（整数格式）
SDL_GetTextureAlphaModFloat：获取纹理透明度调制值（浮点格式）
SDL_GetTextureBlendMode：获取纹理的混合模式
SDL_GetTextureColorMod：获取纹理颜色调制值（整数格式）
SDL_GetTextureColorModFloat：获取纹理颜色调制值（浮点格式）
SDL_GetTexturePalette：获取纹理的调色板（针对调色板纹理）
SDL_GetTextureProperties：获取纹理的属性集合
SDL_GetTextureScaleMode：获取纹理的缩放模式
SDL_GetTextureSize：获取纹理的像素尺寸
SDL_LockTexture：锁定纹理（获取像素缓冲区，可修改纹理数据）
SDL_LockTextureToSurface：锁定纹理并转换为 SDL_Surface（便于像素操作）
SDL_RenderClear：清空渲染目标（用当前绘制颜色填充）
SDL_RenderClipEnabled：检查渲染裁剪是否启用
SDL_RenderCoordinatesFromWindow：将窗口坐标转换为渲染坐标
SDL_RenderCoordinatesToWindow：将渲染坐标转换为窗口坐标
SDL_RenderDebugText：渲染调试文本（简单文字输出）
SDL_RenderDebugTextFormat：渲染格式化调试文本（支持占位符）
SDL_RenderFillRect：填充单个矩形
SDL_RenderFillRects：批量填充多个矩形
SDL_RenderGeometry：渲染几何图形（基于顶点/索引数据）
SDL_RenderGeometryRaw：渲染原始几何数据（无封装，高性能）
SDL_RenderLine：绘制单条线段
SDL_RenderLines：批量绘制多条线段
SDL_RenderPoint：绘制单个点
SDL_RenderPoints：批量绘制多个点
SDL_RenderPresent：提交渲染结果（将后台缓冲区显示到窗口）
SDL_RenderReadPixels：读取渲染目标的像素数据
SDL_RenderRect：绘制矩形边框
SDL_RenderRects：批量绘制多个矩形边框
SDL_RenderTexture：绘制纹理（基础接口）
SDL_RenderTexture9Grid：9宫格绘制纹理（适配拉伸不变形）
SDL_RenderTexture9GridTiled：9宫格平铺绘制纹理
SDL_RenderTextureAffine：仿射变换绘制纹理（平移/旋转/缩放）
SDL_RenderTextureRotated：旋转绘制纹理
SDL_RenderTextureTiled：平铺绘制纹理
SDL_RenderViewportSet：设置渲染视口（批量配置）
SDL_SetDefaultTextureScaleMode：设置默认的纹理缩放模式
SDL_SetGPURenderState：设置 GPU 渲染状态
SDL_SetGPURenderStateFragmentUniforms：设置 GPU 渲染状态的片元着色器统一变量
SDL_SetGPURenderStateSamplerBindings：设置 GPU 渲染状态的采样器绑定
SDL_SetGPURenderStateStorageBuffers：设置 GPU 渲染状态的存储缓冲区
SDL_SetGPURenderStateStorageTextures：设置 GPU 渲染状态的存储纹理
SDL_SetRenderClipRect：设置渲染裁剪矩形
SDL_SetRenderColorScale：设置渲染颜色缩放系数
SDL_SetRenderDrawBlendMode：设置渲染绘制的混合模式
SDL_SetRenderDrawColor：设置渲染绘制的颜色（整数格式）
SDL_SetRenderDrawColorFloat：设置渲染绘制的颜色（浮点格式）
SDL_SetRenderLogicalPresentation：设置渲染逻辑显示模式
SDL_SetRenderScale：设置渲染缩放比例
SDL_SetRenderTarget：设置渲染目标（可渲染到纹理）
SDL_SetRenderTextureAddressMode：设置纹理寻址模式
SDL_SetRenderViewport：设置渲染视口
SDL_SetRenderVSync：设置垂直同步（开启/关闭）
SDL_SetTextureAlphaMod：设置纹理透明度调制（整数格式）
SDL_SetTextureAlphaModFloat：设置纹理透明度调制（浮点格式）
SDL_SetTextureBlendMode：设置纹理的混合模式
SDL_SetTextureColorMod：设置纹理颜色调制（整数格式）
SDL_SetTextureColorModFloat：设置纹理颜色调制（浮点格式）
SDL_SetTexturePalette：设置纹理的调色板
SDL_SetTextureScaleMode：设置纹理的缩放模式
SDL_UnlockTexture：解锁纹理（完成像素修改后提交）
SDL_UpdateNVTexture：更新 NV12/NV21 格式纹理数据
SDL_UpdateTexture：更新纹理像素数据（通用接口）
SDL_UpdateYUVTexture：更新 YUV 格式纹理数据

数据类型

SDL_GPURenderState：GPU 渲染状态的句柄类型（指向渲染管线配置）
SDL_Renderer：渲染器句柄类型（核心渲染上下文）

结构体

SDL_GPURenderStateCreateInfo：创建 GPU 渲染状态的参数结构体
SDL_Texture：纹理对象结构体（存储图像数据和属性）
SDL_Vertex：顶点结构体（包含位置、颜色、纹理坐标等）

枚举

SDL_RendererLogicalPresentation：渲染逻辑显示模式枚举（适配不同屏幕比例）
SDL_TextureAccess：纹理访问权限枚举（静态/动态/渲染目标）
SDL_TextureAddressMode：纹理寻址模式枚举（重复、 clamp、镜像等）

宏

SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE：调试文本字体的字符尺寸（像素）
SDL_GPU_RENDERER：标识 GPU 渲染器的常量
SDL_SOFTWARE_RENDERER：标识软件渲染器的常量

FreeBASIC 示例代码

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

' 全局变量
Dim As SDL_Window Ptr window = NULL
Dim As SDL_Renderer Ptr renderer = NULL
Dim As SDL_Texture Ptr texture = NULL
Dim As SDL_Rect rect1, rect2  ' 绘制矩形
Dim As Integer quit = 0
Dim As SDL_Event evt

' 初始化 SDL 渲染系统
Function InitRendering() As Integer
    ' 初始化 SDL
    If (SDL_Init(SDL_INIT_VIDEO) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "SDL 初始化失败：%s", SDL_GetError())
        Return 0
    End If

    ' 创建窗口和渲染器（一键创建）
    If (SDL_CreateWindowAndRenderer(800, 600, SDL_WINDOW_SHOWN, @window, @renderer) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "创建窗口/渲染器失败：%s", SDL_GetError())
        Return 0
    End If

    ' 设置渲染器绘制颜色（红色，不透明）
    SDL_SetRenderDrawColor(renderer, 255, 0, 0, 255)

    ' 创建测试纹理（32位RGBA，100x100，动态访问）
    texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA8888, _
        SDL_TEXTUREACCESS_STREAMING, 100, 100)
    If (texture = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "创建纹理失败：%s", SDL_GetError())
        Return 0
    End If

    ' 设置纹理颜色调制（绿色调）
    SDL_SetTextureColorMod(texture, 0, 255, 0)

    ' 定义绘制矩形
    rect1.x = 100 : rect1.y = 100 : rect1.w = 200 : rect1.h = 150  ' 填充矩形
    rect2.x = 400 : rect2.y = 200 : rect2.w = 100 : rect2.h = 100  ' 纹理绘制位置

    Return 1
End Function

' 渲染帧
Sub RenderFrame()
    ' 清空渲染目标（用红色填充）
    SDL_RenderClear(renderer)

    ' 绘制填充矩形（蓝色）
    SDL_SetRenderDrawColor(renderer, 0, 0, 255, 255)
    SDL_RenderFillRect(renderer, @rect1)

    ' 绘制纹理
    SDL_RenderTexture(renderer, texture, NULL, @rect2)

    ' 绘制线段（白色）
    SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255)
    SDL_RenderLine(renderer, 0, 0, 800, 600)

    ' 提交渲染结果到窗口
    SDL_RenderPresent(renderer)
End Sub

' 清理资源
Sub Cleanup()
    If (texture <> NULL) Then SDL_DestroyTexture(texture)
    If (renderer <> NULL) Then SDL_DestroyRenderer(renderer)
    If (window <> NULL) Then SDL_DestroyWindow(window)
    SDL_Quit()
End Sub

' 主程序
If (InitRendering() = 0) Then
    Cleanup()
    End 1
End If

' 主循环
While (quit = 0)
    ' 处理事件
    While (SDL_PollEvent(@evt))
        If (evt.type = SDL_QUITEVENT) Then
            quit = 1
        End If
    Wend

    ' 渲染一帧
    RenderFrame()

    ' 控制帧率（约60FPS）
    SDL_Delay(16)
Wend

' 清理资源
Cleanup()
End 0

总结

SDL 2D 渲染子系统核心是 SDL_Renderer（渲染器）和 SDL_Texture（纹理），所有绘制操作需通过渲染器完成，且必须在主线程调用；
FreeBASIC 中使用时，先通过 SDL_CreateWindowAndRenderer 初始化窗口和渲染器，再调用 SDL_RenderXXX 绘制图元/纹理，最后用 SDL_RenderPresent 提交画面；
纹理是高效绘制图像的核心，支持颜色/透明度调制、缩放/旋转等变换，SDL_CreateTextureFromSurface 是加载图像到纹理的常用方式。