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

[Benja Fallenstein]

=============================================================
PEG 1013: Add clipping state to vob scenes
=============================================================

:Author:       Benja Fallenstein
:Last-Modified: $Date: 2002/11/21 23:39:26 $
:Revision:     $Revision: 1.3 $
:Status:       Current


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.

This is needed for alpha4 in order to fix the AWT client.


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 sx, float sh);
   
   /** 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).


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?

 RESOLVED: They will be directed to ``VobCoorder``, since this
 results in less changes to the architecture. There will be
 ``clipRect()`` and ``unclip()`` methods with the same signature
 in ``VobCoorder``.