spine-cpp Runtime Documentation

Licensing

Please see the Spine Runtimes License before integrating the Spine Runtimes into your applications.

Introduction

spine-cpp is a generic runtime for integrating Spine animations in game engines and frameworks written in languages that can natively interface with C++.

spine-cpp provides functionality to:

As the spine-cpp runtime is a generic, engine independent runtime, users are required to implement a set of functions to provide engine specific file i/o and image loading to the spine-cpp runtime, render the data generated by the spine-cpp runtime via the engine's rendering system, and optionally integrate the data with the engine's physics system if more advanced use cases such as rag dolls are required.

The spine-cpp runtime is written using C++03 to guarantee compatibility with a wide range of platforms and compilers.

Other official Spine runtimes are based on spine-cpp and can serve as examples for integration with your engine of choice:

The following sections give a brief, engine independent overview of the spine-cpp runtime and how to use it. Most of the official Spine runtimes based on spine-cpp will encapsulate (parts of) the spine-cpp API in their own, easier to use API. It is still beneficial to understand the basics of the underlying spine-cpp runtime.

Note: This guide assumes you are familiar with the basic runtime architecture and terminology used by Spine. Please also consult the API reference to explore more advanced functions of the runtime.

Exporting Spine assets for spine-cpp

Please follow the instructions in the Spine User Guide on how to:

  1. Export skeleton & animation data to JSON or our binary format
  2. Export texture atlases containing the images of your skeleton

An export of the skeleton data and texture atlas of your skeleton will yield the following files:

  1. skeleton-name.json or skeleton-name.skel, containing your skeleton and animation data.
  2. skeleton-name.atlas, containing information about the texture atlas.
  3. One or more .png files, each representing one page of your texture atlas containing the packed images your skeleton uses.

Note: Instead of creating one texture atlas per skeleton, you may also pack the images of multiple skeletons into a single texture atlas. Please refer to the texture packing guide.

Loading Spine assets

spine-cpp provides APIs to load texture atlases, Spine skeleton data (bones, slots, attachments, skins, animations) and define mix times between animations through animation state data. These three types of data, also known as setup pose data, are generally loaded once and then shared by every game object. The sharing mechanism is achieved by giving each game object its own skeleton and animation state, also known as instance data.

Note: For a more detailed description of the overall loading architecture consult the generic Spine Runtime Documentation.

Loading texture atlases

Texture atlas data is stored in a custom atlas format that describes the location of individual images within atlas pages. The atlas pages themselves are stored as plain .png files next to the atlas.

The Atlas class provides a constructor to load an atlas file from disk and a constructor to load an atlas file from raw in-memory data for this task. If loading the atlas failed, an assert will trigger in debug mode.

#include <spine/spine.h>

using namespace spine;

// Load the atlas from a file. The last argument is engine specific and will
// load an atlas page texture and store it in the Atlas. The texture can
// later be retrieved via Atlas->getRendererObject() by the rendering code.
TextureLoader* textureLoader = new MyEngineTextureLoader();
Atlas* atlas = new Atlas("myatlas.atlas", textureLoader);

// Load the atlas from memory, giving the memory location, the number
// of bytes and the directory relative to which atlas page textures
// should be loaded. The last argument is engine specific and will
// load an atlas page texture and store it in the Atlas. The texture can
// later be retrieved via Atlas->getRendererObject() by the rendering code.
Atlas* atlas = new Atlas(atlasInMemory, atlasDataLengthInBytes, dir, textureLoader);

Loading skeleton data

Skeleton data (bones, slots, constraints, attachments, skins, animations) can be exported to human readable JSON or a custom binary format. spine-cpp stores skeleton data in SkeletonData class instances.

For loading the skeleton data from a JSON export, we create a SkeletonJson instance, which takes the previously loaded Atlas, set the scale of the skeleton and finally read the skeleton data from the file:

#include <spine/spine.h>

using namespace spine;

// Create a SkeletonJson used for loading and set the scale
// to make the loaded data two times as big as the original data
SkeletonJson json(atlas);
json.setScale(2);

// Load the skeleton .json file into a SkeletonData
SkeletonData* skeletonData = json.readSkeletonDataFile(filename);

// If loading failed, print the error and exit the app
if (!skeletonData) {
   printf("%s\n", json.getError().buffer());
   exit(0);
}

Loading skeleton data from a binary export works the same, except we use a SkeletonBinary instead:

// Create a SkeletonBinary used for loading and set the scale
// to make the loaded data two times as big as the original data
SkeletonBinary binary(atlas);
binary.setScale(2);

// Load the skeleton .skel file into a SkeletonData
SkeletonData* skeletonData = binary.readSkeletonDataFile(filename);

// If loading failed, print the error and exit the app
if (!skeletonData) {
   printf("%s\n", binary.getError().buffer());
   exit(0);
}

Preparing animation state data

Spine supports smooth transitions (crossfades) when switching from one animation to another. The crossfades are achieved by mixing one animation with another for a specific mix time. The spine-c runtime provides the AnimationStateData struct to define these mix times:

