simvx.graphics.engine

Top-level engine entry point.

Module Contents

Classes

CubemapHandle	Opaque handle to a GPU cubemap returned by :meth:Engine.load_cubemap.
Engine	Graphics engine — owns the window, GPU context, and render loop.

Data

__all__
log

API

simvx.graphics.engine.__all__

[‘CubemapHandle’, ‘Engine’]

simvx.graphics.engine.log

‘getLogger(…)’

class simvx.graphics.engine.CubemapHandle

Opaque handle to a GPU cubemap returned by :meth:Engine.load_cubemap.

Pass to :meth:~simvx.graphics.renderer.forward.Renderer.set_skybox to install it as the scene skybox / IBL source. The engine takes ownership of the underlying Vulkan resources and destroys them at shutdown.

view: Any

None

sampler: Any

None

image: Any

None

memory: Any

None

class simvx.graphics.engine.Engine(width: int = 1280, height: int = 720, title: str = 'SimVX', backend: str | None = None, renderer: str = 'deferred', max_textures: int = MAX_TEXTURES, visible: bool = True, vsync: bool = False, target_fps: int | None = None)

Graphics engine — owns the window, GPU context, and render loop.

Initialization

property ctx: simvx.graphics.gpu.context.GPUContext

GPU context holding device, physical_device, queues, and command pool.

property render_pass: simvx.graphics._types._VkRenderPass

property extent: tuple[int, int]

property content_scale: tuple[float, float]

HiDPI content scale (e.g. (2.0, 2.0) on a 200% display).

property vsync: bool

Whether vertical sync is currently enabled.

set_vsync(value: bool) → None

Toggle vsync at runtime by recreating the swapchain with a new present mode.

No-op if the requested state matches the current one. Before the engine has a swapchain (pre-run()) the value is stored and used at boot.

property pre_render_callback: collections.abc.Callable[[simvx.graphics._types._VkCommandBuffer], None] | None

Callback invoked after vkBeginCommandBuffer but before the main render pass.

property shader_dir: pathlib.Path

property current_timestamp_pool: simvx.graphics.gpu.timestamp_pool.TimestampPool | None

Return the TimestampPool for the in-flight frame currently recording.

None if the device does not support timestamp queries (the pool list is left empty by _init_vulkan in that case). Renderers wrap each pass with pool.begin(cmd, label) / pool.end(cmd, label).

property mesh_registry: simvx.graphics.renderer.mesh_registry.MeshRegistry

Get mesh registry (lazy init).

property texture_manager: simvx.graphics.materials.texture.TextureManager

Get texture manager (lazy init).

property batch: simvx.graphics.renderer.gpu_batch.GPUBatch

Get the GPU batch renderer (lazy init).

property renderer: simvx.graphics.renderer.forward.Renderer

Get the active renderer (creates the default renderer if none exists).

create_renderer(renderer_type: str = 'forward') → simvx.graphics.renderer.forward.Renderer

Create and initialize a renderer.

property texture_descriptor_layout: simvx.graphics._types._VkDescriptorSetLayout

Get (lazily init) the texture descriptor set layout.

property texture_descriptor_set: simvx.graphics._types._VkDescriptorSet

Get the texture descriptor set (set 1).

create_render_target(width: int, height: int, use_depth: bool = True) → simvx.graphics.renderer.render_target.RenderTarget

Create an offscreen render target for render-to-texture.

load_cubemap(paths_or_hdr: list[str] | str | None = None, *, colour: tuple[float, float, float] | None = None) → simvx.graphics.engine.CubemapHandle

Load a cubemap from 6 face images, a single HDR equirect file, or a solid colour.

Args: paths_or_hdr: List of 6 face paths [+X, -X, +Y, -Y, +Z, -Z], or a single HDR equirectangular image path. None falls back to the colour kwarg. colour: RGB triple in 0..1 used when no paths are provided.

Returns: A :class:CubemapHandle — hand this to :meth:Renderer.set_skybox to install it.

register_texture(image_view: simvx.graphics._types._VkImageView) → int

Register a texture (image view) into the bindless array.

