A damage region marks where to redraw after paint items change.
dotnet add package RecursiveAI.OneRender.ImageRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using OneRender.Painting; var previous = new DisplayList(); var next = new DisplayList(); var id = ItemId.Of(1, 1, 0); var red = new PaintColor(1, 0, 0, 1); previous.FillRect(id, new RectF(10, 10, 20, 20), red); next.FillRect(id, new RectF(20, 10, 20, 20), red); var damage = new DamageRegion(); DisplayList.ComputeDamage(previous, next, damage); Console.WriteLine(damage.Bounds);
RectF { X = 10, Y = 10, Width = 30, Height = 20, Right = 40, Bottom = 30, IsEmpty = False }Unzip the example, then dotnet run.
Full program
using OneRender.Painting; var previous = new DisplayList(); var next = new DisplayList(); var id = ItemId.Of(1, 1, 0); var red = new PaintColor(1, 0, 0, 1); previous.FillRect(id, new RectF(10, 10, 20, 20), red); next.FillRect(id, new RectF(20, 10, 20, 20), red); var damage = new DamageRegion(); DisplayList.ComputeDamage(previous, next, damage); Console.WriteLine(damage.Bounds); var before = OneRender.Image.DisplayListRasterizer.Render(previous, 64, 48); var after = OneRender.Image.DisplayListRasterizer.Render(next, 64, 48); int changed = 0; for (int y = 0; y < 48; y++) for (int x = 0; x < 64; x++) { int offset = (y * 64 + x) * 4; if (before.Pixels.AsSpan(offset, 4).SequenceEqual(after.Pixels.AsSpan(offset, 4))) continue; changed++; var bounds = damage.Bounds; if (x < bounds.X || x >= bounds.Right || y < bounds.Y || y >= bounds.Bottom) throw new InvalidOperationException("Changed pixel outside damage"); } Console.WriteLine($"Changed pixels inside damage: {changed}");
RectF { X = 10, Y = 10, Width = 30, Height = 20, Right = 40, Bottom = 30, IsEmpty = False } Changed pixels inside damage: 400
The full program also rasterizes both frames and checks the changed pixels against the damage bounds. Duplicate or zero item IDs throw DisplayListException.
Variations
Keep a retained frame pair. After defining id and red, commit the same rectangle twice:
var retained = new RetainedDisplayList(); retained.Begin().FillRect(id, new RectF(10, 10, 20, 20), red); retained.Commit(); retained.ClearDamage(); retained.Begin().FillRect(id, new RectF(10, 10, 20, 20), red); retained.Commit(); Console.WriteLine($"Unchanged frame: {retained.Damage.IsEmpty}");
Unchanged frame: TrueRelated recipes
Change page text · Render an animation frame
The short answer
Build the previous and next DisplayList with stable item IDs, then call DisplayList.ComputeDamage(previous, next, damage). The resulting DamageRegion describes changed areas in root-space CSS pixels. If one rectangle moves, both its old position and its new position need repainting.
The full program rasterizes the two lists and checks that every changed pixel is inside the reported bounds. The input is one red rectangle moved horizontally, not an HTML layout change. This isolates the bookkeeping a rendering host needs between frames.
How do dirty rectangles work?
A dirty rectangle marks a part of a surface that needs drawing again. For OneRender, the display-list damage rules compare paint items, not screenshots. Items match by ID. A matched item is unchanged only when its kind, content hash, context hash and root bounds all match.
A moved or edited item contributes its old and new bounds. A removed item contributes its old bounds; an added item contributes its new bounds. The old location matters because painting only the new location would leave the previous pixels on the surface.
Damage is conservative: it includes all differing pixels, but it is not a mask identifying only those pixels. In the example, the two overlapping rectangles merge into a larger bound. Some pixels inside it remain identical. That is expected, and a host must be willing to redraw them.
How do I calculate the bounds of a dirty rectangle?
Use the list’s root bounds through ComputeDamage, rather than manually comparing each item’s local rectangle. Enclosing transforms, clips and groups are included in the context hash. Moving or fading a group therefore affects the items inside it even if their own paint content is unchanged.
Stable IDs are essential. Reuse an item’s ID when repainting the same logical item, and keep IDs unique within a list. The numbers do not encode paint order. If kept items change their relative order, damage must also account for pixels whose overlap changes. Assigning fresh IDs on every frame obscures the distinction between an unchanged item and an item that was removed and added.
The region holds separate rectangles until overlaps or touching edges cause merges. It keeps up to 16 rectangles; another disjoint rectangle collapses them into one bounding rectangle. Bounds is the envelope of the whole region, not necessarily the smallest set of dirty pixels. ToDevicePixels(dpr) rounds that envelope outward to whole device pixels for a device-pixel scissor.
How do I redraw only a changed region?
Keep a persistent surface, clear the dirty area to its background, and redraw every item touching it in paint order, clipped to that area. Do not draw only the item that triggered the change: unchanged foreground and background items may overlap the same region.
The image backend’s DisplayListRasterizer.RenderRegion follows that rule. A host using another backend must implement the corresponding clipping and clearing. The region is repaint accounting, not a renderer on its own.
RetainedDisplayList manages the two-frame lifecycle. Paint into Begin(), call Commit(), repaint its accumulated Damage, then call ClearDamage(). The first commit damages everything. Until the host clears it, later commits add to the region, which lets a host combine several changes before drawing. The variation shows that a second identical frame contributes no new damage after the first frame’s damage is cleared.