Source code for simvx.core.backend

"""Abstract backend interfaces for rendering.

This module defines the interfaces that rendering backends must implement.
Backend implementations (SDL3, Vulkan) should provide concrete implementations
of these abstract classes.
"""


from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from .graphics.material import BaseMaterial
    from .graphics.mesh import BaseMesh

log = logging.getLogger(__name__)




@runtime_checkable
class RenderBackend(Protocol):
    """Abstract interface for rendering backends.

    Any rendering backend (SDL3, Vulkan, etc.) must implement these methods
    to be compatible with the SimVX core engine.
    """



    def init(self, width: int, height: int, title: str) -> None:
        """Initialize the backend with window dimensions and title.

        Args:
            width: Window width in pixels.
            height: Window height in pixels.
            title: Window title text.
        """
        ...




    def begin_frame(self) -> None:
        """Called at the beginning of each frame.

        Used to clear buffers, reset state, and prepare for rendering.
        """
        ...




    def end_frame(self) -> None:
        """Called at the end of each frame.

        Used to present the rendered frame to the display.
        """
        ...




    def render_mesh(
        self,
        mesh: BaseMesh,
        material: BaseMaterial,
        model_matrix: object,  # glm.mat4 or similar
    ) -> None:
        """Render a mesh with the given material and transform.

        Args:
            mesh: The mesh geometry to render.
            material: Material defining appearance.
            model_matrix: World-space transform matrix.
        """
        ...




    def cleanup(self) -> None:
        """Clean up backend resources.

        Called when the application shuts down.
        """
        ...






class Renderer2D(Protocol):
    """2D rendering interface.

    Backends supporting 2D rendering should implement this protocol.
    """



    def draw_filled_rect(
        self, x: float, y: float, width: float, height: float, colour: tuple[int, int, int, int]
    ) -> None:
        """Draw a filled rectangle.

        Args:
            x: Left edge x coordinate.
            y: Top edge y coordinate.
            width: Rectangle width.
            height: Rectangle height.
            colour: RGBA colour tuple (0-255).
        """
        ...




    def draw_line(self, x1: float, y1: float, x2: float, y2: float, colour: tuple[int, int, int, int]) -> None:
        """Draw a line.

        Args:
            x1: Start x coordinate.
            y1: Start y coordinate.
            x2: End x coordinate.
            y2: End y coordinate.
            colour: RGBA colour tuple (0-255).
        """
        ...




    def draw_text(self, text: str, x: float, y: float, scale: float, colour: tuple[int, int, int, int]) -> None:
        """Draw text.

        Args:
            text: Text string to render.
            x: X coordinate.
            y: Y coordinate.
            scale: Text scale/size.
            colour: RGBA colour tuple (0-255).
        """
        ...




    def text_width(self, text: str, scale: float) -> float:
        """Get the width of text when rendered.

        Args:
            text: Text string to measure.
            scale: Text scale/size.

        Returns:
            Width of the text in pixels.
        """
        ...






class Renderer3D(Protocol):
    """3D rendering interface.

    Backends supporting 3D rendering should implement this protocol.
    """



    def render(self, camera_view_matrix: object, camera_projection_matrix: object) -> None:
        """Render the scene with the given camera matrices.

        Args:
            camera_view_matrix: Camera view matrix (glm.mat4 or similar).
            camera_projection_matrix: Camera projection matrix.
        """
        ...