API Reference

The api has a only a few methods to get you started:

• use setupWebGL or createPlayer to initialize the canvas and get an GeppettoPlayer object.
• use prepareAnimation to convert your animation to use with GeppettoPlayer.addAnimation.
• use the AnimationControl (as return of GeppettoPlayer.addAnimation) to control your animation.

setupWebGL

Initializes the WebGL Context of a provided context. Configures the context and returns a GeppettoPlayer bound to this element.

Use this method if you only render Geppetto Animations in your Canvas. Use createPlayer if you want your own control over the canvas configuration

Returns GeppettoPlayer

Arguments

• element HTMLCanvasElement the Canvas DOM element that is not yet initialized with a context

const setupWebGL = (element: HTMLCanvasElement): GeppettoPlayer;

createPlayer

Initializes a player to display in an existing WebGL Environment. Use this function to create a player if you want to have full control over the rendering process (possibly to combine with other render code).

Returns GeppettoPlayer

Arguments

• element HTMLCanvasElement the Canvas DOM element containing a WebGL Context

const createPlayer = (element: HTMLCanvasElement): GeppettoPlayer;

prepareAnimation

Convert the JSON based input animation file into a preprocessed list of buffers to place into WebGL

Returns PreparedImageDefinition PreparedAnimation

Arguments

• imageDefinition ImageDefinition

const prepareAnimation = (imageDefinition: ImageDefinition): PreparedImageDefinition;

GeppettoPlayer

A player to add Gepetto animations to.

destroy()

Destroys all animations added to this player.

Returns void

addAnimation(animation, image, textureUnit, [options])

Add a Geppetto animation to the player.

Returns AnimationControls

Arguments

• animation PreparedImageDefinition an animation prepared with prepareAnimation.
• image HTMLImageElement a HTML Image element with loaded url to use as texture.
• textureUnit number The texture unit to use you can use 0 for your first animation, 1 for your second, etc.
• options Partial<AnimationOptions>

/**
 * Options to set directly when adding an animation.
 **/
interface AnimationOptions {
  
  /**
   * Horizontal position of image in canvas. `0` = center, `-1` = left, `1` = right.
   * @default 0.0
   **/
  panX: number;
  
  /**
   * Vertical position of image in canvas. `0` = center, `-1` = bottom, `1` = top.
   * @default 0.0
   **/
  panY: number;
  
  /**
   * Adds a stacking order to the rendering elements, this helps when
   * stacking multiple animations on top of eachother.
   * @default 0
   **/
  zIndex: number;
  
  /**
   * Zoom level. `1` = 100%, `1.5` is 150%, `0.5` = 50% zoom.
   * @default 1.0
   **/
  zoom: number;
};

render()

Clears the canvas. Use this when you created the player with setupWebGL. If you want to control the rendering process (and the clearing of the canvas) yourself, skip the call to this method in your render cycle.

Returns void

AnimationControls

Options to control the animation, start animation tracks, etc.

destroy()

Clears all memory associated to this animation.

Returns void

getControlValue(controlName)

Retreives current value of a control. This value will not update for each frame of an animation. It will only update at the end of each play iteration of an animation.

Returns number value of the control. Take into account that each control can have different value limits, depending on the amount of step a control has.

Arguments

• controlName string name of the control to get value from

onEvent(callback)

Register a callback to get notifications when an event is triggered. Events can be defined in an animation.

Returns Unsubscribe a function to call to unsubscribe

Arguments

• callback CustomEventCallback function that gets called whenever an event happens. It passes in the eventName, track and time.

type CustomEventCallback = (eventName: string, track: string, time: number): void;

/**
 * Function to call for unsubscribing to an event listener
 **/
type Unsubscribe = (): void;

onTrackStopped(callback)

Register a callback to get notifications when a track is stopped. A track can be stopped for the following reasons.

Returns Unsubscribe a function to call to unsubscribe

Arguments

• callback TrackStoppedCallback function to call when tracks are stopped. The first argument will be the trackname.

type TrackStoppedCallback = (track: string): void;

/**
 * Function to call for unsubscribing to an event listener
 **/
type Unsubscribe = (): void;

render()

Render a frame of the image.

Returns void

setControlValue(controlName, value)

Manipulates a control. Will stop animations that are using this control as well.

Returns void

Arguments

• controlName string name of the control to change
• value number value to set for control. Take into account that each control can have different value limits, depending on the amount of step a control has.

setLooping(loop, trackName)

Set the looping state of an animation track.

Returns void

Arguments

• loop boolean true for looping, false to stop looping.
• trackName string the name of the animation track to adjust.

setPanning(panX, panY)

Update the panning of the animation.

Returns void

Arguments

• panX number value of horizontal panning. 0 = center, -1 = left, 1 = right.
• panY number value of vertical panning. 0 = center, -1 = bottom, 1 = top.

setZIndex(zIndex)

Changes the rendering order of animations.

Returns void

Arguments

• zIndex number The index number for rendering. The higher the number, the more in the front the element will be stacked.

setZoom(zoom)

Updates the zoom level.

Returns void

Arguments

• zoom number 1 = 100%, 1.5 is 150%, 0.5 = 50% zoom.

startTrack(trackName, [options])

Start an animation. Conflicting animations will be automatically stopped.

Returns void

Arguments

• trackName string the name of the animation track to start. If the name is not valid, an exception will be thrown indicating what animation names are available.
• options PlayOptions

type PlayOptions = {
  
  /**
   * Playback speed.
   * @default 1.0
   **/
  speed: number;
  
  /**
   * Start animation at given ms.
   **/
  startAt: number;
};

stopTrack(trackName)

Stop an animation.

Returns void

Arguments

• trackName string the name of the animation track to start. If the name is not valid, an exception will be thrown indicating what animation names are available.