Returns the texture index. Reuses slots freed by

Meth:

unregister_texture; otherwise allocates a new slot from the high-water mark.

update_texture(slot: int, image_view: simvx.graphics._types._VkImageView) → None

Rewrite the descriptor at an existing bindless slot.

Used when the backing image view changes (e.g. render-target resize) but the slot id must remain stable so callers that captured it don’t need re-notification.

unregister_texture(slot: int) → None

Release a bindless texture slot for reuse by a later register_texture.

The descriptor at the slot is left pointing at its old view until something new is bound there; the slot is simply marked free.

upload_texture_pixels(pixels: numpy.ndarray, width: int, height: int) → int

Upload raw RGBA pixel data to GPU. Returns the bindless texture index.

load_mesh(file_path: str) → simvx.graphics._types.MeshHandle

Load a glTF mesh from disk and register it.

Returns: MeshHandle for use in rendering.

create_textured_quad_pipeline(vert_module: simvx.graphics._types._VkShaderModule, frag_module: simvx.graphics._types._VkShaderModule) → tuple[simvx.graphics._types._VkPipeline, simvx.graphics._types._VkPipelineLayout]

Create a textured quad pipeline using the texture descriptor layout. Returns (pipeline, layout).

create_vertex_buffer(vertices: numpy.ndarray) → tuple[Any, simvx.graphics._types._VkDeviceMemory]

Create a GPU vertex buffer and upload data. Returns (buffer, memory).

create_index_buffer(indices: numpy.ndarray) → tuple[Any, simvx.graphics._types._VkDeviceMemory]

Create a GPU index buffer and upload data. Returns (buffer, memory).

create_ssbo(data: numpy.ndarray) → tuple[Any, simvx.graphics._types._VkDeviceMemory]

Create an SSBO and upload data. Returns (buffer, memory).

update_ssbo(memory: simvx.graphics._types._VkDeviceMemory, data: numpy.ndarray) → None

Update SSBO contents in-place via mapped memory.

create_descriptor_pool(max_sets: int = 4) → simvx.graphics._types._VkDescriptorPool

Create a descriptor pool.

create_descriptor_set_layout(binding_count: int = 3) → simvx.graphics._types._VkDescriptorSetLayout

Create a descriptor set layout with N SSBO bindings.

allocate_descriptor_set(pool: simvx.graphics._types._VkDescriptorPool, layout: simvx.graphics._types._VkDescriptorSetLayout) → simvx.graphics._types._VkDescriptorSet

Allocate a descriptor set from pool.

write_descriptor_ssbo(descriptor_set: simvx.graphics._types._VkDescriptorSet, binding: int, buffer: Any, size: int) → None

Bind an SSBO buffer to a descriptor set binding.

compile_and_load_shader(name: str) → simvx.graphics._types._VkShaderModule

Compile a shader from SHADER_DIR and return its module.

create_forward_pipeline(vert_module: simvx.graphics._types._VkShaderModule, frag_module: simvx.graphics._types._VkShaderModule, descriptor_layout: simvx.graphics._types._VkDescriptorSetLayout, texture_layout: simvx.graphics._types._VkDescriptorSetLayout | None = None, render_pass: simvx.graphics._types._VkRenderPass | None = None, extent: tuple[int, int] | None = None) → tuple[simvx.graphics._types._VkPipeline, simvx.graphics._types._VkPipelineLayout]

Create a forward rendering pipeline. Returns (pipeline, pipeline_layout).

If texture_layout is provided, the pipeline uses 2 descriptor set layouts (set 0 = SSBOs, set 1 = textures). If render_pass is provided, uses that instead of the engine’s main render pass.

update_vertex_buffer(memory: simvx.graphics._types._VkDeviceMemory, data: numpy.ndarray) → None

Update vertex buffer contents in-place via mapped memory.

create_line_pipeline(vert_module: simvx.graphics._types._VkShaderModule, frag_module: simvx.graphics._types._VkShaderModule) → tuple[simvx.graphics._types._VkPipeline, simvx.graphics._types._VkPipelineLayout]

