Android 3D Carousel

• 
  Download source - 160.3 KB 

Introduction 

For a while, I was looking for a 3D carousel control for Android platform. The only one I found was UltimateFaves at [1]. But as it turned out, it uses OpenGL. And it’s not open source. I thought if it is possible to avoid a use of OpenGL. Continuing my investigations, I stamped on Coverflow Widget at [2]. And it uses standard Android 2D libraries. So the idea was the same – to use Gallery class for the carousel. The Coverflow Widget just rotates images and I wanted to rotate all group of them. Well, at least it implies the use of simple trig methods. More complicated stuff goes with the Gallery class. If you’d look through the article about Coverflow Widget at [3], you’d see a bunch of problems, such as unavailability of default scope variables in AbsSpinner and AdapterView classes. So I went the same way and rewrote some classes. And the Scroller class will be replaced by the Rotator class which looks like Scroller but it rotates the group of images.

The Preparations

At first, we should decide what parameters will define a behavior of our Carousel. For example, a min quantity of items in the carousel. It will not look nice if it has only one or two items, won’t it? As for performance issue, we have to define max quantity of items. Also, we will need max theta angle for the carousel, what items will be in there, current selected item and if items will be reflected. So let’s define them in attrs.xml file:

<?xml version="1.0" encoding="utf-8"?>
<resources>
	<declare-styleable name="Carousel">
		<attr name="android:gravity" />	
		<attr name="android:animationDuration" />
		<attr name="UseReflection" format="boolean"/>
		<attr name="Items" format="integer"/>
		<attr name="SelectedItem" format="integer"/>
		<attr name="maxTheta" format="float"/>
		<attr name="minQuantity" format="integer"/>
		<attr name="maxQuantity" format="integer"/>
	</declare-styleable>	
</resources>

The Carousel Item Class

To simplify some stuff with carousel, I’ve created CarouselImageView:

public class CarouselImageView extends ImageView 
	implements Comparable<carouselimageview> {
	
	private int index;
	private float currentAngle;
	private float x;
	private float y;
	private float z;
	private boolean drawn;
	
	public CarouselImageView(Context context) {
		this(context, null, 0);
	}	

	public CarouselImageView(Context context, AttributeSet attrs) {
		this(context, attrs, 0);
	}
	
	public CarouselImageView(Context context, AttributeSet attrs, int defStyle) {
		super(context, attrs, defStyle);
	}

	public int compareTo(CarouselImageView another) {
		return (int)(another.z – this.z);
	}

	…
}
</carouselimageview>

It incapsulates the position in 3D space, the index of an item and the current angle of an item. Also implementing it as Comparable will be helpful when we’ll determine a draw order of the items.

The Rotator Class

If you’d look at the source code of Scroller class, you’ll see two modes: the scroll mode and the fling mode supposed just to calculate current offset from the given start point. We’ll just need to remove extra members, add our own and replace the corresponding calculations:

public class Rotator {
    private int mMode;
    private float mStartAngle;
    private float mCurrAngle;
    
    private long mStartTime;
    private long mDuration;
    
    private float mDeltaAngle;
    
    private boolean mFinished;

    private float mCoeffVelocity = 0.05f;
    private float mVelocity;
    
    private static final int DEFAULT_DURATION = 250;
    private static final int SCROLL_MODE = 0;
    private static final int FLING_MODE = 1;
    
    private final float mDeceleration = 240.0f;
    
    
    /**
     * Create a Scroller with the specified interpolator. If the interpolator is
     * null, the default (viscous) interpolator will be used.
     */
    public Rotator(Context context) {
        mFinished = true;
    }
    
    /**
     * 
     * Returns whether the scroller has finished scrolling.
     * 
     * @return True if the scroller has finished scrolling, false otherwise.
     */
    public final boolean isFinished() {
        return mFinished;
    }
    
    /**
     * Force the finished field to a particular value.
     *  
     * @param finished The new finished value.
     */
    public final void forceFinished(boolean finished) {
        mFinished = finished;
    }
    
    /**
     * Returns how long the scroll event will take, in milliseconds.
     * 
     * @return The duration of the scroll in milliseconds.
     */
    public final long getDuration() {
        return mDuration;
    }
    
    /**
     * Returns the current X offset in the scroll. 
     * 
     * @return The new X offset as an absolute distance from the origin.
     */
    public final float getCurrAngle() {
        return mCurrAngle;
    }   
    
    /**
     * @hide
     * Returns the current velocity.
     *
     * @return The original velocity less the deceleration. Result may be
     * negative.
     */
    public float getCurrVelocity() {
        return mCoeffVelocity * mVelocity - mDeceleration * timePassed() /* / 2000.0f*/;
    }