#include <spine/spine.h>

using namespace spine;

// Create the spAnimationStateData
AnimatonStateData* animationStateData = new AnimationStateData(skeletonData);

// Set the default mix time between any pair of animations in seconds.
animationStateData->setDefaultMix(0.1f);

// Set the mix time between from the "jump" to the "walk" animation to 0.2 seconds,
// overwriting the default mix time for this from/to pair.
animationStateData->setMix("jump", "walk", 0.2f);

The mix times defined in AnimationStateData can also be overwritten explicitly when applying animations (see below).

Skeletons

Setup pose data (skeleton data, texture atlases) are supposed to be shared between game objects. spine-cpp provides the Skeleton struct to facilitate this sharing. Every game object receives its own instance of Skeleton which in turn references an SkeletonData and Atlas instance as data sources.

The Skeleton can be freely modified, e.g. by procedurally modifying bones, applying animations or setting attachments and skins specific to a game object, while the underlying skeleton data and texture atlas stay in tact. This mechanism and setup allow sharing SkeletonData and Atlas instances by any amount of game objects.

Creating skeletons

To create a Skeleton instance:

Skeleton* skeleton = new Skeleton(skeletonData);

Every game object will need its own Skeleton. The bulk of the data remains in SkeletonData and Atlas and will be shared by all Skeleton instances to vastly reduce memory consumption and texture switches. The life-time of a Skeleton is thus coupled with the life-time of its corresponding game object.

Bones

A skeleton is a hierarchy of bones, with slots attached to bones, and attachments attached to slots.

Finding bones

All bones in a skeleton have a unique name by which they can be fetched from the skeleton:

// returns 0 if no bone of that name could be found
Bone* bone = skeleton->findBone("mybone");

Local transform

A bone is affected by its parent bone, all the way back to the root bone. E.g. when rotating a bone, all its child bones and all their children are also rotated. To accomplish these hierarchical transformations, each bone has a local transformation relative to its parent bone consisting of:

  • x and y coordinates relative to the parent.
  • rotation in degrees.
  • scaleX and scaleY.
  • shearX and shearY in degrees.

The local transform of a bone can be manipulated procedurally or via applying an animation. The former allows to implement dynamic behavior like having a bone point at a mouse cursor, let feet bones follow the terrain etc. Both procedural modification of the local transform as well as applying animations can be done simultaniously. The end result will be a single combined local transform.

World transform

Once all the local transforms are setup, either through procedurally modifying the local transforms of bones or by applying animations, we need the world transform of each bone for rendering and physics.

The calculation starts at the root bone, and then recursively calculates all child bone world transforms. The calculation also applies IK, transform and path constraints defined by the artist in the Spine editor.

To calculate the world transforms this way, the spine-cpp runtime offers the following method:

skeleton->updateWorldTransform();

The result is stored on each bone, and consists of:

  • a, b, c, and d: a 2x2 column major matrix encoding rotation, scale and shear of the bone.
  • worldX, worldY: the world position of the bone.

Note that worldX and worldY are offset by skeleton->getX() and skeleton->getY(). These two properties can be used to position the skeleton in your game engine's world coordinate system.

In general, the bones' world transforms should never be modified directly. Instead, they should always be derived from the local transforms of the bones in the skeleton by calling Skeleton::updateWorldTransform(). The local transforms can be set either procedurally, e.g. setting the rotation of a bone so it points to the mouse cursor, or by applying animations (see below), or both. Once the (procedural) animation is applied, Skeleton::updateWorldTransform() is called and the resulting world transforms are recalculated based on the local transform as well as any constraints that are applied to bones.

Coordinate system conversion

It is often easier to manipulate bones in the world coordinate system, as this is where coordinates from other entities or input events are usually given. However, since the world transform should not be directly manipulated, we need to apply any changes to a bone based on world coordinate system calculations to the local transform of that bone.

The spine-cpp runtimes provides functions to extract rotation and scale information from the 2x2 world transform matrix of a bone, and transform locations and rotations from local space to world space and vice versa. All these functions assume that the bones' world transforms have been calculated before by calling Skeleton::updateWorldTransform():

Bone* bone = skeleton->findBone("mybone");

// Get the rotation of a bone in world space relative to the world space x-axis in degrees
float rotationX = bone->getWorldRotationX();

// Get the rotation of a bone in world space relative to the world space y-axis in degrees
float rotationY = bone->getWorldRotationY();

// Get the scale of a bone in world space relative to the world space x-axis
float scaleX = bone->getWorldScaleX();

// Get the scale of a bone in world space relative to the world space y-axis
float scaleY = bone->getWorldScaleY();

// Transform a position given in world space to a bone's local space
float localX = 0, localY = 0;
bone->worldToLocal(worldX, worldY, localX, localY);

// Transform a position given in a bone's local space to world space
float worldX = 0, worldY = 0;
bone->localToWorld(localX, localY, worldX, worldY);

// Transform a rotation given in the world space to the bone's local space
float localRotationX = bone->worldToLocalRotation(bone)

