mini_arcade_core.utils.profiler
===============================

.. py:module:: mini_arcade_core.utils.profiler

.. autoapi-nested-parse::

   Game core module defining the Game class and configuration.



Attributes
----------

.. autoapisummary::

   mini_arcade_core.utils.profiler.perf_logger


Classes
-------

.. autoapisummary::

   mini_arcade_core.utils.profiler.Ansi
   mini_arcade_core.utils.profiler.FrameTimingReport
   mini_arcade_core.utils.profiler.FrameTimingFormatter
   mini_arcade_core.utils.profiler.FrameTimerConfig
   mini_arcade_core.utils.profiler.FrameTimer


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

.. py:data:: perf_logger

.. py:class:: Ansi(*args, **kwds)

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


   ANSI escape codes for terminal text formatting.

   cvar RESET (str): Reset all formatting.
   cvar BOLD (str): Bold text.
   cvar DIM (str): Dim text.
   cvar RED (str): Red text.
   cvar GREEN (str): Green text.
   cvar YELLOW (str): Yellow text.
   cvar CYAN (str): Cyan text.
   cvar MAGENTA (str): Magenta text.
   cvar WHITE (str): White text.


   .. py:attribute:: RESET
      :value: '\x1b[0m'



   .. py:attribute:: BOLD
      :value: '\x1b[1m'



   .. py:attribute:: DIM
      :value: '\x1b[2m'



   .. py:attribute:: RED
      :value: '\x1b[91m'



   .. py:attribute:: GREEN
      :value: '\x1b[92m'



   .. py:attribute:: YELLOW
      :value: '\x1b[93m'



   .. py:attribute:: CYAN
      :value: '\x1b[96m'



   .. py:attribute:: MAGENTA
      :value: '\x1b[95m'



   .. py:attribute:: WHITE
      :value: '\x1b[97m'



.. py:class:: FrameTimingReport

   Report of frame timing data.

   :ivar frame_index (int): Index of the frame.
   :ivar diffs_ms (Dict[str, float]): Dictionary of time differences in milliseconds.
   :ivar total_ms (float): Total time in milliseconds.
   :ivar budget_ms (float): Frame budget in milliseconds.


   .. py:attribute:: frame_index
      :type:  int


   .. py:attribute:: diffs_ms
      :type:  Dict[str, float]


   .. py:attribute:: total_ms
      :type:  float


   .. py:attribute:: budget_ms
      :type:  float


.. py:class:: FrameTimingFormatter

   Formats a FrameTimingReport into a colored, multi-line table string.
   Keeps FrameTimer lean and avoids pylint complexity in the timer itself.

   :ivar target_fps (int): Target frames per second for budget calculation.
   :ivar top_n (int): Number of top time-consuming segments to display.
   :ivar min_ms (float): Minimum time in milliseconds to include in the top list.
   :ivar phases (tuple[tuple[str, str], ...]): Tuples of (display name, mark key)
       for table columns.


   .. py:attribute:: target_fps
      :type:  int
      :value: 60



   .. py:attribute:: top_n
      :type:  int
      :value: 6



   .. py:attribute:: min_ms
      :type:  float
      :value: 0.05



   .. py:attribute:: phases
      :type:  tuple[tuple[str, str], Ellipsis]
      :value: (('events', 'frame_start->events_polled'), ('input', 'events_polled->input_built'), ('tick',...



   .. py:method:: make_report(frame_index: int, diffs_ms: Dict[str, float]) -> FrameTimingReport

      Create a FrameTimingReport from the given diffs.

      :param frame_index: Index of the frame.
      :type frame_index: int
      :param diffs_ms: Dictionary of time differences in milliseconds.
      :type diffs_ms: Dict[str, float]
      :return: FrameTimingReport instance.
      :rtype: FrameTimingReport



   .. py:method:: format(report: FrameTimingReport) -> str

      Format the FrameTimingReport into a colored string.

      :param report: FrameTimingReport instance.
      :type report: FrameTimingReport
      :return: Formatted string.
      :rtype: str



.. py:class:: FrameTimerConfig

   Configuration for FrameTimer.

   :ivar enabled (bool): Whether timing is enabled.
   :ivar report_every (int): Number of frames between reports.


   .. py:attribute:: enabled
      :type:  bool
      :value: False



   .. py:attribute:: report_every
      :type:  int
      :value: 60



.. py:class:: FrameTimer

   Simple frame timer for marking and reporting time intervals.

   :ivar config (FrameTimerConfig): Configuration for the timer.
   :ivar formatter (FrameTimingFormatter): Formatter for timing reports.
   :ivar marks (Dict[str, float]): Recorded time marks.


   .. py:attribute:: config
      :type:  FrameTimerConfig


   .. py:attribute:: formatter
      :type:  FrameTimingFormatter


   .. py:attribute:: marks
      :type:  Dict[str, float]


   .. py:method:: clear()

      Clear all recorded marks.



   .. py:method:: mark(name: str)

      Record a time mark with the given name.

      :param name: Name of the mark.
      :type name: str



   .. py:method:: report_ms() -> Dict[str, float]

      Returns diffs between consecutive marks in insertion order.

      :return: Dictionary mapping "start->end" to time difference in milliseconds.
      :rtype: Dict[str, float]



   .. py:method:: should_report(frame_index: int) -> bool

      Determine if a report should be emitted for the given frame index.

      :param frame_index: Current frame index.
      :type frame_index: int
      :return: True if a report should be emitted, False otherwise.
      :rtype: bool



   .. py:method:: emit(frame_index: int)

      Emit a timing report to the performance logger.

      :param frame_index: Current frame index.
      :type frame_index: int