    /**
     * Returns the start X offset in the scroll. 
     * 
     * @return The start X offset as an absolute distance from the origin.
     */
    public final float getStartAngle() {
        return mStartAngle;
    }           
    
    /**
     * Returns the time elapsed since the beginning of the scrolling.
     *
     * @return The elapsed time in milliseconds.
     */
    public int timePassed() {
        return (int)(AnimationUtils.currentAnimationTimeMillis() - mStartTime);
    }
    
    /**
     * Extend the scroll animation. This allows a running animation to scroll
     * further and longer, when used with {@link #setFinalX(int)} 
     * or {@link #setFinalY(int)}.
     *
     * @param extend Additional time to scroll in milliseconds.
     * @see #setFinalX(int)
     * @see #setFinalY(int)
     */
    public void extendDuration(int extend) {
        int passed = timePassed();
        mDuration = passed + extend;
        mFinished = false;
    }
    
    /**
     * Stops the animation. Contrary to {@link #forceFinished(boolean)},
     * aborting the animating cause the scroller to move to the final x and y
     * position
     *
     * @see #forceFinished(boolean)
     */
    public void abortAnimation() {
        mFinished = true;
    }        

    /**
     * Call this when you want to know the new location.  If it returns true,
     * the animation is not yet finished.  loc will be altered to provide the
     * new location.
     */ 
    public boolean computeAngleOffset()
    {
        if (mFinished) {
            return false;
        }
        
        long systemClock = AnimationUtils.currentAnimationTimeMillis();
        long timePassed = systemClock - mStartTime;
        
        if (timePassed < mDuration) {
        	switch (mMode) {
        		case SCROLL_MODE:

        			float sc = (float)timePassed / mDuration;
                    	mCurrAngle = mStartAngle + Math.round(mDeltaAngle * sc);    
                    break;
                    
        		 case FLING_MODE:

        			float timePassedSeconds = timePassed / 1000.0f;
        			float distance;

        			if(mVelocity < 0)
        			{
                    	distance = mCoeffVelocity * mVelocity * timePassedSeconds - 
                    	(mDeceleration * timePassedSeconds * timePassedSeconds / 2.0f);
        			}
        			else{
                    	distance = -mCoeffVelocity * mVelocity * timePassedSeconds - 
                    	(mDeceleration * timePassedSeconds * timePassedSeconds / 2.0f);
        			}

                    mCurrAngle = mStartAngle - Math.signum(mVelocity)*Math.round(distance);
                    
                    break;                    
        	}
            return true;
        }
        else
        {
        	mFinished = true;
        	return false;
        }
    }    
    
    /**
     * Start scrolling by providing a starting point and the distance to travel.
     * 
     * @param startX Starting horizontal scroll offset in pixels. Positive
     *        numbers will scroll the content to the left.
     * @param startY Starting vertical scroll offset in pixels. Positive numbers
     *        will scroll the content up.
     * @param dx Horizontal distance to travel. Positive numbers will scroll the
     *        content to the left.
     * @param dy Vertical distance to travel. Positive numbers will scroll the
     *        content up.
     * @param duration Duration of the scroll in milliseconds.
     */
    public void startRotate(float startAngle, float dAngle, int duration) {
        mMode = SCROLL_MODE;
        mFinished = false;
        mDuration = duration;
        mStartTime = AnimationUtils.currentAnimationTimeMillis();
        mStartAngle = startAngle;
        mDeltaAngle = dAngle;
    }    
    
    /**
     * Start scrolling by providing a starting point and the distance to travel.
     * The scroll will use the default value of 250 milliseconds for the
     * duration.
     * 
     * @param startX Starting horizontal scroll offset in pixels. Positive
     *        numbers will scroll the content to the left.
     * @param startY Starting vertical scroll offset in pixels. Positive numbers
     *        will scroll the content up.
     * @param dx Horizontal distance to travel. Positive numbers will scroll the
     *        content to the left.
     * @param dy Vertical distance to travel. Positive numbers will scroll the
     *        content up.
     */
    public void startRotate(float startAngle, float dAngle) {
        startRotate(startAngle, dAngle, DEFAULT_DURATION);
    }
        
