登录
侧边栏壁纸
博主头像
勇芳

  • 累计撰写 330 篇文章
  • 累计收到 0 条评论
VisualFreeBasic编程文档

SDL3_API分类参考_SDL_image 核心 API 集合（CategoryAPI）

勇芳
2026-3-7 / 0 评论 / 7 阅读

SDL_image 核心 API 集合（CategoryAPI）

SDL_image 是 SDL 的官方图像扩展库，该分类汇总了 SDL_image 所有核心 API，涵盖静态图像加载/保存、动画解码/编码、格式检测、GPU 纹理加载等全量功能，是 SDL 生态中处理图像的核心接口集合。

核心 API 列表（按功能分类）

一、动画编解码核心接口

1. 动画解码器（AnimationDecoder）

  • IMG_CreateAnimationDecoder：创建动画解码器实例（通用接口）
  • IMG_CreateAnimationDecoder_IO：从 SDL_IOStream 流创建动画解码器
  • IMG_CreateAnimationDecoderWithProperties：带自定义属性创建动画解码器（如 GIF 颜色数、AVIF 线程数）
  • IMG_CloseAnimationDecoder：关闭并释放动画解码器资源
  • IMG_GetAnimationDecoderFrame：获取解码器指定索引的帧数据
  • IMG_GetNextAnimationDecoderFrame：获取解码器下一帧数据（逐帧播放）
  • IMG_GetAnimationDecoderMetadata：获取动画元数据（帧数、循环次数等）
  • IMG_GetAnimationDecoderPresentationTimestampMS：获取帧的展示时间戳（毫秒）
  • IMG_GetAnimationDecoderProperties：获取解码器的配置属性
  • IMG_GetAnimationDecoderStatus：获取解码器当前状态（成功/失败/完成等）
  • IMG_ResetAnimationDecoder：重置动画解码器到初始状态

2. 动画编码器（AnimationEncoder）

  • IMG_CreateAnimationEncoder：创建动画编码器实例（通用接口）
  • IMG_CreateAnimationEncoder_IO：从 SDL_IOStream 流创建动画编码器
  • IMG_CreateAnimationEncoderWithProperties：带自定义属性创建动画编码器（如质量、关键帧间隔）
  • IMG_CloseAnimationEncoder：关闭并释放动画编码器资源
  • IMG_AddAnimationEncoderFrame：向编码器添加单帧数据（用于生成动画）

3. 动画流（AnimationStream）

  • IMG_CreateAnimationStream：创建动画流实例（实时编解码）
  • IMG_CreateAnimationStream_IO：从 SDL_IOStream 流创建动画流
  • IMG_CreateAnimationStreamWithProperties：带自定义属性创建动画流
  • IMG_CloseAnimationStream：关闭并释放动画流资源

4. 动画数据结构与工具

  • IMG_Animation：动画数据结构体（包含所有帧、时长、循环等信息）
  • IMG_LoadAnimation：从文件加载完整动画数据（如 GIF/APNG/WEBP）
  • IMG_LoadAnimation_IO：从 SDL_IOStream 流加载动画
  • IMG_LoadAnimationTyped_IO：指定格式从流加载动画（避免自动检测）
  • IMG_FreeAnimation：释放 IMG_Animation 结构体资源
  • IMG_SaveAnimation：将动画数据保存为文件
  • IMG_SaveAnimationTyped_IO：指定格式将动画保存到 SDL_IOStream 流

5. 动画解码器状态枚举

  • IMG_DECODER_STATUS_OK：解码器状态正常（可继续解码）
  • IMG_DECODER_STATUS_COMPLETE：解码完成（所有帧已处理）
  • IMG_DECODER_STATUS_FAILED：解码失败（数据错误/格式不支持）
  • IMG_DECODER_STATUS_INVALID：解码器实例无效（未初始化/已释放）

二、静态图像加载/保存

1. 通用加载接口

  • IMG_Load：从文件加载图像为 SDL_Surface（自动检测格式）
  • IMG_Load_IO：从 SDL_IOStream 流加载图像为 SDL_Surface
  • IMG_LoadTyped_IO：指定格式从流加载图像（如强制按 PNG 解析）
  • IMG_LoadTexture：从文件加载图像为 SDL_Texture（GPU 纹理，需 SDL_Renderer）
  • IMG_LoadTexture_IO：从流加载图像为 SDL_Texture
  • IMG_LoadTextureTyped_IO：指定格式从流加载为 SDL_Texture
  • IMG_LoadGPUTexture：加载图像为 GPU 原生纹理（如 Vulkan/D3D 纹理）
  • IMG_LoadGPUTexture_IO：从流加载为 GPU 原生纹理