Note: Your modifications to the local transform of a bone (and thereby all its children) will be reflected in the bone's world transform after the next call to Skeleton::updateWorldTransform().

Positioning

By default, a skeleton is assumed to be at the origin of the game's world coordinate system. To position a skeleton in a game's world coordinate system, you can use the x and y properties:

// make a skeleton follow a game object in world space
skeleton->setX(myGameObject->worldX);
skeleton->setY(myGameObject->worldY);

Note: Your modifications to the skeleton x and y properties will be reflected in the bone world transforms after the next call to Skeleton::updateWorldTransform().

Flipping

A skeleton can be flipped vertically or horizontally. This allows reusing animations made for one direction for the opposing direction, or for working in coordinate systems with the y-axis pointing downwards (Spine assumes y-axis up by default):

// flip vertically around the x-axis
skeleton->setScaleY(-1);

// flip horizontally around the y-axis
skeleton->setScaleY(-1);

Note: Your modifications to the skeleton scaleX and scaleY properties will be reflected in the bone world transforms after the next call to Skeleton::updateWorldTransform().

Setting skins

The artist creating the Spine skeleton may have added multiple skins to the skeleton to add visual variations of the same skeleton, e.g. a female and male version. The spine-cpp runtime stores skins in instances of Skin.

A skin at runtime is a map defining which attachment goes into which slot of the skeleton. Every skeleton has at least one skin which defines which attachment is on what slot in the skeleton's setup pose. Additionally skins have a name to identify them.

Setting a skin on a skeleton via spine-cpp:

// set a skin by name
skeleton->setSkin("my_skin_name");

// set the default setup pose skin by passing NULL
skeleton->setSkin(NULL);

Note: Setting a skin takes into account what skin and hence which attachments have previously been set. Please refer to the generic runtime guide for more information on setting skins.

Setting attachments

spine-cpp allows setting a single attachment on a skeleton's slot directly, e.g. to switch out weapons. The attachment is first searched in the active skin, and if this fails, in the default setup pose skin:

// Set the attachment called "sword" on the "hand" slot
skeleton->setAttachment("hand", "sword");

// Clear the attachment on the slot "hand" so nothing is shown
skeleton->setAttachment(skeleton, "hand", "");

Tinting

You can tint all attachments in a skeleton by setting the skeleton's color:

// tint all attachments with red and make the skeleton half translucent.
skeleton->getColor().set(1, 0, 0, 0.5f);

Note: Colors in spine-cpp are given as RGBA, with values for each channel in the range [0-1].

When rendering a skeleton, the renderer walks though the draw order of slots on the skeleton and renders the currently active attachment on each slot. In addition to the skeleton's color, every slot also has a color which can be manipulated at runtime:

Slot* slot = skeleton->findSlotByName("mySlot");
slot->getColor().set(1, 0, 1, 1);

Note that slot colors can also be animated. If you manually change a slot's color and then apply an animation that keys that slot's color, your manual change will be overwritten.

Applying animations

The Spine editor lets artists create multiple, uniquely named animations. An animation is a set of timelines. Each timeline specifies at what frame what property of a bone or the skeleton should change to what value. There are many different types of timelines, from timelines defining the transform of a bone over time, to timelines that change the drawing order. Timelines are part of the skeleton data and stored in Animation instances within SkeletonData in spine-cpp.

Timeline API

spine-cpp provides a timeline API should the need arise to directly work with timelines. This low-level functionality allows you to fully customize the way animations defined by your artist are applied to a skeleton.

Animation state API

In almost all cases, you should use the animation state API instead of the timeline API. The animation state API makes task such as applying animations over time, queueing animations, mixing between animations, and applying multiple animations at the same time considerably easier than the low-level timeline API. The animation state API uses the timeline API internally and can thus be seen as a wrapper.

spine-cpp represents an animation state via the AnimationState class. Just like skeletons, an AnimationState is instantiated per game object. In general, you will have one Skeleton and one AnimationState instance per game object in your game. And just like Skeleton, the AnimationState will share SkeletonData (wherein animations and their timelines are stored) and AnimationStateData (wherein mix times are stored) with all other AnimationState instances, sourcing the same skeleton data.

Creating animation states

To create an AnimationStateinstance:

AnimationState* animationState = new AnimationState(animationStateData);

The function takes an AnimationStateData which is usually created when the skeleton data is loaded, and which defines the default mix time as well as mix times between specific animations for crossfades.

Tracks & Queueing

An animation state manages one or more tracks. Each track is a list of animations that should be played back in the order they were added to the track. This is known as queuing. Tracks are indexed starting from 0.

You can queue an animation on a track like this:

// Add the animation "walk" to track 0, without delay, and let it loop indefinitely
int track = 0;
bool loop = true;
float delay = 0;
animationState->addAnimation(track, "walk", loop, delay);

You can queue multiple animations at once as a fire and forget way to create animation sequences:

// Start walking (note the looping)
animationState->addAnimation(0, "walk", true, 0);

// Jump after 3 seconds
animationState->addAnimation(0, "jump", false, 3);

