spine-sdlランタイムドキュメント

ライセンスについて

Spineランタイムをアプリケーションに組み込む前に、必ずSpine Runtimes Licenseを確認してください。

はじめに

インストール方法

spine-sdl ランタイムは C および C++ API として利用できます。C API は汎用spine-cランタイムをベースにしており、C++ API は汎用 spine-cppランタイムをベースにしています。spine-sdl をプロジェクトに統合するには:

  1. まず新しいSDLプロジェクトを作成します。 詳しくはSDLの公式ドキュメントを参照するか、spine-runtimesリポジトリにあるCMake をビルドシステムとして利用しているサンプルをご覧ください。
  2. gitを利用してSpineランタイムのソースをダウンロードします (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が必要です。これは 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インストーラーパッケージからCMakeをインストールします。
  3. git (git clone https://github.com/esotericsoftware/spine-runtimes)を使って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 build dependenciesをインストールします。
  2. git (git clone https://github.com/esotericsoftware/spine-runtimes)を使って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 (git clone https://github.com/esotericsoftware/spine-runtimes)を使って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 ランタイムは、汎用spine-cおよび汎用spine-cppランタイムをベースにした C および C++ の実装です。また、SDL API に基づいたローディングとレンダリングの実装も追加されています。

Spineランタイムのアーキテクチャの詳細についてはSpineランタイムガイドを、Spineで作成されたアニメーションの再生と操作に使用されるCおよびC++のコアAPIについてはspine-cおよび spine-cppのドキュメントを参照してください。

SDL用にエクスポートする

以下の実行方法については、Spineユーザーガイド内で紹介されています :

  1. スケルトン＆アニメーションデータのエクスポート
  2. スケルトンの画像を含むテクスチャアトラスのエクスポート

スケルトンのデータとテクスチャアトラスをエクスポートすると、以下のファイルが得られます:

  1. skeleton-name.json または skeleton-name.skel:　これはスケルトンとアニメーションのデータを含んでいます。
  2. skeleton-name.atlas:　これはテクスチャアトラスの情報を含んでいます。
  3. １つまたは複数の .png ファイル:　これはテクスチャアトラスの各ページで、スケルトンが使用するイメージを含んでいます。

注意: spine-sdlランタイムは、Spineエディターで利用可能な2色カラーティントとスクリーンブレンドモードをサポートしていないので注意してください。

Spineスケルトンのローディング

spine-sdlランタイムは、SDL_Renderer APIを使用してスケルトンを表示します。そのため、エクスポートされたファイルからスケルトンをロードする前に、以下のように SDL_Renderer を作成する必要があります:

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

次に、テクスチャアトラスは、C APIでは次のようにロードできます:

// 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);

アトラスがロードされたら、C API では .json または .skel ファイルを次のようにロードすることができます:

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

C++ APIではスケルトンファイルのロードは次のように行います:

// 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 インスタンスを作成し、スケルトンデータをレンダリングできます。

補足: ロードしたスケルトンデータとアトラスは、spSkeletonDrawable/spine::SkeletonDrawable インスタンス間で共有することができます。これによりメモリ消費量を削減し、同じアトラスデータを共有するスケルトンの一括レンダリングが可能になります。

Skeleton drawable

spine-c および spine-cpp の上に追加されたspine-sdlの主な機能は、スケルトンの描画機能です。これは spSkeleton (C API) または spine::Skeleton (C++ API) を保持し、スケルトンのボーン、スロット、アタッチメント、コンストレイントなどを保存し、spAnimationState (C API) または spine::AnimationState がスケルトンのアニメーションを管理します。Skeleton drawable には、AnimationStateの更新、スケルトンへの適用、スケルトンの更新、 SDL_Renderer を使用したスケルトンの描画を行うメソッドが用意されています。

C APIを使用する場合は、以下のようにして Skeleton drawable を作成することができます:

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

spAnimationStateData はアニメーション間のミックス時間を保存し、内部の spAnimationState を構築するために必要です。詳しくは spine-c のドキュメントを参照してください。

C++ APIの場合、Skeleton drawable の作成は次のように行います:

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

ミックス時間を複数のdrawable間で共有したい場合、オプションで spine::AnimationStateData を spine::SkeletonDrawable コンストラクタに渡すこともできます。詳しくは spine-cpp のドキュメントを参照してください。

Skeleton drawable が作成されると、それに含まれるスケルトンとAnimationStateのインスタンスにアクセスして操作できるようになります。

// 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);

スケルトンやAnimationStateを操作するAPIの詳細についてはspine-cおよびspine-cppのドキュメントを参照してください。

Skeleton drawableは、スケルトンとAnimationStateを簡単に更新するメソッドも提供しています:

// C API
spSkeletonDrawable_update(drawable, deltaTimeInSeconds);

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

updateメソッドは、最後のフレームと現在のフレームとの間の差分時間（秒）を取り、AnimationStateを更新し、AnimationStateをスケルトンに適用し、最後にスケルトンのワールドトランスフォームを更新します。

AnimationStateとスケルトンが更新されたら、以下のようにしてそれを描画することができます:

// 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を解放しても、そこから作成されたスケルトン データとアトラスは解放されません。スケルトン データとアトラスは、それぞれの API (Cの場合は spSkeletonData_dipose(skeletonData)/spAtlas_dispose(atlas)、C++の場合は delete)を使って個別に解放する必要があります。