# Module `rastergraphics` - Graphics primitives for rasters

Graphics primitives for rasters.

#### Maintainer:

David Wood <D.C.Wood@kent.ac.uk>

## Index

- Data type `ANGLE` - ANGLE data type
- Group `ANGLE` - constants
  - Constant `ANGLE.DEGREE` - 2^32 / 360 (approx.)
  - Constant `ANGLE.GRADE` - 2^32 / 400 (approx.)
  - Constant `ANGLE.RADIAN` - 2^31 / pi (approx.)
  - Constant `ANGLE.RIGHT` - 2^30 (exact)
  - Constant `ANGLE.STRAIGHT` - 2^31 (exact)
- Function `CIDROC` - Inverse algorithm; Converts Cartesian (X, Y) to polar coordinates
  - Constant `CORDIC.CONST` - Magic constant
- Group `COLOUR` - Common colours
  - Constant `COLOUR.BLACK`
  - Constant `COLOUR.BLUE`
  - Constant `COLOUR.BROWN`
  - Constant `COLOUR.CYAN`
  - Constant `COLOUR.GREEN`
  - Constant `COLOUR.GREY`
  - Constant `COLOUR.MAGENTA`
  - Constant `COLOUR.MAROON`
  - Constant `COLOUR.NAVY`
  - Constant `COLOUR.OCTARINE`
  - Constant `COLOUR.ORANGE`
  - Constant `COLOUR.PINK`
  - Constant `COLOUR.PURPLE`
  - Constant `COLOUR.RED`
  - Constant `COLOUR.SKY`
  - Constant `COLOUR.VIOLET`
  - Constant `COLOUR.WHITE`
  - Constant `COLOUR.YELLOW`
- Function `CORDIC` - CORDIC rotation algorithm
  - Constant `CORDIC.CONST` - Magic constant
- Group `PALETTE` - Codes for permute arguments
  - Constant `PALETTE.BGR`
  - Constant `PALETTE.BRG`
  - Constant `PALETTE.GBR`
  - Constant `PALETTE.GRB`
  - Constant `PALETTE.RBG`
  - Constant `PALETTE.RGB`
- Function `circle.hits` - Does circle hit anything?
- Process `copy.raster` - Copy one raster onto another
- Function `desaturate.colour` - Desaturate a colour value
- Function `dither` - Dither
- Process `draw.arc` - Draws a circular arc
  - Process `arc` - Basic PROC; arc <= ANGLE.RIGHT
- Process `draw.circle` - Draws a circle
  - Process `points` - Decide how to plot points
  - Process `points.1` - Plots eight points at (+/-x, +/-y) relative to centre (x.0, y0) , all within raster (fast)
  - Process `points.2` - Plots eight points at (+/-x, +/-y) relative to centre (x.0, y0) , some outside raster (slow)
    - Process `point` - Plot point if inside raster
- Process `draw.horizontal.line` - Draws a horizontal line
- Process `draw.line` - Draw a straight line
- Process `draw.rectangle` - Draws a rectangular box
- Process `draw.vertical.line` - Draws a vertical line
- Process `draw.wallpaper` - Cover dst with copies of dst
- Process `fill.circle` - Draws a solid circle
- Process `fill.circle.diameter` - Draws a solid circle
- Process `fill.ellipse.radii` - Draws a solid ellipse
- Process `fill.rectangle` - Draws a solid rectangle
- Process `fill.square` - Draw a solid square
- Function `hsv.to.rgb` - Convert a colour from HSV to RGB
- Function `map.colour.spectrum` - Maps x ( 0.0 <= x < 1.0 ) to INT representing a colour, according to the code permute
- Function `map.colour.wheel` - Maps x ( 0.0 <= x < 1.0 ) to INT representing a colour, according to the code permute
- Function `map.to.components.spectrum` - Maps code value into three BYTEs representing primary colours (not necessarily RGB), with smooth transitions
  - Function `smooth` - Smooth transition
- Function `map.to.components.wheel` - As , but without mapping through black
- Operator `+ (ANGLE, ANGLE)` - Addition operator
- Operator `~ (ANGLE)` - Reverse operator
- Function `pack.colour` - Pack RGB BYTEs to an INT
- Function `pack.colour.float` - As , but taking REAL32 arguments
- Function `pack.colour.permuted` - Maps three BYTEs representing colours to an INT , according to the code permute
- Function `undither` - Reverse Dither
- Function `unpack.colour` - Unpack an INT to RGB BYTEs

## Declarations

