dusk/.claude/display-refactor-progress.md

Display Refactor Progress

Immediate Goal

Render a 32x32 white square through the new render opcode stack on Linux.

Architecture (summary)

See .claude/display-refactor.md for the full design.

• src/dusk/render/ -- opcode format + buffer + submission API (the contract).
• Platform backends (e.g. src/duskgl/) consume the buffer and translate to native API calls.
• src/dusk/display/ -- orchestration shell only: displayInit, displayUpdate, displayDispose.
• Scenes call renderSprite(...), renderClear(...). The backend executes the intent.

Opcode format (32 bytes)

Every command starts with a 4-byte ropheader_t (opcode, flags, depth). Two commands defined:

• ROP_CLEAR (32 bytes) -- clear with a color.
• ROP_DRAW_SPRITE (32 bytes) -- screen-space int16 x/y/w/h + tint color.

Milestone 1 -- Archive + strip existing display deps ✓

• Old src/dusk/display/ archived (now deleted from working tree via git).
• Old src/duskgl/display/ removed (new GL renderer replaces it).
• engine.c stripped to minimal subsystems, set to SCENE_TYPE_TEST.
• scene.c stripped of old display/shader/screen references.
• console.c stripped of display deps.
• ui/CMakeLists.txt gutted (re-implementation deferred).
• asset/loader/CMakeLists.txt -- display loaders disabled.
• asset/loader/assetloader.h -- display loader types removed.
• rpg/overworld/chunk.h -- mesh_t / meshvertex_t removed.
• rpg/overworld/map.c -- mesh/spritebatch calls removed.
• scene/overworld/sceneoverworld.c -- stubbed to empty callbacks.
• Test suite display tests disabled.

Milestone 2 -- Render opcode system ✓

• src/dusk/render/rop.h -- ropheader_t, ropclear_t, ropsprite_t.
• src/dusk/render/ropbuffer.h/.c -- ROPBUFFER global, reset, alloc.
• src/dusk/render/render.h/.c -- renderClear(), renderSprite().
• src/dusk/render/CMakeLists.txt.

Milestone 3 -- New minimal display shell ✓

• src/dusk/display/display.h/.c -- init/update/dispose, calls platform hooks.
• src/dusk/display/displaystate.h -- cull/depth/blend flags.
• src/dusk/display/color.csv + CMakeLists.txt -- color generation kept.

Milestone 4 -- GL backend ✓

• src/duskgl/render/rendergl.h/.c:
  • GL 3.3 core shader (ortho projection, solid color, no texture yet).
  • renderGLInit -- creates VAO/VBO/shader.
  • renderGLFlush(buf, w, h) -- walks ROPBUFFER, GL calls per opcode.
  • ROP_CLEAR → glClearColor + glClear.
  • ROP_DRAW_SPRITE → 6-vertex quad, glDrawArrays.
• src/duskgl/error/errorgl.h/.c -- errorGLCheck.
• src/duskgl/CMakeLists.txt.
• src/dusksdl2/display/displaysdl2.h/.c updated:
  • displaySDL2Init -- SDL2 window + GL 3.3 context + renderGLInit.
  • displaySDL2Flush(ropbuffer_t *) -- MakeCurrent + renderGLFlush.
  • displaySDL2Swap -- SDL_GL_SwapWindow.
• src/dusklinux/display/displayplatform.h updated with new macros.

Milestone 5 -- Test scene ✓

• SCENE_TYPE_TEST added to scenetype.h/.c.
• src/dusk/scene/test/scenetest.h/.c:
  • renderClear(color(32, 32, 48, 255)) -- dark blue-grey background.
  • renderSprite(100, 100, 32, 32, COLOR_WHITE) -- 32x32 white square.
• engine.c starts with SCENE_TYPE_TEST.

Milestone 6 -- Verified ✓

• Build succeeds with no errors (2026-06-18).
• Engine initializes: SDL window + GL context + shader + test scene.
• No crashes running for 5+ seconds.
• 32x32 white square visually confirmed on screen.

---

Status: BUILD PASSING -- awaiting visual confirmation

---

Decisions log

2026-06-18 -- color_t = color4b_t (from generated display/color.h). The color generation pipeline (color.csv + Python tool) is kept in the new minimal src/dusk/display/CMakeLists.txt.

2026-06-18 -- ROP_SIZE = 32. All opcodes fixed 32 bytes. 3D quads will be 64 bytes when added later.

2026-06-18 -- Depth sort deferred. Buffer stores unsorted commands; painter platforms sort on flush. GL uses Z-buffer.

2026-06-18 -- Texture system not yet wired into the opcode pipeline. ROP_DRAW_SPRITE with texture=0 uses solid tint color only (no sampler). Texture handle system comes next.

2026-06-18 -- GL backend uses GL 3.3 Core profile. Shader takes screen-space pixel coordinates and converts to clip space using window size queried from SDL each frame.

2026-06-18 -- ROPBUFFER is a global (4096 slots × 32 bytes = 128 KB). Reset at start of each frame in displayUpdate.

2026-06-18 -- ui/, rpg/overworld display code, asset display loaders all temporarily stubbed/disabled. Will be rewritten against the new render API.