mini_arcade_core.engine.render.viewport
=======================================

.. py:module:: mini_arcade_core.engine.render.viewport

.. autoapi-nested-parse::

   Viewport management for virtual to screen coordinate transformations.



Classes
-------

.. autoapisummary::

   mini_arcade_core.engine.render.viewport.ViewportMode
   mini_arcade_core.engine.render.viewport.ViewportState
   mini_arcade_core.engine.render.viewport.Viewport


Module Contents
---------------

.. py:class:: ViewportMode

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Viewport scaling modes.

   :cvar FIT: Scale to fit within window, preserving aspect ratio (letterbox).
   :cvar FILL: Scale to fill entire window, preserving aspect ratio (crop).


   .. py:attribute:: FIT
      :value: 'fit'



   .. py:attribute:: FILL
      :value: 'fill'



.. py:class:: ViewportState

   Current state of the viewport.

   :ivar virtual_w (int): Virtual canvas width.
   :ivar virtual_h (int): Virtual canvas height.
   :ivar window_w (int): Current window width.
   :ivar window_h (int): Current window height.
   :ivar mode (ViewportMode): Current viewport mode.
   :ivar scale (float): Current scale factor.
   :ivar viewport_w (int): Width of the viewport rectangle on screen.
   :ivar viewport_h (int): Height of the viewport rectangle on screen.
   :ivar offset_x (int): X offset of the viewport rectangle on screen.
   :ivar offset_y (int): Y offset of the viewport rectangle on screen.


   .. py:attribute:: virtual_w
      :type:  int


   .. py:attribute:: virtual_h
      :type:  int


   .. py:attribute:: window_w
      :type:  int


   .. py:attribute:: window_h
      :type:  int


   .. py:attribute:: mode
      :type:  ViewportMode


   .. py:attribute:: scale
      :type:  float


   .. py:attribute:: viewport_w
      :type:  int


   .. py:attribute:: viewport_h
      :type:  int


   .. py:attribute:: offset_x
      :type:  int


   .. py:attribute:: offset_y
      :type:  int


.. py:class:: Viewport(virtual_w: int, virtual_h: int, mode: ViewportMode = ViewportMode.FIT)

   Manages viewport transformations between virtual and screen coordinates.


   .. py:method:: set_virtual_resolution(w: int, h: int)

      Set a new virtual resolution.

      :param w: New virtual width.
      :type w: int

      :param h: New virtual height.
      :type h: int



   .. py:method:: set_mode(mode: ViewportMode)

      Set a new viewport mode.

      :param mode: New viewport mode.
      :type mode: ViewportMode



   .. py:method:: resize(window_w: int, window_h: int)

      Resize the viewport based on the current window size.

      :param window_w: Current window width.
      :type window_w: int

      :param window_h: Current window height.
      :type window_h: int



   .. py:property:: state
      :type: ViewportState


      Get the current viewport state.

      :return: Current ViewportState.
      :rtype: ViewportState

      :raises RuntimeError: If the viewport has not been initialized.


   .. py:method:: screen_to_virtual(x: float, y: float) -> tuple[float, float]

      Convert screen coordinates to virtual coordinates.

      :param x: X coordinate on the screen.
      :type x: float

      :param y: Y coordinate on the screen.
      :type y: float

      :return: Corresponding virtual coordinates (x, y).
      :rtype: tuple[float, float]



   .. py:method:: virtual_to_screen(x: float, y: float) -> tuple[float, float]

      Convert virtual coordinates to screen coordinates.

      :param x: X coordinate in virtual space.
      :type x: float

      :param y: Y coordinate in virtual space.
      :type y: float

      :return: Corresponding screen coordinates (x, y).
      :rtype: tuple[float, float]