### `colourspace.occ`:34Function `desaturate.colour`

`INT FUNCTION desaturate.colour (VAL INT colour, amount)`

Desaturate a colour value.

This adds `amount` to each of the colour's components, capping them at `#FF`.

#### Parameters:

`VAL INT` | `colour` | Colour
`VAL INT` | `amount` | Amount to add

#### Returns:

`INT` |  | The new colour

### `colourspace.occ`:69Function `hsv.to.rgb`

`INT FUNCTION hsv.to.rgb (VAL REAL32 h, s, v)`

Convert a colour from HSV to RGB.

The HSV colourspace specifies colour shades in terms of hue (basic colour), saturation and value (brightness), each a real value between 0 and 1. It's useful if you want to turn a continuous range of values into a smooth series of colours: fix the saturation and value and vary the hue.

This is an implementation of N. Schaller's algorithm.

#### Parameters:

`VAL REAL32` | `h` | Hue
`VAL REAL32` | `s` | Saturation
`VAL REAL32` | `v` | Value

#### Returns:

`INT` |  | `#rrggbb`

### `dither.occ`:28Function `dither`

`INT FUNCTION dither (VAL INT n, i, j)`

Dither

#### Parameters:

`VAL INT` | `n` | Order
`VAL INT` | `i`, `j` | Coordinates

#### Returns:

`INT` |  | Dither

### `dither.occ`:51Function `undither`

`INT, INT FUNCTION undither (VAL INT n, k)`

Reverse Dither

#### Parameters:

`VAL INT` | `n` | Order
`VAL INT` | `k` | Count

#### Returns:

`INT` | `i`, `j` | Coordinates

### `disc.occ`:30Process `fill.circle`

`PROC fill.circle (VAL INT x, y, r, VAL INT colour, [][]INT raster)`

Draws a solid circle. Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Coordinates of centre
`VAL INT` | `r` | Radius
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `hit.occ`:29Function `circle.hits`

`BOOL FUNCTION circle.hits (VAL INT X, Y, radius, colour, VAL [][]INT raster)`

Does circle hit anything?

#### Parameters:

`VAL INT` | `X`, `Y` | Centre of circle
`VAL INT` | `radius` | Radius
`VAL INT` | `colour` | Colour of target
`VAL [][]INT` | `raster` | Raster

### `wallpaper.occ`:27Process `draw.wallpaper`

`PROC draw.wallpaper (VAL [][]INT src, [][]INT dst)`

Cover `dst` with copies of `dst`

#### Parameters:

`VAL [][]INT` | `src` | Source raster
`[][]INT` | `dst` | Destination raster

### `line.occ`:37Process `draw.line`

`PROC draw.line (INT x.0, y.0, VAL INT d.x, d.y, VAL INT c.0, c.1, [][]INT raster)`

Draw a straight line.

Returns end point in `(x.0, y.0)`.

Does nothing if `(x.0, y.0)` is outside `raster`.

Based on Foley & van Dam, Computer Graphics Principles and Practice, Second Edition in C, Fig. 3.8.

#### Parameters:

`INT` | `x.0`, `y.0` | Starting point
`VAL INT` | `d.x`, `d.y` | Relative position of end point
`VAL INT` | `c.0` | Stop when line hits this colour
`VAL INT` | `c.1` | Draw in this colour ...
`[][]INT` | `raster` | ... on this raster

### `angle.inc`:28Data type `ANGLE`

`DATA TYPE ANGLE`

ANGLE data type

An `ANGLE` is measured in units of 2^32 bits = 1 turn = 4 right angles = 2 pi radians = 360 degrees = 400 grades. Like times, angles wrap round without overflowing.

### `angle.inc`:30Group `ANGLE`

``

constants

### `angle.inc`:32Constant `ANGLE.STRAIGHT`

`VAL ANGLE ANGLE.STRAIGHT`

2^31 (exact)

### `angle.inc`:33Constant `ANGLE.RIGHT`

`VAL ANGLE ANGLE.RIGHT`

2^30 (exact)

### `angle.inc`:34Constant `ANGLE.RADIAN`

`VAL ANGLE ANGLE.RADIAN`

2^31 / pi (approx.)

### `angle.inc`:35Constant `ANGLE.DEGREE`

`VAL ANGLE ANGLE.DEGREE`

2^32 / 360 (approx.)

### `angle.inc`:38Constant `ANGLE.GRADE`

`VAL ANGLE ANGLE.GRADE`

2^32 / 400 (approx.)

