simvx.core.viewport

Viewport, SubViewport, and Display system for SimVX.

Module Contents

Classes

StretchMode

StretchAspect

VSyncMode

WindowMode

DisplaySettings

Project-level display configuration. Read from simvx.toml.

SubViewport

Renders its children to an offscreen texture.

ViewportContainer

Control that owns a :class:SubViewport and ties its resolution to the layout.

Functions

find_outside_subviewports

The first node_type under root in Node.find order, not entering a SubViewport.

Data

log

API

simvx.core.viewport.log

‘getLogger(…)’

class simvx.core.viewport.StretchMode[source]

Bases: enum.IntEnum

DISABLED

0

CANVAS_ITEMS

1

VIEWPORT

2

__abs__()
__add__()
__and__()
__bool__()
__ceil__()
__delattr__()
__dir__()
__divmod__()
__eq__()
__float__()
__floor__()
__floordiv__()
__format__()
__ge__()
__getattribute__()
__getnewargs__()
__getstate__()
__gt__()
__hash__()
__index__()
__int__()
__invert__()
__le__()
__lshift__()
__lt__()
__mod__()
__mul__()
__ne__()
__neg__()
__new__()
__or__()
__pos__()
__pow__()
__radd__()
__rand__()
__rdivmod__()
__reduce__()
__reduce_ex__()
__repr__()
__rfloordiv__()
__rlshift__()
__rmod__()
__rmul__()
__ror__()
__round__()
__rpow__()
__rrshift__()
__rshift__()
__rsub__()
__rtruediv__()
__rxor__()
__setattr__()
__sizeof__()
__str__()
__sub__()
__subclasshook__()
__truediv__()
__trunc__()
__xor__()
as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
is_integer()
class numerator
class real
to_bytes()
__deepcopy__(memo)
__copy__()
name()
value()
class simvx.core.viewport.StretchAspect[source]

Bases: enum.IntEnum

IGNORE

0

KEEP

1

KEEP_WIDTH

2

KEEP_HEIGHT

3

EXPAND

4

__abs__()
__add__()
__and__()
__bool__()
__ceil__()
__delattr__()
__dir__()
__divmod__()
__eq__()
__float__()
__floor__()
__floordiv__()
__format__()
__ge__()
__getattribute__()
__getnewargs__()
__getstate__()
__gt__()
__hash__()
__index__()
__int__()
__invert__()
__le__()
__lshift__()
__lt__()
__mod__()
__mul__()
__ne__()
__neg__()
__new__()
__or__()
__pos__()
__pow__()
__radd__()
__rand__()
__rdivmod__()
__reduce__()
__reduce_ex__()
__repr__()
__rfloordiv__()
__rlshift__()
__rmod__()
__rmul__()
__ror__()
__round__()
__rpow__()
__rrshift__()
__rshift__()
__rsub__()
__rtruediv__()
__rxor__()
__setattr__()
__sizeof__()
__str__()
__sub__()
__subclasshook__()
__truediv__()
__trunc__()
__xor__()
as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
is_integer()
class numerator
class real
to_bytes()
__deepcopy__(memo)
__copy__()
name()
value()
class simvx.core.viewport.VSyncMode[source]

Bases: enum.IntEnum

DISABLED

0

ENABLED

1

ADAPTIVE

2

MAILBOX

3

__abs__()
__add__()
__and__()
__bool__()
__ceil__()
__delattr__()
__dir__()
__divmod__()
__eq__()
__float__()
__floor__()
__floordiv__()
__format__()
__ge__()
__getattribute__()
__getnewargs__()
__getstate__()
__gt__()
__hash__()
__index__()
__int__()
__invert__()
__le__()
__lshift__()
__lt__()
__mod__()
__mul__()
__ne__()
__neg__()
__new__()
__or__()
__pos__()
__pow__()
__radd__()
__rand__()
__rdivmod__()
__reduce__()
__reduce_ex__()
__repr__()
__rfloordiv__()
__rlshift__()
__rmod__()
__rmul__()
__ror__()
__round__()
__rpow__()
__rrshift__()
__rshift__()
__rsub__()
__rtruediv__()
__rxor__()
__setattr__()
__sizeof__()
__str__()
__sub__()
__subclasshook__()
__truediv__()
__trunc__()
__xor__()
as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
is_integer()
class numerator
class real
to_bytes()
__deepcopy__(memo)
__copy__()
name()
value()
class simvx.core.viewport.WindowMode[source]

Bases: enum.IntEnum

WINDOWED

0

FULLSCREEN

1

BORDERLESS

2

MAXIMIZED

3

