日志（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()