spine-sdl 运行时文档

Licensing

将官方的Spine Runtime整合到你的应用程序前请务必先阅读 Spine 运行时许可证.

开始使用

安装

spine-sdl 运行时以 C 和 C++ API 的形式提供. C API 基于通用的spine-c运行时, C++ API 基于通用的spine-cpp运行时. 若要将 spine-sdl 集成到你的项目中请按以下步骤进行:

  1. 创建一个新的 SDL 项目. 参见 SDL 文档 或查看 spine-runtimes repository中的示例, 该示例使用 CMake 作为构建系统.
  2. 使用 git 下载 Spine Runtimes 源码 (git clone https://github.com/esotericsoftware/spine-runtimes).
  3. 如果你在使用 C:
    • 将 spine-c/spine-c/src/spine 中的源码和文件 spine-sdl/src/spine-sdl-c.c 添加到你的项目中.
    • 将文件夹 spine-c/spine-c/include 和 spine-sdl/src/ 添加到你的头文件搜索路径中.

  4. 如果你在使用 C++:
    • 将 spine-cpp/spine-cpp/src/spine 中的源码和文件 spine-sdl/src/spine-sdl-cpp.cpp 的源码添加到你的项目中.
    • 将文件夹 spine-cpp/spine-cpp/include 和 spine-sdl/src 添加到你的头文件搜索路径中.

在你的 C 或 C++ 代码中, 需包含以下任一头文件才能访问 spine-sdl API :

// C API
#include <spine-sdl-c.h>

// C++ API
#include <spine-sdl-cpp.h>

注意: spine-sdl 基于 SDL_RenderGeometry API, 该 API 自 SDL 2.0.18 版本开始引入. SDL 的早期版本与 spine-sdl 并不兼容.

示例项目

spine-sdl 的示例项目可以在 Windows，Linux 和 Mac OS X 上运行. 对于spine-c的示例, 请参见example/main.c; 而对于 spine-cpp 的示例, 则请参见example/main.cpp.

Windows

  1. 安装 Visual Studio Community并确保安装了对 C++ 的支持.
  2. 通过 Windows installer package 安装 CMake.
  3. 使用 git 下载 Spine Runtimes 存储库(git clone https://github.com/esotericsoftware/spine-runtimes), 也可以通过上文提到的下载按钮以 zip 格式下载.
  4. 从开始菜单中打开 CMake GUI.
  5. 点击 Browse Source 并选择 spine-runtimes 目录.
  6. 点击 Browse Build 并选择 spine-runtimes/spine-sdl/build 目录. 你可以直接在文件对话框中通过New Folder选项创建build文件夹.
  7. 点击 Configure. 然后点击 Generate. 这将在 spine-runtimes/spine-sdl/build 中创建一个名为 spine.sln 的 Visual Studio 解决方案文件, 并下载 SDL 依赖项.
  8. 在 Visual Studio 中打开 spine.sln 文件.
  9. 在解决方案资源管理器中右键单击 spine-sdl-example-c 或 spine-sdl-example-cpp 项目，并从上下文菜单中选择 Set as Startup Project.
  10. 点击 Local Windows Debugger 来运行示例项目.

完整示例代码可见 main.cpp.

Linux

  1. 安装 SDL 构建依赖项.
  2. 使用 git 下载 Spine Runtimes 存储库(git clone https://github.com/esotericsoftware/spine-runtimes), 也可以通过上文提到的下载按钮以 zip 格式下载.
  3. 打开一个终端, cd到 spine-runtimes/spine-sdl 文件夹.
  4. 输入 mkdir build && cd build && cmake ../.. 生成 Make 文件.
  5. 输入 make 编译示例项目.
  6. 输入 cd spine-sdl && ./spine-sdl-c-example (C) 或 cd spine-sdl && ./spine-sdl-cpp-example (C++) 运行示例.

Mac OS X

  1. 安装 Xcode.
  2. 安装 Homebrew.
  3. 打开一个终端并通过 brew install cmake 安装 CMake.
  4. 使用 git 下载 Spine Runtimes 存储库(git clone https://github.com/esotericsoftware/spine-runtimes), 也可以通过上文提到的下载按钮以 zip 格式下载.
  5. 打开一个终端, cd 到 spine-runtimes/spine-sdl 文件夹.
  6. 输入 mkdir build && cd build && cmake ../.. 生成 Make 文件.
  7. 输入 make 编译示例项目.
  8. 输入 cd spine-sdl && ./spine-sdl-c-example (C) 或 cd spine-sdl && ./spine-sdl-cpp-example (C++) 运行示例.

使用 spine-sdl

Spine-sdl 运行时支持使用SDL播放和操作 Spine 创建的动画. Spine-sdl 运行时既有 C 也有 C++ 的实现, 分别基于通用的spine-c和spine-cpp运行时. 它基于 SDL API 增加了文件加载和图像渲染实现.

请参阅 Spine 运行时指南 以获取 Spine 运行时架构的详细概述, spine-c 和 spine-cpp 文档则提供了用于播放和操作 Spine 动画的核心 API 的信息.

为SDL导出资产

请按Spine用户指南中的步骤操作以:

  1. 导出 skeleton & animation data
  2. 导出包含skeleton图片的texture atlases

导出skeleton数据和skeleton texture atlas将生成以下文件:

  1. skeleton-name.json or skeleton-name.skel, 其中包含skeleton和动画数据.
  2. skeleton-name.atlas, 其包含了texture atlas的信息.
  3. 一个或多个 .png 文件, 每个文件表示了texture atlas中的一页.

注意: Spine-sdl 运行时目前不支持以预乘 alpha 导出的atlas. Spine-sdl 运行时也不支持 Spine 编辑器中的双色tinting和screen blend模式.

载入 Spine skeletons

Spine-sdl 运行时使用 SDL_Renderer API 来显示skeleton. 在加载从Spine导出的Skeleton之前, 必须先创建一个 SDL_Renderer:

SDL_Renderer *renderer = SDL_CreateRenderer(window, -1, SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC);

下一步是使用C API载入texture atlas:

// C API
spAtlas *atlas = spAtlas_createFromFile("data/spineboy.atlas", renderer);

如果使用C++ API, 则额外需要一个 SDLTextureLoader 对象:

// C++ API
spine::SDLTextureLoader textureLoader(renderer);
spine::Atlas atlas("data/spineboy.atlas", &textureLoader);

atlas加载后, C-API可以通过如下方式加载 .json or .skel 文件:

// C API
spSkeletonJson *json = spSkeletonJson_create(atlas);
spSkeletonData *skeletonData = spSkeletonJson_readSkeletonDataFile(json, "data/spineboy-pro.json");
spSkeletonJson_dispose(json);

C++ API的skeleton加载方式如下:

// C++ API
spine::AtlasAttachmentLoader attachmentLoader(&atlas);
spine::SkeletonJson json(&attachmentLoader);
spine::SkeletonData *skeletonData = json.readSkeletonDataFile("data/spineboy-pro.json");

spAtlas/spine::Atlas 和 spSkeletonData/spine::SkeletonData 实例可以用来创建 spSkeletonDrawable/spine::SkeletonDrawable 实例,用以渲染skeleton数据.

注意: 已加载的skeleton数据和atlas可在且应在 spSkeletonDrawable/spine::SkeletonDrawable 实例间共享, 以减少内存消耗并使批量渲染共享同atlas数据的skeleton.

Skeleton drawable

在 spine-c 和 spine-cpp 的基础上, spine-sdl 的主要新增内容是skeleton drawable对象. 它持有一个 spSkeleton (C API) 或 spine::Skeleton (C++ API)对象, 该对象用于存储skeleton的骨骼、槽位、附件、约束等, 以及一个 spAnimationState (C API) or spine::AnimationState(C++ API)对象, 它用于让skeleton动起来. Skeleton drawable对象提供了更新动画状态、将动画状态应用到skeleton、更新skeleton并使用 SDL_Renderer 绘制skeleton的方法.

使用C API可以按如下方式创建skeleton drawable:

// C API
spAnimationStateData *animationStateData = spAnimationStateData_create(skeletonData);
spSkeletonDrawable *drawable = spSkeletonDrawable_create(skeletonData, animationStateData);

spAnimationStateData 存储了动画间的mix时间, 而它是构建内部对象 spAnimationState 所必需的类. 请参阅 spine-c 文档以了解更多信息.

如果使用C++ API, 则创建skeleton drawable对象的方式如下:

// C++ API
spine::SkeletonDrawable drawable(skeletonData);

如果你希望在drawable对象间共享mix时间, 可以选择将 spine::AnimationStateData 传入 spine::SkeletonDrawable 构造函数. 请参阅 spine-cpp 文档以了解更多相关信息.

创建了skeleton drawable对象后, 就可以访问内含的skeleton和动画状态实例以便操作它们.

// C API
drawable->skeleton->x = 400;
drawable->skeleton->y = 500;
spSkeleton_setToSetupPose(drawable->skeleton);

spAnimationState_setAnimationByName(drawable->animationState, 0, "portal", 0);
spAnimationState_addAnimationByName(drawable->animationState, 0, "run", -1, 0);

C++写法:

// C++ API
drawable.skeleton->setPosition(400, 500);
drawable.skeleton->setToSetupPose();

drawable.animationState->setAnimation(0, "portal", true);
drawable.animationState->addAnimation(0, "run", true, 0);

请参阅 spine-c 和 spine-cpp 文档, 以了解更多关于API如何操作skeleton和动画状态的信息.

Skeleton drawable还提供了一种方便的方法来更新其内含的skeleton和动画状态:

// C API
spSkeletonDrawable_update(drawable, deltaTimeInSeconds);

// C++ API
drawable.update(deltaTimeInSeconds);

update方法接收上一帧和当前帧之间的时间差, 然后更新动画状态, 将动画状态应用到skeleton, 最后更新skeleton的世界变换.

在更新动画状态和skeleton后, 可以以如下方式绘制它们:

// C API
spSkeletonDrawable_draw(drawable, renderer);

// C++ API
drawable.draw(renderer);

一旦你不再需要skeleton drawable对象, 可以通过以下方式释放内存:

// C API
spSkeletonDrawable_dipose(drawable);

// C++ API, if the drawable was allocated on the heap via new
delete drawable;

注意: 销毁skeleton drawable对象并不会销毁它所创建的skeleton数据和atlas. Skeleton数据和atlas需要通过各自的 API 单独销毁(在 C 中使用 spSkeletonData_dipose(skeletonData)/spAtlas_dispose(atlas), 在 C++ 中则使用 delete 关键字).