// Once we are done jumping, idle indefinitely
animationState->addAnimation(0, "idle", true, 0);

You can also clear all animations queued in a track:

// Clear all animations queued on track 0
animationState->clearTrack(0);

// Clear all animations queued on all tracks
animationState->clearTracks(animationState);

Instead of clearing and adding a new animation to a track, you can call AnimationState::setAnimation(). This will clear all tracks, but remember what the last played back animation was before clearing and crossfade to the newly set animation. This way you can smoothly transition from one animation sequence to the next. You can add more animations to the track after calling AnimationState::setAnimation() by calling AnimationState::addAnimation():

// Whatever is currently playing on track 0, clear the track and crossfade
// to the "shot" animation, which should not be looped (last parameter).
animationState->addAnimation(0, "shot", false, 0);

// After shooting, we want to idle again
animationState->addAnimation(0, "idle", true, 0);

To crossfade to the setup pose of the skeleton from an animation, you can use AnimationState::setEmptyAnimation(), AnimationState::addEmptyAnimation(), where the former clears the current track and crossfades to the skeleton, and the later enqueues a crossfade to the setup pose as part of the animation sequence on the track:

// Whatever is currently playing on track 0, clear the track and crossfade
// to the setup pose for 0.5 seconds (mix time).
animationState->setEmptyAnimation(0, 0.5f);

// Add a crossfade to the setup pose for 0.5 seconds as part of the animation
// sequence in track 0, with a delay of 1 second.
animationState->addEmptyAnimation(0, 0.5f, 1)

For simple games, using a single track is usually enough to achieve your goals. More complex games may want to queue animations on separate tracks, e.g. to simultaniously play back a walk animation while shooting. This is where the real power of Spine comes into play:

// Apply the "walk" animation on track 0 indefinitely.
animationState->setAnimation(0, "walk", true);

// Simultaniously apply a "shot" animation on track 1 once.
animationState->setAnimation(1, "shot", false);

Note that if you apply animations simultaniously like that, animations on the higher track will overwrite animations on the lower track for every value both animations have keyed. For authoring animations, this means to make sure two animations to be played back simultaniously don't key the same values in the skeleton, e.g. the same bone, attachment, color etc. Additive animation blending lets you add the results of timelines on different tracks that effect the same skeleton property.

You can control the mixing of animations on different tracks via track entries

Track Entries

Every time you enqueue an animation on a track of an animation state, the corresponding functions will return an TrackEntry instance. This track entry allows you to further customize both the queued animation, as well as its mixing behaviour with regards to animations on the same or other tracks. See the TrackEntry documentation for the full API.

As an example, lets assume the mix time between a "walk" and "run" animation defined in an AnimationStateData is to high for this specific game object in its current situation. You can modify the mix time between "walk" and "run" ad-hoc, just for this specific queued animation:

// Walk indefinitely
sanimationState->setAnimation(0, "walk", true);

// At some point, queue the run animation. We want to speed up the mixing
// between "walk" and "run" defined in the `AnimationStateData` (let's say 0.5 seconds)
// for this one specific call to be faster (0.1 seconds).
TrackEntry* entry = animationState->addAnimation(0, "run", true, 0);
entry->setMixDuration(0.1f);

You can hold on to the TrackEntry to modify it over time. The TrackEntry will be valid for as long as the animation is queued on that track. Once the animation is completed, the TrackEntry will be deallocated. Any subsequent access will be invalid and likely result in a segfault. You can register a listener to get notified when the animation and hence the track entry are no longer valid.

Events

An animation state generates events while playing back queued animations to notify a listener about changes:

  • An animation started.
  • An animation was interrupted, e.g. by clearing a track.
  • An animation was completed, which may occur multiple times if looped.
  • An animation has ended, either due to interruption or it has completed and is not looped.
  • An animation and its corresponding TrackEntry have been disposed and are no longer valid.
  • A user defined event was fired.

You can listen for these events by registering a function either with the animation state, or with individual TrackEntry instances returned by the animation state.

// Define the function that will be called when an event happens
void callback (AnimationState* state, EventType type, TrackEntry* entry, Event* event) {
   const String& animationName = (entry && entry->getAnimation()) ? entry->getAnimation()->getName() : String("");

   switch (type) {
   case EventType_Start:
      printf("%d start: %s\n", entry->getTrackIndex(), animationName.buffer());
      break;
   case EventType_Interrupt:
      printf("%d interrupt: %s\n", entry->getTrackIndex(), animationName.buffer());
      break;
   case EventType_End:
      printf("%d end: %s\n", entry->getTrackIndex(), animationName.buffer());
      break;
   case EventType_Complete:
      printf("%d complete: %s\n", entry->getTrackIndex(), animationName.buffer());
      break;
   case EventType_Dispose:
      printf("%d dispose: %s\n", entry->getTrackIndex(), animationName.buffer());
      break;
   case EventType_Event:
      printf("%d event: %s, %s: %d, %f, %s\n", entry->getTrackIndex(), animationName.buffer(), event->getData().getName().buffer(), event->getIntValue(), event->getFloatValue(),
            event->getStringValue().buffer());
      break;
   }
   fflush(stdout);
}

