============================================================= PEG 1013: Add clipping state to vob scenes ============================================================= :Author: Benja Fallenstein :Date: $Date: 2002/10/08 23:44:07 $ :Revision: $Revision: 1.1 $ :Status: Incomplete Currently there is no way to clip vobs independent of the ``GraphicsAPI`` used. In OpenGL, clipping is handled through the ``gzz.gfx.gl.Stencil`` class, which uses OpenGL state: Being passed a ``Runnable`` object, the class sets up OpenGL state so that a given area is clipped, calls the ``Runnable`` which places vobs into the vobscene that are rendered with the given clip, then removes the clipping state and returns. In AWT, clipping is currently unhandled. Changes ------- Add the following methods to ``VobScene``:: /** Clip a rectangle. * This changes the currently clipping area to the intersection * of the given rectangle (as interpreted in the given * coordinate system) with the old clipping area, and pushes * the old clipping area onto a stack of clipping areas. * All vobs placed into this VobScene until ``unclip()`` * is called will be rendered with the new clipping area. *

* The clipping area is the area where graphics are drawn. * Note that the stack of clipping areas is a way to * specify the semantics of this method, and is not required * to be implemented through a stack data structure. */ void clipRect(int cs, float x, float y, float w, float h); /** Pop the topmost clipping area off the stack. * The last pushed clipping area is popped off the stack and * made current. * @throws IndexOutOfBoundsException if the stack is empty. */ void unclip(); Non-rectangular clips need to be handled in a ``GraphicsAPI``-specific manner, because our least common denominator is rectangluarly shaped clipping. (Of course, rectangularity is defined by the coordinate system: if the coordinate system is not orthogonal, the clipped area may not be a rectangle.) The ``unclip()`` method is needed so that several clips can be applied hierarchically without difficulty. In OpenGL, these methods can be implemented using OpenGL state, as in the ``Stencil`` class. (The two methods here are less powerful than what the ``Stencil`` class provides, because they are least-common-denominator. OpenGL specific methods can provide more powerful clipping functionality, should it be needed.) In AWT, these methods can be implement using ``java.awt.Graphics`` state combined with a stack of ``java.awt.Shape`` objects representing the different clipping areas (``java.util.ArrayList`` contains convenience methods for being used as a stack). Open issues ----------- How are the new ``VobScene`` methods implemented? Will there be ``GraphicsAPI``-specific subclasses, or will the calls be passed to ``VobCoorder``, which has ``GraphicsAPI``-dependent implementations currently?