simvx.graphics.render2d.clip_scope

The clip + transform scope table (design §2.5).

Today, clip/transform nesting is implicit in walk recursion plus push/pop stacks. Once items live in one flat sorted list the recursion is gone, so the nesting must be encoded. This module is that encoding (the model, §2.5 – not yet wired to a real walk):

• Each push_clip/pop_clip (and the synthesised per-child Control wrap, §2.5) opens/closes a :class:ClipScope. A scope’s effective scissor is the intersection of its own rect with its parent’s effective scissor, computed once at open time and stored with a parent pointer.

• Every Item records the :class:ClipScopeId active at emission. After sort, the scissor is read straight off the item’s scope – no draw-time clip stack.

• A scope also carries a transform id so the Control walk’s implicit per-child translate (§2.5) is reproduced as a scope entry rather than baked.

The hard invariant (§2.5): clipping is a filter, never an ordering input. A scope id travels with its item through the sort; banding never moves an item across a clip boundary. So the table only needs to reproduce, for any item, the exact effective scissor + transform its recursive push/pop would have produced.

Module Contents

Classes

ClipScope	One entry in the :class:ClipScopeTable (design §2.5).
ClipScopeTable	Builds + stores nested clip/transform scopes for a flat item list (§2.5).

Data

__all__
Rect
ROOT_CLIP_SCOPE

API

simvx.graphics.render2d.clip_scope.__all__

[‘ROOT_CLIP_SCOPE’, ‘ClipScope’, ‘ClipScopeTable’]

simvx.graphics.render2d.clip_scope.Rect

None

simvx.graphics.render2d.clip_scope.ROOT_CLIP_SCOPE

0

class simvx.graphics.render2d.clip_scope.ClipScope

Bases: typing.NamedTuple

One entry in the :class:ClipScopeTable (design §2.5).

scissor is the effective rect (already intersected up the parent chain), so a batch sets the scissor straight from scissor with no walk. None means unbounded. transform is an index into the per-item transform column (-1 = inherit parent / identity), reproducing the Control per-child translate that the walk synthesises.

parent: int

None

scissor: simvx.graphics.render2d.clip_scope.Rect | None

None

transform: int

None

class simvx.graphics.render2d.clip_scope.ClipScopeTable

Builds + stores nested clip/transform scopes for a flat item list (§2.5).

Usage models the collection pass: maintain an open-scope cursor, and

Meth:

push / :meth:pop around clipped subtrees (or call :meth:open directly with an explicit parent). Items record :attr:current at emission. After collection the table is a flat array indexed by ClipScopeId; the effective scissor + transform are read with O(1) :meth:scissor /

Meth:

get.

The root scope (id :data:ROOT_CLIP_SCOPE) is always present, unclipped, identity transform.

Initialization

__slots__

(‘_scopes’, ‘_stack’)

__len__() → int

property current: int

The currently-open scope id (what an emitted item would record).

open(parent: int, clip: simvx.graphics.render2d.clip_scope.Rect | None = None, transform: int = -1) → int

Create a child scope under parent and return its id.

The new scope’s effective scissor is the intersection of clip with parent’s effective scissor (§2.5), so nesting is resolved once at open time. Does not change :attr:current – use :meth:push for the stack-style collection cursor.

push(clip: simvx.graphics.render2d.clip_scope.Rect | None = None, transform: int = -1) → int

Open a child scope under :attr:current, make it current, return id.

pop() → int

Close the current scope, restoring its parent as current; returns the scope that was just closed (it remains stored in the table).

get(scope_id: int) → simvx.graphics.render2d.clip_scope.ClipScope

Return the :class:ClipScope record for scope_id.

scissor(scope_id: int) → simvx.graphics.render2d.clip_scope.Rect | None

Return the effective (intersected) scissor for scope_id (§2.5).

ancestry(scope_id: int) → list[int]

Return [scope_id, parent, ..., root] – the nesting chain (§2.5).

Proves the flat table reproduces push/pop nesting: walking parent pointers recovers exactly the recursive scope stack that was open when the scope was created.