// Register the function as a listener on the animation state. It will be called for all
// animations queued on the animation state.
animationState->setListener(myListener);

// Or you can register the function as a listener for events for a specific animation you enqueued
TrackEntry* trackEntry = animationState->setAnimation(0, "walk", true);
trackEntry->setListener(myListener);

User defined events are perfect to mark times in an animation at which sounds should be played back, e.g. foot steps.

Changes made to the animation state within a listener, such as setting a new animation, are not applied to skeletons until the next time AnimationState::apply is called. You can immediately apply the changes within the listener:

void myListener(AnimationState* state, EventType type, TrackEntry* entry, Event* event) {
   if (somecondition) {
      state->setAnimation(0, "run", false);
      state->update(0);
      state->apply(skeleton);
   }
}

Applying animation states

Animation states are inherently time-based. To advance their state, you will need to update them every tick, supplying the amount of time that has passed since the last update in seconds:

state->update(deltaTimeInSeconds);

This will advance the playback of animations on each track, coordinate crossfades and call any listeners you might have registered.

After updating the animation state, you want to apply it to a skeleton to update its bones local transforms, attachments, slot colors, draw order and anything else that can be animated:

state->apply(*skeleton);

With the skeleton posed and animated, you finally update its bones world transforms to prepare it for rendering or physics:

skeleton->updateWorldTransform();

Putting it all together

Here's a simplified example of how to put all the above together, from loading and instantiating to applying animations (scroll to see all the code):

// Setup pose data, shared by all skeletons
Atlas* atlas;
SkeletonData* skeletonData;
AnimationStateData* animationStateData;

// 5 skeleton instances and their animation states
Skeleton* skeleton[5];
AnimationState* animationState[5];
char* animationNames[] = { "walk", "run", "shot" };

void setup() {
   // setup your engine so textures can be loaded for atlases, create a window, etc.
   engine_setup();

   // Load the texture atlas
   atlas = new Atlas("spineboy.atlas", MyEngineTextureLoader());
   if (atlas.getPages().size() == 0) {
      printf("Failed to load atlas");
      delete atlas;
      exit(0);
   }

   // Load the skeleton data
   SkeletonJson json(atlas);
   skeletonData = json.readSkeletonDataFile("spineboy.json");
   if (!skeletonData) {
      printf("Failed to load skeleton data");
      delete atlas;
      exit(0);
   }

   // Setup mix times
   animationStateData = new AnimationStateData(skeletonData);
   animationStateData->setDefaultMix(0.5f);
   animationStateDAta->setMix("walk", "run", 0.2f);
   animationStateData->setMix("walk", "shot", 0.1f);
}

void mainLoop() {
   // Create 5 skeleton instances and animation states
   // representing 5 game objects
   for (int i = 0; i < 5; i++) {
      // Create the skeleton and put it at a random position
      Skeleton* skeleton = new Skeleton(skeletonData);
      skeleton->setX(random(0, 200));
      skeleton->setY(random(0, 200));

      // Create the animation state and enqueue a random animation, looping
      AnimationState *animationState = new AnimationState(animationStateData);
      animationState->setAnimation(0, animationNames[random(0, 3)], true);
   }

   while (engine_gameIsRunning()) {
      engine_clearScreen();

      // update the game objects
      for (int i = 0; i < 5; i++) {
         Skeleton* skeleton = skeletons[i];
         AnimationState* animationState = animationStates[i];

         // First update the animation state by the delta time
         animationState->update(engine_getDeltaTime());

         // Next, apply the state to the skeleton
         animationState->apply(skeleton);

         // Calculate world transforms for rendering
         skeleton->updateWorldTransform();

         // Hand off rendering the skeleton to the engine
         engine_drawSkeleton(skeleton);
      }
   }

   // Dispose of the instance data. Normally you'd do this when
   // a game object is disposed.
   for (int i = 0; i < 5) {
      delete skeletons[i];
      delete animationStates[i];
   }
}

void dispose() {
   // dispose all the shared resources
   delete atlas;
   delete skeletonData;
   delete animationStateData;
}

int main(int argc, char* argv) {
   setup();
   mainLoop();
   dispose();
}

Note the distinction of setup pose data (Atlas, SkeletonData, AnimationStateData) and instance data (Skeleton, AnimationState) and their different life-times.

Memory management

We have tried to make spine-cpp memory management as straight forward as possible. Any class or struct that is allocted via new needs to be deallocated with the corresponding delete. The life-time of class instances depends on what type of class instance it is. General rules of thumb:

  • Create setup pose data shared by instance data (Atlas, SkeletonData, AnimationStateData) at game or level startup, dispose it at game or level end.
  • Create instance data (Skeleton, AnimationState) when the corresponding game object is created, dispose it when the corresponding game object is destroyed.

