Raxol.UI.Rendering.DamageTracker (Raxol v2.6.0)

View Source

Tracks damaged/dirty regions in the UI tree to optimize rendering. Only re-renders areas that have actually changed, reducing unnecessary work.

Damage Types

  • :content - Text or visual content changed
  • :layout - Size or position changed
  • :style - Visual styling changed
  • :structure - Child nodes added/removed/reordered

Path representation

Paths stored in the damage_map keys and in each region.path are reversed: the leaf index is at the head of the list and the root step is at the tail. A forward path [0, 1, 2] (root -> child 0 -> grandchild 1 -> great-grandchild 2) appears here as [2, 1, 0].

This lets path construction stay O(1) per step ([idx | rev_path] prepend) and lets get_node_at_rev_path/2 walk without an extra reversal. Consumers that need a forward path can call Enum.reverse/1; compute_damage/2 accepts forward-ordered input paths from callers and reverses them once on entry.

Summary

Types

damage_map()
damage_region()
damage_type()

Functions

compute_damage(arg1, tree)

Computes damaged regions from a tree diff result. Returns a map of path -> damage_region for efficient lookups.

filter_viewport_damage(damage_map, viewport)

Filters damage regions to only those that intersect with the viewport. Optimizes rendering by skipping off-screen damage.

group_by_priority(damage_map)

Groups damage regions by priority for batch processing. High priority damages are processed first.

merge_damage(existing_damage, new_damage)

Merges two damage maps, keeping higher priority damages. Used for accumulating damage across multiple updates.

optimize_damage_regions(damage_map)

Optimizes damage regions by combining adjacent/overlapping regions. Reduces the number of separate render operations needed.

Types

damage_map()

@type damage_map() :: %{required([integer()]) => damage_region()}

damage_region()

@type damage_region() :: %{
  path: [integer()],
  type: damage_type(),
  bounds:
    %{x: integer(), y: integer(), width: integer(), height: integer()} | nil,
  priority: :low | :medium | :high
}

damage_type()

@type damage_type() :: :content | :layout | :style | :structure

Functions

compute_damage(arg1, tree)

@spec compute_damage(
  diff_result :: :no_change | {:replace, any()} | {:update, [integer()], any()},
  tree :: map() | nil
) :: damage_map()

Computes damaged regions from a tree diff result. Returns a map of path -> damage_region for efficient lookups.

filter_viewport_damage(damage_map, viewport)

@spec filter_viewport_damage(damage_map(), %{
  x: integer(),
  y: integer(),
  width: integer(),
  height: integer()
}) :: damage_map()

Filters damage regions to only those that intersect with the viewport. Optimizes rendering by skipping off-screen damage.

group_by_priority(damage_map)

@spec group_by_priority(damage_map()) :: %{
  high: [damage_region()],
  medium: [damage_region()],
  low: [damage_region()]
}

Groups damage regions by priority for batch processing. High priority damages are processed first.

merge_damage(existing_damage, new_damage)

@spec merge_damage(damage_map(), damage_map()) :: damage_map()

Merges two damage maps, keeping higher priority damages. Used for accumulating damage across multiple updates.

optimize_damage_regions(damage_map)

@spec optimize_damage_regions(damage_map()) :: damage_map()

Optimizes damage regions by combining adjacent/overlapping regions. Reduces the number of separate render operations needed.