Phase 4: The Frame Buffer — Draw First, Show Second

Where This Lesson Fits

In Phase 1, we drew pixels and text, then called show(). Phase 2 gave us bits and masks. In Phase 3, we found the exact byte and bit for a screen coordinate.

Now we can ask: if drawing changes those bytes, why doesn’t the physical screen change immediately?

Today’s goal is to track two things separately: the image being prepared in the Pico’s memory and the image currently held by the OLED controller.

Try Two Screens

A frame is one complete image. A frame buffer is memory holding the pixels of that image. Our program’s frame buffer lives in the Pico’s RAM, the working memory used while the program runs.

The OLED controller has its own display memory. Drawing in the Pico’s RAM does not automatically change that separate memory. show() sends the prepared bytes to the controller.

Try that separation on a small display first:

Q1: Can you change the picture without changing the display?

Problem: Draw a small pattern on the left. Press show(), then change one more pixel. Which picture changes at each step?

Q2: Does clearing RAM erase the visible picture?

Problem: Send a pattern with show(). Press fill(0): clear RAM. Predict what another press of show() will do, then try it.

Follow the Real Bytes

On our 128 × 64 OLED, the Pico’s frame buffer contains 1,024 bytes. The driver exposes that same storage as oled.buffer. Drawing methods change these bytes; they do not create a separate picture hidden elsewhere.

For the driver included in the Phase 1 kit, the path is:

Pico RAM                     OLED controller
┌──────────────────┐         ┌──────────────────┐
│ oled.buffer      │ show()  │ display memory   │
│ 1,024 image bytes│ ──────► │ drives the pixels│
└──────────────────┘  I²C    └──────────────────┘
  ↑ drawing changes this       keeps the last data sent

pixel(), text(), and fill() edit the frame buffer. text() turns character shapes into pixel changes in RAM; we will explore drawing shapes in Phase 5.

In this driver, show() sets the destination column and page ranges, then sends the whole buffer, even if only one pixel changed. It does not clear RAM afterward. The controller uses its own memory to keep driving the display between transfers; the Pico does not need to resend the picture continuously for it to remain visible while powered and configured normally.

The transfer takes time. Preparing a complete frame before sending it avoids deliberately sending each unfinished drawing stage, but it does not make the physical transfer instantaneous. We will examine the I²C bytes and the controller itself in later phases.

Try It on the Pico

Download the Phase 4 frame lab. Save it alongside ssd1306.py on the Pico using the wiring from Phase 1. Run it in Thonny, then use the Shell to press Enter at each checkpoint. No rewiring is needed.

The first two experiments are ready to run. Later TODOs are commented out until you reach their problems. If you do not have the hardware, use the toy and trace the code on paper.

For the snippets below, run the starter’s setup first so oled exists. Each experiment explicitly establishes its starting picture. input() pauses the program until you press Enter, giving you time to compare RAM with the screen.

Q3: Where is WAITING while the program waits?

Problem: Predict the display before and after pressing Enter:

oled.fill(0)
oled.show()
oled.text("WAITING", 0, 0)
input("Inspect the screen, then press Enter: ")
oled.show()

Q4: What does the buffer’s length tell us?

Problem: Predict len(oled.buffer) for our display. Explain why it is not the number of lit pixels.

Q5: Can a drawing method change the byte you calculated?

Problem: Complete Experiment 3 in the starter. Begin with a cleared buffer and blank display. Draw pixel (37, 29), inspect byte 421, pause, and finally display the pixel.

oled.fill(0)
oled.show()
oled.pixel(37, 29, 1)
print("Byte 421:", oled.buffer[421])
input("The screen is blank. Press Enter to show the pixel: ")
oled.show()

Q6: Does a raw buffer edit follow the same rule?

Problem: Replace oled.pixel(37, 29, 1) in Q5 with a raw byte edit that preserves neighboring bits. Will the timing change?

oled.buffer[421] |= 1 << 5

Keep Track of Two Images

Q7: What survives a clear?

Problem: Trace the buffer and screen at each pause:

oled.fill(0)
oled.text("OLD", 0, 0)
oled.show()
input("Pause A: ")
oled.fill(0)
input("Pause B: ")
oled.text("NEW", 0, 0)
input("Pause C: ")
oled.show()

Q8: Is show() a list of drawing commands?

Problem: Suppose you draw A, clear RAM, then draw B, all before calling show(). Will the screen play back A, a blank frame, and B?

Q9: Does show() consume the image?

Problem: After drawing and displaying a picture, call show() again without changing RAM. What appears? How many image bytes does each call send on our 128 × 64 display?

Assemble a Complete Frame

Drawing several things into RAM lets us decide when to send the result. For a static screen, we can clear the prepared image, add all its parts, then call show() once.

Q10: Can two lines arrive as one prepared frame?

Problem: Complete Experiment 4 in the starter: prepare READY at (0, 0) and PICO at (0, 16), then send the finished frame once. Avoid displaying a blank frame between the previous picture and this one.

oled.fill(0)
oled.text("READY", 0, 0)
oled.text("PICO", 0, 16)
oled.show()

Q11: Is one show() enough forever?

Problem: You display a picture, change one pixel in RAM, and want that change to appear. Do you need another show()? What if you make no changes at all?

Q12: Can you explain the whole journey?

Problem: Explain what happens from oled.text("HI", 0, 0) to seeing HI on the OLED. Include the two memory locations and the job of show().

Next: Drawing Graphics

We can now explain where a picture waits and when it reaches the OLED. In Phase 5, we will use pixels, lines, rectangles, and text to build complete scenes, then change those scenes over time.

Back to Phase 3: Memory Organization ← · Revisit Phase 1’s drawing experiments

Glossary