"""IOverlayLayer — interface for pluggable overlay layers drawn on CameraView."""

from __future__ import annotations

from abc import ABC, abstractmethod

from PySide6.QtCore import QRect
from PySide6.QtGui import QPainter


class IOverlayLayer(ABC):
    """
    Interface for a single overlay layer drawn over the camera frame.

    Each layer receives the active QPainter and the video rect (the letterboxed
    area where the camera image was drawn) so it can position elements relative
    to the actual video content if needed.

    To add a new overlay (e.g. YOLO bboxes):
        1. Subclass IOverlayLayer.
        2. Implement paint().
        3. Register with CameraView.add_overlay_layer().

    No Qt subclassing is required — layers are plain Python objects.
    """

    @property
    def name(self) -> str:
        """Human-readable identifier used in menus / debug output."""
        return type(self).__name__

    @property
    def visible(self) -> bool:
        """Whether this layer should be drawn."""
        return self._visible

    @visible.setter
    def visible(self, value: bool) -> None:
        self._visible = value

    def __init__(self) -> None:
        self._visible: bool = True

    @abstractmethod
    def paint(self, painter: QPainter, video_rect: QRect) -> None:
        """
        Draw this layer.

        Args:
            painter:    Active QPainter on the CameraView widget.
                        Caller saves/restores painter state around each layer.
            video_rect: The QRect where the camera image was drawn (letterboxed).
                        Use this to position overlays relative to the video image.
        """