02. Display and Drawing

The display has three useful layers.

Which Layer Should I Use?

Use grid.* when you want the smallest teaching surface:

  • grid.clear
  • grid.set
  • grid.get
  • grid.toggle
  • grid.rect
  • grid.fill
  • grid.show

Use matrix.* when you want named drawing operations:

  • matrix.pixel!
  • matrix.line
  • matrix.rect
  • matrix.fillRect
  • matrix.show

Use tm1629.* when you want the more advanced display helpers such as staged next-frame updates, procedural filling, sprite blits, or the built-in Life stepper.

For first experiments, stay with grid and matrix.

Light Pixels And Draw A Line

matrix.init:
grid.clear:
grid.set: 0, 0, true
grid.set: 11, 7, true
matrix.line: 0, 0, 11, 7, true
grid.show:

That shows the usual drawing pattern:

  • draw into the framebuffer first
  • then show the framebuffer

If you forget the final show, the display does not change yet.

Draw Rectangles

matrix.init:
grid.clear:
matrix.rect: 0, 0, 12, 8, true
matrix.fillRect: 2, 2, 3, 2, true
grid.show:

This is enough for borders, paddles, simple HUD blocks, and board-sized sprites.

Fill The Screen Procedurally

When you want to compute each pixel rather than set them one by one, use tm1629.populate:

matrix.init:
tm1629.populate: fn with x, y [ ((x + y) % 2) == 1 ]
grid.show:

The painter function receives x and y and returns a boolean for that pixel.

That is a useful shape for:

  • checkerboards
  • procedural patterns
  • simple terrain
  • debugging coordinate logic

Sprite-Like Thinking

Once you start thinking in rows or reusable shapes, the advanced tm1629.* layer becomes useful. The two most important ideas are:

  • the current framebuffer
  • the next framebuffer

The next-frame helpers are for animation that should update in one visible step instead of drawing live into the current buffer pixel by pixel.

The pattern looks like this:

tm1629.nextClear:
tm1629.nextPixel!: 2, 3, true
tm1629.nextPixel!: 3, 3, true
tm1629.commitNext:
grid.show:

You do not need this layer for every sketch. Reach for it when you want more control over animation or whole-frame updates.

A Useful Mental Model

If your idea sounds like:

  • “light this pixel”
  • “draw this line”
  • “draw this box”

stay at grid.* or matrix.*.

If your idea sounds like:

  • “build the next frame”
  • “fill the display from a rule”
  • “step a simulation”

start looking at tm1629.*.

Next: Inputs and controls .