__abs__()
__add__()
__and__()
__bool__()
__ceil__()
__delattr__()
__dir__()
__divmod__()
__eq__()
__float__()
__floor__()
__floordiv__()
__format__()
__ge__()
__getattribute__()
__getnewargs__()
__getstate__()
__gt__()
__hash__()
__index__()
__int__()
__invert__()
__le__()
__lshift__()
__lt__()
__mod__()
__mul__()
__ne__()
__neg__()
__new__()
__or__()
__pos__()
__pow__()
__radd__()
__rand__()
__rdivmod__()
__reduce__()
__reduce_ex__()
__repr__()
__rfloordiv__()
__rlshift__()
__rmod__()
__rmul__()
__ror__()
__round__()
__rpow__()
__rrshift__()
__rshift__()
__rsub__()
__rtruediv__()
__rxor__()
__setattr__()
__sizeof__()
__str__()
__sub__()
__subclasshook__()
__truediv__()
__trunc__()
__xor__()
as_integer_ratio()
bit_count()
bit_length()
conjugate()
class denominator
class imag
is_integer()
class numerator
class real
to_bytes()
__deepcopy__(memo)
__copy__()
name()
value()
class simvx.core.viewport.DisplaySettings[source]

Project-level display configuration. Read from simvx.toml.

Initialization

compute_canvas_transform(window_width: int, window_height: int) → numpy.ndarray[source]

Compute the 2D canvas transform matrix based on stretch settings.

Returns 3x3 affine matrix to apply to all 2D rendering.

compute_viewport_rect(window_width: int, window_height: int) → tuple[int, int, int, int][source]

Compute the viewport rectangle (x, y, w, h) for 3D rendering.

class simvx.core.viewport.SubViewport(name='SubViewport', **kwargs)[source]

Bases: simvx.core.graphics.texture_slot.TextureSlot, simvx.core.node.Node

Renders its children to an offscreen texture.

The SubViewport’s subtree is rendered into its own offscreen render target each frame, using its own camera: a Camera3D and/or Camera2D placed among its children (a sensible default is used if none is present). The rendered colour buffer is exposed as a bindless texture index via

Attr:

texture, which other nodes in the main scene can sample: assign it to a Material.albedo_tex_index for a 3D “monitor in the world”, or feed a Sprite2D for a 2D minimap / picture-in-picture.

The render-to-texture integration is driven from the graphics backend (simvx.graphics.renderer.sub_viewport.SubViewportManager), not from this node: core stays rendering-agnostic. SubViewports render before the main scene pass each frame, so the main pass samples fresh content the same frame. A SubViewport that samples another SubViewport sees the previous frame’s content (one-frame lag).

The texture is display-referred: the viewport’s 3D content renders as linear HDR and is tone-mapped with the same exposure and curve the main scene uses, so a Sprite2D drawing it at 1:1 shows what the main scene would show for that camera. The curve comes from a WorldEnvironment inside the viewport’s subtree when it has one, and otherwise from the main scene’s. Only the tone curve follows that rule; the post effects (bloom, fog and the rest) do not run on the feed. The viewport’s 2D content draws over the feed after the tone curve, as the main scene’s screen-space 2D does.

Properties: size: Offscreen target dimensions in pixels. transparent_bg: Clear to transparent instead of opaque black. render_target_update_mode: "always" (default, render every frame), "once" (render a single frame then freeze), or "disabled" (never render; the slot stays valid but stale). use_occlusion: Run the two-phase Hi-Z occlusion cull for this view’s own camera (desktop renderer; the web Hi-Z is single-phase and has no per-view hook yet). Off by default: an offscreen view is usually small enough that the occlusion pass costs more than it saves. In the pipelined render mode the cull is deferred (the view renders un-culled with a one-time warning), like probe capture.

Initialization

size

‘Property(…)’

transparent_bg

‘Property(…)’

render_target_update_mode

‘Property(…)’

use_occlusion

‘Property(…)’

property texture[source]

The rendered texture, usable as material input or Sprite2D texture.

property texture_size: tuple[int, int][source]

Pixel dimensions of the underlying render target.

property texture_slot: int
publish_texture_slot(slot: int) → None
publish_overlay_slot(slot: int) → None
strict_errors: ClassVar[bool]

True

dev_checks: ClassVar[bool]

None

dev_warnings: ClassVar[bool]

None

freeze_check_interval: ClassVar[float]

1.0

dynamic: bool

False

visible

‘Property(…)’

update_mode

‘Property(…)’

focus_mode

‘Property(…)’

drag_threshold

‘Property(…)’

focus_entered

‘Signal(…)’

focus_exited

‘Signal(…)’

__properties__: ClassVar[dict[str, simvx.core.descriptors.Property]]