    /**
     * Start scrolling based on a fling gesture. The distance travelled will
     * depend on the initial velocity of the fling.
     * 
     * @param velocityAngle Initial velocity of the fling (X) 
     * measured in pixels per second.
     */
    public void fling(float velocityAngle) {
    	
        mMode = FLING_MODE;
        mFinished = false;

        float velocity = velocityAngle;
     
        mVelocity = velocity;
        mDuration = (int)(1000.0f * Math.sqrt(2.0f * mCoeffVelocity * 
        		Math.abs(velocity)/mDeceleration));
        
        mStartTime = AnimationUtils.currentAnimationTimeMillis();        
    }
}

The CarouselSpinner Differences with the AbsSpinner

First, it extends CarouselAdapter vs AdapterView. Those differences I’ll describe later. Second, the modified constructor where the retrieving of AbsSpinner entries were removed. The third difference is modified setSelection(int) method. It was just call to setSelectionInt left. The next change is unavailable variables were replaced with their getters. As for default generated layout parameters, both were set to WRAP_CONTENT. The main changes concern pointToPosition method. In AbsSpinner, it determines if definite item was touched on a screen no matter whether it’s current or not. In CarouselSpinner, all touches will concern only the current item. So just return selected item index:

public int pointToPosition(int x, int y) {    	
  	// All touch events are applied to selected item
   	return mSelectedPosition;
}

The CarouselAdapter vs. AdapterView

The only changes are in updateEmptyStatus method where unavailable variables were replaced with their getters.

The Carousel Class

Here FlingRunnable class was replaced with FlingRotateRunnable which is much like FlingRunnable but makes deal with angle vs. x-coordinate:

private class FlingRotateRunnable implements Runnable {

        /**
         * Tracks the decay of a fling rotation
         */		
		private Rotator mRotator;

		/**
         * Angle value reported by mRotator on the previous fling
         */
        private float mLastFlingAngle;
        
        /**
         * Constructor
         */
        public FlingRotateRunnable(){
        	mRotator = new Rotator(getContext());
        }
        
        private void startCommon() {
            // Remove any pending flings
            removeCallbacks(this);
        }
        
        public void startUsingVelocity(float initialVelocity) {
            if (initialVelocity == 0) return;
            
            startCommon();
                        
            mLastFlingAngle = 0.0f;
            
           	mRotator.fling(initialVelocity);
                        
            post(this);
        }               
        
        public void startUsingDistance(float deltaAngle) {
            if (deltaAngle == 0) return;
            
            startCommon();
            
            mLastFlingAngle = 0;
            synchronized(this)
            {
            	mRotator.startRotate(0.0f, -deltaAngle, mAnimationDuration);
            }
            post(this);
        }
        
        public void stop(boolean scrollIntoSlots) {
            removeCallbacks(this);
            endFling(scrollIntoSlots);
        }        
        
        private void endFling(boolean scrollIntoSlots) {
            /*
             * Force the scroller's status to finished (without setting its
             * position to the end)
             */
        	synchronized(this){
        		mRotator.forceFinished(true);
        	}
            
            if (scrollIntoSlots) scrollIntoSlots();
        }
                		
		public void run() {
            if (Carousel.this.getChildCount() == 0) {
                endFling(true);
                return;
            }			
            
            mShouldStopFling = false;
            
            final Rotator rotator;
            final float angle;
            boolean more;
            synchronized(this){
	            rotator = mRotator;
	            more = rotator.computeAngleOffset();
	            angle = rotator.getCurrAngle();	            
            }            
         
            // Flip sign to convert finger direction to list items direction
            // (e.g. finger moving down means list is moving towards the top)
            float delta = mLastFlingAngle - angle;                        
            
            //////// Should be reworked
            trackMotionScroll(delta);
            
            if (more && !mShouldStopFling) {
                mLastFlingAngle = angle;
                post(this);
            } else {
                mLastFlingAngle = 0.0f;
                endFling(true);
            }              
	}		
}

I also added ImageAdapter class as it is in Coverflow Widget with a possibility to add a reflection to the images. And some new private variables were added to support Y-axe angle, reflection and so on. The constructor retrieves list of images, creates ImageAdapter and sets it. The main thing in the constructor is setting the object to support static transformations. And to place images into their places:

/**
	 * Setting up images
	 */
	void layout(int delta, boolean animate){
		        
        if (mDataChanged) {
            handleDataChanged();
        }
        
        // Handle an empty gallery by removing all views.
        if (this.getCount() == 0) {
            resetList();
            return;
        }
        
        // Update to the new selected position.
        if (mNextSelectedPosition >= 0) {
            setSelectedPositionInt(mNextSelectedPosition);
        }        
        
        // All views go in recycler while we are in layout
        recycleAllViews();        
        
        // Clear out old views
        detachAllViewsFromParent();
        
        
        int count = getAdapter().getCount();
        float angleUnit = 360.0f / count;

        float angleOffset = mSelectedPosition * angleUnit;
        for(int i = 0; i< getAdapter().getCount(); i++){
        	float angle = angleUnit * i - angleOffset;
        	if(angle < 0.0f)
        		angle = 360.0f + angle;
           	makeAndAddView(i, angle);        	
        }

        // Flush any cached views that did not get reused above
        mRecycler.clear();

        invalidate();

        setNextSelectedPositionInt(mSelectedPosition);
        
        checkSelectionChanged();
        
        ////////mDataChanged = false;
        mNeedSync = false;
        
        updateSelectedItemMetadata();
        }