Track entries (TrackEntry) are valid from a call to one of the enqueuing animation state functions (AnimationState::setAnimation(), AnimationState::addAnimation(), AnimationState::setEmptyAnimation(), AnimationState::addEmptyAnimation()) until the EventType_dispose event is send to your listener. Accessing the track entry after this event will likely result in a segmentation fault.

When creating structs, you often pass in other structs as references. The referencing struct will never dispose the referenced struct. E.g. an Skeleton references a SkeletonData which in turn references an Atlas.

  • Disposing the Skeleton will not dispose the SkeletonData nor the Atlas. This makes sense, as the SkeletonData is likely shared by other Skeletoninstances.
  • Disposing the SkeletonData will not dispose the Atlas. This also makes sense, as the Atlas may be shared by other SkeletonData instances, e.g. if the atlas contains the images of multiple skeletons.

If you use a custom allocator, you can overwrite Spine's allocation strategy by implementing your own SpineExtension. Your custom SpineExtension may derrive from DefaultSpineExtension and should overwrite the _alloc, _calloc, _realloc and _free (inheriting the implementation of _readFile). You can then set the extension with a call to spine::SpineExtension::setInstance() on program startup. Alternatively, if you do not use Spine runtime engine integration, you have to implement the spine::getDefaultExtension() method to provide Spine with an extension that's compatible with the memory management and file management of your engine.

Spine also comes with a simple memory leak detector in the form of a SpineExtension wrapper class called DebugExtension in spine/Debug.h. Wrapping another extension with DebugExtension will enable the debug extension to track your allocations, along with the file locations and line numbers, provided you allocated your Spine objects like this:

Skeleton* skeleton = new (__FILE__, __LINE__) Skeleton(skeletonData);

The __FILE__ and __LINE__ arguments are used by the debug extension to keep track where allocations have happened. When your program, exits, you can let the debug extension print a report to stdout.

#include <spine/Extension.h>
#include <spine/Debug.h>

static DebugExtension *debugExtension = NULL;

// This will be used by Spine to get the initial extension instance.
SpineExtension* spine::getDefaultExtension() {
   // return a default spine extension that uses standard malloc for memory
   // management, and wrap it in a debug extension.
   debugExtension = new DebugExtension(new DefaultSpineExtension());
   return debugExtension;
}

int main (int argc, char** argv) {
   ... your app code allocating Spine objects via `new (__FILE__, __LINE__) SpineClassName()` and deallocating via `delete instance` ...

   debugExtension->reportLeaks
();
}

Integrating spine-cpp in your engine

Integrating the sources

spine-cpp is a set a of C++ header and implementation files found in the spine-cpp/spine-cpp folder of the runtime Git repository.

  1. Clone the Spine runtime repository or download it as a ZIP file
  2. Copy the sources from the spine-cpp/spine-cpp/src/spine folder to the source folder of your project and make sure they are part of the compilation step of your project.
  3. copy the folder spine containing the headers from the spine-cpp/spine-cpp/include folder to the header folder of your project and make sure they are part of the include path the compiler uses to look up headers. Make sure to keep the spine folder as the spine-cpp sources include headers via #include "spine/xxx.h".

If you compile your project you will receive linker errors for the function the spine-cpp runtime expects you to implement. E.g. compiling with Clang will yield something like:

Undefined symbols for architecture x86_64:
"spine::getDefaultExtension()", referenced from:
    spine::SpineExtension::getInstance() in libspine-cpp.a(Extension.cpp.o)
ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Implementing memory and file I/O

The function the linker can not find is responsible for returning a SpineExtension. The spine-cpp runtime expects you to implement a class derrived from this class via APIs provided by your engine. The extension is defined in Extension.h.

Note: if you are using any of the official Spine runtimes that are based on the spine-cpp runtime, these functions plus rendering are already implemented for you. You can ignore this section.

If you are happy with Spine using malloc, free and FILE based file i/o, you can use the DefaultSpineExtension and implement the missing function like this:

#include <spine/Extension.h>

spine::SpineExtension *spine::getDefaultExtension() {
   return new spine::DefaultSpineExtension();
}

Otherwise you can derrive from either SpineExtension or DefaultSpineExtension and override the _malloc, _calloc, _realloc, _free and _readFile methods.

Implementing a TextureLoader

spine-cpp's Atlas class expects to be passed an instance of TextureLoader to load and create an engine specific texture representation for a single atlas page. The TextureLoader class has two methods, load to load a method for an atlas page given a path, and unload to dispose of the texture.

The load function may store the texture in the atlas page via a call to AtlasPage::setRendererObject(). This makes it easy later on to get the texture an attachment references via a region in an atlas page.

The load method is also supposed to set the width and height of the AtlasPage in pixels according to the texture file loaded by the engine. This data is required to compute texture coordinates by spine-c.

The load function's path parameter is the path to the page image file, relative to the .atlas file path passed to the Atlas constructor, or relative to the dir parameter of the second Atlas constructor that loads the atlas from meory.

For the purpose of illustration, assume your engine provides the following API to work with textures:

struct Texture {
   // ... OpenGL handle, image data, whatever ...
   int width;
   int height;
};

