Skip to content

feat(graphics): add double buffering with dirty region tracking#97

Merged
ryanbreen merged 4 commits intomainfrom
feature/graphics-stack
Jan 16, 2026
Merged

feat(graphics): add double buffering with dirty region tracking#97
ryanbreen merged 4 commits intomainfrom
feature/graphics-stack

Conversation

@ryanbreen
Copy link
Owner

@ryanbreen ryanbreen commented Jan 16, 2026

Summary

Implements Phase 1 and Phase 2 of the graphics stack for tear-free shell rendering:

  • Double buffering: Shadow buffer in heap memory mirrors hardware framebuffer. All rendering happens to shadow buffer, then flush() copies to hardware.
  • Dirty region tracking: Only modified regions are flushed to hardware, reducing memory bandwidth. Partial flush optimization copies just the dirty scanline segments.
  • Scroll optimization: scroll_hardware_up() shifts hardware buffer directly for efficient scrolling.
  • Two-phase initialization: Direct mode during early boot (before heap), upgrades to double buffering after heap init.

Test plan

  • Build passes with zero warnings (both interactive and testing features)
  • Boot-stages test: 226/226 stages passed
  • 12 unit tests covering:
    • DirtyRegion state management (4 tests)
    • DoubleBufferedFrameBuffer state (3 tests)
    • Actual byte copy verification (2 tests)
    • Partial flush optimization proof (1 test)
    • Coordinate interpretation regression guard (1 test)
    • Scroll operation (1 test)
  • Technical validation: APPROVED (A/A scores)

Changes

File Changes
kernel/src/graphics/mod.rs New graphics module
kernel/src/graphics/double_buffer.rs DirtyRegion + DoubleBufferedFrameBuffer + 12 tests
kernel/src/logger.rs Integration with ShellFrameBuffer
kernel/src/lib.rs Conditional graphics module export
kernel/src/main.rs Call to upgrade_to_double_buffer after heap init

🤖 Generated with Claude Code

ryanbreen and others added 4 commits January 16, 2026 06:22
@ryanbreen @claude
feat(graphics): add double buffering for tear-free shell rendering
b79ea6f 
Implement Phase 1 of the graphics stack roadmap with double buffering
support for the interactive shell framebuffer.

Architecture:
- DoubleBufferedFrameBuffer: heap-allocated shadow buffer with flush()
- ShellFrameBuffer: Option<DoubleBufferedFrameBuffer> for lazy upgrade
- Direct writes during early boot (before heap), double-buffered after

Key features:
- Shadow buffer allocated after heap init via upgrade_to_double_buffer()
- Batched writes with dirty tracking for efficient flushing
- Safe slice operations for shadow buffer, unsafe only for hardware copy
- Zero warnings, no #[allow(dead_code)] annotations

Files:
- kernel/src/graphics/mod.rs - new graphics module
- kernel/src/graphics/double_buffer.rs - DoubleBufferedFrameBuffer impl
- kernel/src/logger.rs - ShellFrameBuffer with optional double buffering
- kernel/src/main.rs - upgrade call after memory::init()

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ryanbreen @claude
feat(graphics): add dirty region tracking for partial framebuffer flush
b3da906 
Phase 2 of graphics stack: Enhanced framebuffer features

- Add DirtyRegion struct for tracking modified rectangular areas
- Implement partial flush that only copies dirty scanline regions
- Add scroll_hardware_up for optimized scroll operations
- Track modifications at pixel granularity in write_pixel
- Reduce memory bandwidth by avoiding full buffer copies

Performance improvement: Only flushing changed regions instead of
the entire framebuffer (4MB at 1080p) on every character write.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ryanbreen @claude
fix(graphics): correct dirty region coordinate handling and add tests
c4ef0a2 
Fixes issues identified by technical validation:

1. Fix coordinate bug in write_pixel dirty region marking:
   - Changed from absolute buffer offset to within-scanline byte offset
   - mark_region_dirty now receives x_byte_offset (x * bytes_per_pixel)
     instead of byte_offset (which included row offset)

2. Add unit tests for DirtyRegion:
   - dirty_region_new_is_empty: verifies new() creates empty region
   - dirty_region_mark_expands: verifies mark_dirty sets correct bounds
   - dirty_region_mark_unions: verifies multiple marks union correctly
   - dirty_region_clear_resets: verifies clear() resets to empty

3. Add unit tests for DoubleBufferedFrameBuffer:
   - double_buffer_new_not_dirty: verifies initial state
   - double_buffer_mark_region_sets_dirty: verifies marking works
   - double_buffer_flush_clears_dirty: verifies flush resets state

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ryanbreen @claude
test(graphics): add comprehensive tests for partial flush optimization
00a7971 
Adds 5 tests to verify the core dirty region tracking behavior:

1. double_buffer_flush_copies_dirty_bytes
   - Verifies flush() actually copies bytes from shadow to hardware

2. double_buffer_flush_only_copies_dirty_region
   - Verifies non-dirty regions are NOT touched (partial flush works)

3. double_buffer_flush_full_copies_everything
   - Verifies flush_full() copies entire buffer regardless of dirty state

4. double_buffer_coordinate_interpretation
   - Guards against regression of x_byte_offset bug
   - Verifies x coordinates are within-row offsets, not absolute

5. double_buffer_scroll_hardware_up
   - Tests hardware buffer scroll operation

These tests address validation feedback that the previous tests only
verified state management but not the actual optimization behavior.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ryanbreen ryanbreen merged commit a09ae65 into main Jan 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ryanbreen