位操作子系统（CategoryBits）

SDL 提供了用于操作二进制位和位掩码的工具函数，简化常见的位运算逻辑实现。

函数

SDL_HasExactlyOneBitSet32：检测 32 位无符号整数中是否恰好只有 1 个位被置 1（返回非 0 表示是，0 表示否；0 值返回 0）
SDL_MostSignificantBitIndex32：获取 32 位无符号整数中最高有效位（最左侧置 1 的位）的索引（如 0x80000000 返回 31，0x00000001 返回 0，0 值返回 -1）

数据类型

（无）

结构体

（无）

枚举

（无）

宏

（无）

FreeBASIC 示例代码

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

' 补充函数声明（FreeBASIC 绑定可能缺失）
Declare Function SDL_HasExactlyOneBitSet32 CDecl (ByVal x As UInteger) As Integer
Declare Function SDL_MostSignificantBitIndex32 CDecl (ByVal x As UInteger) As Integer

' 示例1：检测是否为2的幂（恰好1个位置1）
Sub CheckPowerOfTwo()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【示例1：检测2的幂】")

    ' 测试用例：2的幂、非2的幂、0值
    Dim As UInteger testValues(5) = {1, 2, 4, 8, 6, 0}
    For i As Integer = 0 To UBound(testValues)
        Dim As UInteger value = testValues(i)
        Dim As Integer isPowerOfTwo = SDL_HasExactlyOneBitSet32(value)

        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, _
            "数值 0x%08X (%d)：%s2的幂", _
            value, value, IIf(isPowerOfTwo, "是", "不是"))
    Next
End Sub

' 示例2：获取最高有效位索引
Sub GetMSBIndex()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【示例2：获取最高有效位索引】")

    ' 测试用例：不同位置的置1位、0值
    Dim As UInteger testValues(6) = { _
        &H00000001, ' 第0位 → 索引0
        &H00000080, ' 第7位 → 索引7
        &H00008000, ' 第15位 → 索引15
        &H00800000, ' 第23位 → 索引23
        &H80000000, ' 第31位 → 索引31
        &H12345678, ' 混合位 → 最高位28
        0           ' 0值 → 索引-1
    }

    For i As Integer = 0 To UBound(testValues)
        Dim As UInteger value = testValues(i)
        Dim As Integer msbIndex = SDL_MostSignificantBitIndex32(value)

        If (msbIndex = -1) Then
            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "数值 0x%08X：无有效位（索引-1）", value)
        Else
            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, _
                "数值 0x%08X：最高有效位索引 = %d（对应2^%d = %d）", _
                value, msbIndex, msbIndex, 1 Shl msbIndex)
        End If
    Next
End Sub

' 示例3：位掩码有效性检测
Sub ValidateBitmask()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【示例3：位掩码有效性检测】")

    ' 场景：某功能仅允许单个标志位（而非组合位），需检测输入是否合法
    Enum FeatureFlags
        FLAG_A = 1 Shl 0  ' 0x00000001
        FLAG_B = 1 Shl 1  ' 0x00000002
        FLAG_C = 1 Shl 2  ' 0x00000004
        FLAG_D = 1 Shl 3  ' 0x00000008
    End Enum

    ' 测试输入：合法（单标志）、非法（多标志）、0值
    Dim As UInteger inputs(3) = {FLAG_A, FLAG_B Or FLAG_C, FLAG_D, 0}
    For i As Integer = 0 To UBound(inputs)
        Dim As UInteger input = inputs(i)
        Dim As Integer isValid = SDL_HasExactlyOneBitSet32(input)

        If (input = 0) Then
            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "输入掩码 0x%08X：空值（无功能选中）", input)
        ElseIf (isValid) Then
            Dim As Integer flagIndex = SDL_MostSignificantBitIndex32(input)
            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, _
                "输入掩码 0x%08X：合法（单标志位，索引%d）", input, flagIndex)
        Else
            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, _
                "输入掩码 0x%08X：非法（多个标志位同时选中）", input)
        End If
    Next
End Sub