Texture* engine_loadTexture(const char* file);
void engine_disposeTexture(Texture* texture);

Implementing TextureLoader is then as simple as:

#include <spine/TextureLoader.h>

class MyTextureLoader: public TextureLoader {
   public:
      TextureLoader() { }

      virtual ~TextureLoader() { }

      // Called when the atlas loads the texture of a page.
      virtual void load(AtlasPage& page, const String& path) {
         Texture* texture = engine_loadTexture(path);

         // if texture loading failed, we simply return.
         if (!texture) return;

         // store the Texture on the rendererObject so we can
         // retrieve it later for rendering.
         page.setRendererObject(texture);

         // store the texture width and height on the spAtlasPage
         // so spine-c can calculate texture coordinates for
         // rendering.
         page.setWidth(texture->width)
         page.setHeight(texture->height);
      }

      // Called when the atlas is disposed and itself disposes its atlas pages.
      virtual void unload(void* texture) {
         // the texture parameter is the texture we stored in the page via page->setRendererObject()
         engine_disposeTexture(texture);
      }
}

The resulting texture loader can then be passed to either of the two Atlas constructors.

Implementing Rendering

Rendering a Spine skeleton means rendering all currently active attachments in the current draw order. The draw order is defined as an array of slots on the skeleton.

Drawable attachments (regions, (deformable) meshes) define UV mapped, vertex colored, triangle meshes. Both RegionAttachment and MeshAttachment implement the HasRendererObject interface, which lets us fetch the the atlas page texture previously loaded via an engine specific TextureLoader, to which the triangles of the attachment are mapped.

Assuming you already have animated your skeleton, either procedurally or via an animation state, and that you have updated the skeleton bones' world transform via a call to Skeleton::updateWorldTransform(), you can render a skeleton as follows:

  • For each slot in the draw order array of the skeleton
    • Fetch the currently active attachment from the slot (can be null if no attachment is active)
    • Fetch the blend mode from the slot and translate it to your engine's API
    • Calculate the tint color based on the skeleton's and slot's color
    • Check the type of the attachment
      • If it is a region attachment
        • Compute its world vertices by calling RegionAttachment::computeWorldVertices
        • Fetch the atlas page texture from the attachment's render object
        • Calculate the tint color of the attachment by multiplying the skeleton and slot color, given as RGBA in the range [0-1] per channel
        • Combine the world space vertices, UVs and color into a triangle mesh
        • Bind the texture through your engine's API
        • Submit the mesh for rendering
      • If it is a mesh attachment
        • Compute its world vertices by calling VertexAttachment::computeWorldVertices
        • Fetch the atlas page texture from the attachment's render object
        • Calculate the tint color of the attachment by multiplying the skeleton and slot color, given as RGBA in the range [0-1] per channel
        • Combine the world space vertices, UVs and color into a triangle mesh
        • Bind the texture through your engine's API
        • Submit the mesh for rendering

Translating this to your engine should be trivial, provided your engine allows rendering of UV mapped, vertex colored triangle meshes. For illustration purposes, let's assume the following engine API:

// A single vertex with UV
struct Vertex {
   // Position in x/y plane
   float x, y;

   // UV coordinates
   float u, v;

   // Color, each channel in the range from 0-1
   // (Should really be a 32-bit RGBA packed color)
   spine::Color color;
};

enum BlendMode {
   // See http://esotericsoftware.com/git/spine-runtimes/blob/spine-libgdx/spine-libgdx/src/com/esotericsoftware/spine/BlendMode.java#L37
   // for how these translate to OpenGL source/destination blend modes.
   BLEND_NORMAL,
   BLEND_ADDITIVE,
   BLEND_MULTIPLY,
   BLEND_SCREEN,
}

// Draw the given mesh.
// - vertices is a pointer to an array of Vertex structures
// - indices is a pointer to an array of indices. Consecutive indices of 3 form a triangle.
// - numIndices the number of indices, must be divisble by 3, as there are 3 vertices in a triangle.
// - texture the texture to use
// - blendMode the blend mode to use
void engine_drawMesh(Vertex* vertices, unsigned short* indices, size_t numIndices, Texture* texture, BlendMode blendmode);

The rendering process can then be implemented like this:

spine::Vector<Vertex> vertices;
unsigned short quadIndices[] = {0, 1, 2, 2, 3, 0};

