Wikitude SDK API Reference

API Docs for: 4.1.1
Show:

AnimatedImageDrawable Class

Extends ImageDrawable
Module: AR

AnimatedImageDrawable allows to create animated images using sprite sheets.

A sprite sheet is an image file which contains all key frame images required for the animation. The key frame image size (width and height) is passed at creation time and must be equal for all key frame images. Key frame images will be managed in an array, starting with entry 0. The key frame image array will be filled from left to right, row by row. Any partly filled key frames at the edge of the sprites sheet will be ignored.

The default anchor settings for an AnimatedImageDrawable are as follows:

  • horizontal anchor: AR.CONST.HORIZONTAL_ANCHOR.CENTER
  • vertical anchor: AR.CONST.VERTICAL_ANCHOR.MIDDLE

On creation, setup parameters can be passed to customize the properties of the AnimatedImageDrawable.

Example:
//create a new AnimatedImageDrawable from an ImageResource and pass some setup parameters
var animatedImageDrawable = new AR.AnimatedImageDrawable(imageResource, 5, 40, 50 {
  enabled : false,
  offsetX : 1,
  rotation : 190
});
// start playing the Animation, with keyframes 0-4, each keyframe is shown 10 miliseconds, and the animation is looped 10 times
animatedImageDrawable.animate([0, 1, 2, 3, 4], 10, 10);

Constructor

AnimatedImageDrawable

(
  • imageResource
  • height
  • keyFrameWidth
  • keyFrameHeight
  • options
)

Parameters:

  • imageResource ImageResource

    The imageResource representing the sprite sheet which is used for the AnimatedImageDrawable.

  • height Number

    The height of the AnimatedImageDrawable, in SDUs. The height is set at creation time, width is calculated according to the aspect ratio of the underlying key frame images.

  • keyFrameWidth Number

    The width of the key frame images in the sprite sheet, in pixels. Must be a whole number.

  • keyFrameHeight Number

    The height of the key frame images in the sprite sheet, in pixels. Must be a whole number.

  • options Object optional

    Setup-Parameters to customize additional object properties.

    Accepted options-properties are

    • keyFrame (defaults to 0) Number optional

      The start keyframe.

    • enabled (defaults to true) Boolean optional
    • mirrored (defaults to true) Boolean optional
    • horizontalAnchor Number optional
    • verticalAnchor Number optional
    • offsetX (defaults to 0) Number optional
    • offsetY (defaults to 0) Number optional
    • zOrder (defaults to 0) Number optional
    • rotation (defaults to 0) Number optional
    • scale (defaults to 1) Number optional
    • opacity (defaults to 1) Number optional
    • onClick Function optional
    • onFinish Function optional
    • roll (defaults to 0) Number optional
    • tilt (defaults to 0) Number optional
    • heading (defaults to 0) Number optional

Methods

animate

(
  • keyFrames
  • duration
  • loopTimes
)

Starts the animation based on the key frames provided.

Parameters:

  • keyFrames Number[]

    The keyframes that will be played one by one. The numbers in the array will be clamped to the available keyframes in the key frame image array. Must be an array of whole numbers.

  • duration Number

    The duration of each keyframe in milliseconds. Must be a whole number.

  • loopTimes (defaults to 1) Number optional

    Defines how often the animation should be played in a row. A negative value indicates an infinite looping.
    The parameter is optional and defaults to 1. Must be a whole number.

destroy

()

Inherited from ARchitectObject

Destroys the object.

getBoundingRectangle

() BoundingRectangle

Inherited from Drawable2D

Returns the BoundingRectangle for this Drawable2D. In case of an error, null will be returned.

Returns:

BoundingRectangle:

the BoundingRectangle for the Drawable2D

setKeyFrame

(
  • keyFramePos
)

Stops any animation and sets the content of the AnimatedImageDrawable to a still image that is at position keyFrameNr in the key frame image array. The keyFramePos will be clamped to valid positions in the key frame image array in case the number exceeds the available frames.

Parameters:

  • keyFramePos Int

    The position of the key frame in the array.

Properties

destroyed

Boolean

Inherited from ARchitectObject

Indicates if the object has already been destroyed.

enabled

Boolean

Inherited from Drawable

Flag to enable/disable the Drawable. If the Drawable is disabled, it will never appear on the screen and triggers on this Drawable will never be fired. In case it is enabled, it can be rendered on the screen and fire triggers.

Default: true

heading

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.heading instead.

height

Number

Inherited from ImageDrawable

The ImageDrawable's height in SDUs. The width of the ImageDrawable will be calculated accordingly based on the aspect ratio of the underlying Image.

horizontalAnchor

Number

Inherited from Drawable2D

The horizontal anchor defines which pixel (in a horizontal pixel row) of the Drawable2D will be placed right at the screen position of the GeoObject represented by the Drawable2D.

Valid values are defined in AR.CONST.HORIZONTAL_ANCHOR. For example, if LEFT is set as horizontal anchor of an ImageDrawable, the image's left edge will match the calculated position of the Drawable2D.

The default horizontal anchor points is dependent on the concrete class of the Drawable2D.

imageResource

ImageResource

Inherited from ImageDrawable

