PEG 1013: Add clipping state to vob scenes

Author: Benja Fallenstein
Revision: 1.6
Status: Current

Currently there is no way to clip vobs independent of the GraphicsAPI used. In OpenGL, clipping is handled through the 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.


Add the following methods to VobScene:

/** Intersect the clipping area with the given cs's "unit square".
 *  This changes the current clipping area to the intersection
 *  of the old clipping area with the "unit square" of the given
 *  coordinate system, and pushes the old clipping area onto 
 *  a stack of clipping areas.
 *  All vobs placed into this VobScene will be rendered
 *  with the new clipping area, until ``unclip()`` is called,
 *  restoring the old 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 clip(int cs);

/** 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).