Porting Rust Embedded Graphics: Qualify Pixel Mapping Before Optimizing the Driver

A custom embedded-graphics display port needs a correct coordinate-to-color contract before it needs a fast transfer loop. A driver can draw a centered rectangle convincingly while corrupting clipped images or rejecting harmless off-screen pixels. Qualify those cases deliberately before treating a working demo as a reusable DrawTarget implementation.

This guide uses embedded-graphics 0.8.2 and its documented DrawTarget contract. The patterns and test procedure are proposed, not results from a particular panel or Rust build. Controller commands, bus transactions and electrical initialization still need their own driver-specific verification.

Establish the baseline pixel path

The DrawTarget reference requires draw_iter and Dimensions. Individual pixels can arrive in an arbitrary order. Coordinates outside the target must be discarded without an error or panic. A driver should therefore avoid assuming that every primitive arrives as one contiguous rectangle.

For a hypothetical small target, submit a deliberately scrambled list of distinct visible pixels, mixed with points beyond each boundary. The expected image contains only the visible points at their stated coordinates. This pattern separates address sequencing assumptions from basic color encoding. A uniform fill would hide many of those mistakes.

Keep the test target small enough to inspect every pixel. Include the origin, final valid row and column, and negative coordinates. These are proposed input cases, not permission to send invalid controller addresses: clipping belongs before translating a point into a hardware address.

Preserve the original color stream when clipping

The same trait's contiguous-fill contract pairs colors with the original area's row-first coordinate sequence. Clipping changes which pairs are visible; it must not shift the color stream onto a smaller rectangle. A color iterator that ends early is also a supported case rather than a reason to invent additional colors.

Consider a hypothetical three-column image whose leftmost column lies outside the display. Give each source position a different identifiable color. The first visible target column should receive the second source column, not the first color yielded by the iterator. Intersecting the rectangle first and then consuming colors from its beginning loses that relationship.

Design the test across both horizontal and vertical clipping. A top-edge case catches omitted source rows, while a left-edge case catches per-row offsets. Check the lower-right corner separately so an optimized transfer does not write beyond the accepted window after the visible portion ends.

Compare an accelerated path with a simple reference

Only after the baseline is correct should the port override bulk operations for controller-assisted fills or larger transfers. Preserve a simple reference implementation in the qualification harness and compare the resulting pixel maps for the same inputs. The reference is an engineering test choice, not a claim that a slower implementation is always deployable on the target.

Use nonuniform images for contiguous fills and repeated solid-color regions for the solid-fill path. Include fully invisible areas and short color sequences. A performance improvement is acceptable only when it preserves the supported rendering result and error behavior. Transfer speed alone cannot reveal a shifted row or a dropped edge pixel.

Distinguish drawing success from display communication

The rendering abstraction does not prove that a buffered driver's drawing call has transmitted pixels. For a concrete example, ssd1306 0.10.0 BufferedGraphicsMode draws into system-memory pixel storage and exposes a separate flush operation to update the display.

Define two observations when the selected port buffers output: the expected buffer contents after drawing, and the expected panel update after the driver's transfer step. Investigate a correct buffer with an unchanged panel at the transfer boundary rather than rewriting clipping code. Conversely, a successful bus transaction does not rescue an already incorrect pixel map.

Complete the port review with the tested dimensions, coordinate cases, color patterns and selected implementation paths. Actual hardware qualification should additionally cover controller addressing and transfer failures. Keeping these boundaries visible makes the driver reusable across scenes instead of merely reliable for the first centered demo.