***************************
* Raspberry Pi Beamertool *
***************************
Original von Moritz <mo@blog-srv.net>, portiert auf Raspberry Pi 4 /
Raspberry Pi OS Lite (64bit) bzw. Debian 13 "trixie".

--------------------------------
Architektur: mpv als alleiniger Anzeigepfad
--------------------------------
Das Original nutzte den alten Broadcom-"Legacy"-Grafikstack
(bcm_host/Dispmanx/EGL, OpenGL ES 1.1 Fixed-Function, OpenMAX IL/ilclient),
der auf dem Pi 4/Debian 13 nicht mehr existiert. Der erste Portierungs-
Ansatz (SDL2 mit dem "kmsdrm"-Videotreiber, direkt auf den Bildschirm
gezeichnet) erwies sich in der Praxis auf manchen Pi4/Debian-13-
Kombinationen als unzuverlässig - trotz erkanntem Monitor blieb der
Bildschirm mitunter schwarz, ohne dass ein Fehler geloggt wurde.

Die jetzige Architektur nutzt daher denselben Ansatz wie das parallel
entwickelte Python-Schwesterprojekt (rpi-beamertool v3, Pi Zero 2 W):
EINE dauerhaft laufende **mpv-Instanz ist der alleinige Anzeigepfad**.
mpv's eigener GPU/DRM-Renderpfad hat sich als deutlich robuster erwiesen.

 - Unser Programm zeichnet die Laser-Simulation komplett UNSICHTBAR im
   Hintergrund (EGL "surfaceless"-Kontext über /dev/dri/renderD128 - kein
   Bildschirm, kein Connector, keine Monitor-Erkennung nötig) und schickt
   die fertigen Frames als Rohvideo-Strom über eine benannte Pipe (FIFO)
   an mpv (Demuxer "rawvideo").
 - Der Media Player (Fotos/Videos aus ./media/) schaltet mpv per IPC-
   Kommando ("loadfile") stattdessen direkt auf die gewählte Datei um -
   mpv decodiert selbst, unser Programm muss dafür nichts mehr rendern.
 - Umschalten zwischen beiden Modi passiert nahtlos durch ein erneutes
   "loadfile" per IPC.

Das ist deutlich robuster, hat aber eine Konsequenz: Video-**Gobos**
innerhalb der Laser-Simulation (Textur-Dateien wie z.B. 194.h264) werden
aktuell NICHT dekodiert (ein zweiter Video-Decoder-Prozess würde mit dem
alleinigen mpv kollidieren) - sie zeigen einen blauen Platzhalter. Das
Kernfeature (DMX-gesteuerte Gobos/Muster als PNG/GIF) sowie der komplette
Media Player sind davon nicht betroffen.

Weitere Änderungen:
 - Autostart über systemd (rpi-beamertool.service) statt /etc/rc.local
 - Installer nutzt apt statt aptitude und baut aus dem Quellcode
 - Konfigurierbare Streaming-Auflösung/Framerate (config.txt:
   RENDER_WIDTH/RENDER_HEIGHT/RENDER_FPS, Standard 960x540@25fps -
   Kompromiss aus Bildschärfe und CPU-/Pipe-Last auf dem Pi4)

Unverändert/portabel geblieben: Art-Net-Empfang, ncurses-Konsole,
Canvas-/Zoom-/Rotationslogik, GIF-/PNG-Loader (für die normalen
Bild-Gobos), das PHP-Webinterface (tools/index.php).

-----------------------------
Media Player
-----------------------------
Zusätzlich zur Laser-Simulation gibt es einen Media Player, der Fotos/
Videos aus dem Verzeichnis /opt/rpi-beamertool/media/ abspielt (mpv spielt
sie direkt ab - Formate: alles was mpv kann, u.a. png/jpg/jpeg/bmp/gif/
mp4/mkv/mov/avi/webm). Er wird über einen eigenen, vom Laser-Kanalblock
unabhängigen Art-Net-Kanal gesteuert (config.txt: MEDIA_PLAYER_CHANNEL,
absoluter Kanal 1-512):

 - Wert 0: normale Laser-Simulation (Standard)
 - Wert 1-255: Media Player aktiv, der Wert wählt die Datei aus dem
   alphabetisch sortierten Verzeichnisinhalt (in Einerschritten, mit
   Wraparound falls weniger Dateien vorhanden sind als DMX-Werte)

-----------------------------
Installation
-----------------------------
Getestet mit Raspberry Pi OS Lite (64bit, Bookworm/Trixie) und Debian 13
"trixie" auf einem Raspberry Pi 4.

Automatisch (empfohlen):

    sudo ./tools/rpi-bt-install.sh

Das Skript installiert die Build-Abhängigkeiten, baut das Programm, kopiert
alles nach /opt/rpi-beamertool und richtet den systemd-Autostart ein.

Manuell:

    sudo apt-get update
    sudo apt-get install build-essential cmake pkg-config \
        libegl1-mesa-dev libgles2-mesa-dev libncurses-dev mpv ffmpeg

    mkdir build && cd build
    cmake ..
    make -j$(nproc)
    ./rpi-beamertool

-----------------------------
Bedienung / Deinstallation
-----------------------------
    systemctl start rpi-beamertool      # bzw. tools/rpi-bt-start.sh
    systemctl restart rpi-beamertool    # bzw. tools/rpi-bt-restart.sh
    journalctl -u rpi-beamertool -f     # Logs
    sudo ./tools/rpi-bt-uninstall.sh    # deinstallieren

-----
INFO:
-----
 - Braucht einen angeschlossenen, erkannten Monitor (mpv zeigt sonst
   naturgemäß nichts an), aber KEINEN eigenen Bildschirmzugriff für unser
   Programm selbst mehr - dadurch auch kein TTY/VT-Gerangel mehr wie bei
   der direkten kmsdrm-Variante.
 - Der ausführende Nutzer muss in den Gruppen "video" und "render" sein
   (macht der Installer automatisch); nach dem ersten Hinzufügen ggf.
   einmal neu einloggen/rebooten.
 - Bei Rucklern in der Laser-Simulation zuerst RENDER_WIDTH/RENDER_HEIGHT/
   RENDER_FPS in config.txt reduzieren.
 - Video-Gobos (Textur-Dateien wie z.B. 194.h264) werden aktuell nicht
   dekodiert (blauer Platzhalter, siehe oben) - PNG/GIF-Gobos sind davon
   nicht betroffen.
 - Die Berechnung der automatischen Drehungen und des Shutters erfolgt pro
   Frame (wie im Original/Windows-Beamertool). Besser wäre eine
   Berechnung pro Zeit, da die Framerate bei vielen großen Gobos absinken
   kann.
 - Der Animationsregler ist wirkungslos, das Steuern von GIF-Animationen
   ist (noch) nicht implementiert.
 - Man kann wählen, ob sich die Zoomfunktion wie im Original verhält oder
   in einen Kreis zoomt.