The imageResource representing the ImageDrawable.

mirrored

Boolean

Inherited from Drawable

Flag to enable/disable mirroring for this Drawable. When using the front camera, a mirrored drawable will be rotated 180 degree around its y axis.

Default: true for generic drawables, false for labels and HTMLDrawables

offsetX

Number

Inherited from Drawable2D

The horizontal offset to the calculated position of the Drawable2D, in SDUs. A positive offsetX causes the Drawable2D to move right, a negative offsetX causes it to move left.

Default: 0

offsetY

Number

Inherited from Drawable2D

The vertical offset to the calculated position of the Drawable2D, in SDUs. A positive offsetY causes the Drawable2D to move up, a negative offsetY causes it to move down.

Default: 0

opacity

Number

Inherited from Drawable2D

A value within the interval from 0.0 to 1.0 defining the opacity of the entire Drawable2D. A value of 0 indicates full transparency, a value of 1 indicates full opacity.

Default: 1

roll

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.roll instead.

rotate.heading

Number

Inherited from Drawable

Defines a rotation of the Drawable around the y-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.

Default: 0

rotate.roll

Number

Inherited from Drawable

Defines a rotation of the Drawable around the z-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.

Default: 0

rotate.tilt

Number

Inherited from Drawable

Defines a rotation of the Drawable around the x-axis, specified in degrees. Values will be applied modulo 360. A value of 361 degrees has the same effect as setting the value to 1 degree.

Default: 0

rotation

Number

Inherited from Drawable2D

Defines the rotation of the Drawable, in degrees, with the rotation axis perpendicular to the screen plain. For example, setting rotation to 45.0 on a square plain image turns it into a rhombus. A positive value defines a rotation in clockwise direction, a negative value defines a rotation in anti-clockwise direction. Rotation can influence the BoundingRectangle of the Drawable (for example, when a Rectangle is rotated).

Note, rotation is applied in addition to any roll-tilt-heading rotations defined. Rotation specifies the rotation on the screen, with the origin of the rotation being the center of the Drawable2D, including any offsets etc.

Default: 0

scale

Number

Inherited from Drawable2D

The scale factor for the Drawable2D. A scale factor greater than 1 enlarges the drawable, a scale factor less than 1 shrinks it down. Only values greater than or equal to 0 are allowed. A scale factor of 0 makes the Drawable2D invisible. A scale factor of 2 doubles the size of the Drawable2D, a scale factor of 0.5 halfs the size of the Drawable2D. Scale will influence the BoundingRectangle of the Drawable, but it will not influence the original properties of the Drawable2D.

Default: 1

scaling

Number deprecated

Inherited from Drawable2D

Deprecated: Use scale instead.

tilt

Number deprecated

Inherited from Drawable

Deprecated: Use rotate.tilt instead.

verticalAnchor

Number

Inherited from Drawable2D

The vertical anchor defines which pixel (in a vertical pixel column) of the Drawable2D will be placed right at the screen position of the GeoObject represented by the Drawable2D.

Valid values are defined in AR.CONST.VERTICAL_ANCHOR. For example, if TOP is set as horizontal anchor of an Image, the image's top edge will match the calculated position of the Drawable2D.

The default vertical anchor points is dependent on the concrete class of the Drawable2D.

zOrder

Number

Inherited from Drawable2D

If multiple Drawable2Ds are assigned to a certain GeoObject, the zOrder defines the drawing order of these Drawables. In case the Drawables overlap, the Drawable with the higher zOrder value is rendered on top of the others (e.g. a Drawable with zOrder 1 is rendered on top of a Drawable of zOrder 0, which again is rendered on top of -1). In case Drawables have the same zOrder defined, and they overlap, the behavior is undefined and might cause unexpected results, thus it is good practice to define the zOrder for potentially overlapping Drawables.

To specify the rendering order of the Drawables of different GeoObjects, refer to GeoObject.renderingOrder.

Must be a whole number.

Default: 0

Events

onClick

Inherited from Drawable

When the Drawable is clicked, the system will trigger Drawable.onClick(ARObject). A click on the screen might hit multiple Drawables, thus a click creates a "clicked Drawables-queue", with the uppermost Drawable in the front of the queue. The return value of the function determines if, after the onClick()-Function was executed for this Drawable, the queue shall continue to execute onClick() for the next Drawable in the queue. In case the last Drawable in the queue still requests to continue the click-queue, ARObject.onClick() will be executed. If the queue still continues, context.onScreenClick() will be executed.

The return value of the function determines what happens next. If false, the click-queue should not stop with this Drawable. Thus, the next Drawable's onClick() function will be executed. This is the default value in case no return value is set or the function is not defined for this Drawable. If true, the queue-execution will stop at the current Drawable, underlying Drawables will not receive onClick() calls.

Event Payload:

  • arObject ARObject

    the ARObject the clicked Drawable is attached to.

    The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onClick.

onFinish

The trigger will fire when the AnimatedImageDrawable finishes.

The trigger is null by default, and will thus result in no action executed when the trigger fires. A developer can add custom functionality by assigning a custom function to onFinish.

triggers.onClick

deprecated

Inherited from Drawable

Deprecated: Use onClick instead.