Emulated hardware is managed by writing to memory-mapped ports beginning at address $ff80.

const SIbaseAddress=0xff80, SIrefreshOff=0, SIrefreshOn=1, SIgraphicsMode=2, SIkeyInterface=3;

SIrefreshOff             Write <any> to force OFF register refresh and display animation
SIrefreshOn              Write <any> to re-enable register refresh and display animation
SIgraphicsMode           Write <number of colours> to select graphics mode (2, 4, 16 allowed values)
SIkeyInterface           Write 0 then read an ASCII code (if<128), write 255 to clear the keyboard buffer

This is a simple way of switching on or off the “Refresh” checkbox from within a running program. For example, it might be a good idea not to have animation during an intensive routine such as clearing the screen. Simply write any value to SIbaseAddress+SIrefreshOff to turn Refresh off, or to SIbaseAddress+SIrefreshOn to turn it on again.

init:
  clr SIbaseAddress+SIrefreshOff
  jsr ClrScrr
  clr SIbaseAddress+SIrefreshOn
  

There are three bitmap graphics modes, differing by the resolution and colours available.

2 colours, 1 bit per pixel
4 colours, 2 bits per pixel
16 colours, 4 bits per pixel

To select a mode, simply write the number of colours to SIbaseAddress+SIgraphicsMode

Select16colmode:
  lda #16
  sta SIbaseAddress+SIgraphicsMode
  

Now all writes to the graphics display area will be interpreted in this mode. Note that to save time this does NOT effect anything already on the display until the memory is read or written. So you may need to clear the screen after selecting the mode.

In all modes the graphics RAM beings at $0600 and is 6K bytes long. In 2 colour mode it is 256 pixels wide by 192 pixels high. It is conventional to map the display with the top-left at (0,0) and the bottom right at (255,191) using the same virtual coordinates whatever the colour mode. Therefore in 4-colour mode pixels are 2*1 units in size, and in 15-colour mode 2*2 units.

Using 2-colour mode as an example, memory layout is from screen left to right, then top to bottom. So pixels (0,0) to (7,0) are stored in the byte at offset 0. The most significant bit in the byte represents the leftmost pixel. To represent a row of 256 pixels takes 32 bytes. So we add 32 bytes to the base address for each row moved down, thus pixel (0,1) is stored in the byte at offset 32.

The 4-colour mode needs 2 bits for each pixel, thus to store pixels of colours of successively 0, 1, 2, 3 at coordinates (0,0), (2,0), (4,0), (6,0)

const grxBase=$0600, grxSize=$1800, gLineBytes2=$20, , gLineBytes4=$20, gLineBytes16=$40