None

classmethod __init_subclass__(**kwargs)
property name: str
property visible_in_tree: bool
property input_player: simvx.core.input.players.InputPlayer
property input_context: simvx.core.input.contexts.InputContext | None
reset_error() → None
add_child(node: simvx.core.node.T) → simvx.core.node.T
remove_child(node: simvx.core.node.Node) → None
reparent(new_parent: simvx.core.node.Node)
node_at(path, default=_NO_DEFAULT)
find(target, *, direct: bool = False)
find_all(target, *, direct: bool = False)
expect(target, *, direct: bool = False)
ancestor(target)
walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]
property path: str
property is_scene_root: bool
add_to_group(group: str)
remove_from_group(group: str)
is_in_group(group: str) → bool
on_ready() → None
on_enter_tree() → None
on_exit_tree() → None
on_update(dt: float) → None
on_fixed_update(dt: float) → None
on_draw(canvas) → None
on_draw_3d(gizmos) → None
on_picked(event: simvx.core.input.events.PickEvent) → bool | None
on_gui_input(event: simvx.core.input.events.GuiInputEvent) → bool | None
start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle
stop_coroutine(gen_or_handle)
property focused: bool
property focus_rect: tuple[float, float, float, float] | None
drag_threshold_for(pointer_type: simvx.core.input.enums.PointerType | str) → float
grab_focus() → None
release_focus() → None
capture_pointer(pointer_id: int | None = None) → None
release_pointer(pointer_id: int | None = None) → None
queue_redraw() → None
property render_dirty: bool
clear_children()
destroy()
property destroying: bool
property destroyed: bool
call_deferred(method: collections.abc.Callable[..., Any], *args: Any) → None
property app
property tree: simvx.core.scene_tree.SceneTree
property viewport_size: simvx.core.math.types.Vec2
property viewport_insets: tuple[float, float, float, float]
property physics
property physics_2d
__getitem__(key: str)
classmethod get_properties() → dict[str, simvx.core.descriptors.Property]
__repr__()
simvx.core.viewport.find_outside_subviewports(root: simvx.core.node.Node, node_type: type[simvx.core.viewport.find_outside_subviewports.T]) → simvx.core.viewport.find_outside_subviewports.T | None[source]

The first node_type under root in Node.find order, not entering a SubViewport.

A WorldEnvironment or Camera3D inside a SubViewport belongs to that viewport, so a lookup for the main scene’s must not reach it. root itself may be a SubViewport: find_outside_subviewports(viewport, WorldEnvironment) finds that viewport’s own environment and skips any nested viewport’s.

class simvx.core.viewport.ViewportContainer(name='ViewportContainer', **kwargs)[source]

Bases: simvx.core.ui.core.Control

Control that owns a :class:SubViewport and ties its resolution to the layout.

Register the viewport with :meth:set_viewport. With stretch enabled (the default) that call resizes the viewport’s offscreen target to match the control’s current rect, so an offscreen view laid out by a container renders at exactly the pixel size it will be shown at, with no rescaling. With stretch disabled the viewport keeps whatever size it was given and the container only holds the reference.

stretch is sampled inside :meth:set_viewport, so it applies at registration time: after the control is resized, call :meth:set_viewport again (or assign viewport.size) to re-match the target.

The container does not blit anything by itself. To show the rendered result, sample viewport.texture from a Sprite2D or a material, as described on :class:SubViewport.

Initialization

stretch

‘Property(…)’

set_viewport(viewport: simvx.core.viewport.SubViewport)[source]

Host viewport, matching its offscreen size to this control when stretch.

size_x

‘Property(…)’

size_y

‘Property(…)’

min_size_x

‘Property(…)’

min_size_y

‘Property(…)’

anchor_left

‘Property(…)’

anchor_top

‘Property(…)’

anchor_right

‘Property(…)’

anchor_bottom

‘Property(…)’

margin_left

‘Property(…)’

margin_top

‘Property(…)’

margin_right

‘Property(…)’

margin_bottom

‘Property(…)’

anchor

‘Property(…)’

inset

‘Property(…)’

dismiss_on_outside_click

‘Property(…)’

clip_contents

‘Property(…)’

focus_mode

‘Property(…)’

tooltip

‘Property(…)’

pointer_filter

‘Property(…)’

cursor_shape

‘Property(…)’

pointer_types: frozenset[simvx.core.input.enums.PointerType] | None

None

touch_target: bool

False

property wants_text_input: bool
size_flags_horizontal

‘Property(…)’

size_flags_vertical

‘Property(…)’

stretch_ratio

‘Property(…)’

max_size

‘Property(…)’