### `angle.inc`:48Operator `+ (ANGLE, ANGLE)`

`ANGLE INLINE FUNCTION "+" (VAL ANGLE X, Y)`

Addition operator

#### Parameters:

`VAL ANGLE` | `X`, `Y` | Operands

#### Returns:

`ANGLE` |  | `X + Y`

### `angle.inc`:64Operator `~ (ANGLE)`

`ANGLE INLINE FUNCTION "~" (VAL ANGLE X)`

Reverse operator

#### Parameters:

`VAL ANGLE` | `X` | Operands

#### Returns:

`ANGLE` |  | Opposite direction

### `ellipse.occ`:31Process `fill.ellipse.radii`

`PROC fill.ellipse.radii (VAL INT x, y, a, b, VAL INT colour, [][]INT raster)`

Draws a solid ellipse. Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Coordinates of centre
`VAL INT` | `a`, `b` | X and Y radii
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `circle.occ`:34Process `draw.circle`

`PROC draw.circle (VAL INT x.0, y.0, radius, VAL INT colour, [][]INT raster)`

Draws a circle.

Clips as necessary.

Based on Foley & van Dam, Computer Graphics Principles and Practice, Second Edition in C, Fig. 3.16.

#### Parameters:

`VAL INT` | `x.0`, `y.0` | Centre
`VAL INT` | `radius` | Radius
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `circle.occ`:42Process `points.1`

`INLINE PROC points.1 (VAL INT x, y)`

Plots eight points at `(+/-x, +/-y)` relative to centre `(x.0, y0)`, all within raster (fast).

### `circle.occ`:59Process `points.2`

`PROC points.2 (VAL INT x, y)`

Plots eight points at `(+/-x, +/-y)` relative to centre `(x.0, y0)`, some outside raster (slow).

### `circle.occ`:65Process `point`

`PROC point (VAL INT x, y)`

Plot point if inside raster

#### Parameters:

`VAL INT` | `x`, `y` | Coordinates

### `circle.occ`:93Process `points`

`INLINE PROC points (VAL INT x, y, VAL BOOL b)`

Decide how to plot points

#### Parameters:

`VAL INT` | `x`, `y` | Coordinates
`VAL BOOL` | `b` | How to plot

### `spectrum.occ`:31Function `map.to.components.spectrum`

`BYTE, BYTE, BYTE FUNCTION map.to.components.spectrum (VAL REAL64 x)`

Maps code value into three `BYTEs` representing primary colours (not necessarily RGB), with smooth transitions.

#### Parameters:

`VAL REAL64` | `x` | Value `(0.0 <= x < 1.0)`

#### Returns:

`BYTE` | `"red"`, `"green"`, `"blue"` |

### `spectrum.occ`:41Function `smooth`

`BYTE INLINE FUNCTION smooth (VAL REAL64 x)`

Smooth transition.

#### Parameters:

`VAL REAL64` | `x` | Argument; `0.0 <= x <= 1.0`

#### Returns:

`BYTE` |  | `0 <= "colour" <= #FF`

### `spectrum.occ`:75Function `map.to.components.wheel`

`BYTE, BYTE, BYTE FUNCTION map.to.components.wheel (VAL REAL64 x)`

As `map.to.components.spectrum`, but without mapping through black.

### `spectrum.occ`:115Function `pack.colour.permuted`

`INT FUNCTION pack.colour.permuted (VAL BYTE r, g, b, VAL INT permute)`

Maps three `BYTEs` representing colours to an `INT`, according to the code `permute`.

#### Parameters:

`VAL BYTE` | `r`, `g`, `b` | "red", "green", "blue"
`VAL INT` | `permute` | Permutation code

#### Returns:

`INT` |  | #rrggbb

### `spectrum.occ`:159Function `map.colour.spectrum`

`INT FUNCTION map.colour.spectrum (VAL REAL64 x, VAL INT permute)`

Maps `x` (`0.0 <= x < 1.0`) to `INT` representing a colour, according to the code `permute`. Shades from black through "red", "yellow", "green", "cyan", "magenta", back to "red", and finally black.

`x >= 1.0` shown as black; `x < 0.0` shown as dark grey.

#### Parameters:

`VAL REAL64` | `x` | `(0.0 <= x < 1.0)`
`VAL INT` | `permute` | Permutation code

#### Returns:

`INT` |  | `#rrggbb`

### `spectrum.occ`:188Function `map.colour.wheel`

`INT FUNCTION map.colour.wheel (VAL REAL64 x, VAL INT permute)`