2. 格式专属加载接口

  • IMG_LoadBMP_IO/IMG_LoadPNG_IO/IMG_LoadJPG_IO：BMP/PNG/JPG 格式专属加载
  • IMG_LoadGIF_IO/IMG_LoadWEBP_IO/IMG_LoadAVIF_IO：GIF/WEBP/AVIF 格式专属加载
  • IMG_LoadICO_IO/IMG_LoadCUR_IO：图标/光标格式加载
  • IMG_LoadSVG_IO/IMG_LoadSizedSVG_IO：SVG 矢量图加载（支持指定尺寸）
  • IMG_LoadXPM_IO/IMG_ReadXPMFromArray：XPM 格式加载（支持内存数组）
  • IMG_LoadANIAnimation_IO/IMG_LoadGIFAnimation_IO：ANI/GIF 动画专属加载
  • IMG_LoadAPNGAnimation_IO/IMG_LoadWEBPAnimation_IO：APNG/WEBP 动画专属加载

3. 图像保存接口

  • IMG_Save：将 SDL_Surface 保存为图像文件（自动检测格式）
  • IMG_SaveTyped_IO：指定格式将图像保存到 SDL_IOStream 流
  • IMG_SaveBMP/IMG_SavePNG/IMG_SaveJPG：BMP/PNG/JPG 格式专属保存
  • IMG_SaveGIF/IMG_SaveWEBP/IMG_SaveAVIF：GIF/WEBP/AVIF 格式专属保存
  • IMG_SaveICO/IMG_SaveCUR：图标/光标格式保存
  • IMG_SaveANIAnimation_IO/IMG_SaveGIFAnimation_IO：ANI/GIF 动画专属保存
  • IMG_SaveAPNGAnimation_IO/IMG_SaveWEBPAnimation_IO：APNG/WEBP 动画专属保存

三、格式检测接口

  • IMG_isBMP/IMG_isPNG/IMG_isJPG：检测数据是否为 BMP/PNG/JPG 格式
  • IMG_isGIF/IMG_isAVIF/IMG_isWEBP：检测数据是否为 GIF/AVIF/WEBP 格式
  • IMG_isICO/IMG_isCUR/IMG_isANI：检测数据是否为 ICO/CUR/ANI 格式
  • IMG_isSVG/IMG_isTIF/IMG_isXPM：检测数据是否为 SVG/TIF/XPM 格式
  • IMG_isLBM/IMG_isPCX/IMG_isPNM：检测数据是否为 LBM/PCX/PNM 格式
  • IMG_isQOI/IMG_isXCF/IMG_isXV：检测数据是否为 QOI/XCF/XV 格式
  • IMG_isJXL：检测数据是否为 JXL（JPEG XL）格式

四、特殊功能接口

  • IMG_CreateAnimatedCursor：从动画数据创建系统动画光标
  • IMG_GetClipboardImage：获取剪贴板中的图像数据（SDL_Surface）
  • IMG_ReadXPMFromArrayToRGB888：从 XPM 数组加载为 RGB888 格式图像

五、属性常量（编解码配置）

1. 解码器属性

  • IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING：解码器关联的文件名属性
  • IMG_PROP_ANIMATION_DECODER_CREATE_TYPE_STRING：解码器目标格式（如 "gif"/"avif"）
  • IMG_PROP_ANIMATION_DECODER_CREATE_GIF_NUM_COLORS_NUMBER：GIF 解码颜色数限制
  • IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_MAX_THREADS_NUMBER：AVIF 解码最大线程数
  • IMG_PROP_ANIMATION_DECODER_METADATA_FRAME_COUNT_NUMBER：动画帧数元数据
  • IMG_PROP_ANIMATION_DECODER_METADATA_LOOP_COUNT_NUMBER：动画循环次数元数据

2. 编码器属性

  • IMG_PROP_ANIMATION_ENCODER_CREATE_QUALITY_NUMBER：编码质量（0-100）
  • IMG_PROP_ANIMATION_ENCODER_CREATE_TYPE_STRING：编码器目标格式
  • IMG_PROP_ANIMATION_ENCODER_CREATE_AVIF_KEYFRAME_INTERVAL_NUMBER：AVIF 关键帧间隔
  • IMG_PROP_ANIMATION_ENCODER_CREATE_GIF_USE_LUT_BOOLEAN：GIF 编码是否使用颜色查找表

3. 通用属性

  • IMG_PROP_METADATA_AUTHOR_STRING：图像作者元数据
  • IMG_PROP_METADATA_COPYRIGHT_STRING：图像版权元数据
  • IMG_PROP_METADATA_TITLE_STRING：图像标题元数据
  • IMG_PROP_ANIMATION_STREAM_CREATE_QUALITY_NUMBER：动画流编码质量

