# Class Drawing

java.lang.Object
uk.ac.starlink.ttools.plot.Drawing

All Implemented Interfaces:
  `Pixellator`

public class Drawing extends Object implements Pixellator
Provides drawing primitives on a pixel map. This is a bit like a `Graphics`, but renders only to a one-bit-per-pixel bitmap. After drawings have been done, the object can be used as a `Pixellator` to get a list of the pixels which have been hit at least once by one of the drawing methods called during the life of the object. Pixels will not be repeated in this list.

The drawing methods are intended to be as efficient as possible. Bounds checking is done, so it is generally not problematic (or inefficient) to attempt drawing operations with coordinates far outside the drawing's range.

Since:
  20 Mar 2007
Author:
  Mark Taylor

## Constructor Summary

Constructors
Constructor
Description
`Drawing(Rectangle bounds)`
Constructs a drawing with given pixel bounds.

## Method Summary

Modifier and Type
Method
Description
`void`
`addPixel(int x, int y)`
Adds a single pixel to the list of pixels which have been plotted.
`void`
`addPixels(Pixellator pixellator)`
Adds all the pixels from the given Pixellator to this drawing.
`static Pixellator`
`combinePixellators(Pixellator[] pixers)`
Combines an array of given pixellators to produce a single one which iterates over all the pixels.
`void`
`draw(Shape shape)`
Draws the outline of an arbitrary shape.
`void`
`drawEllipse(int x0, int y0, int ax, int ay, int bx, int by)`
Draws the outline of an ellipse with no restrictions on the alignment of its axes.
`void`
`drawLine(int x0, int y0, int x1, int y1)`
Draws a straight line between two points.
`void`
`drawOval(int x, int y, int width, int height)`
Draws the outline of an ellipse with horizontal/vertical axes.
`void`
`fill(Shape shape)`
Fills an arbitrary shape.
`void`
`fillEllipse(int x0, int y0, int ax, int ay, int bx, int by)`
Fills an ellipse with no restrictions on the alignment of its axes.
`void`
`fillOval(int x, int y, int width, int height)`
Fills an ellipse with horizontal/vertical axes.
`void`
`fillRect(int x, int y, int width, int height)`
Fills a rectangle.
`Rectangle`
`getBounds()`
Returns a copy of the bounding rectangle for this pixellator.
`int`
`getX()`
Returns the X value for the current point.
`int`
`getY()`
Returns the Y value for the current point.
`boolean`
`next()`
Moves to the next point in the sequence.
`void`
`start()`
Makes this object ready to iterate.

### Methods inherited from class Object

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

## Constructor Details

### Drawing

public Drawing(Rectangle bounds)
Constructs a drawing with given pixel bounds.

Parameters:
  `bounds` - rectangle giving the region in which pixels may be plotted

## Method Details

### getBounds

public Rectangle getBounds()
Description copied from interface: `Pixellator`
Returns a copy of the bounding rectangle for this pixellator. All points iterated over by this object will fall within this rectangle. If this object has no points, `null` may be returned.

Specified by:
  `getBounds` in interface `Pixellator`
Returns:
  bounds

### addPixel

public void addPixel(int x, int y)
Adds a single pixel to the list of pixels which have been plotted. Calling it with coordinates which have already been plotted, or which are outside this drawing's bounds, has no effect.

Parameters:
  `x` - X coordinate
  `y` - Y coordinate

### drawLine

public void drawLine(int x0, int y0, int x1, int y1)
Draws a straight line between two points.

Parameters:
  `x0` - X coordinate of first point
  `y0` - Y coordinate of first point
  `x1` - X coordinate of second point
  `y1` - Y coordinate of second point
See Also:
  - `Graphics.drawLine(int, int, int, int)`

### fillRect

public void fillRect(int x, int y, int width, int height)
Fills a rectangle.

Parameters:
  `x` - X coordinate of top left corner
  `y` - Y coordinate of top left corner
  `width` - width
  `height` - height
See Also:
  - `Graphics.fillRect(int, int, int, int)`

### drawOval

public void drawOval(int x, int y, int width, int height)
Draws the outline of an ellipse with horizontal/vertical axes.

Parameters:
  `x` - X coordinate of top left corner of enclosing rectangle
  `y` - Y coordinate of top left corner of enclosing rectangle
  `width` - width of enclosing rectangle
  `height` - height of enclosing rectangle
See Also:
  - `Graphics.drawOval(int, int, int, int)`

### fillOval

public void fillOval(int x, int y, int width, int height)
Fills an ellipse with horizontal/vertical axes.

Parameters:
  `x` - X coordinate of top left corner of enclosing rectangle
  `y` - Y coordinate of top left corner of enclosing rectangle
  `width` - width of enclosing rectangle
  `height` - height of enclosing rectangle
See Also:
  - `Graphics.drawOval(int, int, int, int)`

### drawEllipse

public void drawEllipse(int x0, int y0, int ax, int ay, int bx, int by)
Draws the outline of an ellipse with no restrictions on the alignment of its axes.

Parameters:
  `x0` - X coordinate of ellipse centre
  `y0` - Y coordinate of ellipse centre
  `ax` - X component of semi-major (or -minor) axis
  `ay` - Y component of semi-major (or -minor) axis
  `bx` - X component of semi-minor (or -major) axis
  `by` - Y component of semi-minor (Or -major) axis

### fillEllipse

public void fillEllipse(int x0, int y0, int ax, int ay, int bx, int by)
Fills an ellipse with no restrictions on the alignment of its axes.

Parameters:
  `x0` - X coordinate of ellipse centre
  `y0` - Y coordinate of ellipse centre
  `ax` - X component of semi-major (or -minor) axis
  `ay` - Y component of semi-major (or -minor) axis
  `bx` - X component of semi-minor (or -major) axis
  `by` - Y component of semi-minor (Or -major) axis

### fill

public void fill(Shape shape)
Fills an arbitrary shape.

Parameters:
  `shape` - shape to fill
See Also:
  - `Graphics2D.fill(Shape)`

### draw

public void draw(Shape shape)
Draws the outline of an arbitrary shape. May not be that efficient.

Parameters:
  `shape` - shape to draw
See Also:
  - `Graphics2D.draw(Shape)`

### addPixels

public void addPixels(Pixellator pixellator)
Adds all the pixels from the given Pixellator to this drawing.

Parameters:
  `pixellator` - iterator over pixels to add

### start

public void start()
Description copied from interface: `Pixellator`
Makes this object ready to iterate. Should be called before any call to `Pixellator.next()`.

Specified by:
  `start` in interface `Pixellator`

### next

public boolean next()
Description copied from interface: `Pixellator`
Moves to the next point in the sequence. Must be called before any call to `Pixellator.getX()`/`Pixellator.getY()`. Returns value indicates whether there is a next point.

Specified by:
  `next` in interface `Pixellator`
Returns:
  next true iff there are more points

### getX

public int getX()
Description copied from interface: `Pixellator`
Returns the X value for the current point.

Specified by:
  `getX` in interface `Pixellator`
Returns:
  x

### getY

public int getY()
Description copied from interface: `Pixellator`
Returns the Y value for the current point.

Specified by:
  `getY` in interface `Pixellator`
Returns:
  y

### combinePixellators

public static Pixellator combinePixellators(Pixellator[] pixers)
Combines an array of given pixellators to produce a single one which iterates over all the pixels. It is tempting just to provide a new Pixellator implementation which iterates over its consituent ones to do this, but that would risk returning some pixels multiple times, which we don't want.

Parameters:
  `pixers` - array of pixellators to combine
Returns:
  pixellator comprising the union of the supplied ones