[Gzz] PEG 1013: Add clipping state to vob scenes

[Benja Fallenstein]

=============================================================
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.
    *  <p>
    *  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?