Maps `x` (`0.0 <= x < 1.0`) to `INT` representing a colour, according to the code `permute`. Shades from "red" through "yellow", "green", "cyan", "magenta", back to "red".

`x >= 1.0` shown as black; `x < 0.0` shown as white.

#### Parameters:

`VAL REAL64` | `x` | `(0.0 <= x < 1.0)`
`VAL INT` | `permute` | Permutation code

#### Returns:

`INT` |  | `#rrggbb`

### `cordic.occ`:55Function `CORDIC`

`INT, INT FUNCTION CORDIC (VAL INT X, Y, VAL ANGLE theta)`

CORDIC rotation algorithm.

See here for details.

Rotates vector through angle

#### Parameters:

`VAL INT` | `X`, `Y` | Coordinates of vector
`VAL ANGLE` | `theta` | Angle

#### Returns:

`INT` | `X`, `Y` | Rotated through `theta`

### `cordic.occ`:65Constant `CORDIC.CONST`

`VAL INT CORDIC.CONST`

Magic constant

### `cordic.occ`:101Function `CIDROC`

`INT, ANGLE FUNCTION CIDROC (VAL INT X, Y)`

Inverse `CORDIC` algorithm; Converts Cartesian `(X, Y)` to polar coordinates.

#### Parameters:

`VAL INT` | `X`, `Y` | Coordinate of vector

#### Returns:

`INT` |  | radius `sqrt(X^2 + Y^2)`
`ANGLE` |  | angle `arctan(Y/X)`

### `cordic.occ`:105Constant `CORDIC.CONST`

`VAL INT CORDIC.CONST`

Magic constant

### `disc2.occ`:30Process `fill.circle.diameter`

`PROC fill.circle.diameter (VAL INT x, y, d, VAL INT colour, [][]INT raster)`

Draws a solid circle. Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Coordinates of centre
`VAL INT` | `d` | Diameter
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `rectangle.occ`:32Process `fill.rectangle`

`PROC fill.rectangle (VAL INT x.0, y.0, w.0, h.0, VAL INT colour, [][]INT raster)`

Draws a solid rectangle.

Clips as necessary.

#### Parameters:

`VAL INT` | `x.0`, `y.0` | Top left corner
`VAL INT` | `w.0` | Width
`VAL INT` | `h.0` | Height/depth
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `rectangle.occ`:78Process `fill.square`

`PROC fill.square (VAL INT x, y, s, VAL INT colour, [][]INT raster)`

Draw a solid square.

### `arc.occ`:33Process `draw.arc`

`PROC draw.arc (VAL INT x.0, y.0, radius, VAL ANGLE t.0, t.1, VAL INT colour, [][]INT raster)`

Draws a circular arc.

#### Parameters:

`VAL INT` | `x.0`, `y.0` | Coordinates of centre
`VAL INT` | `radius` | Radius
`VAL ANGLE` | `t.0`, `t.1` | Range of `ANGLE`s
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `arc.occ`:39Process `arc`

`PROC arc (VAL ANGLE t.0, t.1)`

Basic PROC; `arc <= ANGLE.RIGHT`

#### Parameters:

`VAL ANGLE` | `t.0`, `t.1` | Range of `ANGLE`s

### `graphics.inc`:27Group `COLOUR`

``

Common colours

Assume coded as `#rrggbb`, which ain't necessarily so.

### `graphics.inc`:31Constant `COLOUR.BLACK`

`VAL INT COLOUR.BLACK`

### `graphics.inc`:32Constant `COLOUR.WHITE`

`VAL INT COLOUR.WHITE`

### `graphics.inc`:33Constant `COLOUR.RED`

`VAL INT COLOUR.RED`

### `graphics.inc`:34Constant `COLOUR.GREEN`

`VAL INT COLOUR.GREEN`

### `graphics.inc`:35Constant `COLOUR.BLUE`

`VAL INT COLOUR.BLUE`

### `graphics.inc`:36Constant `COLOUR.YELLOW`

`VAL INT COLOUR.YELLOW`

### `graphics.inc`:37Constant `COLOUR.CYAN`

`VAL INT COLOUR.CYAN`

### `graphics.inc`:38Constant `COLOUR.MAGENTA`

`VAL INT COLOUR.MAGENTA`

### `graphics.inc`:39Constant `COLOUR.GREY`

`VAL INT COLOUR.GREY`

### `graphics.inc`:40Constant `COLOUR.ORANGE`

`VAL INT COLOUR.ORANGE`

