- 最新文章
-
SDL3_API分类参考_像素管理（CategoryPixels） 像素管理子系统（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）的转换依赖矩阵系数。 -
SDL3_API分类参考_2D渲染（CategoryRender） 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 是加载图像到纹理的常用方式。
-
SDL3_API分类参考_版本（CategoryVersion） 版本子系统（CategoryVersion） 用于查询 SDL 版本信息的功能集，可分别获取应用编译时依赖的头文件版本和运行时链接的库文件版本。 函数 SDL_GetRevision：获取 SDL 库的版本修订号（字符串形式，如 git 提交哈希） SDL_GetVersion：获取运行时链接的 SDL 库的版本号（填充 SDL_version 结构体，包含主/次/微版本） 数据类型 （无） 结构体 （无） 枚举 （无） 宏 SDL_MAJOR_VERSION：提取版本号中的主版本号（如 3.1.2 中的 3） SDL_MICRO_VERSION：提取版本号中的微版本号（如 3.1.2 中的 2） SDL_MINOR_VERSION：提取版本号中的次版本号（如 3.1.2 中的 1） SDL_REVISION：SDL 库的编译时修订号（宏定义，静态值） SDL_VERSION：将主/次/微版本号填充到 SDL_version 结构体中（编译时使用） SDL_VERSION_ATLEAST：判断当前 SDL 版本是否≥指定版本（如 SDL_VERSION_ATLEAST(3,0,0)） SDL_VERSIONNUM：将主/次/微版本号合并为一个整数（便于版本比较，格式：主版本1000 + 次版本100 + 微版本） SDL_VERSIONNUM_MAJOR：从合并后的版本整数中提取主版本号 SDL_VERSIONNUM_MICRO：从合并后的版本整数中提取微版本号 SDL_VERSIONNUM_MINOR：从合并后的版本整数中提取次版本号 FreeBASIC 示例代码 ' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL 库） #Include "SDL.bi" ' 主程序示例 Dim As SDL_version linkedVersion ' 存储运行时链接的 SDL 版本 Dim As ZString Ptr revisionStr ' 存储修订号字符串 ' 1. 获取运行时 SDL 库版本 SDL_GetVersion(@linkedVersion) SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "运行时 SDL 版本：%d.%d.%d", _ linkedVersion.major, linkedVersion.minor, linkedVersion.patch) ' 2. 获取 SDL 修订号 revisionStr = SDL_GetRevision() If (revisionStr <> NULL) Then SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL 修订号：%s", revisionStr) Else SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL 修订号：未知") End If ' 3. 编译时版本检查（宏使用） #If SDL_VERSION_ATLEAST(3, 0, 0) Then SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "编译时依赖 SDL 3.x 及以上版本") #Else SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "编译时依赖 SDL 版本低于 3.0.0") #End If ' 4. 版本号数值比较 Dim As UInteger versionNum = SDL_VERSIONNUM(linkedVersion.major, linkedVersion.minor, linkedVersion.patch) SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "版本号数值：%d", versionNum) ' 检查是否满足最低版本要求（如 3.1.0） If (versionNum >= SDL_VERSIONNUM(3, 1, 0)) Then SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "满足 3.1.0 及以上版本要求") Else SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "版本过低，至少需要 SDL 3.1.0") End If ' 5. 提取版本号各部分（宏示例） SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "主版本号：%d", SDL_MAJOR_VERSION(linkedVersion)) SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "次版本号：%d", SDL_MINOR_VERSION(linkedVersion)) SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "微版本号：%d", SDL_MICRO_VERSION(linkedVersion))
-
SDL3_API分类参考_断言（CategoryAssert） 断言子系统（CategoryAssert） SDL 提供的增强型断言宏，功能远超常规的 assert 宏，核心特性如下： 利用 sizeof 运算符特性：禁用的断言会从编译代码中完全移除，且仅在断言中引用的变量不会触发“未使用变量”的编译器警告； 避免悬空 else 问题：支持 if (x) SDL_assert(y); else do_something(); 这类写法，行为稳定； 跨平台一致性：不依赖各平台编译器/C 运行时的实现，所有平台行为统一； 多级别断言：提供 SDL_assert、SDL_assert_release、SDL_assert_paranoid 等不同级别，而非“全有或全无”的单一选项； 丰富的失败响应：断言失败时支持重试、触发调试器、终止程序、单次忽略、永久忽略等操作； 可视化提示：默认尝试弹出对话框提示用户（若平台支持），也可自定义回调函数处理断言失败； 重试机制：断言失败后可重试（比如网络故障修复后重新验证条件）； 忽略选项：支持单次忽略或永久忽略某类无害的断言失败； 统计能力：向应用程序提供所有断言失败的统计数据和详细信息； 环境变量控制：自动化脚本可通过环境变量控制默认断言处理器行为； 静态分析友好：Clang 静态分析会将 SDL 断言视为“恒真”（假设调试构建能检测断言错误），减少误报。 使用方式：编译调试版本时，在代码中按需添加断言检测逻辑即可！ 函数 SDL_GetAssertionHandler：获取当前设置的自定义断言处理函数 SDL_GetAssertionReport：获取所有断言失败的报告（返回 SDL_AssertData 链表） SDL_GetDefaultAssertionHandler：获取 SDL 默认的断言处理函数 SDL_ReportAssertion：手动触发断言报告（底层接口，一般无需直接调用） SDL_ResetAssertionReport：清空所有断言失败的报告数据 SDL_SetAssertionHandler：设置自定义的断言失败处理函数（替换默认逻辑） 数据类型 SDL_AssertionHandler：断言处理函数的函数指针类型（自定义断言处理时需实现） 结构体 SDL_AssertData：存储单个断言失败的详细信息（断言表达式、文件、行号、失败次数等） 枚举 SDL_AssertState：定义断言失败后的处理状态（重试、终止、单次忽略、永久忽略等） 宏 SDL_assert：基础断言宏（调试版本启用，发布版本禁用） SDL_assert_always：强制启用的断言（无论编译模式，始终生效） SDL_ASSERT_FILE：获取断言所在文件路径（内部宏） SDL_ASSERT_LEVEL：定义断言启用级别（控制不同级别断言是否生效） SDL_assert_paranoid：偏执级断言（仅在开启极致调试时启用，用于细粒度检测） SDL_assert_release：发布版本断言（仅在发布版本中启用，检测严重问题） SDL_AssertBreakpoint：触发调试器断点（断言失败时调用） SDL_disabled_assert：禁用断言的占位宏（编译时会被移除） SDL_enabled_assert：启用断言的核心宏（内部实现） SDL_FILE：等价于 FILE，获取当前文件路径 SDL_FUNCTION：等价于 func，获取当前函数名 SDL_LINE：等价于 LINE，获取当前行号 SDL_NULL_WHILE_LOOP_CONDITION：检测 while 循环条件为 NULL 的断言（专用宏） SDL_TriggerBreakpoint：同 SDL_AssertBreakpoint，触发调试断点 FreeBASIC 示例代码 ' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL 库） #Include "SDL.bi" ' 自定义断言处理函数示例 Function CustomAssertHandler Cdecl (ByVal data As SDL_AssertData Ptr, ByVal userdata As Any Ptr) As SDL_AssertState ' 打印断言失败详情 SDL_LogError(SDL_LOG_CATEGORY_ASSERT, "断言失败：") SDL_LogError(SDL_LOG_CATEGORY_ASSERT, " 文件：%s", data->file) SDL_LogError(SDL_LOG_CATEGORY_ASSERT, " 行号：%d", data->line) SDL_LogError(SDL_LOG_CATEGORY_ASSERT, " 函数：%s", data->function_) SDL_LogError(SDL_LOG_CATEGORY_ASSERT, " 表达式：%s", data->condition) SDL_LogError(SDL_LOG_CATEGORY_ASSERT, " 失败次数：%d", data->trigger_count) ' 这里返回“重试”，也可根据需求返回 SDL_ASSERT_ABORT/SDL_ASSERT_IGNORE 等 Return SDL_ASSERT_RETRY End Function ' 主程序示例 Dim As Integer testValue = -1 ' 设置自定义断言处理器 SDL_SetAssertionHandler(@CustomAssertHandler, NULL) ' 示例1：基础断言（调试模式生效） SDL_assert(testValue > 0) ' testValue=-1，断言失败 ' 示例2：始终生效的断言 SDL_assert_always(testValue <> 0) ' 即使发布版本也会触发 ' 示例3：发布版本断言（仅在 release 模式生效） SDL_assert_release(testValue < 100) ' 表达式为真，断言通过 ' 示例4：获取并打印断言报告 Dim As SDL_AssertData Ptr report = SDL_GetAssertionReport() If (report <> NULL) Then SDL_LogInfo(SDL_LOG_CATEGORY_ASSERT, "断言失败总数：%d", report->trigger_count) SDL_ResetAssertionReport() ' 清空报告 End If ' 恢复默认断言处理器 SDL_SetAssertionHandler(SDL_GetDefaultAssertionHandler(), NULL)
-
SDL3_API分类参考_日志（CategoryLog） 日志（CategoryLog） SDL 提供的轻量级日志系统，支持为日志消息设置优先级和分类： 日志的 SDL_LogPriority（日志优先级）用于标识消息的重要程度； 日志的 SDL_LogCategory（日志分类）用于标识消息所属的功能域。 每个日志分类都有预设的最低优先级阈值：只有当消息的优先级大于或等于该阈值时，这条日志才会被实际输出。 SDL 自身的日志默认输出优先级低于默认阈值，因此默认情况下不会主动打印 SDL 内部日志。 你可以通过以下方式动态调整日志输出的详细程度： 编程方式：调用 SDL_SetLogPriority() 或 SDL_SetHint(SDL_HINT_LOGGING, ...)； 环境变量：设置 SDL_LOGGING 环境变量（格式为逗号分隔的 分类=级别 键值对），用于定义 SDL 应用的默认日志级别。 日志分类取值说明 可以是数字编号，或以下预定义字符串： app（应用层）、error（错误）、assert（断言）、system（系统）、audio（音频）、video（视频）、render（渲染）、input（输入）、test（测试）； * 表示所有未单独指定的分类。 日志级别取值说明 可以是数字级别，或以下预定义字符串： trace（追踪）、verbose（详细）、debug（调试）、info（信息）、warn（警告）、error（错误）、critical（严重）； quiet 表示禁用该分类的日志输出。 若省略分类，将为所有分类设置统一的日志级别。 如果未设置 SDL_HINT_LOGGING 提示，默认日志级别等价于： app=info,assert=warn,test=verbose,*=error 不同平台的日志输出目标 Windows：调试输出流（Debug Output）； Android：系统日志（Logcat）； 其他平台：标准错误输出（stderr）。 日志使用注意事项 无需在日志消息末尾添加换行符（\n），函数会自动补充； 为保证跨平台行为一致，不要在单条日志中包含换行符（比如试图一次调用输出多行），这种用法可能导致平台相关的异常行为，建议每行日志单独调用一次函数，且消息中不含换行； 每个日志调用都是原子操作，多线程日志输出时不会出现消息截断的问题。 函数 SDL_GetDefaultLogOutputFunction：获取 SDL 默认的日志输出回调函数 SDL_GetLogOutputFunction：获取当前生效的日志输出回调函数 SDL_GetLogPriority：获取指定日志分类的当前最低输出优先级 SDL_Log：输出一条默认优先级（info）、默认分类（app）的日志（支持格式化字符串） SDL_LogCritical：输出一条“严重”优先级的日志（默认分类为 app） SDL_LogDebug：输出一条“调试”优先级的日志（默认分类为 app） SDL_LogError：输出一条“错误”优先级的日志（默认分类为 app） SDL_LogInfo：输出一条“信息”优先级的日志（默认分类为 app） SDL_LogMessage：输出指定分类、指定优先级的日志（核心通用接口，支持格式化） SDL_LogMessageV：基于 va_list 可变参数列表输出指定分类/优先级的日志（底层实现） SDL_LogTrace：输出一条“追踪”优先级的日志（默认分类为 app） SDL_LogVerbose：输出一条“详细”优先级的日志（默认分类为 app） SDL_LogWarn：输出一条“警告”优先级的日志（默认分类为 app） SDL_ResetLogPriorities：重置所有日志分类的优先级为默认值 SDL_SetLogOutputFunction：设置自定义的日志输出回调函数（替换默认输出逻辑） SDL_SetLogPriorities：批量设置所有日志分类的最低输出优先级（按位掩码） SDL_SetLogPriority：设置指定日志分类的最低输出优先级 SDL_SetLogPriorityPrefix：设置是否在日志中添加优先级前缀（如 [CRITICAL]、[WARN]） 数据类型 SDL_LogOutputFunction：日志输出回调函数的函数指针类型（自定义日志输出时需实现） 结构体 （无） 枚举 SDL_LogCategory：定义日志分类的枚举（如应用、音频、视频、错误等） SDL_LogPriority：定义日志优先级的枚举（如追踪、调试、信息、警告、错误、严重等） 宏 （无） FreeBASIC 示例代码 ' 引入 SDL 相关声明（需确保 FreeBASIC 已链接 SDL 库） #Include "SDL.bi" ' 示例1：基础日志输出 SDL_Log("应用启动，版本：%s", "1.0.0") ' 默认 info 级别、app 分类 SDL_LogWarn(SDL_LOG_CATEGORY_AUDIO, "音频设备初始化警告：设备数量 = %d", 0) ' 音频分类 警告级别 SDL_LogError(SDL_LOG_CATEGORY_VIDEO, "窗口创建失败：%s", SDL_GetError()) ' 视频分类 错误级别 SDL_LogCritical(SDL_LOG_CATEGORY_SYSTEM, "系统资源不足，程序即将退出") ' 系统分类 严重级别 ' 示例2：调整日志输出级别（让视频分类输出所有级别日志） SDL_SetLogPriority(SDL_LOG_CATEGORY_VIDEO, SDL_LOG_PRIORITY_TRACE) ' 示例3：输出低优先级日志（仅当视频分类级别调整后才会显示） SDL_LogTrace(SDL_LOG_CATEGORY_VIDEO, "视频驱动初始化：检测到 %d 个显示器", SDL_GetNumVideoDisplays()) ' 示例4：重置所有日志优先级为默认值 SDL_ResetLogPriorities()
-
SDL3_API分类参考_错误处理（CategoryError） 错误处理（CategoryError） SDL 提供的轻量级错误消息处理函数集。 绝大多数应用程序只会通过一个核心函数与这些 API 交互：当几乎所有 SDL 函数调用返回失败时，你可以通过 SDL_GetError() 获取该错误对应的人类可读字符串描述。 这些错误字符串是按线程独立维护的，应用程序也可以自定义错误信息（这在基于 SDL 构建供其他应用使用的库时非常常用），只需调用 SDL_SetError() 即可设置自定义错误信息。 一种常见的使用模式是：设计一个返回布尔值的函数（true 表示成功，false 表示失败），当内部操作失败时执行如下逻辑： ' FreeBASIC 示例代码 If (something_went_wrong) Then ' 设置错误信息并返回失败 SDL_SetError("该操作因以下原因失败：错误码 = %d", errcode) Return False End If 另一种常见做法是：如果已知触发失败的底层操作已经调用了 SDL_SetError()，则直接返回 false 即可，错误信息会自动向上传递。 函数 SDL_ClearError：清空当前线程的错误信息 SDL_GetError：获取当前线程的错误描述字符串 SDL_OutOfMemory：抛出“内存不足”错误并返回 0（常用于内存分配失败场景） SDL_SetError：设置自定义错误信息（支持格式化字符串） SDL_SetErrorV：基于 va_list 可变参数列表设置错误信息（底层实现函数） 数据类型 （无） 结构体 （无） 枚举 （无） 宏 SDL_InvalidParamError：快速设置“无效参数”错误（参数：参数名） SDL_Unsupported：快速设置“功能不支持”错误
-
SDL3_API分类参考_对象属性（CategoryProperties） 对象属性（CategoryProperties） 属性（Property）是一种可以在运行时通过名称创建和获取的变量。 所有属性都属于一个属性组（属性组ID：SDL_PropertiesID）。 属性组可通过 SDL_CreateProperties 函数创建，通过 SDL_DestroyProperties 函数销毁。 可通过以下函数向属性组添加/获取属性： SDL_SetPointerProperty / SDL_GetPointerProperty：操作 void* 指针类型 SDL_SetStringProperty / SDL_GetStringProperty：操作字符串类型 SDL_SetNumberProperty / SDL_GetNumberProperty：操作有符号64位整数类型 SDL_SetFloatProperty / SDL_GetFloatProperty：操作浮点类型 SDL_SetBooleanProperty / SDL_GetBooleanProperty：操作布尔类型 可通过 SDL_ClearProperty 从属性组中移除属性。 函数/类型/枚举/宏 翻译 + 简要说明 英文名称 中文翻译 简要说明 SDL_ClearProperty 清除属性 从属性组中移除指定名称的属性 SDL_CopyProperties 复制属性 将一个属性组的所有属性复制到另一个属性组 SDL_CreateProperties 创建属性组 新建一个空的属性组并返回其ID SDL_DestroyProperties 销毁属性组 释放属性组及其所有属性占用的内存 SDL_EnumerateProperties 枚举属性 遍历属性组中所有属性并调用回调函数 SDL_GetBooleanProperty 获取布尔属性 从属性组中读取布尔类型属性值 SDL_GetFloatProperty 获取浮点属性 从属性组中读取浮点类型属性值 SDL_GetGlobalProperties 获取全局属性组 获取SDL全局属性组的ID SDL_GetNumberProperty 获取数值属性 从属性组中读取64位有符号整数属性值 SDL_GetPointerProperty 获取指针属性 从属性组中读取指针类型属性值 SDL_GetPropertyType 获取属性类型 获取指定属性的类型（SDL_PropertyType） SDL_GetStringProperty 获取字符串属性 从属性组中读取字符串类型属性值 SDL_HasProperty 检查属性存在性 判断属性组中是否存在指定名称的属性 SDL_LockProperties 锁定属性组 加锁属性组以保证线程安全 SDL_SetBooleanProperty 设置布尔属性 向属性组写入布尔类型属性值 SDL_SetFloatProperty 设置浮点属性 向属性组写入浮点类型属性值 SDL_SetNumberProperty 设置数值属性 向属性组写入64位有符号整数属性值 SDL_SetPointerProperty 设置指针属性 向属性组写入指针类型属性值 SDL_SetPointerPropertyWithCleanup 设置带清理的指针属性 写入指针属性并指定清理回调函数 SDL_SetStringProperty 设置字符串属性 向属性组写入字符串类型属性值 SDL_UnlockProperties 解锁属性组 释放属性组的线程锁 SDL_CleanupPropertyCallback 属性清理回调函数类型 释放指针属性时的回调函数类型定义 SDL_EnumeratePropertiesCallback 属性枚举回调函数类型 枚举属性时的回调函数类型定义 SDL_PropertiesID 属性组ID类型 标识属性组的唯一ID类型 SDL_PropertyType 属性类型枚举 定义所有支持的属性类型（指针/字符串/数值等） SDL_PROP_NAME_STRING 属性名字符串宏 用于标准化属性名称的宏定义 FreeBASIC 示例代码 ' 编译前需确保已链接SDL2库 ' 编译命令示例：fbc -s console -lSDL2 properties_demo.bas #include "SDL.bi" ' 错误检查宏 #define CHECK_ERROR(ret, msg) if (ret <> 0) then print msg & " 失败，错误：" & *SDL_GetError() : goto cleanup Sub DemoProperties() Dim As SDL_PropertiesID props = SDL_CreateProperties() If (props = 0) Then Print "创建属性组失败，错误：" & *SDL_GetError() Return End If Print "成功创建属性组，ID：" & props ' 1. 设置/获取字符串属性 Dim As Integer ret = SDL_SetStringProperty(props, "window.title", "SDL属性示例") CHECK_ERROR(ret, "设置字符串属性") Dim As ZString Ptr title = SDL_GetStringProperty(props, "window.title", "默认标题") Print "读取窗口标题：" & *title ' 2. 设置/获取数值属性（64位整数） ret = SDL_SetNumberProperty(props, "window.width", 800) CHECK_ERROR(ret, "设置数值属性") Dim As Int64 width = SDL_GetNumberProperty(props, "window.width", 640) Print "读取窗口宽度：" & width ' 3. 设置/获取布尔属性 ret = SDL_SetBooleanProperty(props, "fullscreen", SDL_TRUE) CHECK_ERROR(ret, "设置布尔属性") Dim As SDL_bool fullscreen = SDL_GetBooleanProperty(props, "fullscreen", SDL_FALSE) Print "读取全屏状态：" & IIf(fullscreen = SDL_TRUE, "开启", "关闭") ' 4. 检查属性是否存在 If (SDL_HasProperty(props, "window.height") = SDL_FALSE) Then Print "属性 window.height 不存在，设置默认值 600" ret = SDL_SetNumberProperty(props, "window.height", 600) CHECK_ERROR(ret, "设置默认高度") End If ' 5. 枚举所有属性（自定义回调函数） Print vbCrLf & "枚举所有属性：" Sub EnumerateCallback cdecl (ByVal userdata As Any Ptr, ByVal name As Const ZString Ptr, ByVal type_ As SDL_PropertyType) As SDL_bool Print "属性名：" & *name & "，类型：" & type_ Return SDL_TRUE ' 继续枚举 End Sub SDL_EnumerateProperties(props, @EnumerateCallback, Null) ' 6. 清除单个属性 ret = SDL_ClearProperty(props, "fullscreen") CHECK_ERROR(ret, "清除全屏属性") If (SDL_HasProperty(props, "fullscreen") = SDL_FALSE) Then Print vbCrLf & "已成功清除 fullscreen 属性" End If cleanup: ' 销毁属性组 If (props <> 0) Then SDL_DestroyProperties(props) Print vbCrLf & "已销毁属性组" End If End Sub ' 主程序 SDL_Init(SDL_INIT_VIDEO) DemoProperties() SDL_Quit() Print vbCrLf & "按任意键退出..." Sleep
-
SDL3_API分类参考_配置变量（CategoryHints） 配置变量（CategoryHints） 本文件包含用于设置和获取配置提示（Hint）的函数，并按字母顺序列出所有提示项。 提示的命名规范为 SDL_HINT_X，其中 SDL_X 是可用于覆盖默认值的环境变量名。 通常来说，这些提示仅作参考——在特定平台上可能被支持也可能不适用，但它们为应用程序或用户提供了一种向库告知期望运行方式的途径。 函数 SDL_AddHintCallback - 为指定提示添加值变更时的回调函数 SDL_GetHint - 获取指定提示的当前值 SDL_GetHintBoolean - 将提示值以布尔类型获取 SDL_RemoveHintCallback - 移除提示的回调函数 SDL_ResetHint - 重置单个提示为默认值 SDL_ResetHints - 重置所有提示为默认值 SDL_SetHint - 设置提示的值（普通优先级） SDL_SetHintWithPriority - 按优先级设置提示的值 数据类型 SDL_HintCallback - 提示值变化时的回调函数类型 结构体 (无) 枚举 SDL_HintPriority - 提示设置优先级枚举 宏（提示项） SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED - 鼠标捕获时是否允许 Alt+Tab 切换窗口 SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY - Android 平台是否允许重建 Activity SDL_HINT_ANDROID_BLOCK_ON_PAUSE - Android 暂停时是否阻塞线程 SDL_HINT_ANDROID_LOW_LATENCY_AUDIO - Android 是否开启低延迟音频 SDL_HINT_ANDROID_TRAP_BACK_BUTTON - Android 是否拦截返回键 SDL_HINT_APP_ID - 应用程序 ID SDL_HINT_APP_NAME - 应用程序名称 SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS - Apple TV 手柄是否生成 UI 事件 SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION - Apple TV 遥控器是否允许旋转 SDL_HINT_ASSERT - 断言行为配置 SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE - ALSA 默认音频设备 SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE - ALSA 默认播放设备 SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE - ALSA 默认录音设备 SDL_HINT_AUDIO_CATEGORY - 音频类别（iOS/macOS） SDL_HINT_AUDIO_CHANNELS - 音频通道数 SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME - 音频设备显示的应用图标名 SDL_HINT_AUDIO_DEVICE_RAW_STREAM - 是否使用原始音频流 SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES - 音频设备采样帧数 SDL_HINT_AUDIO_DEVICE_STREAM_NAME - 音频流名称 SDL_HINT_AUDIO_DEVICE_STREAM_ROLE - 音频流角色 SDL_HINT_AUDIO_DISK_INPUT_FILE - 磁盘音频输入文件 SDL_HINT_AUDIO_DISK_OUTPUT_FILE - 磁盘音频输出文件 SDL_HINT_AUDIO_DISK_TIMESCALE - 磁盘音频时间缩放 SDL_HINT_AUDIO_DRIVER - 指定音频驱动 SDL_HINT_AUDIO_DUMMY_TIMESCALE - 虚拟音频时间缩放 SDL_HINT_AUDIO_FORMAT - 音频格式 SDL_HINT_AUDIO_FREQUENCY - 音频采样率 SDL_HINT_AUDIO_INCLUDE_MONITORS - 音频是否包含显示器设备 SDL_HINT_AUTO_UPDATE_JOYSTICKS - 是否自动更新操纵杆状态 SDL_HINT_AUTO_UPDATE_SENSORS - 是否自动更新传感器 SDL_HINT_BMP_SAVE_LEGACY_FORMAT - BMP 保存为旧格式 SDL_HINT_CAMERA_DRIVER - 指定摄像头驱动 SDL_HINT_CPU_FEATURE_MASK - CPU 功能屏蔽掩码 SDL_HINT_DISPLAY_USABLE_BOUNDS - 显示可用区域 SDL_HINT_EGL_LIBRARY - 指定 EGL 库路径 SDL_HINT_EMSCRIPTEN_ASYNCIFY - Emscripten 是否使用 Asyncify SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR - Emscripten Canvas 选择器 SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT - Emscripten 键盘监听元素 SDL_HINT_ENABLE_SCREEN_KEYBOARD - 是否启用屏幕键盘 SDL_HINT_EVDEV_DEVICES - evdev 设备路径 SDL_HINT_EVENT_LOGGING - 事件日志开关 SDL_HINT_FILE_DIALOG_DRIVER - 文件对话框驱动 SDL_HINT_FORCE_RAISEWINDOW - 强制置顶窗口 SDL_HINT_FRAMEBUFFER_ACCELERATION - 帧缓冲加速 SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES - 忽略指定游戏控制器 SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT - 仅保留指定游戏控制器 SDL_HINT_GAMECONTROLLER_SENSOR_FUSION - 游戏手柄传感器融合 SDL_HINT_GAMECONTROLLERCONFIG - 游戏控制器配置字符串 SDL_HINT_GAMECONTROLLERCONFIG_FILE - 游戏控制器配置文件 SDL_HINT_GAMECONTROLLERTYPE - 游戏控制器类型 SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT - GDK 文本输入默认内容 SDL_HINT_GDK_TEXTINPUT_DESCRIPTION - GDK 文本输入描述 SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH - GDK 文本输入最大长度 SDL_HINT_GDK_TEXTINPUT_SCOPE - GDK 文本输入范围 SDL_HINT_GDK_TEXTINPUT_TITLE - GDK 文本输入标题 SDL_HINT_GPU_DRIVER - 指定 GPU 驱动 SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS - HIDAPI 只枚举控制器 SDL_HINT_HIDAPI_IGNORE_DEVICES - HIDAPI 忽略设备 SDL_HINT_HIDAPI_LIBUSB - HIDAPI 使用 libusb SDL_HINT_HIDAPI_LIBUSB_GAMECUBE - libusb 支持 GameCube SDL_HINT_HIDAPI_LIBUSB_WHITELIST - libusb 白名单 SDL_HINT_HIDAPI_UDEV - HIDAPI 使用 udev SDL_HINT_IME_IMPLEMENTED_UI - IME 是否使用自定义 UI SDL_HINT_INVALID_PARAM_CHECKS - 是否检查非法参数 SDL_HINT_IOS_HIDE_HOME_INDICATOR - iOS 隐藏底部指示条 SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS - 后台是否接收摇杆事件 SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES - 街机摇杆设备 SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED - 排除街机摇杆 SDL_HINT_JOYSTICK_BLACKLIST_DEVICES - 摇杆设备黑名单 SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED - 排除摇杆黑名单 SDL_HINT_JOYSTICK_DEVICE - 指定摇杆设备 SDL_HINT_JOYSTICK_DIRECTINPUT - 使用 DirectInput 摇杆 SDL_HINT_JOYSTICK_ENHANCED_REPORTS - 增强摇杆报告 SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES - 飞行摇杆设备 SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED - 排除飞行摇杆 SDL_HINT_JOYSTICK_GAMECUBE_DEVICES - GameCube 设备 SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED - 排除 GameCube SDL_HINT_JOYSTICK_GAMEINPUT - 使用 GameInput 摇杆 SDL_HINT_JOYSTICK_HAPTIC_AXES - 摇杆触觉轴 SDL_HINT_JOYSTICK_HIDAPI - 使用 HIDAPI 摇杆 SDL_HINT_JOYSTICK_HIDAPI_8BITDO - 支持 8BitDo 手柄 SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS - 合并 Switch 左右手柄 SDL_HINT_JOYSTICK_HIDAPI_FLYDIGI - 支持飞智手柄 SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE - 支持 GameCube SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE - GameCube 震动刹车 SDL_HINT_JOYSTICK_HIDAPI_GAMESIR - 支持盖世小鸡手柄 SDL_HINT_JOYSTICK_HIDAPI_GIP - 支持 GIP 设备 SDL_HINT_JOYSTICK_HIDAPI_GIP_RESET_FOR_METADATA - GIP 重置元数据 SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS - 支持 Switch JoyCon SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED - JoyCon Home 灯控制 SDL_HINT_JOYSTICK_HIDAPI_LG4FF - 支持 LG 力反馈 SDL_HINT_JOYSTICK_HIDAPI_LUNA - 支持 Luna 手柄 SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC - 支持任天堂经典手柄 SDL_HINT_JOYSTICK_HIDAPI_PS3 - 支持 PS3 手柄 SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER - PS3 六轴驱动 SDL_HINT_JOYSTICK_HIDAPI_PS4 - 支持 PS4 手柄 SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL - PS4 报告间隔 SDL_HINT_JOYSTICK_HIDAPI_PS5 - 支持 PS5 手柄 SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED - PS5 玩家灯 SDL_HINT_JOYSTICK_HIDAPI_SHIELD - 支持 Shield 手柄 SDL_HINT_JOYSTICK_HIDAPI_SINPUT - 支持 SInput SDL_HINT_JOYSTICK_HIDAPI_STADIA - 支持 Stadia 手柄 SDL_HINT_JOYSTICK_HIDAPI_STEAM - 支持 Steam 手柄 SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED - Steam Home 灯 SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI - 支持 Steam HORI SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK - 支持 Steam Deck SDL_HINT_JOYSTICK_HIDAPI_SWITCH - 支持 Switch 手柄 SDL_HINT_JOYSTICK_HIDAPI_SWITCH2 - 支持 Switch 2 手柄 SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED - Switch Home 灯 SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED - Switch 玩家灯 SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS - 垂直使用 JoyCon SDL_HINT_JOYSTICK_HIDAPI_WII - 支持 Wii 手柄 SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED - Wii 玩家灯 SDL_HINT_JOYSTICK_HIDAPI_XBOX - 支持 Xbox 手柄 SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 - 支持 Xbox 360 手柄 SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED - Xbox360 玩家灯 SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS - Xbox360 无线 SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE - 支持 Xbox One 手柄 SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED - XboxOne Home 灯 SDL_HINT_JOYSTICK_HIDAPI_ZUIKI - 支持 ZUIKI SDL_HINT_JOYSTICK_IOKIT - 使用 IOKit 摇杆 SDL_HINT_JOYSTICK_LINUX_CLASSIC - Linux 经典摇杆 SDL_HINT_JOYSTICK_LINUX_DEADZONES - Linux 摇杆死区 SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS - Linux 数字 POV 帽 SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES - Linux 帽键死区 SDL_HINT_JOYSTICK_MFI - 支持 MFi 手柄 SDL_HINT_JOYSTICK_RAWINPUT - 使用 RawInput 摇杆 SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT - RawInput 与 XInput 关联 SDL_HINT_JOYSTICK_ROG_CHAKRAM - 支持 ROG Chakram SDL_HINT_JOYSTICK_THREAD - 摇杆使用独立线程 SDL_HINT_JOYSTICK_THROTTLE_DEVICES - 油门设备 SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED - 排除油门设备 SDL_HINT_JOYSTICK_WGI - 使用 Windows.Gaming.Input SDL_HINT_JOYSTICK_WHEEL_DEVICES - 方向盘设备 SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED - 排除方向盘 SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES - 零居中设备 SDL_HINT_KEYCODE_OPTIONS - 键值选项 SDL_HINT_KMSDRM_ATOMIC - KMSDRM 使用原子模式 SDL_HINT_KMSDRM_DEVICE_INDEX - KMSDRM 设备索引 SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER - KMSDRM 需要 DRM 主权限 SDL_HINT_LOGGING - 日志配置 SDL_HINT_MAC_BACKGROUND_APP - macOS 后台应用 SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK - Ctrl+点击模拟右键 SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH - macOS OpenGL 异步派发 SDL_HINT_MAC_OPTION_AS_ALT - Option 键当作 Alt SDL_HINT_MAC_PRESS_AND_HOLD - 长按按键 SDL_HINT_MAC_SCROLL_MOMENTUM - 滚动动量 SDL_HINT_MAIN_CALLBACK_RATE - 主回调频率 SDL_HINT_MOUSE_AUTO_CAPTURE - 鼠标自动捕获 SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR - 默认系统光标 SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS - 双击半径 SDL_HINT_MOUSE_DOUBLE_CLICK_TIME - 双击间隔 SDL_HINT_MOUSE_DPI_SCALE_CURSORS - 按 DPI 缩放光标 SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE - 相对模式模拟光标跳转 SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH - 点击穿透获取焦点 SDL_HINT_MOUSE_NORMAL_SPEED_SCALE - 普通鼠标速度缩放 SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE - 相对模式光标可见 SDL_HINT_MOUSE_RELATIVE_MODE_CENTER - 相对模式保持居中 SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE - 相对鼠标速度缩放 SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE - 系统相对速度缩放 SDL_HINT_MOUSE_RELATIVE_WARP_MOTION - 跳转模拟相对运动 SDL_HINT_MOUSE_TOUCH_EVENTS - 鼠标生成触摸事件 SDL_HINT_MUTE_CONSOLE_KEYBOARD - 静音控制台键盘 SDL_HINT_NO_SIGNAL_HANDLERS - 不安装信号处理器 SDL_HINT_OPENGL_ES_DRIVER - OpenGL ES 驱动 SDL_HINT_OPENGL_FORCE_SRGB_CAPABLE - 强制 sRGB 能力 SDL_HINT_OPENGL_FORCE_SRGB_FRAMEBUFFER - 强制 sRGB 帧缓冲 SDL_HINT_OPENGL_LIBRARY - 指定 OpenGL 库 SDL_HINT_OPENVR_LIBRARY - 指定 OpenVR 库 SDL_HINT_OPENXR_LIBRARY - 指定 OpenXR 库 SDL_HINT_ORIENTATIONS - 屏幕方向 SDL_HINT_PEN_MOUSE_EVENTS - 手写笔生成鼠标事件 SDL_HINT_PEN_TOUCH_EVENTS - 手写笔生成触摸事件 SDL_HINT_POLL_SENTINEL - 轮询哨兵 SDL_HINT_PREFERRED_LOCALES - 首选区域 SDL_HINT_PS2_GS_HEIGHT - PS2 GS 高度 SDL_HINT_PS2_GS_MODE - PS2 GS 模式 SDL_HINT_PS2_GS_PROGRESSIVE - PS2 GS 逐行扫描 SDL_HINT_PS2_GS_WIDTH - PS2 GS 宽度 SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE - 关闭最后窗口退出 SDL_HINT_RENDER_DIRECT3D11_DEBUG - D3D11 渲染调试 SDL_HINT_RENDER_DIRECT3D11_WARP - D3D11 使用 WARP SDL_HINT_RENDER_DIRECT3D_THREADSAFE - D3D 渲染线程安全 SDL_HINT_RENDER_DRIVER - 指定渲染驱动 SDL_HINT_RENDER_GPU_DEBUG - GPU 渲染调试 SDL_HINT_RENDER_GPU_LOW_POWER - GPU 低功耗模式 SDL_HINT_RENDER_LINE_METHOD - 线条渲染方式 SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE - Metal 首选低功耗 GPU SDL_HINT_RENDER_VSYNC - 渲染垂直同步 SDL_HINT_RENDER_VULKAN_DEBUG - Vulkan 渲染调试 SDL_HINT_RETURN_KEY_HIDES_IME - 回车隐藏输入法 SDL_HINT_ROG_GAMEPAD_MICE - ROG 游戏鼠标 SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED - 排除 ROG 鼠标 SDL_HINT_RPI_VIDEO_LAYER - 树莓派视频层 SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME - 禁止屏保活动名 SDL_HINT_SHUTDOWN_DBUS_ON_QUIT - 退出时关闭 DBus SDL_HINT_STORAGE_TITLE_DRIVER - 标题存储驱动 SDL_HINT_STORAGE_USER_DRIVER - 用户存储驱动 SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL - 强制实时关键线程 SDL_HINT_THREAD_PRIORITY_POLICY - 线程优先级策略 SDL_HINT_TIMER_RESOLUTION - 定时器精度 SDL_HINT_TOUCH_MOUSE_EVENTS - 触摸生成鼠标事件 SDL_HINT_TRACKPAD_IS_TOUCH_ONLY - 触控板只当触摸 SDL_HINT_TV_REMOTE_AS_JOYSTICK - 电视遥控器作摇杆 SDL_HINT_VIDEO_ALLOW_SCREENSAVER - 允许屏保 SDL_HINT_VIDEO_DISPLAY_PRIORITY - 显示器优先级 SDL_HINT_VIDEO_DOUBLE_BUFFER - 视频双缓冲 SDL_HINT_VIDEO_DRIVER - 指定视频驱动 SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES - 虚拟视频保存帧 SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK - EGL GetDisplay 降级 SDL_HINT_VIDEO_FORCE_EGL - 强制使用 EGL SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY - macOS 全屏菜单可见 SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES - macOS 全屏 Spaces SDL_HINT_VIDEO_MATCH_EXCLUSIVE_MODE_ON_MOVE - 移动时匹配独占模式 SDL_HINT_VIDEO_METAL_AUTO_RESIZE_DRAWABLE - Metal 自动调整画布 SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS - 失去焦点最小化 SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES - 离屏视频保存帧 SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS - 同步窗口操作 SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR - Wayland 使用 libdecor SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION - Wayland 显示模式模拟 SDL_HINT_VIDEO_WAYLAND_MODE_SCALING - Wayland 模式缩放 SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR - Wayland 优先 libdecor SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY - Wayland 按显示缩放 SDL_HINT_VIDEO_WIN_D3DCOMPILER - Windows D3D 编译器 SDL_HINT_VIDEO_X11_EXTERNAL_WINDOW_INPUT - X11 外部窗口输入 SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR - X11 绕过合成器 SDL_HINT_VIDEO_X11_NET_WM_PING - X11 WM Ping SDL_HINT_VIDEO_X11_NODIRECTCOLOR - X11 不使用直接颜色 SDL_HINT_VIDEO_X11_SCALING_FACTOR - X11 缩放因子 SDL_HINT_VIDEO_X11_VISUALID - X11 VisualID SDL_HINT_VIDEO_X11_WINDOW_VISUALID - X11 窗口 VisualID SDL_HINT_VIDEO_X11_XRANDR - X11 使用 XRandR SDL_HINT_VITA_ENABLE_BACK_TOUCH - Vita 启用后触摸 SDL_HINT_VITA_ENABLE_FRONT_TOUCH - Vita 启用前触摸 SDL_HINT_VITA_MODULE_PATH - Vita 模块路径 SDL_HINT_VITA_PVR_INIT - Vita PVR 初始化 SDL_HINT_VITA_PVR_OPENGL - Vita PVR OpenGL SDL_HINT_VITA_RESOLUTION - Vita 分辨率 SDL_HINT_VITA_TOUCH_MOUSE_DEVICE - Vita 触摸转鼠标 SDL_HINT_VULKAN_DISPLAY - Vulkan 显示器 SDL_HINT_VULKAN_LIBRARY - 指定 Vulkan 库 SDL_HINT_WAVE_CHUNK_LIMIT - WAVE 块限制 SDL_HINT_WAVE_FACT_CHUNK - WAVE FACT 块 SDL_HINT_WAVE_RIFF_CHUNK_SIZE - WAVE RIFF 块大小 SDL_HINT_WAVE_TRUNCATION - WAVE 截断 SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED - 置顶时激活窗口 SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN - 显示时激活窗口 SDL_HINT_WINDOW_ALLOW_TOPMOST - 允许窗口置顶 SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN - 隐藏光标时可使用窗口边框 SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 - Windows Alt+F4 关闭 SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS - 启用菜单助记符 SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP - 启用 Windows 消息循环 SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE - 窗口背景擦除模式 SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL - 强制内核信号量 SDL_HINT_WINDOWS_GAMEINPUT - 使用 Windows GameInput SDL_HINT_WINDOWS_INTRESOURCE_ICON - Windows 图标资源 SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL - Windows 小图标资源 SDL_HINT_WINDOWS_RAW_KEYBOARD - 使用原始键盘 SDL_HINT_WINDOWS_RAW_KEYBOARD_EXCLUDE_HOTKEYS - 原始键盘排除系统热键 SDL_HINT_WINDOWS_USE_D3D9EX - 使用 D3D9Ex SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT - 强制 OverrideRedirect SDL_HINT_X11_WINDOW_TYPE - X11 窗口类型 SDL_HINT_X11_XCB_LIBRARY - 指定 XCB 库 SDL_HINT_XINPUT_ENABLED - 启用 XInput FreeBASIC 示例代码（Hint 使用示范） #include "SDL3/SDL.bi" #include "SDL3/SDL_main.bi" Function SDL_main (argc As Integer, argv As ZString Ptr) As Integer SDL_Init(SDL_INIT_VIDEO) ' 设置提示：渲染器使用 VSYNC SDL_SetHint(SDL_HINT_RENDER_VSYNC, "1") ' 获取提示值 Dim As ZString Ptr vsync = SDL_GetHint(SDL_HINT_RENDER_VSYNC) Print "VSYNC: "; *vsync ' 以布尔值获取 Dim As Boolean bvsync = SDL_GetHintBoolean(SDL_HINT_RENDER_VSYNC, SDL_FALSE) Print "VSYNC bool: "; bvsync SDL_Quit() Return 0 End Function
-
SDL3_API分类参考_初始化与退出（CategoryInit） 初始化与退出（CategoryInit） 所有 SDL 程序在开始使用该库之前都需要先初始化它。 几乎所有程序都可以在启动时简单调用 SDL_Init() 函数， 并通过少量标志位指定要启用的子系统。这些标志位的作用是确保 SDL 不会尝试去访问 你并不打算使用的操作系统底层组件。例如，你可能使用 SDL 处理视频和输入， 但选择第三方库处理音频，这种情况下只需省略 SDL_INIT_AUDIO 标志位，就能确保第三方音频库获得完全的控制权。 大多数应用程序在终止时应调用 SDL_Quit()。该函数会清理（几乎）所有 SDL 分配的资源， 尤为重要的是，如果你此前为游戏修改了显示器分辨率，它会确保分辨率恢复到用户预期的状态。 强烈建议 SDL3 应用程序在启动时调用 SDL_SetAppMetadata() 来填充程序的相关信息。 这一步完全可选，但能带来一些细节上的优化（比如可为 macOS 菜单提供「关于」对话框、 在系统音频混音器中显示应用名称等）。如果想要提供大量应用信息， 可使用更详细的 SDL_SetAppMetadataProperty() 函数。 函数 SDL_GetAppMetadataProperty - 获取应用程序指定的元数据属性值 SDL_Init - 初始化 SDL 库，可指定要启用的子系统 SDL_InitSubSystem - 初始化指定的 SDL 子系统（在主初始化后补充启用） SDL_IsMainThread - 检查当前线程是否为 SDL 主线程 SDL_Quit - 退出 SDL 并清理所有已初始化的子系统资源 SDL_QuitSubSystem - 退出指定的 SDL 子系统并释放其资源 SDL_RunOnMainThread - 将指定回调函数放到 SDL 主线程中执行 SDL_SetAppMetadata - 设置应用程序的基础元数据（名称、版本、作者等） SDL_SetAppMetadataProperty - 设置应用程序的自定义元数据属性 SDL_WasInit - 查询指定的 SDL 子系统是否已初始化 数据类型 SDL_AppEvent_func - 应用程序事件回调函数的类型定义 SDL_AppInit_func - 应用程序初始化回调函数的类型定义 SDL_AppIterate_func - 应用程序主循环迭代回调函数的类型定义 SDL_AppQuit_func - 应用程序退出回调函数的类型定义 SDL_InitFlags - SDL 初始化标志位的数值类型，用于指定要启用的子系统 SDL_MainThreadCallback - 主线程回调函数的函数指针类型 结构体 (无) 枚举 SDL_AppResult - 定义应用程序回调函数的返回结果类型 宏 (无) 补充：SDL 初始化的 FreeBASIC 示例代码 #include "SDL3/SDL.bi" #include "SDL3/SDL_main.bi" Function SDL_main (argc As Integer, argv As ZString Ptr) As Integer ' 初始化 SDL 视频和输入子系统 Dim As Integer initResult = SDL_Init(SDL_INIT_VIDEO Or SDL_INIT_INPUT) If initResult < 0 Then Print "SDL 初始化失败: " & *SDL_GetError() Return 1 End If ' 设置应用元数据 SDL_SetAppMetadata("我的SDL应用", "1.0.0", "我的公司") ' 检查视频子系统是否初始化成功 Dim As Uint32 wasInit = SDL_WasInit(SDL_INIT_VIDEO) If wasInit = SDL_INIT_VIDEO Then Print "视频子系统已初始化" End If ' 应用程序核心逻辑写在这里 ' 退出 SDL，清理资源 SDL_Quit() Return 0 End Function
-
SDL3_API分类参考_应用程序入口（CategoryMain） 应用程序入口（CategoryMain） 如有必要，重新定义 main() 函数，使其能被 SDL 调用。 为了保证该函数在所有平台上的行为一致，应用程序的 main() 函数 应按如下形式编写： #include "SDL3/SDL.bi" #include "SDL3/SDL_main.bi" Function SDL_main (argc As Integer, argv As ZString Ptr) As Integer ' 应用程序逻辑写在这里 Return 0 End Function SDL 会自行处理不同平台下调用该函数的平台相关细节。 应用程序也可在此处通过 SDL_MAIN_USE_CALLBACKS 宏配置使用主回调函数。 SDL_main.h 是一个「单头文件库」，也就是说， 包含该头文件会向程序中插入代码，多数情况下你应该只包含它一次。SDL.h 不会自动包含此头文件。 更多信息请参考： https://wiki.libsdl.org/SDL3/README-main-functions 函数 SDL_AppEvent - 处理应用程序相关的事件回调 SDL_AppInit - 应用程序初始化回调函数，在启动时执行 SDL_AppIterate - 应用程序主循环迭代回调，每帧执行 SDL_AppQuit - 应用程序退出回调函数，在退出前执行清理操作 SDL_EnterAppMainCallbacks - 进入应用程序主回调模式 SDL_GDKSuspendComplete - 通知SDL GDK平台应用暂停已完成 SDL_main - SDL应用程序的主入口点，替代标准main函数 SDL_RegisterApp - 注册应用程序与SDL子系统关联 SDL_RunApp - 运行SDL应用程序的主循环 SDL_SetMainReady - 标记SDL主函数已准备就绪 SDL_UnregisterApp - 注销已注册的应用程序，释放相关资源 数据类型 SDL_main_func - 定义SDL主函数的函数指针类型 结构体 (无) 枚举 (无) 宏 SDL_MAIN_AVAILABLE - 标记SDL_main函数可用 SDL_MAIN_HANDLED - 告知SDL应用程序已自行处理主函数 SDL_MAIN_NEEDED - 指示SDL需要提供主函数实现 SDL_MAIN_USE_CALLBACKS - 启用SDL主回调函数模式 SDLMAIN_DECLSPEC - 用于SDL_main相关函数的声明规范宏