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.

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).

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

script_error_raised

‘Signal(…)’

dynamic: bool

False

visible

‘Property(…)’

update_mode

‘Property(…)’

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

None

classmethod __init_subclass__(**kwargs)
property name: str
property visible_in_tree: bool
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(renderer) → None
on_picked(event: simvx.core.events.InputEvent) → None
on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None
start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle
stop_coroutine(gen_or_handle)
queue_redraw() → None
property render_dirty: bool
clear_children()
destroy()
property destroying: 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__()
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(…)’

dismiss_on_outside_click

‘Property(…)’

clip_contents

‘Property(…)’

focus_mode

‘Property(…)’

tooltip

‘Property(…)’

mouse_filter

‘Property(…)’

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
touch_mode: str

‘mouse’

property theme: simvx.core.ui.types.Theme | None
property mouse_over: bool
property focused: bool
property disabled: bool
get_theme() → simvx.core.ui.types.Theme
queue_redraw()
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]
is_point_inside(point) → bool
place_bottom_strip(height: float) → None
place_top_strip(height: float) → None
set_anchor_preset(preset: simvx.core.ui.enums.AnchorPreset)
activate() → bool
set_focus()
grab_focus()
release_focus()
has_focus() → bool
focus_next_control()
focus_previous_control()
grab_mouse()
release_mouse()
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(…)’

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)
transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]
draw_polygon(renderer, points: list[simvx.core.math.types.Vec2], closed=True, colour=None)
wrap_screen(margin: float = 20)
hdr

‘Property(…)’

property transform_render_dirty: bool
strict_errors: ClassVar[bool]

True

dev_checks: ClassVar[bool]

None

script_error_raised

‘Signal(…)’

dynamic: bool

False

visible

‘Property(…)’

update_mode

‘Property(…)’

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

None

classmethod __init_subclass__(**kwargs)
property name: str
property visible_in_tree: bool
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(renderer) → None
on_picked(event: simvx.core.events.InputEvent) → None
on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None
start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle
stop_coroutine(gen_or_handle)
property render_dirty: bool
clear_children()
destroy()
property destroying: 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__()