Here are the methods to set up images. The height of an image is set three times lesser than parent height to make the carousel fit parent view. It should be reworked later.

private void makeAndAddView(int position, float angleOffset) {
        CarouselImageView child;
  
        if (!mDataChanged) {
            child = (CarouselImageView)mRecycler.get(position);
            if (child != null) {

                // Position the view
                setUpChild(child, child.getIndex(), angleOffset);
            }
            else
            {
                // Nothing found in the recycler -- ask the adapter for a view
                child = (CarouselImageView)mAdapter.getView(position, null, this);

                // Position the view
                setUpChild(child, child.getIndex(), angleOffset);            	
            }
            return;
        }

        // Nothing found in the recycler -- ask the adapter for a view
        child = (CarouselImageView)mAdapter.getView(position, null, this);

        // Position the view
        setUpChild(child, child.getIndex(), angleOffset);
    }      

    private void setUpChild(CarouselImageView child, int index, float angleOffset) {
                
    	// Ignore any layout parameters for child, use wrap content
        addViewInLayout(child, -1 /*index*/, generateDefaultLayoutParams());

        child.setSelected(index == this.mSelectedPosition);
        
        int h;
        int w;
        
        if(mInLayout)
        {
	        h = (this.getMeasuredHeight() - 
		this.getPaddingBottom() - this.getPaddingTop())/3;
	        w = this.getMeasuredWidth() - 
		this.getPaddingLeft() - this.getPaddingRight(); 
        }
        else
        {
	        h = this.getHeight()/3;
	        w = this.getWidth();        	
        }
        
        child.setCurrentAngle(angleOffset);
        Calculate3DPosition(child, w, angleOffset);
        
        // Measure child
        child.measure(w, h);
        
        int childLeft;
        
        // Position vertically based on gravity setting
        int childTop = calculateTop(child, true);
        
        childLeft = 0;

        child.layout(childLeft, childTop, w, h);
    } 

Let’s look at trackMotionScroll method in the Gallery class, it’s called when the widget is being scrolled or flinged and does the necessary stuff for the Gallary animation. But it moves images just by x-coordinate. To make them rotate in 3D space, we must create different functionality. We just change the current angle of an image and calculate it’s position in 3D space:

void trackMotionScroll(float deltaAngle) {
    
        if (getChildCount() == 0) {
            return;
        }
                
        for(int i = 0; i < getAdapter().getCount(); i++){
        	CarouselImageView child = (CarouselImageView)getAdapter().getView(i, null, null);
        	float angle = child.getCurrentAngle();
        	angle += deltaAngle;
        	while(angle > 360.0f)
        		angle -= 360.0f;
        	while(angle < 0.0f)
        		angle += 360.0f;
        	child.setCurrentAngle(angle);
            Calculate3DPosition(child, getWidth(), angle);        	
        }
        
        // Clear unused views
        mRecycler.clear();        
        
        invalidate();
    }	

And after images were flinged or scrolled, we have to place them into the corresponding places:

/**
     * Brings an item with nearest to 0 degrees angle to this angle and sets it selected 
     */
    private void scrollIntoSlots(){
    	
    	// Nothing to do
        if (getChildCount() == 0 || mSelectedChild == null) return;
        
        // get nearest item to the 0 degrees angle
        // Sort itmes and get nearest angle
    	float angle; 
    	int position;
    	
    	ArrayList<carouselimageview> arr = new ArrayList<carouselimageview>();
    	
        for(int i = 0; i < getAdapter().getCount(); i++)
        	arr.add(((CarouselImageView)getAdapter().getView(i, null, null)));
        
        Collections.sort(arr, new Comparator<carouselimageview>(){
			@Override
			public int compare(CarouselImageView c1, CarouselImageView c2) {
				int a1 = (int)c1.getCurrentAngle();
				if(a1 > 180)
					a1 = 360 - a1;
				int a2 = (int)c2.getCurrentAngle();
				if(a2 > 180)
					a2 = 360 - a2;
				return (a1 - a2) ;
			}        	
        });        
        
        angle = arr.get(0).getCurrentAngle();
                
        // Make it minimum to rotate
    	if(angle > 180.0f)
    		angle = -(360.0f - angle);
    	
        // Start rotation if needed
        if(angle != 0.0f)
        {
        	mFlingRunnable.startUsingDistance(-angle);
        }
        else
        {
            // Set selected position
            position = arr.get(0).getIndex();
            setSelectedPositionInt(position);
        	onFinishedMovement();
        }        
    }
