Animator Demo I

For many applications, particularly those that are scientific or educational in nature, or games that implement realistic physics, it is important to be able to simulate precise motion of objects governed by mathematical equations. In this project we introduce the basics of how to use a Java thread to implement motion of objects on the screen governed by mathematical models. For an introduction to some of the graphics methods discussed here, see the Android Animation and Graphics document.

Methods for 2D Animation

We have several options for 2D graphical animation in Android, varying in complexity and speed:

1. The simplest but least powerful and least flexible option is to draw graphics or animations into a View object from your layout. In this approach you just define the graphics that go into the View and the drawing (and possible simple animation) of your graphics can be handled by Android's normal View hierarchy drawing process. This method is only adequate for fixed images, or simple pre-defined animations. We won't discuss it further here, but for a basic introduction see View Animation and Canvas and Drawables. For specific discussion of simple fixed animation that can be implemented in this way see Property Animation and Animation Resources.
   
   

   A tweened animation can perform a series of simple position, size, rotation, and transparency transformations on the contents of a View object. A frame animation is a "traditional" animation in that is corresponds to displaying a sequence of related images ("flip-book animation"). Both of these kinds of animation can be implemented either in code or in XML resources, but often it is simplest to do it entirely within XML.

   
   


2. For any animation that regularly needs to redraw itself a much better animation choice is to draw directly to a Canvas. Games, and the sort of scientific animation we are addressing here, are likely to fall into this category. A Canvas serves as an interface to the actual surface upon which your graphics will be drawn. It holds all of your draw calls, but display of the drawing is performed (through the agency of the Canvas) upon an underlying Bitmap that is placed into the window by the system at the appropriate time. There are several ways to do this, differing primarily in whether the Canvas is obtained and managed by you or by the system, and whether the drawing operations take place on the main thread holding the View or on a separate thread.


• The simplest way to implement this approach is to create a custom component by subclassing View and overriding its onDraw(Canvas canvas) method to define your draws on the Canvas supplied with onDraw. Because these operations are all done on the same (UI) thread as your custom View component, you can then request a redraw directly with the invalidate() method of View. (See the discussion of communication between threads in the Progress Bar Example project.) For animations that do not require much computing and need not be updated particularly rapidly, this may be an adequate approach. It was, for example, the method that we used in the Draggable Symbols II project to drag one symbol at a time about the stage.


• The first option placed the redrawing and associated computation on the main UI thread. Thus it could lead to non-responsiveness if the required computation becomes appreciable. A better alternative is to subclass View as above and to use the Canvas supplied and managed by Android through the onDraw(Canvas canvas) method for redraws, but to move the computation to a separate thread. Then, as discussed in the Progress Bar Example, we must deal with the issue that the second thread cannot call invalidate( ) directly on the UI-thread View. In that case, we must either define a Handler on the main UI thread to receive messages from the second thread and initiate invalidate( ), or use the View method postInvalidate( ), which is legal on a non-UI thread.
  
  

  We shall use the second method in the project Animator Demo 2. We used the first method in the Progress Bars example.)

  
  


• The preceding two approaches have the advantage of relative simplicity since the Canvas used for drawing is supplied and managed by the system through the onDraw(Canvas canvas) method of View. It has the disadvantage that the maximum speed of animation is restricted because it is dependent on a request to the system to redraw the screen, which will be honored only when the system is ready to do so. A faster alternative is to move the animation to a separate thread that manages a SurfaceView (which provides a dedicated drawing surface embedded inside a view hierarchy), with access to the drawing surface typically implemented through the SurfaceHolder interface, and perform draws as fast as the thread can execute (with no invalidate( ) calls). The disadvantage is that you must manage the drawing Canvas yourself, but the potential increase in speed makes this the preferred method for performance-intensive 2D animation.

