`simvx.graphics.engine`¶

Top-level engine entry point.

Module Contents¶

Classes¶

Engine

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

API¶

simvx.graphics.engine.__all__¶: [‘Engine’]

simvx.graphics.engine.log¶: ‘getLogger(…)’

simvx.graphics.engine.VkInstance¶: None

simvx.graphics.engine.VkDevice¶: None

simvx.graphics.engine.VkPhysicalDevice¶: None

simvx.graphics.engine.VkQueue¶: None

simvx.graphics.engine.VkSurfaceKHR¶: None

simvx.graphics.engine.VkRenderPass¶: None

simvx.graphics.engine.VkPipeline¶: None

simvx.graphics.engine.VkPipelineLayout¶: None

simvx.graphics.engine.VkCommandBuffer¶: None

simvx.graphics.engine.VkFramebuffer¶: None

simvx.graphics.engine.VkShaderModule¶: None

simvx.graphics.engine.VkImage¶: None

simvx.graphics.engine.VkImageView¶: None

simvx.graphics.engine.VkDeviceMemory¶: None

simvx.graphics.engine.VkDescriptorPool¶: None

simvx.graphics.engine.VkDescriptorSetLayout¶: None

simvx.graphics.engine.VkDescriptorSet¶: None

simvx.graphics.engine.VkSampler¶: None

simvx.graphics.engine.VkDebugUtilsMessengerEXT¶: 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)¶

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

Initialization

property device: simvx.graphics.engine.VkDevice¶

property physical_device: simvx.graphics.engine.VkPhysicalDevice¶

property render_pass: simvx.graphics.engine.VkRenderPass¶

property extent: tuple[int, int]¶

property graphics_queue: simvx.graphics.engine.VkQueue¶

property cmd_pool: Any¶

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.engine.VkDescriptorSetLayout¶: Get (lazily init) the texture descriptor set layout.

property texture_descriptor_set: simvx.graphics.engine.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.engine.VkImageView) → int¶: Register a texture (image view) into the bindless array. Returns the 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.engine.VkShaderModule, frag_module: simvx.graphics.engine.VkShaderModule) → tuple[simvx.graphics.engine.VkPipeline, simvx.graphics.engine.VkPipelineLayout]¶: Create a textured quad pipeline using the texture descriptor layout. Returns (pipeline, layout).

create_vertex_buffer(vertices: numpy.ndarray) → tuple[Any, simvx.graphics.engine.VkDeviceMemory]¶: Create a GPU vertex buffer and upload data. Returns (buffer, memory).

create_index_buffer(indices: numpy.ndarray) → tuple[Any, simvx.graphics.engine.VkDeviceMemory]¶: Create a GPU index buffer and upload data. Returns (buffer, memory).

create_ssbo(data: numpy.ndarray) → tuple[Any, simvx.graphics.engine.VkDeviceMemory]¶: Create an SSBO and upload data. Returns (buffer, memory).

update_ssbo(memory: simvx.graphics.engine.VkDeviceMemory, data: numpy.ndarray) → None¶: Update SSBO contents in-place via mapped memory.

create_descriptor_pool(max_sets: int = 4) → simvx.graphics.engine.VkDescriptorPool¶: Create a descriptor pool.

create_descriptor_set_layout(binding_count: int = 3) → simvx.graphics.engine.VkDescriptorSetLayout¶: Create a descriptor set layout with N SSBO bindings.

allocate_descriptor_set(pool: simvx.graphics.engine.VkDescriptorPool, layout: simvx.graphics.engine.VkDescriptorSetLayout) → simvx.graphics.engine.VkDescriptorSet¶: Allocate a descriptor set from pool.

write_descriptor_ssbo(descriptor_set: simvx.graphics.engine.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.engine.VkShaderModule¶: Compile a shader from SHADER_DIR and return its module.

create_forward_pipeline(vert_module: simvx.graphics.engine.VkShaderModule, frag_module: simvx.graphics.engine.VkShaderModule, descriptor_layout: simvx.graphics.engine.VkDescriptorSetLayout, texture_layout: simvx.graphics.engine.VkDescriptorSetLayout | None = None, render_pass: simvx.graphics.engine.VkRenderPass | None = None, extent: tuple[int, int] | None = None) → tuple[simvx.graphics.engine.VkPipeline, simvx.graphics.engine.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.engine.VkDeviceMemory, data: numpy.ndarray) → None¶: Update vertex buffer contents in-place via mapped memory.

create_line_pipeline(vert_module: simvx.graphics.engine.VkShaderModule, frag_module: simvx.graphics.engine.VkShaderModule) → tuple[simvx.graphics.engine.VkPipeline, simvx.graphics.engine.VkPipelineLayout]¶: Create a line rendering pipeline. Returns (pipeline, pipeline_layout).

create_ui_pipeline(vert_module: simvx.graphics.engine.VkShaderModule, frag_module: simvx.graphics.engine.VkShaderModule) → tuple[simvx.graphics.engine.VkPipeline, simvx.graphics.engine.VkPipelineLayout]¶: Create a solid-color UI pipeline. Returns (pipeline, pipeline_layout).

push_constants(cmd: simvx.graphics.engine.VkCommandBuffer, pipeline_layout: simvx.graphics.engine.VkPipelineLayout, data: bytes | bytearray) → None¶: Push constant data (view + proj).

enable_picking(descriptor_layout: simvx.graphics.engine.VkDescriptorSetLayout, descriptor_set: simvx.graphics.engine.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 (color, width, enabled).

draw_text(text: str, x: float = 10, y: float = 10, font: str | None = None, size: float = 24.0, color: 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. color: RGBA color 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, .color, and .texture_index properties. Setting .text or .color 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.engine.VkCommandBuffer, tuple[int, int]], None] | None = None, pre_render: collections.abc.Callable[[simvx.graphics.engine.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.

`__all__`
`log`
`VkInstance`
`VkDevice`
`VkPhysicalDevice`
`VkQueue`
`VkSurfaceKHR`
`VkRenderPass`
`VkPipeline`
`VkPipelineLayout`
`VkCommandBuffer`
`VkFramebuffer`
`VkShaderModule`
`VkImage`
`VkImageView`
`VkDeviceMemory`
`VkDescriptorPool`
`VkDescriptorSetLayout`
`VkDescriptorSet`
`VkSampler`
`VkDebugUtilsMessengerEXT`

simvx.graphics.engine¶

Module Contents¶

Classes¶

Data¶

API¶

`simvx.graphics.engine`¶