void drawSkeleton(Skeleton* skeleton) {
   // For each slot in the draw order array of the skeleton
   for (size_t i = 0, n = skeleton->getSlots().size(); i < n; ++i) {
      Slot* slot = skeleton->getDrawOrder()[i];

      // Fetch the currently active attachment, continue
      // with the next slot in the draw order if no
      // attachment is active on the slot
      Attachment* attachment = slot->getAttachment();
      if (!attachment) continue;

      // Fetch the blend mode from the slot and
      // translate it to the engine blend mode
      BlendMode engineBlendMode;
      switch (slot->getData().getBlendMode()) {
         case BlendMode_Normal:
            engineBlendMode = BLEND_NORMAL;
            break;
         case BlendMode_Additive:
            engineBlendMode = BLEND_ADDITIVE;
            break;
         case BlendMode_Multiply:
            engineBlendMode = BLEND_MULTIPLY;
            break;
         case BlendMode_Screen:
            engineBlendMode = BLEND_SCREEN;
            break;
         default:
            // unknown Spine blend mode, fall back to
            // normal blend mode
            engineBlendMode = BLEND_NORMAL;
      }

      // Calculate the tinting color based on the skeleton's color
      // and the slot's color. Each color channel is given in the
      // range [0-1], you may have to multiply by 255 and cast to
      // and int if your engine uses integer ranges for color channels.
      Color skeletonColor = skeleton->getColor();
      Color slotColor = slot->getColor();
      Color tint(skeletonColor.r * slotColor.r, skeletonColor.g * slotColor.g, skeletonColor.b * slotColor.b, skeletonColor.a * slotColor.a);

      // Fill the vertices array, indices, and texture depending on the type of attachment
      Texture* texture = NULL;
      unsigned short* indices = NULL;
      if (attachment->getRTTI().isExactly(RegionAttachment::rtti)) {
         // Cast to an spRegionAttachment so we can get the rendererObject
         // and compute the world vertices
         RegionAttachment* regionAttachment = (RegionAttachment*)attachment;

         // Ensure there is enough room for vertices
         vertices.setSize(4, Vertex());

         // Computed the world vertices positions for the 4 vertices that make up
         // the rectangular region attachment. This assumes the world transform of the
         // bone to which the slot (and hence attachment) is attached has been calculated
         // before rendering via Skeleton::updateWorldTransform(). The vertex positions
         // will be written directoy into the vertices array, with a stride of sizeof(Vertex)
         regionAttachment->computeWorldVertices(slot->getBone(), &vertices.buffer().x, 0, sizeof(Vertex));

         // Our engine specific Texture is stored in the AtlasRegion which was
         // assigned to the attachment on load. It represents the texture atlas
         // page that contains the image the region attachment is mapped to.
         texture = (Texture*)((AtlasRegion*)regionAttachment->getRendererObject())->page->getRendererObject();

         // copy color and UVs to the vertices
         for (size_t j = 0, l = 0; j < 4; j++, l+=2) {
            Vertex& vertex = vertices[j];
            vertex.color.set(tint);
            vertex.u = regionAttachment->getUVs()[l];
            vertex.v = regionAttachment->getUVs()[l + 1];
         }

         // set the indices, 2 triangles forming a quad
         indices = quadIndices;
      } else if (attachment->getRTTI().isExactly(MeshAttachment::rtti)) {
         // Cast to an MeshAttachment so we can get the rendererObject
         // and compute the world vertices
         MeshAttachment* mesh = (MeshAttachment*)attachment;

         // Ensure there is enough room for vertices
         vertices.setSize(mesh->getWorldVerticesLength() / 2, Vertex());

         // Computed the world vertices positions for the vertices that make up
         // the mesh attachment. This assumes the world transform of the
         // bone to which the slot (and hence attachment) is attached has been calculated
         // before rendering via Skeleton::updateWorldTransform(). The vertex positions will
         // be written directly into the vertices array, with a stride of sizeof(Vertex)
         size_t numVertices = mesh->getWorldVerticesLength() / 2;
         mesh->computeWorldVertices(slot, 0, numVertices, vertices.buffer(), 0, sizeof(Vertex));

         // Our engine specific Texture is stored in the AtlasRegion which was
         // assigned to the attachment on load. It represents the texture atlas
         // page that contains the image the region attachment is mapped to.
         texture = (Texture*)((AtlasRegion*)mesh->getRendererObject())->page->getRendererObject();

         // Copy color and UVs to the vertices
         for (size_t j = 0, l = 0; j < numVertices; j++, l+=2) {
            Vertex& vertex = vertices[j];
            vertex.color.set(tint);
            vertex.u = mesh->getUVs()[l];
            vertex.v = mesh->getUVs()[l + 1];
         }

         // set the indices, 2 triangles forming a quad
         indices = quadIndices;
      }

      // Draw the mesh we created for the attachment
      engine_drawMesh(vertices, 0, vertexIndex, texture, engineBlendMode);
   }
}

This naive implementation will get you up and running quickly. However, there are a couple of low-hanging fruit in terms of optimization:

  • engine_drawMesh is assumed to submit the mesh for rendering immediately. This means we issue one draw call per attachment on the skeleton. A production grade implementation should batch all the meshes into a single mesh. Ideally, if all attachments use the same texture atlas page and blend mode, drawing a skeleton will only incure a single draw call. If all skeletons in a scene share the same texture atlas page and blend mode, you can even batch all skeletons into a single mesh, and hence a single draw call.
  • The current setup does not support two color tinting.
  • The current setup does not support clipping.

In the code above (and in all Spine Runtimes using spine-cpp as the base), we make use of spine::Vector, a light-weight container. Since standard C++ RTTI can be heavy, we have also opted to implement our own RTTI solution. You can see it used in the above code to distinguish between types of attachments.