Let's now implement these ideas in some basic 2D animation. The example that we choose is to animate the motion of a planet around the Sun, assuming the planet to be in a circular orbit around a fixed Sun. The method that we shall use for this illustration is to implement the animation update on a dedicated thread and use postInvalidate( ) from that thread to force periodic screen updates.

Creating the Project in Android Studio

Following the general procedure in Creating a New Project, either choose Start a new Android Studio project from the Android Studio homepage, or from the Android Studio interface choose File > New > New Project. Fill out the fields in the resulting screens as follows,

where you should substitute your namespace for <YourNamespace> (com.lightcone in my case) and <ProjectPath> is the path to the directory where you will store this Android Studio Project (/home/guidry/StudioProjects/ in my case). If you have chosen to use version control for your projects, go ahead and commit this project to version control.

Thread Options

As discussed in Progress Bars, there are two basic ways to implement threading:

1. Create a new class that extends Thread and override its run() method.


2. Provide a new Thread instance with a Runnable object using the Runnable interface during its creation.

In Progress Bars we used the first approach and created a new class extending Thread. In this project we shall use the second approach and produce thread-based animation by creating a class that implements the Runnable interface.

Implementing an Animation Thread Using Runnable

Use Android Studio to create a new public class MotionRunner.java, having it subclass View and implement Runnable:

package <YourNamespace>.animatordemo;
import android.view.View;

public class MotionRunner extends View implements Runnable {


}

This should indicate an error in the line defining MotionRunner (it will be underlined with a wiggly red line). Let Android Studio fix it: click on the line and execute Alt-Enter. This indicates that we should implement methods (associated with the Runnable interface). Select that and select the run() method from the popup menus and Android Studio should insert a stub defining the method. But the first line still will have a wiggly red line under it. Repeat the Alt-Enter magic trick, which will indicate that we need to create a constructor matching super. Select that and from the resulting popup select View(context:Context). Android Studio should insert another method and now everything should compile, with the code now reading

package <YourNamespace>.animatordemo;

import android.content.Context;
import android.view.View;

public class MotionRunner extends View implements Runnable {

   public MotionRunner(Context context) {
      super(context);
      
   }

   @Override
   public void run() {
      
   }
   
}

This should compile with no errors. Now edit MotionRunner.java so that it reads

package <YourNamespace>.animatordemo;
    
import android.content.Context;
import android.util.Log;
import android.view.View;

public class MotionRunner extends View implements Runnable {
      
   private Thread animator = null;      // The thread that will hold the animation
   private long delay;                  // Delay in ms controlling speed of thread looping
   private boolean please_stop = false; // Boolean controlling whether thread loop is running
   
   public MotionRunner(Context context) {
      super(context);
   }

   @Override
   public void run() {
      while(!please_stop) {
            Log.i("ANIMATOR","  ..... LOOPED");
            // Wait then execute it again
            try { Thread.sleep(delay); } catch (InterruptedException e) { ; }
      }	
   }
   
   // Method to start animation loop
   public void startIt(long delay) {
      this.delay = delay;
      animator = new Thread(this);
      animator.start();
   }
   
   // Method to stop animation loop
   public void stopLooper(){
      please_stop = true;
   }
   
   // Method to resume animation loop
   public void startLooper(long delay){
      please_stop = false;
      if(animator == null) {
            startIt(delay);
      }
   }    
}

where the required changes are highlighted in red. Let's describe briefly the functionality of this code.

• Because we have implemented the Runnable interface, we are required to provide an implementation of its run( ) method (which is called whenever a thread starts that has been created by the class implementing Runnable). In this case run( ) will be invoked when the Thread corresponding to the variable animator is started.


• Within the run( ) method we implement a while-loop that will execute as long as the boolean please_stop is false. For now we have just put a diagnostic output to the logcat stream to indicate that the thread is running. Later we will do more interesting things with this thread.


