# Class PixelDrawing

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.PixelDrawing

All Implemented Interfaces:
  `PixerFactory`

public class PixelDrawing extends Object implements PixerFactory
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 `PixerFactory` 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:
  13 Sep 2021
Author:
  Mark Taylor

## Constructor Summary

Constructors
Constructor
Description
`PixelDrawing(int x0, int y0, int width, int height)`
Constructs a drawing with bounds given explicitly.
`PixelDrawing(Rectangle bounds)`
Constructs a drawing with bounds given by a rectangle.

## 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 if it is within this drawing's bounds.
`void`
`addPixelUnchecked(int x, int y)`
Adds a single pixel to the list of pixels which have been plotted without bounds checking.
`boolean`
`contains(int x, int y)`
Indicates whether a given position is within the bounds of this drawing.
`Pixer`
`createPixer()`
Returns a Pixer that interrogates this drawing's bitmap.
`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)`
Deprecated.
may be slow for large shapes; use fillPolygon if possible
`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`
`fillPolygon(int[] xs, int[] ys, int np)`
Draws a filled polygon on this drawing.
`void`
`fillRect(int x, int y, int width, int height)`
Fills a rectangle.
`int`
`getMaxX()`
Returns the highest X value from each created pixer.
`int`
`getMaxY()`
Returns the highest Y value from each created pixer.
`int`
`getMinX()`
Returns the lowest X value from each created pixer.
`int`
`getMinY()`
Returns the lowest Y value from each created pixer.
`int`
`getPixelCount()`
Returns the number of pixels over which each created pixer iterates.
`BitSet`
`getPixels()`
Returns the pixel mask containing the data for this drawing.

### Methods inherited from class Object

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

## Constructor Details

### PixelDrawing

public PixelDrawing(Rectangle bounds)
Constructs a drawing with bounds given by a rectangle.

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

### PixelDrawing

public PixelDrawing(int x0, int y0, int width, int height)
Constructs a drawing with bounds given explicitly.

Parameters:
  `x0` - lower bound of X coordinate
  `y0` - upper bound of Y coordinate
  `width` - extent in X direction
  `height` - extent in Y direction

## Method Details

### addPixel

public void addPixel(int x, int y)
Adds a single pixel to the list of pixels which have been plotted if it is within this drawing's bounds. 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

### addPixelUnchecked

public void addPixelUnchecked(int x, int y)
Adds a single pixel to the list of pixels which have been plotted without bounds checking. An assertion is made that the coordinates are outside of this drawing's bounds.

Parameters:
  `x` - X coordinate, must be within this drawing's X bounds
  `y` - Y coordinate, must be within this drawing's Y bounds

### 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

### fillPolygon

public void fillPolygon(int[] xs, int[] ys, int np)
Draws a filled polygon on this drawing.

Parameters:
  `xs` - X coordinates of vertices
  `ys` - Y coordinates of vertices
  `np` - number of vertices

### fill

@Deprecated public void fill(Shape shape)
Deprecated.
may be slow for large shapes; use fillPolygon if possible
Fills an arbitrary shape.

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

### contains

public boolean contains(int x, int y)
Indicates whether a given position is within the bounds of this drawing.

Parameters:
  `x` - X coordinate
  `y` - Y coordinate
Returns:
  true iff (x,y) is in bounds

### getPixels

public BitSet getPixels()
Returns the pixel mask containing the data for this drawing. The coordinate mapping is not currently defined, but the return value of this method for two PixelDrawings with the same bounds will have the same bit-to-pixel correspondance; a set bit corresponds to a painted pixel. This value may be modified in place.

Returns:
  bit map giving pixel data

### getMinX

public int getMinX()
Description copied from interface: `PixerFactory`
Returns the lowest X value from each created pixer.

Specified by:
  `getMinX` in interface `PixerFactory`
Returns:
  minimum X coordinate

### getMaxX

public int getMaxX()
Description copied from interface: `PixerFactory`
Returns the highest X value from each created pixer.

Specified by:
  `getMaxX` in interface `PixerFactory`
Returns:
  maximum X coordinate

### getMinY

public int getMinY()
Description copied from interface: `PixerFactory`
Returns the lowest Y value from each created pixer.

Specified by:
  `getMinY` in interface `PixerFactory`
Returns:
  minimum Y coordinate

### getMaxY

public int getMaxY()
Description copied from interface: `PixerFactory`
Returns the highest Y value from each created pixer.

Specified by:
  `getMaxY` in interface `PixerFactory`
Returns:
  maximum Y coordinate

### getPixelCount

public int getPixelCount()
Description copied from interface: `PixerFactory`
Returns the number of pixels over which each created pixer iterates.

Specified by:
  `getPixelCount` in interface `PixerFactory`
Returns:
  pixel count

### createPixer

public Pixer createPixer()
Returns a Pixer that interrogates this drawing's bitmap. May not be maximally efficient if it will be called many times.

Specified by:
  `createPixer` in interface `PixerFactory`
Returns:
  pixer