Create a line rendering pipeline. Returns (pipeline, pipeline_layout).

create_ui_pipeline(vert_module: simvx.graphics._types._VkShaderModule, frag_module: simvx.graphics._types._VkShaderModule) → tuple[simvx.graphics._types._VkPipeline, simvx.graphics._types._VkPipelineLayout]

Create a solid-colour UI pipeline. Returns (pipeline, pipeline_layout).

push_constants(cmd: simvx.graphics._types._VkCommandBuffer, pipeline_layout: simvx.graphics._types._VkPipelineLayout, data: bytes | bytearray) → None

Push constant data (view + proj).

enable_picking(descriptor_layout: simvx.graphics._types._VkDescriptorSetLayout, descriptor_set: simvx.graphics._types._VkDescriptorSet) → None

Initialize the GPU pick pass for mouse picking.

pick_entity(x: int, y: int, view_proj_data: bytes, vertex_buffer: Any, index_buffer: Any, index_count: int, instance_count: int) → int

Read entity ID at screen position (x, y). Returns entity index or -1.

set_selected_objects(selected: list[tuple[simvx.graphics._types.MeshHandle, numpy.ndarray, int]]) → None

Set the list of selected objects to highlight with outlines.

Args: selected: List of (mesh_handle, transform_4x4, material_id) tuples.

clear_selected_objects() → None

Clear all selection outlines.

property outline_pass: simvx.graphics.renderer.outline_pass.OutlinePass | None

Access outline pass for configuration (colour, width, enabled).

draw_text(text: str, x: float = 10, y: float = 10, font: str | None = None, size: float = 24.0, colour: tuple[float, ...] = (1.0, 1.0, 1.0, 1.0)) → None

Draw 2D overlay text (call each frame).

Args: text: String to render. x, y: Top-left position in pixels. font: Path to .ttf file (auto-detects system font if None). size: Text size in pixels. colour: RGBA colour tuple.

create_text_texture(font: str | None = None, size: int = 32, width: int = 256, height: int = 64) → Any

Create a texture with rendered text for use on 3D objects.

Returns a TextTexture with .text, .colour, and .texture_index properties. Setting .text or .colour re-renders and re-uploads the texture.

set_key_callback(callback: collections.abc.Callable[[int, int, int], None]) → None

Register callback(key, action, mods) for keyboard events.

set_mouse_button_callback(callback: collections.abc.Callable[[int, int, int], None]) → None

Register callback(button, action, mods) for mouse button events.

set_cursor_pos_callback(callback: collections.abc.Callable[[float, float], None]) → None

Register callback(x, y) for cursor position events.

set_scroll_callback(callback: collections.abc.Callable[[float, float], None]) → None

Register callback(x_offset, y_offset) for scroll wheel events.

set_char_callback(callback: collections.abc.Callable[[int], None]) → None

Register callback(codepoint) for character input events.

set_cursor_shape(shape: int) → None

Set cursor shape. 0=arrow, 1=ibeam, 2=crosshair, 3=hand, 4=hresize, 5=vresize.

property cursor_pos: tuple[float, float]

Current cursor position in screen coordinates.

run(callback: collections.abc.Callable[[], None] | None = None, setup: collections.abc.Callable[[], None] | None = None, render: collections.abc.Callable[[simvx.graphics._types._VkCommandBuffer, tuple[int, int]], None] | None = None, pre_render: collections.abc.Callable[[simvx.graphics._types._VkCommandBuffer], None] | None = None) → None

Start the main loop.

Args: callback: Legacy per-frame callback (called before draw). setup: Called once after Vulkan init, before the loop. render: Custom render callback receiving (command_buffer, extent). If provided, replaces the built-in triangle rendering. pre_render: Called with command_buffer after vkBeginCommandBuffer but before the main render pass. Use for offscreen passes.

capture_frame() → numpy.ndarray

Capture the last rendered framebuffer as an RGBA numpy array.

Returns (height, width, 4) uint8 array. Must be called after _draw_frame().

property window_size: tuple[int, int]

Current window (width, height). Writable to programmatically resize.

shutdown() → None

Clean up all resources.