org.gicentre.utils.move
Class Clipper

java.lang.Object
  org.gicentre.utils.move.Clipper

public class Clipper
extends java.lang.Object

Class for limiting drawing to a fixed rectangular area. Simple usage example:

 import org.gicentre.utils.gui.Clipper;
 Clipper clipper;
 
 void setup() {
     //...
     size(600, 400);
     clipper = new Clipper(this, 100, 100, 300, 200); // x, y, width, height
     //...
 }
 
 void draw() {
     drawSomeStuffAsUsual();
     
     clipper.startClipping();
     drawStuffYouWantToClip();
     clipper.stopClipping();
     
     drawSomeOtherStuffAsUsual();
 }
 

Limitations:

• only works with JAVA2D
• clipping is ignored when writing to PDF using startRecording()
• boundaries must be always given in absolute coordinate system (matrix transitions and scalings are ignored)

Version:

3.3, 3rd June, 2012.

Author:

Alexander Kachkaev with minor modifications by Jo Wood. Inspired by Aidan Slingsby's GraphicBuffer

Field Summary

protected processing.core.PApplet	applet
protected java.awt.geom.Rectangle2D	clippingRect
protected boolean	enabled
protected processing.core.PGraphicsJava2D	pGraphics2D

Constructor Summary

Clipper(processing.core.PApplet applet)
Creates a new clipper set to the bounds of the given sketch.

Clipper(processing.core.PApplet applet, float x, float y, float width, float height)
Creates a new Clipper instance capable of limiting all drawing to within the given rectangular bounds.

Clipper(processing.core.PApplet applet, java.awt.geom.Rectangle2D clippingRect)
Creates a new Clipper instance capable of limiting all drawing to within the given rectangular bounds.

Method Summary

boolean	contains(float x, float y) Reports whether or not the given point lies within the clipping rectangle.
boolean	contains(processing.core.PVector p) Reports whether or not the given point lies within the clipping rectangle.
java.awt.geom.Rectangle2D	getClippingRect() Reports the clipping rectangle, whether or not is is currently active.
boolean	isClipping() Reports whether or not clipping mode is currently active.
boolean	isEnabled() Reports whether or not clipping is enabled.
void	setClippingRect(float x, float y, float width, float height) Sets the clipping rectangle and applies it if currently clipping
void	setClippingRect(java.awt.geom.Rectangle2D clippingRect) Sets the clipping rectangle and applies it if currently clipping
void	setEnabled(boolean enabled) Determines whether or not clipping is enabled.
void	startClipping() Starts clipping all drawn content to the screen bounds of the current clip area.
void	stopClipping() Stops any active clipping.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

applet

protected processing.core.PApplet applet

pGraphics2D

protected processing.core.PGraphicsJava2D pGraphics2D

clippingRect

protected java.awt.geom.Rectangle2D clippingRect

enabled

protected boolean enabled

Constructor Detail

Clipper

public Clipper(processing.core.PApplet applet)

Creates a new clipper set to the bounds of the given sketch.

Parameters:

applet - Sketch in which to enable clipping.

Clipper

public Clipper(processing.core.PApplet applet,
               float x,
               float y,
               float width,
               float height)

Creates a new Clipper instance capable of limiting all drawing to within the given rectangular bounds. Clipping is enabled by default, but not active.

Parameters:

applet - Sketch in which to enable clipping.

x - x coordinate of the top-left of the clipping rectangle.

y - y coordinate of the top-left of the clipping rectangle.

width - Width of the clipping rectangle.

height - Height of the clipping rectangle.

See Also:

startClipping(), stopClipping(), setEnabled(boolean)

Clipper

public Clipper(processing.core.PApplet applet,
               java.awt.geom.Rectangle2D clippingRect)

Creates a new Clipper instance capable of limiting all drawing to within the given rectangular bounds. Clipping is enabled by default, but not active.

Parameters:

applet - Sketch in which to enable clipping.

clippingRect - Bounds of the rectangle within which clipping is to be applied.

See Also:

startClipping(), stopClipping(), setEnabled(boolean)

Method Detail

startClipping

public void startClipping()

Starts clipping all drawn content to the screen bounds of the current clip area. If startClipping for the current clipper is called before stopClipping somewhere else, an exception is thrown.

stopClipping

public void stopClipping()

Stops any active clipping.

setClippingRect

public void setClippingRect(float x,
                            float y,
                            float width,
                            float height)

Sets the clipping rectangle and applies it if currently clipping

Parameters:

x - x coordinate of the top-left of the clipping rectangle.

y - y coordinate of the top-left of the clipping rectangle.

width - Width of the clipping rectangle.

height - Height of the clipping rectangle.

setClippingRect

public void setClippingRect(java.awt.geom.Rectangle2D clippingRect)

Sets the clipping rectangle and applies it if currently clipping

Parameters:

clippingRect - The clipping rectangle to apply.

getClippingRect

public java.awt.geom.Rectangle2D getClippingRect()

Reports the clipping rectangle, whether or not is is currently active.

Returns:

Bounds of the current clipping rectangle.

contains

public boolean contains(float x,
                        float y)

Reports whether or not the given point lies within the clipping rectangle. The result is independent of whether or not clipping is currently active.

Parameters:

x - x coordinate of the point to test.

y - y coordinate of the point to test.

Returns:

True if the given point is within the clipping rectangle, false otherwise.

contains

public boolean contains(processing.core.PVector p)

Reports whether or not the given point lies within the clipping rectangle. The result is independent of whether or not clipping is currently active.

Parameters:

p - Point to test.

Returns:

True if the given point is within the clipping rectangle, false otherwise.

isClipping

public boolean isClipping()

Reports whether or not clipping mode is currently active. Note that the result is only true between startClipping() and stopClipping() method calls.

Returns:

True if called while clipping is currently active, otherwise false.

See Also:

isEnabled()

isEnabled

public boolean isEnabled()

Reports whether or not clipping is enabled. Unlike isClipping(), this returns true even before startClipping() and after stopClipping().

Returns:

True if clipping is enabled.

See Also:

isClipping(), setEnabled(boolean)

setEnabled

public void setEnabled(boolean enabled)

Determines whether or not clipping is enabled. If enabled is false, no clipping happens between startClipping() and stopClipping() (startClipping is ignored). If called with enabled=false during clipping, clipping is stopped.