software renderer: support aligned dirty regions

[okhsunrog]

Some display controllers cannot program arbitrary GRAM address windows: the CO5300, SH8601A, RM67162, and RM690B0 require both the start coordinate and the extent of the address window to be even on each axis, and packed display transports can impose other granularities (e.g. an eight-pixel horizontal grid for byte-addressed e-paper). A platform adapter cannot fix this up by rounding the PhysicalRegion returned after rendering — pixels added by that rounding are not guaranteed to have been repainted and may contain stale framebuffer contents, particularly with reused or swapped buffers. The renderer itself has to expand the damage before drawing and return a matching physical region. This PR adds an opt-in per-axis alignment grid to the software renderer; the default of 1×1 keeps the existing behavior. Screen dimensions must be multiples of the configured alignment (checked with a debug_assert).

• Add DirtyRegionAlignment and SoftwareRenderer::set_dirty_region_alignment() / dirty_region_alignment() to the Rust API
• Expand the logical dirty region before partial rendering so the pixels added by alignment are actually repainted, in both the render() and render_by_line() paths
• Snap the resulting physical region to the grid in panel coordinates, i.e. after RenderingRotation, so rotated screens align on the panel's native axes
• Expose the setting in the C++ platform API as SoftwareRenderer::set_dirty_region_alignment(horizontal, vertical)
• Fix PhysicalRegion::count including rectangles that were entirely clipped out by the screen bounds — such regions previously reported empty boxes; this fix applies with the default alignment too
• Add unit tests for grid snapping, rotated panel axes, and the clipped-rectangle count fix, plus a regression test that renders with garbage-initialized buffers and verifies the expanded pixels in line-buffer, reused-buffer, and swapped-buffers modes

Verified on physical hardware with a CO5300-driven Waveshare ESP32-S3-Touch-AMOLED-2.16 (480×480 AMOLED, QSPI, RGB565 partial uploads from a PSRAM framebuffer) using a 2×2 alignment: https://github.com/okhsunrog/waveshare-esp32s3-amoled-2-16. Both the full-frame and aligned partial-frame upload paths render correctly on the panel.

[okhsunrog]

@tronical @ogoffart what do you think about this one? I can change the API if you have other preferences

[tronical]

I wonder if this should be a function of TargetPixelBuffer (experimental right now). Somehow this doesn't feel like a renderer specific attribute but more of the target buffer we're rendering to (as used by the scanout that has these requirements).

Cool that you're tracking this down, btw :)

[okhsunrog]

I wonder if this should be a function of TargetPixelBuffer (experimental right now). Somehow this doesn't feel like a renderer specific attribute but more of the target buffer we're rendering to (as used by the scanout that has these requirements).

I'm not sure, what about render_by_line? It's needed by many MCUs

[ogoffart]

Thanks for this PR
Thisis indeed something that's needed. especially for monochrome screen that byte 8 pixels into one byte.
And this is indeed very useful with the line by line renderer as well.

An alternative API could be to add an extension point to the traits TargetPixelBuffer and LineBufferProvider

For example

trait TargetPixelBuffer /*or LineBufferProvider*/ {
  // ... existing stuff ...

  fn adjust_dirty_region(&self, region: PhysicalRegion) -> PhysicalRegion {
      region                                                             
  }
}

But maybe that's overengineering it?

[ogoffart]

pre-existing: I wonder if the duplicated code between render and prepare_scene could be simplified.