property size: simvx.core.math.types.Vec2
property min_size: simvx.core.math.types.Vec2
content_signature() → object
content_uses(chars: str) → bool
autosize_to_content() → None
accepts_pointers

‘Property(…)’

property theme: simvx.core.ui.types.Theme | None
property mouse_over: bool
property disabled: bool
get_theme() → simvx.core.ui.types.Theme
property viewport_size: simvx.core.math.types.Vec2
property viewport_insets: tuple[float, float, float, float]
queue_redraw()
size_floor() → tuple[float, float]
get_minimum_size() → simvx.core.math.types.Vec2
add_child(node: simvx.core.node.T) → simvx.core.node.T
get_rect() → tuple[float, float, float, float]
get_global_rect() → tuple[float, float, float, float]
property focus_rect: tuple[float, float, float, float] | None
is_point_inside(point) → bool
is_hit(event: simvx.core.input.events.PointerEvent) → bool
classmethod __init_subclass__(**kwargs)
activate() → bool
focus_next_control()
focus_previous_control()
set_drag_preview(control: simvx.core.ui.core.Control)
property is_overlay_open: bool
show_overlay(modality: str = 'light', *, dim: bool | None = None, dismiss: bool | None = None, inert: bool | None = None, owner: simvx.core.ui.core.Control | None = None, initial_focus: simvx.core.ui.core.Control | None = None) → None
close_overlay() → None
position

‘_SpatialVecProperty(…)’

rotation

‘Property(…)’

scale

‘_SpatialVecProperty(…)’

top_level

‘Property(…)’

z_index

‘Property(…)’

z_as_relative

‘Property(…)’

render_layer

‘Property(…)’

set_render_layer(index: int, enabled: bool = True) → None
is_on_render_layer(index: int) → bool
property absolute_z_index: int
property rotation_degrees: float
property world_position: simvx.core.math.types.Vec2
property world_rotation: float
property world_scale: simvx.core.math.types.Vec2
property world_transform: tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2, float]
property forward: simvx.core.math.types.Vec2
property right: simvx.core.math.types.Vec2
translate(offset: tuple[float, float] | numpy.ndarray)
rotate(radians: float)
rotate_deg(degrees: float)
look_at(target: tuple[float, float] | numpy.ndarray)
to_global(point) → simvx.core.math.types.Vec2
to_local(point) → simvx.core.math.types.Vec2
transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]
wrap_screen(margin: float = 20)
post_processed

‘Property(…)’

property transform_render_dirty: bool
strict_errors: ClassVar[bool]

True

dev_checks: ClassVar[bool]

None

dev_warnings: ClassVar[bool]

None

freeze_check_interval: ClassVar[float]

1.0

dynamic: bool

False

visible

‘Property(…)’

update_mode

‘Property(…)’

drag_threshold

‘Property(…)’

focus_entered

‘Signal(…)’

focus_exited

‘Signal(…)’

__properties__: ClassVar[dict[str, simvx.core.descriptors.Property]]

None

property name: str
property visible_in_tree: bool
property input_player: simvx.core.input.players.InputPlayer
property input_context: simvx.core.input.contexts.InputContext | None
reset_error() → None
remove_child(node: simvx.core.node.Node) → None
reparent(new_parent: simvx.core.node.Node)
node_at(path, default=_NO_DEFAULT)
find(target, *, direct: bool = False)
find_all(target, *, direct: bool = False)
expect(target, *, direct: bool = False)
ancestor(target)
walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]
property path: str
property is_scene_root: bool
add_to_group(group: str)
remove_from_group(group: str)
is_in_group(group: str) → bool
on_ready() → None
on_enter_tree() → None
on_exit_tree() → None
on_update(dt: float) → None
on_fixed_update(dt: float) → None
on_draw(canvas) → None
on_draw_3d(gizmos) → None
on_picked(event: simvx.core.input.events.PickEvent) → bool | None
on_gui_input(event: simvx.core.input.events.GuiInputEvent) → bool | None
start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle
stop_coroutine(gen_or_handle)
property focused: bool
drag_threshold_for(pointer_type: simvx.core.input.enums.PointerType | str) → float
grab_focus() → None
release_focus() → None
capture_pointer(pointer_id: int | None = None) → None
release_pointer(pointer_id: int | None = None) → None
property render_dirty: bool
clear_children()
destroy()
property destroying: bool
property destroyed: bool
call_deferred(method: collections.abc.Callable[..., Any], *args: Any) → None
property app
property tree: simvx.core.scene_tree.SceneTree
property physics
property physics_2d
__getitem__(key: str)
classmethod get_properties() → dict[str, simvx.core.descriptors.Property]
__repr__()