source: trunk/src/org/expeditee/gio/GraphicsSurfaceStack.java@ 1097

package org.expeditee.gio;

import java.util.Stack;

import org.expeditee.core.Clip;
import org.expeditee.core.EnforcedClipStack;
import org.expeditee.core.Image;
import org.expeditee.core.EnforcedClipStack.EnforcedClipKey;

/**
 * Helper-class for the graphics manager to maintain a stack of drawing
 * surfaces. Should be sub-typed by the platform-specific graphics manager
 * to use the appropriate surface class.
 */
public abstract class GraphicsSurfaceStack<T> {

        /** The root surface corresponds to drawing directly into the window. */
        private T _rootSurface;
        /** The surface that drawing commands should draw into. */
        private T _currentSurface;
        /** The stack of drawing surfaces. */
        private Stack<T> _surfaceStack;
        /** The image that produced the current drawing surface. */
        private Image _currentImage;
        /** The stack of images that produced the surfaces in the surface stack. */
        private Stack<Image> _imageStack;
        /** The clip-stack for the root surface. */
        private EnforcedClipStack _rootClipStack;
        /** The clip-stack for the current surface. */
        private EnforcedClipStack _currentClipStack;
        /** The clip-stack for each drawing surface. */
        private Stack<EnforcedClipStack> _clipStackStack;
        
        /** Constructor specifying no root surface. */
        public GraphicsSurfaceStack()
        {
                this(null);
        }
        
        /** Constructor specifying the root surface. */
        public GraphicsSurfaceStack(T rootSurface)
        {
                setRootSurface(rootSurface);
                _currentImage = null;
                _surfaceStack = new Stack<T>();
                _imageStack = new Stack<Image>();
                _rootClipStack = _currentClipStack = new EnforcedClipStack();
                _clipStackStack = new Stack<EnforcedClipStack>();
        }
        
        /** Should be overridden by sub-types to allow a drawing surface to be extracted from an image. */
        public abstract T getSurfaceFromImage(Image image);
        
        /** Should be overridden by sub-types to set the actual clip on a given surface. */
        public abstract void setSurfaceClip(T surface, Clip clip);
        
        /** Pushes a new image onto the stack, and sets it as the current drawing surface. */
        public void push(Image image)
        {
                if (image == null) return;
                
                _currentSurface = getSurfaceFromImage(image);
                _currentImage = image;
                _currentClipStack = new EnforcedClipStack();
                _surfaceStack.push(_currentSurface);
                _imageStack.push(image);
                _clipStackStack.push(_currentClipStack);
        }
        
        /** Removes an image from the stack. The removed image is returned, or null if the root surface was current. */
        public Image pop()
        {
                if (_surfaceStack.isEmpty()) return null;
                
                Image oldTop = _imageStack.pop();
                _surfaceStack.pop();
                _clipStackStack.pop();
                
                if (!_surfaceStack.isEmpty()) {
                        _currentSurface = _surfaceStack.peek();
                        _currentImage = _imageStack.peek();
                        _currentClipStack = _clipStackStack.peek();
                } else {
                        _currentSurface = _rootSurface;
                        _currentImage = null;
                        _currentClipStack = _rootClipStack;
                }
                
                return oldTop;
        }
        
        /** Gets a reference to the current drawing surface. */
        public T getCurrentSurface()
        {
                return _currentSurface;
        }
        
        /** Gets a reference to the top image on the stack. */
        public Image getCurrentImage()
        {
                return _currentImage;
        }
        
        /** Pushes a new clip onto the stack, ensuring that it is a sub-area of the top of the stack. */
        public EnforcedClipKey pushClip(Clip clip)
        {
                EnforcedClipKey key = _currentClipStack.push(clip);
                if (key != null) ensureClip();
                return key;
        }
        
        /** Pops the top of the current clip-stack if there given key corresponds to it. */
        public Clip popClip(EnforcedClipKey key)
        {
                Clip clip = _currentClipStack.pop(key);
                if (clip != null) ensureClip();
                return clip;
        }
        
        /** Returns a copy of the top of the current clip-stack. */
        public Clip peekClip()
        {
                return _currentClipStack.peek();
        }
        
        /** Ensures the current clip is applied to the underlying surface. */
        public void ensureClip()
        {
                setSurfaceClip(_currentSurface, _currentClipStack.peek());
        }
        
        /** Updates the root surface. Does not affect any stacked image surfaces. */
        public void setRootSurface(T rootSurface)
        {
                if (_currentSurface == _rootSurface) _currentSurface = rootSurface;
                _rootSurface = rootSurface;
                
        }
}