Module Screen.Hit_gridSource

Spatial indexing for mouse hit testing.

A hit grid maps screen coordinates to integer element IDs. Lookup is O(1); registration is O(region area).

Constants

Sourceval empty_id : int

empty_id is 0. Represents the absence of any element.

Types

Sourcetype rect = {
  1. x : int;
  2. y : int;
  3. width : int;
  4. height : int;
}

The type for rectangular areas in cell coordinates.

Sourcetype t

The type for hit grids. Internally backed by an int32 bigarray for cache locality.

Lifecycle

Sourceval create : width:int -> height:int -> t

create ~width ~height is a hit grid of the given dimensions with all cells set to empty_id.

Sourceval resize : t -> width:int -> height:int -> unit

resize t ~width ~height updates t's dimensions to width and height. All cells are reset to empty_id. Internal storage is grown only when necessary.

Sourceval clear : t -> unit

clear t resets all cells to empty_id. The clip stack is preserved.

Operations

Sourceval add : t -> x:int -> y:int -> width:int -> height:int -> id:int -> unit

add t ~x ~y ~width ~height ~id fills the rectangular region with id (painter's algorithm: overwrites any existing IDs). The rectangle is clipped to the grid bounds and the active clip region. Zero or negative dimensions are a no-op.

Sourceval get : t -> x:int -> y:int -> int

get t ~x ~y is the element ID at (x, y), or empty_id if the coordinates are out of bounds.

Sourceval blit : src:t -> dst:t -> unit

blit ~src ~dst copies the content of src into dst. dst is resized to match src.

Clipping

Hierarchical clipping for hit regions. When a clip is active, add operations are constrained to the intersection of the clip rectangle and the grid bounds. This prevents elements inside overflow-hidden containers from receiving mouse events outside their visible area.

Push/pop pairs must be balanced.

Sourceval push_clip : t -> rect -> unit

push_clip t r pushes a clipping rectangle. The effective clip is the intersection of r with the current clip (hierarchical narrowing).

Sourceval pop_clip : t -> unit

pop_clip t pops the most recent clip. No-op if the stack is empty.

Sourceval clear_clip : t -> unit

clear_clip t removes all clipping regions.

Sourceval with_clip : t -> rect -> (unit -> 'a) -> 'a

with_clip t r f runs f () with r as the active clip and pops it on return (even on exception).