六、版本相关宏/函数

  • IMG_Version：获取当前 SDL_image 库的版本信息
  • SDL_IMAGE_MAJOR_VERSION：SDL_image 主版本号宏（如 3 代表 SDL_image 3.x）
  • SDL_IMAGE_VERSION：构造版本结构体的宏
  • SDL_IMAGE_VERSION_ATLEAST：编译期检查 SDL_image 版本是否满足最低要求

FreeBASIC 示例代码

' 引入 SDL 及 SDL_image 相关声明（需链接 SDL3 和 SDL3_image 库）
#Include "SDL.bi"
#Include "SDL_image.bi"

' 补充关键类型/宏声明（FreeBASIC 绑定可能缺失）
Type IMG_Animation  ' 简化版动画结构体（完整定义需参考 SDL_image 源码）
    frames As SDL_Surface Ptr Ptr  ' 帧数据数组
    delays As Integer Ptr          ' 每帧延迟（毫秒）
    count As Integer               ' 总帧数
    loops As Integer               ' 循环次数（0=无限）
End Type

Declare Function IMG_LoadAnimation CDecl (ByVal file As ZString Ptr) As IMG_Animation Ptr
Declare Sub IMG_FreeAnimation CDecl (ByVal anim As IMG_Animation Ptr)
Declare Function IMG_isGIF CDecl (ByVal src As Const Any Ptr, ByVal len As Size_t) As SDL_bool
Declare Function IMG_SavePNG CDecl (ByVal surface As SDL_Surface Ptr, ByVal file As ZString Ptr) As SDL_bool

' 检查 SDL_image 版本
Sub CheckImageVersion()
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "【检查 SDL_image 版本】")

    Dim As SDL_version ver
    IMG_Version(@ver)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL_image 版本：%d.%d.%d", ver.major, ver.minor, ver.patch)

    ' 编译期版本检查示例
    #If SDL_IMAGE_VERSION_ATLEAST(3, 0, 0)
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "✓ 满足 SDL_image 3.0.0 最低版本要求")
    #Else
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "✗ 不满足 SDL_image 3.0.0 最低版本要求")
    #EndIf
End Sub

' 加载并显示静态图像（PNG/JPG）
Sub LoadStaticImageExample(ByVal filename As ZString Ptr)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【加载静态图像：%s】", filename)

    ' 加载图像为 SDL_Surface
    Dim As SDL_Surface Ptr surface = IMG_Load(filename)
    If (surface = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "加载失败：%s", SDL_GetError())
        Exit Sub
    End If

    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "图像信息：%dx%d 像素，%d 位深", _
        surface->w, surface->h, surface->format->BitsPerPixel)

    ' 保存为 PNG 格式（格式转换示例）
    Dim As ZString * 256 savePath
    SDL_snprintf(@savePath, sizeof(savePath), "saved_%s.png", SDL_GetBasename(filename))
    If (IMG_SavePNG(surface, @savePath) = SDL_TRUE) Then
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "已保存为：%s", savePath)
    End If

    ' 释放资源
    SDL_DestroySurface(surface)
End Sub

' 加载并解析 GIF 动画
Sub LoadGifAnimationExample(ByVal filename As ZString Ptr)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, vbCrLf & "【加载 GIF 动画：%s】", filename)

    ' 1. 检测文件是否为 GIF 格式
    Dim As SDL_RWops Ptr rw = SDL_RWFromFile(filename, "rb")
    If (rw = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "打开文件失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 读取文件头用于格式检测
    Dim As UByte header(0 To 3)
    SDL_RWread(rw, @header(0), 1, 4)
    SDL_RWseek(rw, 0, RW_SEEK_SET)  ' 重置文件指针

    If (IMG_isGIF(@header(0), 4) = SDL_TRUE) Then
        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "✓ 检测为 GIF 格式文件")
    Else
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "✗ 非 GIF 格式文件")
        SDL_RWclose(rw)
        Exit Sub
    End If
    SDL_RWclose(rw)

    ' 2. 加载 GIF 动画数据
    Dim As IMG_Animation Ptr anim = IMG_LoadAnimation(filename)
    If (anim = NULL) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "加载动画失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 3. 解析动画信息
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "动画总帧数：%d", anim->count)
    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "循环次数：%s", IIf(anim->loops=0, "无限", Str(anim->loops)))

    ' 打印每帧延迟
    For i As Integer = 0 To anim->count - 1
        If (anim->frames[i] <> NULL) Then
            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "帧 %d：%dx%d 像素，延迟 %d 毫秒", _
                i, anim->frames[i]->w, anim->frames[i]->h, anim->delays[i])
        End If
    Next

    ' 4. 释放动画资源
    IMG_FreeAnimation(anim)
End Sub

