simvx.graphics.engine

Top-level engine entry point.

Module Contents

Classes

Engine

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

Data

__all__
log

API

simvx.graphics.engine.__all__

[‘Engine’]

simvx.graphics.engine.log

‘getLogger(…)’

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)

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 shader_dir: pathlib.Path

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

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

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

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.

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

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

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

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

load_texture(file_path: str) → int

Load a PNG/JPG texture from disk. Returns the 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.

get_cursor_pos() → tuple[float, float]

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

set_window_size(width: int, height: int) → None

Programmatically resize the window.

shutdown() → None

Clean up all resources.