• The speed with which this loop executes is controlled by the long integer delay, since the sleep(long time) method of Thread requests that the thread sleep for delay milliseconds each time through the while-loop (the delay is only a request and will not be implemented precisely). Since the sleep(time) method throws the exception InterruptedException, it must be enclosed in a try-catch clause to handle the exception


• The method startIt(long delay) instantiates a Thread and starts it (which will cause the run( ) method to be executed). The methods stopLooper( ) and startLooper(long delay) turn the while-loop in run( ) off and on by setting the value of the boolean please_stop to true or false, respectively.

Now let's modify MainActivity.java to run the animation thread.

Running the Animation Thread

Open MainActivity.java and modify it to read

package <YourNamespace>.animatordemo;
    
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.view.ViewGroup;

public class MainActivity extends AppCompatActivity  {
   
  private long delay = 40;      // Delay in ms controlling speed of thread looping
  MotionRunner mrunner;
       
   @Override
   public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
        // Instantiate the class MotionRunner to define the entry screen display
      mrunner = new MotionRunner(this);
      mrunner.setLayoutParams(new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,
               ViewGroup.LayoutParams.MATCH_PARENT));
      setContentView(mrunner);
      mrunner.startIt(delay);
   }

   @Override
   public void onPause() {
      super.onPause();
      // Stop animation loop if going into background
      mrunner.stopLooper();
   }
   
   @Override
   public void onResume() {
      super.onResume();
      // Resume animation loop
      mrunner.startLooper(delay);
   }
}

where changes are highlighted in red. This segment of code

• Defines an instance mrunner of the class MotionRunner that we just created.


• Sets the content view for the entry screen to mrunner using the View method. setLayoutParams and the Activity method setContentView.


• Executes the startIt(delay) method of the MotionRunner instance to start the animation.


• Defines onPause() and onResume() methods that pause and resume the animation by executing the stopLooper() and startLooper() methods, respectively, of MotionRunner when the app goes into and returns from the background.