' 主程序
Sub Main()
    ' 初始化 SDL 视频子系统（加载图像需要）
    If (SDL_Init(SDL_INIT_VIDEO) < 0) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL 初始化失败：%s", SDL_GetError())
        Exit Sub
    End If

    ' 初始化 SDL_image（加载所有支持的格式）
    Dim As Integer flags = IMG_INIT_PNG Or IMG_INIT_JPG Or IMG_INIT_GIF Or IMG_INIT_WEBP
    If (IMG_Init(flags) <> flags) Then
        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_image 初始化失败：%s", IMG_GetError())
        SDL_Quit()
        Exit Sub
    End If

    ' 运行示例
    CheckImageVersion()
    LoadStaticImageExample(StrPtr("test.png"))  ' 替换为实际的图像文件路径
    LoadGifAnimationExample(StrPtr("test.gif")) ' 替换为实际的 GIF 文件路径

    ' 清理资源
    IMG_Quit()
    SDL_Quit()

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

' 运行主程序
Main()

核心知识点补充

  1. SDL_image 初始化与清理：

    • 必须调用 IMG_Init() 初始化并指定支持的格式（如 IMG_INIT_PNG/IMG_INIT_GIF），未指定的格式无法加载；
    • 初始化标志需与返回值对比，确认所有格式都成功初始化；
    • 程序退出前必须调用 IMG_Quit() 释放 SDL_image 资源。

  2. 动画处理关键要点：

    • IMG_Animation 是动画的核心数据结构，包含所有帧的 SDL_Surface、每帧延迟、循环次数；
    • 加载 GIF/APNG 等动画时，优先使用 IMG_LoadAnimation，而非普通的 IMG_Load（后者仅加载第一帧）；
    • 动画帧的延迟单位为毫秒，需结合 SDL_Delay() 实现逐帧播放。

  3. 格式检测规则：

    • IMG_isXXX() 函数仅需传入文件头前几个字节（通常 4-8 字节）即可检测格式；
    • 检测前需确保数据指针有效，且长度不小于格式标识的最小长度；
    • 推荐先检测格式再加载，可提前过滤不支持的文件。

  4. IOStream 接口优势：

    • _IO 后缀的接口支持从内存流/网络流加载图像，无需写入本地文件；
    • 使用 SDL_IOStream 时可通过 IMG_PROP_*_IOSTREAM_AUTOCLOSE 属性控制流的自动关闭；
    • 适合处理加密/压缩的图像数据（先解密/解压到内存流，再加载）。

  5. 跨平台注意事项：

    • SVG 加载依赖系统的 SVG 解析库（如 librsvg），部分平台需额外链接；
    • AVIF/WEBP 等现代格式需确保 SDL_image 编译时启用了对应编解码器；
    • 移动平台需注意文件路径格式（如 Android 的 assets 目录需用 SDL_RWFromFile 配合绝对路径）。

总结

  1. 核心优势：

    • 一站式支持数十种图像格式，无需单独集成各格式的编解码库；
    • 无缝衔接 SDL 核心库，加载的图像可直接用于 SDL 渲染/显示；
    • 支持动画编解码、GPU 纹理加载等高级功能，满足游戏/多媒体开发需求；
    • 跨平台接口统一，无需适配不同系统的图像处理逻辑。

  2. 使用建议：

    • 初始化时仅指定实际需要的格式标志（减少库体积和内存占用）；
    • 加载大图像/动画时优先使用 IOStream 接口，避免内存峰值；
    • 动画播放需注意帧延迟的累积，避免播放速度不一致；
    • 保存图像时指定格式专属接口（如 IMG_SavePNG），比通用 IMG_Save 更稳定。

  3. 关键点回顾：

    • SDL_image 是 SDL 的图像扩展库，核心功能包括静态图像加载/保存、动画编解码、格式检测；
    • IMG_Init()/IMG_Quit() 是初始化/清理的必选接口，需指定支持的格式标志；
    • IMG_Animation 结构体封装动画全量数据，IMG_LoadAnimation 用于加载GIF/APNG等动画；
    • _IO 后缀接口支持流操作，适合内存/网络图像处理，_Typed_IO 接口可强制指定格式解析。
0
版权属于： 勇芳
本文链接： http://bbs.yfvb.com/post-330.html
文章声明： 本文版权内容属于《勇芳软件工作室》转载请标明出处
相关推荐
VisualFreeBasic控件_Image 图像
VisualFreeBasic控件_Image 图像
 VisualFreeBasic控件_控件数组
VisualFreeBasic控件_控件数组
 VisualFreeBasic控件_Line 线条
VisualFreeBasic控件_Line 线条
 VisualFreeBasic游戏趣味编程_10.6_得分计算与胜负判断
VisualFreeBasic游戏趣味编程_10.6_得分计算与胜负判断

评论一下？

OωO
取消