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

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:283Process 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:354Process 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:415Process 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.