' 示例4：性能对比（SDL函数 vs 手动实现）
Sub PerformanceComparison()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【示例4：性能对比】")

    Const TEST_COUNT As ULongInt = 100000000 ' 1亿次调用
    Dim As UInteger testValue = &H12345678
    Dim As ULongInt startTicks, endTicks
    Dim As Double elapsed

    ' 测试 SDL_MostSignificantBitIndex32
    startTicks = SDL_GetPerformanceCounter()
    For i As ULongInt = 1 To TEST_COUNT
        Dim As Integer idx = SDL_MostSignificantBitIndex32(testValue)
    Next
    endTicks = SDL_GetPerformanceCounter()
    elapsed = (endTicks - startTicks) / SDL_GetPerformanceFrequency()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, _
        "SDL_MostSignificantBitIndex32 执行%llu次耗时：%.3f秒", TEST_COUNT, elapsed)

    ' 测试手动实现的最高有效位查找
    startTicks = SDL_GetPerformanceCounter()
    For i As ULongInt = 1 To TEST_COUNT
        Dim As Integer idx = -1
        Dim As UInteger val = testValue
        If (val <> 0) Then
            For j As Integer = 31 DownTo 0
                If (val And (1 Shl j)) Then
                    idx = j
                    Exit For
                End If
            Next
        End If
    Next
    endTicks = SDL_GetPerformanceCounter()
    elapsed = (endTicks - startTicks) / SDL_GetPerformanceFrequency()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, _
        "手动实现 执行%llu次耗时：%.3f秒", TEST_COUNT, elapsed)
End Sub

' 主程序
Sub Main()
    ' 初始化 SDL
    If (SDL_Init(0) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL 初始化失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 运行示例
    CheckPowerOfTwo()
    GetMSBIndex()
    ValidateBitmask()
    PerformanceComparison()

    ' 清理 SDL
    SDL_Quit()

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "程序正常退出")
End Sub

' 运行主程序
Main()

核心知识点补充

位操作函数的实现原理：
- SDL_HasExactlyOneBitSet32：利用位运算特性 x & (x - 1) == 0（仅当 x 是 2 的幂时成立），同时排除 x=0 的情况；
- SDL_MostSignificantBitIndex32：底层使用 CPU 指令（如 x86 的 bsr、ARM 的 clz）实现，比手动循环查找快数十倍。

函数返回值规则：	函数	输入值	返回值
SDL_HasExactlyOneBitSet32	0	0	无置 1 位，不是 2 的幂
SDL_HasExactlyOneBitSet32	1 (0x00000001)	非0	恰好 1 位，是 2 的幂
SDL_HasExactlyOneBitSet32	6 (0x00000110)	0	多个位置 1，不是 2 的幂
SDL_MostSignificantBitIndex32	0	-1	无有效位
SDL_MostSignificantBitIndex32	8 (0x00001000)	3	最高位是第 3 位

典型应用场景：
- 2 的幂检测：内存分配、缓冲区大小校验（如纹理尺寸需为 2 的幂）；
- 最高有效位查找：快速计算数值的二进制位数、动态调整位掩码范围；
- 单标志位校验：确保输入的位掩码仅包含一个功能标志（避免多标志冲突）。
性能优势：
- SDL 位操作函数基于 CPU 专用指令实现，比手动循环/位运算快 10~100 倍；
- 内联实现无函数调用开销，适合高频调用场景（如图形渲染、数据压缩）。

总结

核心优势：
- 封装底层 CPU 位操作指令，无需开发者关注架构差异；
- 提供语义清晰的函数接口，避免手写易出错的位运算逻辑；
- 极致的执行性能，远超手动实现的位操作代码；
- 返回值规则明确，边界条件（如 0 值）处理完善。
使用建议：
- 检测 2 的幂时，优先使用 SDL_HasExactlyOneBitSet32 而非手写 x & (x-1) == 0（已处理 x=0 边界）；
- 查找最高有效位时，必须使用 SDL_MostSignificantBitIndex32（性能和兼容性最优）；
- 位掩码校验场景中，用 SDL_HasExactlyOneBitSet32 确保输入仅含单个标志位；
- 64 位数值可通过拆分高位/低位，结合 32 位函数实现类似功能。
关键点回顾：
- SDL_HasExactlyOneBitSet32 是检测「2 的幂」的最优方式，返回非 0 表示是 2 的幂；
- SDL_MostSignificantBitIndex32 基于 CPU 专用指令实现，返回最高置 1 位的索引（0~31），0 值返回 -1；
- SDL 位操作函数性能远超手动实现，适合高频调用的性能关键路径。