### `graphics.inc`:41Constant `COLOUR.PINK`

`VAL INT COLOUR.PINK`

### `graphics.inc`:42Constant `COLOUR.SKY`

`VAL INT COLOUR.SKY`

### `graphics.inc`:43Constant `COLOUR.MAROON`

`VAL INT COLOUR.MAROON`

### `graphics.inc`:44Constant `COLOUR.BROWN`

`VAL INT COLOUR.BROWN`

### `graphics.inc`:45Constant `COLOUR.NAVY`

`VAL INT COLOUR.NAVY`

### `graphics.inc`:46Constant `COLOUR.PURPLE`

`VAL INT COLOUR.PURPLE`

### `graphics.inc`:47Constant `COLOUR.VIOLET`

`VAL INT COLOUR.VIOLET`

### `graphics.inc`:49Constant `COLOUR.OCTARINE`

`VAL INT COLOUR.OCTARINE`

### `graphics.inc`:61Function `pack.colour`

`INT INLINE FUNCTION pack.colour (VAL BYTE r, g, b)`

Pack RGB `BYTEs` to an `INT`.

Assume coded as `#rrggbb`, which ain't necessarily so.

#### Parameters:

`VAL BYTE` | `r`, `g`, `b` | Primary colour components

#### Returns:

`INT` |  | `#rrggbb`

### `graphics.inc`:69Function `pack.colour.float`

`INT INLINE FUNCTION pack.colour.float (VAL REAL32 r, g, b)`

As `pack.colour`, but taking `REAL32` arguments.

#### Parameters:

`VAL REAL32` | `r`, `g`, `b` | Primary colour components in the range 0.0 to 1.0

#### Returns:

`INT` |  | `#rrggbb`

### `graphics.inc`:78Function `unpack.colour`

`BYTE, BYTE, BYTE INLINE FUNCTION unpack.colour (VAL INT c)`

Unpack an `INT` to RGB `BYTEs`.

#### Parameters:

`VAL INT` | `c` | `#rrggbb`

#### Returns:

`BYTE` | `r`, `g`, `b` | Primary colour components

### `graphics.inc`:82Group `PALETTE`

``

Codes for `permute` arguments.

### `graphics.inc`:86Constant `PALETTE.RGB`

`VAL INT PALETTE.RGB`

### `graphics.inc`:87Constant `PALETTE.BGR`

`VAL INT PALETTE.BGR`

### `graphics.inc`:88Constant `PALETTE.RBG`

`VAL INT PALETTE.RBG`

### `graphics.inc`:89Constant `PALETTE.BRG`

`VAL INT PALETTE.BRG`

### `graphics.inc`:90Constant `PALETTE.GRB`

`VAL INT PALETTE.GRB`

### `graphics.inc`:91Constant `PALETTE.GBR`

`VAL INT PALETTE.GBR`

### `lines.occ`:31Process `draw.horizontal.line`

`PROC draw.horizontal.line (VAL INT x, y, l, VAL INT colour, [][]INT raster)`

Draws a horizontal line.

Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Starting point
`VAL INT` | `l` | Length
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `lines.occ`:67Process `draw.vertical.line`

`PROC draw.vertical.line (VAL INT x, y, l, VAL INT colour, [][]INT raster)`

Draws a vertical line.

Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Starting point
`VAL INT` | `l` | Length
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `lines.occ`:104Process `draw.rectangle`

`PROC draw.rectangle (VAL INT x, y, w, h, VAL INT colour, [][]INT raster)`

Draws a rectangular box.

Clips as necessary.

#### Parameters:

`VAL INT` | `x`, `y` | Top left corner
`VAL INT` | `w` | Width
`VAL INT` | `h` | Height/depth
`VAL INT` | `colour` | Colour
`[][]INT` | `raster` | Raster

### `copy.occ`:41Process `copy.raster`

`PROC copy.raster (VAL [][]INT src, VAL INT x, y, c, f, [][]INT dst)`

Copy one raster onto another.

One corner of `src` always maps to `(x, y)` of `dst`.

Let the least significant three bits of `f` be abc:

- a = 1: flip about `\`, then
- b = 1: flip about `|`
- c = 1: flip about `-`

Hence

- f = 7: flip about `/`

#### Parameters:

`VAL [][]INT` | `src` | Source raster
`VAL INT` | `x`, `y` | Top left of target in `dst`
`VAL INT` | `c` | Transparent colour -- don't copy
`VAL INT` | `f` | Orientation
`[][]INT` | `dst` | Destination raster