If this app is now run on a phone or emulator you should see a blank screen (since we haven't told it to display anything yet), but in the logcat output there should be a sequence of "LOOPED" strings indicating that the while-loop in the thread is executing. By changing the value of the variable delay you should be able to approximately control how often this string is output. You also should find that the loop stops if you send the app to the background by hitting the back button or the home button.

Adding Animated Motion

We now have a basic animation thread running, so lets animate something with it by using the methods that mrunner inherits from View to implement the motion of objects on the screen.

Geometry of the Planetary Orbit

The geometry that will be assumed for the planetary orbit is illustrated in the following figure,

where the Sun is positioned at the center of the display screen, which is taken as the origin of the coordinate system (more realistic geometries for planetary orbits will be considered in the later projects Animator Demo II and Solar System).

The animation will consist of moving the planet by a small increment Δθ on the circular orbit each time through the while-loop of the run() method, with the size of the increment Δθ controlled by the integer steps and the clockwise direction corresponding to positive Δθ increments. This may be implemented through the following additions and modifications.

New Imports and Variables

First, add the imports and new variables indicated in red in the following listing to MotionRunner.java.

package <YourNamespace>.animatordemo;
import android.content.Context;
import android.util.Log;
import android.view.View;

import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.drawable.ShapeDrawable;
import android.graphics.drawable.shapes.OvalShape;

public class MotionRunner extends View implements Runnable {

   private Thread animator = null;              // The thread that will hold the animation
   private long delay;                          // Delay in ms controlling speed of thread looping
   private boolean please_stop = false;         // Boolean controlling whether thread loop is running
	
  private static final int ORBIT_COLOR = Color.argb(255, 66, 66, 66);
  private static final int PLANET_COLOR = Color.argb(255, 0, 0, 0);
  private static final int SUN_COLOR = Color.argb(255, 255, 0, 0);
  private static final double RAD_CIRCLE = 2*Math.PI;  // Number radians in a circle
  private Paint paint;                 // Paint object controlling screen draw format
  private ShapeDrawable planet;        // Planet symbol
  private int planetRadius = 7;        // Radius of spherical planet (pixels)
  private int sunRadius = 12;          // Radius of Sun (pixels)
  private float X0 = 0;                // X offset from center (pixels)
  private float Y0 = 0;                // Y offset from center (pixels)
  private float X;                     // Current X position of planet (pixels)
  private float Y;                     // Current Y position of planet (pixels)
  private float centerX;               // X for center of display (pixels)
  private float centerY;               // Y for center of display (pixels)
  private float R0;                    // Radius of circular orbit (pixels)
  private int nsteps = 600;            // Number animation steps around circle
  private double theta;                // Angle around orbit (radians)
  private double dTheta;               // Angular increment each step (radians)
  private double direction = -1;       // Direction: counter-clockwise -1; clockwise +1
   
   
   public MotionRunner(Context context) {
         super(context);
   }

where the purpose of each variable is defined in the comments.

Setup and Initialization in the Constructor

Next, add to the constructor of MotionRunner.java the statements in red in the following listing.

public MotionRunner(Context context) {
     super(context);
      
   // Initialize angle and angle step (in radians) 
   theta = 0;
   dTheta = RAD_CIRCLE/((double) nsteps);     // Angle increment in radians

   // Define the planet as circular shape
   planet = new ShapeDrawable(new OvalShape());
   planet.getPaint().setColor(PLANET_COLOR);
   planet.setBounds(0, 0, 2*planetRadius, 2*planetRadius);	
   
   // Set up the Paint object that will control format of screen draws
   paint = new Paint();
   paint.setAntiAlias(true);
   paint.setTextSize(14);
   paint.setStrokeWidth(1); 
   
}

where the purpose of the statements should be clear from the comments and the documentation for the methods of the classes ShapeDrawable and Paint.

Getting the Device Screen Size

Since we will need to know the display size of the view to calculate geometries, let's get the height and width of the full display. This may be accomplished by overriding the View method onSizeChanged(int w, int h, int oldw, int oldh), adding to MotionRunner the new method

/*
The View display size is only available after a certain stage of the layout.  Before then
the width and height are by default set to zero.  The onSizeChanged method of View is called 
when the size is changed and its arguments give the new and old dimensions.  Thus this can be
used to get the sizes of the View after it has been laid out (or if the layout changes, as in a
switch from portrait to landscape mode, for example).
*/

@Override
protected void onSizeChanged  (int w, int h, int oldw, int oldh){
   // Coordinates for center of screen
   centerX = w/2;
   centerY = h/2;
   // Make orbital radius a fraction of minimum of width and height of display
   R0 = (float) (0.90*Math.min(centerX, centerY));
   // Set the initial position of the planet (translate by planetRadius so center of planet
   // is at this position)
   X = centerX - planetRadius ;
   Y = centerY - R0 - planetRadius;
}

You might wonder why we use this method to get the view height and width. Why not just call the View methods getWidth() and getHeight() in the constructor, for example? Recall that we are generally using layouts that adapt to the device in use, so the geometry is known only at runtime. Furthermore, the screen geometry may change during execution if, for example, the device is switched from portrait to landscape display.

• For these reasons, the getWidth() and getHeight() methods of View will return zero if called too early (for example, within the constructor), because at that point Android doesn't yet know what the layout sizes will be.


• The view sizes are only available at some point in the layout phase as the app is executing.


• The protected method onSizeChanged(int w, int h, int oldw, int oldh) of View is executed by Android when the sizes are changed, where the arguments w and h are the new width and height, and oldw and oldh are the old values.


• Thus, we can override this method to retrieve the width and height of the view as soon as they have been changed from their default values of zero. (Alternatively, we can retrieve the width and height after the layout phase; for example, within the while-loop of the run() method.)

Method to Increment the Angle and Compute New Position Coordinates

Next we add a method newXY() that will increment the angle θ and compute the corresponding screen coordinates X and Y for the planet. Add to MotionRunner.java the following code:

// Method to increment theta and compute the new X and Y 

private void newXY(){
   theta += dTheta;     
   if(theta > RAD_CIRCLE) theta -= RAD_CIRCLE;  // For convenience, keep angle 0-2pi
   X =  (float)(R0*Math.sin(direction*theta)) + centerX - planetRadius;
   Y =  centerY - (float)(R0*Math.cos(direction*theta)) - planetRadius;
   Log.i("ANIMATOR", "X="+X+" Y="+Y);
}

Notice the use of the variable direction to control whether the motion is clockwise or counterclockwise, and that for convenience we have implemented some logic so that at any time in the animation the angle (which is specified in radians in the calculation, since the trigonometric methods expect radians for the angles) lies in the interval 0 to 2π.

Modifications of the run() Method

Now we modify run() to invoke the newXY() method that increments the position of the planet. The required changes are indicated in red in the following listing.

@Override
public void run() {
   while(!please_stop) {

   //Log.i("ANIMATOR","  ..... LOOPED");
   
   // Move planet by dTheta and compute new X and Y
   
   newXY();
   
   // Must use postInvalidate() rather than invalidate() to request redraw since
   // this is invoked from different thread than the one that created the View
   
   postInvalidate();

      // Wait, then execute it again
      try { Thread.sleep(delay); } catch (InterruptedException e) { ; }
   }	
}

Note that the View method postInvalidate( ), which causes the invalidate to happen on a subsequent cycle through the event loop, must be used rather than invalidate( ) to request a redraw from a thread other than the one that created the View (see the discussion above).

Overriding the onDraw(Canvas canvas) Method

Finally, we must override the onDraw(Canvas canvas) method inherited from View to reflect the updated position of the planet when the screen is redrawn in response to the postInvalidate( ) request in run( ). To do so, add the following two methods to MotionRunner.java.

/*
This method will be called each time the screen is redrawn. The draw is
on the Canvas object, with formatting controlled by the Paint object. 
When to redraw is under Android control, but we can request a redraw 
using the method invalidate() or postInvalidate() inherited from the View superclass.
In this case we must use postInvalidate(), since we are updating on a thread separate
from the main UI thread.
*/

@Override
public void onDraw(Canvas canvas) {
   super.onDraw(canvas);
   drawBackground(paint, canvas);
   canvas.save();
   canvas.translate(X + X0, Y + Y0);
   planet.draw(canvas);
   canvas.restore();
}

// Called by onDraw to draw the background
private void drawBackground(Paint paint, Canvas canvas){
   paint.setColor(SUN_COLOR);
   paint.setStyle(Paint.Style.FILL);
   canvas.drawCircle(centerX + X0, centerY + Y0, sunRadius, paint);
   paint.setStyle(Paint.Style.STROKE);
   paint.setColor(ORBIT_COLOR);
   canvas.drawCircle(centerX + X0, centerY + Y0, R0, paint);
}

The techniques used here are documented under the methods for the Android classes Canvas, Paint, and Color, and are similar to those already discussed in conjunction with the onDraw method in the DraggableSymbols project. Notice that the Canvas on which were are drawing is supplied as the argument canvas, so we don't have to manage the Canvas; we only have to draw on it. The formatting of our drawing is controlled by the Paint object paint that was initialized in the MotionRunner constructor.

Run Planet, Run!

If this code is compiled and run it on an emulator, phone, or tablet, you should see the planet moving around the Sun in a circle, as in the following figure.

A look at the logcat output should reveal a steady stream of X and Y position updates because of the Log.i( ) statement that we inserted, and if you hit the back or home buttons the screen animation and this stream of position updates should halt, indicating that the onPause( ) method of MainActivity has stopped execution of the update thread by invoking the stopLooper( ) method of MotionRunner.

Last modified: July 7, 2016