Home > Devices > Fire Phone

Adding Animations to Your App

Introduction

This page provides an introduction to Euclid animation concepts and gives code samples to show how to run animations in your app.

Animation Terminology

This section provides an introduction to the concepts that you will be working with when you add animations to an app.

To learn more about creating your own custom assets and animations, see Using the Custom Control Authoring Tools for Fire Phone.

Assets

A 3D asset is collection of the following items which, when combined, visually form a 3D model:

  • Attachment points
  • Meshes
  • Animations
  • Materials
  • Layouts
  • State Machines

Typically, graphics designers will create your 3D assets using specialized tools.

Attachment Points

An attachment point is a point on an asset where you can attach scenes (via ZSceneViews) or Euclid Z- controls. Attachment points are pre-defined; you cannot programmatically add or change attachment points. To attach an object to an attachment point, you need both the attachment point name and the view that you are attaching.

The following example shows how to attach ZExtrudedText widget to the mModelBook at a specified position. Note that the mModelBook in this sample is actually a zSceneViewDelegate object:

ZExtrudedText text = new ZExtrudedText(this);

AttachPoint ap = mModelBook.getSceneTree().getAttachPoint(attach_point_name);

ap.attachView(text);

Keep the following guidelines in mind when working with attachment points:

  • If you attach a view that has other views attached, deleting the attached child view will delete the entire view hierarchy.
  • You cannot delete attachment points because those are pre-defined when your asset is created. You can detach the views that are attached to those attachment points. (You can later delete a view after detaching that view.) On ZSceneView, call the detachView method to detach a view at the attachment point that you specify.
  • You cannot change the size of an attachment point programmatically. This property, as well as all other properties on a scene (animations, states, etc), are all specified by the asset's designer.

State Machines

A state machine is a collection of related states that are grouped together. This grouping ensures a smooth transition for the animation as you move through the states from the first state to final state. You run your animations by setting a goal state for the state machine; the animation runs by progressing through its appropriate sequences until it reaches the goal state.

ZSceneViews

Use a ZSceneView control for displaying a 3D asset, applying scaling, and making use of an asset's features (animations, parametric animations, attachment points). You can set a scale type using the ZSceneView delegate's setScaleType method. See ZSceneView.setScaleType for valid scale types.

ZSceneView has an underlying data structure called ZSceneTree, which is responsible for state machines, animations and attachment points, and the ZSceneViewDelegate class has a getSceneTree method for returning the scene tree. The following snippet gets the bounds of the mModelBook object.

// mModelBook is a ZSceneViewDelegate object.
ZBoundingBox mBounds = mModelBook.getSceneTree().getBounds();

Running Animations

If your asset has animations, the easiest way to run those animations is to set the goal state for your ZStateMachine, which allows the asset to run through its animation sequence until it reaches the goal state.

The following snippet (also used in the State Machines example above) runs an animation by setting the goal state:

// mGoalState - Goal state for the state machine
int mGoalState = ...
ZStateMachine sm = mModelBook.getSceneTree().getStateMachine(stateMachineName);
String goalStateName = sm.getStates()[mGoalState]);
sm.setGoalState(goalStateName);

Note: You can only dynamically run an animation by using an Android ObjectAnimator. Because an ObjectAnimator is an Android object designed for 2D assets, some 3D assets might not be compatible with this object. If you needed to use the object animator for your app, you could get the names of your animations by calling getAnimationNames(), and return the index of the animation that you want. If you already know the name of the animation, you could also use hasAnimation() to check if the animation exists.

Running Parametric Animations

A parameteric animation parameterizes the size/scale/width/length/orientation of an animation.

If you use a parameterized animation, you can adjust the properties of your asset programmatically. For example, you can use parametric animations to change the size of a pie wedge in a pie chart as an animation sequence progresses.

The following code snippet retrieves your animation:

ZSceneTree st = ...
String ANIM_LEFT_LEG = ....
NamedAnimation leftLeg = st.getAnimation(ANIM_LEFT_LEG);

To set the position of the animation, use the set method, such as in the following snippet:

leftLeg.set(st, leftLeg.getDuration()); // full extension

For more complex animations, you can use code similar to the following example:

animator = ValueAnimator.ofFloat(start, end);
        animator.setDuration(duration);
        animator.addUpdateListener(new ValueAnimator.AnimatorUpdateListener() {
            @Override
            public void onAnimationUpdate(ValueAnimator animation) {
                mNamedAnimation.set(mSceneTree, (Float) animation.getAnimatedValue());
            }
        });

        animator.start();