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

package org.expeditee.gio;

import java.util.Stack;

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

/**
 * 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;

        }
}