Directly addressing pixels in PICO-8

During a discussion at the virtual Galway 1GAM meetup August Darren from Mind Cauldron was wondering how to address individual pixels using peek and poke in the PICO-8 fantasy console video display. PICO-8 reserves a virtual address space of 32768 bytes to store state and graphics information.

If we take a look at the PICO-8 memory map we can see that the video memory is mapped as from addresses 0x6000-0x7fff (24576-32767 in decimal), or the last 16KiB of memory. This area of memory is mapped to a 128x128 grid at 4-bits per pixel (AKA a Bitmap), that means we have up to 16 colours numbered 0-15. We can address two pixels directly using the poke() function in PICO-8 to write bytes to memory, but how do we then address individual pixels in the bitmap?

We need to use a technique called bitshifting to address the pixels individually. To shift bits in PICO-8 we use the << and >> operators or we can also use the Shl and Shr functions. It should be noted the Shl and Shr functions were deprecated in PICO-8  v0.2.0, so we should favour the use of << and >> for shift-left and shift-right in our code. We need to be able to address the high and low nibble of each byte in the bitmap. In the PICO-8 bitmap the low nibble corresponds to the left pixel, the high nibble the the right pixel.

Here's some example code that sets the top left two pixels to red and blue:

-- clear the screen to black
cls(0)

-- 4-bit value for the left pixel
left_pixel=8 -- red
-- 4-bit value for the right pixel
right_pixel=12 -- blue
-- combine the 4-bit values into
-- one 8-bit value using bitshift
pixels=(right_pixel<<4) + left_pixel
-- plot the top left two pixels
poke(0x6000,pixels)
	
-- hit the z key to exit --
repeat
  flip()
until btnp(4)