The gallery contract — Parallax Sketchbook

SKETCHBOOK / 01 The Living Gallery · 2-week chapter

Page 1 of 4: The Living Gallery begins with owners

Architecture / boundaries

The Living Gallery begins with owners

Build a small application that can prepare several image studies, replace a selected study, and shut down predictably. Its central problem is not a universal engine architecture. It is keeping scene data, work, results, and presentation alive for exactly the operations that use them.

Draw the owners first: application state owns the current asset revision; an accepted job owns its input payload; a result owns its produced value. Views are temporary access paths, not a second ownership system. Shared ownership is justified when independent operations genuinely need the same lifetime, not simply because a pointer is inconvenient.

Begin with the checksum batch, then build the supplied asynchronous image pipeline. Its workers prepare owned gradient images, and Gallery publishes the current generation while retaining a prior image on failure. The terminal driver saves a real PPM image. The separate Asio experiment teaches coroutine suspension; the PMR experiment renders tile samples. A window, file decoder, cache, and GPU backend remain distinct integrations.

TRY IT IN YOUR STUDIO

Draw application, asset, job, result, and display boxes. Label every edge owns, borrows, or identifies by value.

From the page to your own work

Your studio assignment.

Define a finishable Living Gallery with explicit data and work boundaries.

A finish line you can see

An ownership diagram, a bounded work API, and tests for rejected and failed work.

Name a single owner for every mutable resource.
Distinguish caller allocation from accepted-batch bounds.
Check invalid jobs before dispatch.
State which reference pieces are supplied and which application pieces are yours.

Keep the evidence in your weekly notebook ↗

Explain it like an engineer

Try answering aloud before opening the review notes. Use your own implementation as evidence.

Why does RAII not make every async capture safe?

Cleanup follows owner lifetime, while a worker may still borrow that owner.
Join or otherwise establish completion before destruction.
A view and a shared pointer express different contracts.

These prompts support practice; they are not an automatic assessment of your work.

A tip for this exercise

Choose one small owned preparation operation before designing the gallery architecture. Draw its payload, result, and current asset as separate owners, then mark every temporary view and the point where work finishes.

Hints, when you need them.

Try a first step, then reveal as much help as you need. Each hint gets a little more specific.

1Hint 1 · Find a starting point

Walk each arrow in the owner diagram and ask what happens if the caller returns early. Identify the completion boundary that keeps every worker borrow valid.

2Hint 2 · Choose an approach

Write accepted job and payload limits before dispatch. Distinguish validation errors from failed job results, and remember that constructing a caller-owned vector may allocate before the batch can validate it.

3Hint 3 · Check your reasoning

Exercise the companion with exactly 32 jobs and then 33. The latter must be rejected before dispatch; separately inject one job failure and record its result without treating a partial batch as a published asset.

A small creative variation ↗

Replace checksum samples with a small owned image-operation description in your own branch, keeping the same batch limits.

Optional. Save it for later if this chapter already feels full.

Coming back after a break? ↩

Run one successful job and draw its input and result owners before changing the interface.

Books & principles behind this study +

Original Parallax explanations and assignments, with these works for further reading.

YOUR MARGIN NOTES

Leave yourself a good question.

What changed your mind? What would you try next?

Notes for The gallery contract

Notes are private to this browser and saved as you write.

A CHECKPOINT, NOT A SCORE

Can you explain the idea and try the exercise yourself?

Completion records your own assessment. It does not compile or test your C++.

Companion source 14 files