</carouselimageview></carouselimageview></carouselimageview>

And to scroll to the definite item:

void scrollToChild(int i){		
		
	CarouselImageView view = (CarouselImageView)getAdapter().getView(i, null, null);
	float angle = view.getCurrentAngle();
		
	if(angle == 0)
		return;
		
	if(angle > 180.0f)
		angle = 360.0f - angle;
	else
		angle = -angle;

    	mFlingRunnable.startUsingDistance(-angle);
}

Here’s the Calculate3DPosition method:

private void Calculate3DPosition
(CarouselImageView child, int diameter, float angleOffset){
    angleOffset = angleOffset * (float)(Math.PI/180.0f);

    float x = -(float)(diameter/2*Math.sin(angleOffset));
    float z = diameter/2 * (1.0f - (float)Math.cos(angleOffset));
    float y = - getHeight()/2 + (float) (z * Math.sin(mTheta));

    child.setX(x);
    child.setZ(z);
    child.setY(y);
}

Some methods that don’t have a sense with 3D gallery were removed: offsetChildrenLeftAndRight, detachOffScreenChildren, setSelectionToCenterChild, fillToGalleryLeft, fillToGalleryRight.

So, the main thing that happens with images is in getChildStaticTransformation method, where they are transformed in 3D space. It just takes a ready to use position from CarouselImage class that was calculated by Calculate3DPosition while flinging/scrolling and moves an image there:

protected boolean getChildStaticTransformation
	(View child, Transformation transformation) {

	transformation.clear();
	transformation.setTransformationType(Transformation.TYPE_MATRIX);
		
	// Center of the item
	float centerX = (float)child.getWidth()/2, centerY = (float)child.getHeight()/2;
		
	// Save camera
	mCamera.save();
		
	// Translate the item to it's coordinates
	final Matrix matrix = transformation.getMatrix();
	mCamera.translate(((CarouselImageView)child).getX(), 
				((CarouselImageView)child).getY(), 
				((CarouselImageView)child).getZ());
		
	// Align the item
	mCamera.getMatrix(matrix);
	matrix.preTranslate(-centerX, -centerY);
	matrix.postTranslate(centerX, centerY);
		
	// Restore camera
	mCamera.restore();		
		
	return true;
}    

One thing to know is that if you will just rotate images and position them in 3D space, they can overlap each other in the wrong order. For example, an image with 100.0 z-coordinate can be drawn in front of image with 50.0 z-coordinate. To resolve this trouble, we can override getChildDrawingOrder:

protected int getChildDrawingOrder(int childCount, int i) {

    	// Sort Carousel items by z coordinate in reverse order
    	ArrayList<carouselimageview> sl = new ArrayList<carouselimageview>();
    	for(int j = 0; j < childCount; j++)
    	{
    		CarouselImageView view = (CarouselImageView)getAdapter().
						getView(j,null, null);
    		if(i == 0)
    			view.setDrawn(false);
    		sl.add((CarouselImageView)getAdapter().getView(j,null, null));
    	}

    	Collections.sort(sl);
    	
    	// Get first undrawn item in array and get result index
    	int idx = 0;
    	
    	for(CarouselImageView civ : sl)
    	{
    		if(!civ.isDrawn())
    		{
    			civ.setDrawn(true);
    			idx = civ.getIndex();
    			break;
    		}
    	}
    	
    	return idx;
    }

</carouselimageview></carouselimageview>

Ok, it still has a lot to do, like bugs catching and optimization. I didn’t yet test all the functionality, but in the first approximation, it works.

Icons were taken from here: [4].

P.S. Fixed bug in Rotator class. Jerky "scroll into slots" was made more soft and fluid.

Reworked the Rotator class. It uses only angular acceleration now. 

Fixed  Jelly Bean issue. 

Resources 

1. http://ultimatefaves.com/
2. http://www.inter-fuser.com/2010/02/android-coverflow-widget-v2.html
3. http://www.inter-fuser.com/2010/01/android-coverflow-widget.html
4. http://www.iconsmaster.com/Plush-Icons-Set/