# Module `sdlraster` - SDL raster interface

SDL raster interface.

This module provides an SDL-based portable bitmap ("raster") display.

sdlraster uses the ring pattern. `RASTER` arrays cycle around a ring of processes. One of the processes is `raster.display` (or `raster.display.simple`), which generates fresh rasters on startup, and draws rasters it receives to the display before passing them around the ring again. The other processes in the ring can do whatever they like to the rasters before passing them on.

To shut down the ring, a raster of height zero is sent around the ring, replacing one of the existing rasters. Each process passes it on and then exits, aside from the process that sent it which just waits to receive it again before exiting. (You can use `raster.shutdown` to do this.)

To avoid races with multiple shutdown messages, only one process is permitted to initiate shutdown; that is, if you're using `raster.display.simple`, then you mustn't try to shut down the ring from any other process.

Programs that don't care about input events can use `raster.display.simple`, which simply shuts down the ring when the user closes the window. If you want to handle keyboard or mouse input, `raster.display` provides an extra channel which delivers SDL events as `RASTER.EVENT` structures; in that case, you must shut down the ring using `raster.shutdown` when you want to exit.

(This module also provides the old `SDLRaster` and `miniraster` interfaces for backwards compatibility, but you should not use them in new code.)

## Index

- Constant `EVENT.CHECK.TIME` - The time between event checks, in nanoseconds
- Constant `MAX.RASTERS` - The maximum number of initial rasters allowed in the ring
- Process `raster.clear` - Clear a raster to a solid colour
- Process `raster.convert.event` - Convert an into a
- Process `raster.display` - Raster display process
- Process `raster.display.simple` - Simple interface for programs that don't need to handle events
- Process `raster.shutdown` - Shut down a raster ring

## Declarations

### `sdlraster.occ`:65Constant `MAX.RASTERS`

`VAL INT MAX.RASTERS`

The maximum number of initial rasters allowed in the ring.

### `sdlraster.occ`:68Constant `EVENT.CHECK.TIME`

`VAL INT EVENT.CHECK.TIME`

The time between event checks, in nanoseconds.

### `sdlraster.occ`:74Process `raster.clear`

`PROC raster.clear (RASTER r, VAL INT colour)`

Clear a raster to a solid colour.

### `sdlraster.occ`:107Process `raster.convert.event`

`PROC raster.convert.event (SDL.Event event, RESULT RASTER.EVENT ev)`

Convert an `SDL.Event` into a `RASTER.EVENT`.

### `sdlraster.occ`:280Process `raster.display`

`PROC raster.display (VAL []BYTE title, VAL INT width, height, num.rasters, CHAN RASTER in?, out!, CHAN RASTER.EVENT events!)`

Raster display process. Generate a number of rasters on startup, and draw incoming rasters to the display. In addition, report any events received on the display.

This process provides `num.rasters + 1` places of buffering in the ring.

#### Parameters:

`VAL []BYTE` | `title` | Window title
`VAL INT` | `width` | Width of window
`VAL INT` | `height` | Height of window
`VAL INT` | `num.rasters` | Initial number of rasters to inject into the ring. This must be at least 1, and no more than `MAX.RASTERS`.
`CHAN RASTER` | `in` | Raster input
`CHAN RASTER` | `out` | Raster output
`CHAN RASTER.EVENT` | `events` | Input events. When it shuts down, the raster will send a `RASTER.ET.SHUTDOWN` event as its last message, so you know when to stop reading from this channel.

### `sdlraster.occ`:347Process `raster.shutdown`

`PROC raster.shutdown (CHAN RASTER in?, out!)`

Shut down a raster ring. You must have read a raster from the ring yourself before calling this. This outputs an empty raster, and then discards incoming rasters until the empty one's received again.

### `sdlraster.occ`:408Process `raster.display.simple`

`PROC raster.display.simple (VAL []BYTE title, VAL INT width, height, num.buffers, CHAN RASTER in?, out!)`

Simple interface for programs that don't need to handle events. This automatically shuts down the ring when the window is closed; otherwise it behaves like `raster.display`.