Files
VCCPlusOSS/docs/macos/GRAPHICS_CORE.md
T

5.9 KiB
Raw Blame History

Graphics and frame timing — Phase 1

Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.

Portable interfaces

  • VideoState holds borrowed emulated memory and a host-owned render surface. It contains no window handles. The Windows SystemState inherits these fields, preserving source access for existing callers; VideoHost.cpp forwards surface and clearing requests to the Windows implementation.

  • The Mac checks use a packed 640 × 480 surface of 32-bit 0x00RRGGBB pixels. Pitch is measured in pixels, not bytes. On the supported little-endian hosts the bytes are B, G, R, zero. The native display bridge treats these as opaque pixels rather than interpreting the zero byte as transparency. The renderer still retains upstream 8/16/24-bit entry points for Windows, but the Mac path and new pixel tests use 32-bit output only.

  • ApplyVideoRegister and ApplyTimerRegister connect machine-register writes directly to a selected GimeGpu. Tests now use the real graphics/timer implementation instead of recording those calls. External input, cartridge devices, audio delivery, cassette files, and printer output remain explicit test replacements.

  • RunFrame is a synchronous execution operation. It returns when a frame completes, the debugger halts, a cycle budget is reached, or the CPU makes no progress. The final instruction can exceed the requested budget. Budget-limited frames can resume; the function does not restart the raster, pace wall-clock time, lock a window, or flush audio. The Windows event-based frame loop uses it too, replacing a loop that could wait indefinitely after a breakpoint.

Only one scheduled GPU/machine may own the global scheduler and host bindings at a time. Install the machine, video and debugger hosts, initialize memory/CPU, reset the scheduler, and then reset/configure the GPU before execution. Keep the surface and borrowed memory alive during rendering. Call StopEvents before changing hosts, memory, or the scheduled GPU. GPU callbacks carry weak lifetime guards, so abandoned callbacks cannot dereference a destroyed renderer. StopEvents cancels all owned raster and timer tags, while leaving unrelated scheduler events alone. Immediate debugger preview GPUs do not own scheduled raster tags.

Seven added checks

Check Coverage
Pixel output Known red/green/blue/white values, nibble order, horizontal/vertical doubling, alternating black scanlines, and unsupported-width regression
Mode sweep 2,304 CoCo 3 / compatibility register combinations across every active row, framebuffer guards, and a separate composite PMODE4 artifact-path check
Raster timing Both CPUs complete 263-line frames; 912 clocks per line; four-line VSYNC pulse; subsequent frame period of 239,856 clocks
Full-frame pixels CPU-driven eight-bar RGB image, every active pixel checked independently, and top/bottom border placement
GIME timers Fast-clock restart delay, interrupt issue delay, overlapping delayed IRQs for short periods, zero-count stop, and scanline-clock countdown
Video lifecycle Reset replaces existing callbacks, stop cancels owned events, and destroyed renderer callbacks expire safely
Frame stops Breakpoint halt returns immediately, bounded work, partial-frame resume, and stalled-CPU detection

The synthetic BRA loop takes three CPU cycles per instruction. At 16 clocks per cycle, the first completed frame consumes 14,994 cycles because event boundaries are exclusive and execution finishes whole instructions; the following frame consumes 14,991 cycles. These checks preserve the retained source's timing model. They do not establish exact agreement with every GIME revision or a new Windows trace.

The mode sweep includes combinations whose derived width exceeds the supported framebuffer. Those layouts are deliberately skipped, rather than allowed to write into unrelated rows. The sweep establishes memory safety for the tested inputs; it is not visual parity evidence for every mode, palette, scroll, or mid-line register transition.

Corrections and validation

Graphics operations now use their own GPU instance rather than accidentally calling the global Windows renderer. Raster update bookkeeping is initialized and cleared on reset; display geometry is established before the first sync event. Timer clock selection lives in the GPU, reset/stop cancels its scheduled work, and switching away from the fast timer cancels its remaining retrigger event. Multiple delayed IRQs are preserved when the timer period is shorter than the issue delay.

AddressSanitizer found an existing framebuffer overflow: a 1-bpp/128-byte row derived 1,024 pixels, causing the unsigned stretch factor to underflow and a border write to land past the framebuffer. Unsupported oversized layouts now leave the surface untouched, and duplicated border-row writes are bounded. A targeted regression check accompanies the broader sweep.

The full RGB color-bar frame was also exported outside the repository and visually inspected. It is generated entirely from authored RAM contents and the retained renderer; no ROM file, screenshot, binary, or user media was added to Git. See the build guide for current validation results.

Subsequent integration and open qualification

The Mac controller, native boot, audio/cassette, input and selected cartridge/storage devices now use this renderer. The native Metal display presents the active picture at 4:3 with the selected scaling/filtering; the core framebuffer contract above remains unchanged. Physical Intel/macOS 14, broader guest video modes, Windows recompilation/reference comparison and the wider representation audit remain open in the porting plan.