doc: update

1 files changed, 98 insertions, 51 deletions

diff --git a/projekt_doku.asciidoc b/projekt_doku.asciidoc
index 41bfa73..9c26a37 100644
--- a/projekt_doku.asciidoc
+++ b/projekt_doku.asciidoc
@@ -49,7 +49,7 @@ Für die Bildübertragung wird 'DirectFB Voodoo' eingesetzt.
 == Ist-Zustand
 
 Verwendet werden Fernseher der 7000er Serie von Philips, auf die eine,
-direkt vom Hersteller erweiterte Firmware geladen wird. Diese beinhaltet die
+direkt vom Hersteller überarbeitete Firmware geladen wird. Diese beinhaltet die
 'JointSpace' Erweiterung.
 
 Als Datenquelle dient eine Windows-Installation in einer virtuellen Maschinen,
@@ -58,11 +58,12 @@ verwendet.
 
 Die einzelnen Fernseher sind alle in eigenen Netzen, da zum Verbindungsaufbau
 ein Netzwerk-Broadcast genutzt wird und sich so die Fernseher gegenseitig
-stören würden, wenn in einem Netzwerk enthalten.
+stören würden, wenn sie Teil ein und der selben Netzwerk-Broadcast-Domain
+wären.
 
-Der Firefox-Browser wird für die Darstellung im Vollbildmodus eingesetzt, da
-er unter Windows einer der stabilsten und ausgetestetsten, standardkonformer
-Browser ist.
+Der Firefox-Browser wird mit Hilfe seines Vollbildmodus' für die Darstellung
+eingesetzt, da er unter Windows einer der stabilsten und ausgetestetsten,
+standardkonformen Browser ist.
 
 Die Fernseher bieten eine native Auflösung von +1920x1080+ Pixeln,
 die Remote-Anzeige funktioniert aber nur bis zur Auflösung von +1280x720+
@@ -89,11 +90,11 @@ Als Basis für die Programmtechnische Umsetzung dient der Bestehende
 Windows-Client Pluggit, sodass die bereits ausgetestete Remote-Rendering
 Infrastruktur wiederverwendet werden kann.
 
-Pluggit wurde so verändert, dass es X11-Protokoll anstatt der WinAPI verwendet
-wird, um den Inhalt eines Fensters oder des ganzen Framebuffers anzuzeigen.
+Pluggit wurde so verändert, dass das X11-Protokoll anstatt der WinAPI verwendet
+wird, um den Inhalt eines Fensters oder auch des ganzen Framebuffers anzuzeigen.
 
 Dazu ist eine 'SourceX11' Klasse notwendig, die das in Pluggit enthaltene
-Interface 'Source' implementiert. 
+Interface 'Source' implementiert, und somit als Datenlieferer agiert. 
 
 // TODO: Graph?
 
@@ -103,15 +104,16 @@ Die DirectFB-Voodoo Plattform nutzt als Standardmethode zum Verbindungsaufbau
 einen Broadcast Request, um verfügbare Anzeigegeräte zu finden.
 Dies ist für den Einsatz im Heimnetzwerk gedacht, bei dem der
 Verbindungsaufwand möglichst gering gehalten werden soll.
-Sind mehrere der Fernseher in einem Netzwerk, so ist nicht eindeutig
+Sind mehrere der Fernseher in einer Broadcast-Domain, so ist nicht eindeutig
 definiert, welcher zuerst auf den Broadcast antwortet, und dadurch für die
 Verbindung ausgewählt werden wird. 
-Aus diesem Grund ist eine sofortige Unicast-Verbindung nötig.
+Aus diesem Grund ist eine ausschließliche Unicast-Verbindung nötig.
 
-Die Bibliothek bietet kein direktes API, um die Ziel-Addresse zu verarbeiten.
-Die Initialisierungsmethode +DirectFB::Init()+ erwartet einen Argumentenzähler
-und -vektor. Dieser Vektor bezieht sich auf die Kommandozeilen Argumente,
-im folgenden beispielhaft dargestellt:
+Die Bibliothek bietet kein direktes API, um die Ziel-Adresse zu verarbeiten.
+Die Initialisierungsmethode +DirectFB::Init()+ erwartet aber einen
+Argumentenzähler und -vektor.
+Dieser Vektor bezieht sich auf die Kommandozeilen Argumente, im folgenden
+C-Code ist dies Beispielhaft dargestellt:
 
 [source,c]
 ----
@@ -125,13 +127,18 @@ main(int argc, char *argv[])
 }
 ----
 
++DirectFB::Init()+ würde nun Kommandozeilen parameter beginnend mit +--dfb:+
+auswerten. In diesem Fall würde +--dfb:remote=ip.address+ übergeben werden,
+und somit implizit, das Voodoo-Discovery (Broadcast) ausgelassen,
+und anstatt dessen direkt zur IP verbunden.
+
 ==== Verbindungsabbruch
 Bricht die Verbindung ab -- z.B. durch Ausschalten des Fernsehers oder durch
 Auswählen einer anderen Quelle -- wird dies durch die DirectFB Bibliothek
 nicht an die Anwendung signalisiert.
 
 Im produktiven Einsatz ist es bei Remote-Steuerung deshalb nicht zu erkennen,
-ob die Verbindung besteht. Im weiteren ist auch keine automatisierte
+ob die Verbindung noch besteht. Außerdem ist auch keine automatisierte
 Neuverbindung möglich.
 
 //die Anwendung signalisiert.
@@ -146,7 +153,8 @@ und bricht die Programmausführung ab.
 Ein Shell-Script das 'Pluggit' überwacht, erkennt dies am Rückgabe-Status des
 Pluggit-Prozesses und startet diesen neu.
 
-//== Webbrowser-Rendering
+//TODO: Add shell script here
+
 
 === Framebuffer Größenlimit
 Bei der Verwendung von 'Pluggit' unter Windows besteht das Problem, dass eine
@@ -157,6 +165,8 @@ Bei Verwendung von z.B. einer +1920x1080+ Auflösung -- bei einem Fernseher,
 der diese Auflösung per HDMI unterstützt -- signalisiert das API
 einen Fehler, dass ein invalides Argument übergeben wurde.
 
+Diese Limitierung ist also nicht zu beheben und muss als gegeben hingenommen
+werden.
 
 === Framebuffer Auslesen
 Das X11-Protokoll bietet die Möglichkeit den angezeigten Framebuffer
@@ -165,29 +175,46 @@ Das X11-Protokoll bietet die Möglichkeit den angezeigten Framebuffer
 Darüber hinaus gibt es eine Anbindung an +shmget(2)+, sodass Unix
 Shared-Memory verwendet werden kann.
 Dies bietet den Vorteil, dass die Framebuffer-Daten nicht über den
-X11-Protokoll-Socket übertragen werden müssen, sondern direkt gelesen werden
-können.
-Es wird ein X11-Pixmap erzeugt, welchem ein auf XImage auf Shared-Memory Basis
+X11-Protokoll-Socket übertragen werden müssen -- wie bei +XGetSubImage+,
+sondern direkt gelesen werden können.
+Es wird ein X11-Pixmap erzeugt, welchem ein XImage auf Shared-Memory Basis
 zugrunde liegt.
 Zum Auslesen wird nun +XCopyArea(3)+ mit dem X11-Pixmap als Argument
-aufgerufen. Der X-Server schreibt in der Folge den angefragten Bildinhalt
+ausgeführt. Der X-Server schreibt in der Folge den angefragten Bildinhalt
 in den Shared-Memory, 
 
-
-=== Multi-Client
+=== Multiple Streams
 
 Teil der Anforderung ist, mehrere Fernseher gleichzeitig mit unterschiedlichen
 Bildern zu beliefern.
+Dazu ist es notwendig Bilddaten aus mehreren Browser-Fenstern auszulesen.
+
+Theoretisch sind mehrere Methoden denkbar:
+Es könnten mehrere X-Server gestartet und pro X-Server immer ein
+Browser im Vollbild-Modus angezeigt werden.
+Weiterhin könnten auf einem X-Server die Browser auf Virtuelle Desktops
+verteilt werden.
+Diese Methoden scheitern am Damage-Handling, das bewirkt, dass nicht sichtbare
+Teile eines Fensters nicht (neu)gezeichnet werden.
 
-Um mehrere Fenster darzustellen, wird ein großer Anzeigebereich benötigt.
-Mit 'XRandR' wird dies durch folgenden Aufruf erreicht:
+Eine weitere Möglichkeit wäre OffScreen-Rendering.
+Dies muss aber direkt von Browsern unterstützt werden, wofur keine
+Unterstützung festgestellt werden konnte.
+
+Deshalb wird um mehrere Fenster darzustellen, ein großer Anzeigebereich
+benötigt, auf dem alle Fenster gleichzeitig Platz finden.
+Mit dem X11 'XRandR'-Protokoll ist die möglich und wird durch folgenden Aufruf
+erreicht:
 
 [source,sh]
 ----
-xrandr --fb $((1280*3+10))x768
+xrandr --fb $((1280*3+10))x768 # <1>
 ----
+<1> Es werden 10 hinzuaddiert, damit Platz für Fensterrahmen bleibt.
+
+In Abbildung 2 ist eine Beispiel-Konfiguration für 3 Multiple Streams aufgeführt.
 
-.X11-Fenster Konfiguration
+.Multiple Browser-Fenster 
 image::framebuffer.svg[]
 
 === Browser
@@ -199,32 +226,36 @@ wird.
 
 In Betracht kommt auf Grund der Bekanntheit und Stabilität der
 Firefox-Browser.
-Dieser kann nur im Vollbild-Modus so konfiguriert werden, dass nur der Inhalt
-im X11-Fenster -- welches ausgelesen werden soll -- angezeigt wird, Menus und
-Scrollbars sind im normalen Floating-Modus immer vorhanden.
+Dieser kann allerdings nur im Vollbild-Modus so konfiguriert werden, dass nur
+der Inhalt im X11-Fenster -- welches ausgelesen werden soll -- angezeigt wird,
+Menus und Scrollbars sind im normalen Floating-Modus immer vorhanden.
 Ein weiteres Problem stellt die eindeutige Adressierung der WindowID, bei
-Veränderung mehrerer Firefox-Fenster.
+Verwendung mehrerer Firefox-Fenster.
 Es gibt keine direkte Möglichkeit die WindowID zu erhalten, nur über Matching
 des Titels des Firefox-Fensters.
-Die Verwendung für mehrere Infoscreens würde es nötig machen den Titel des
-angezeigten Inhalts zu wissen, und in der Programmlogik zu berücksichtigen.
-Eine Veränderung des Inhalts würde damit auch eine Anpassung des Programms
-erfordern.
+Die Verwendung für mehrere Infoscreens würde es aber nötig machen den Titel
+des angezeigten Inhalts zu wissen, und in der Programmlogik zu
+berücksichtigen.  Eine Veränderung des Inhalts würde damit auch eine Anpassung
+des Programms erfordern. Dies ist nicht wünschenswert.
 
 Deshalb wird ein Web-Browser benötigt, der es ermöglicht nur den Inhalt der
 Website im X11-Fenster darzustellen.
-Der Browser 'Surf' footnote:[http://surf.suckless.org] von 'suckless.org' ist
+Der Browser 'surf' footnote:[http://surf.suckless.org] von 'suckless.org' ist
 mit dem Prinzip erstellt worden, in andere Programme über das X11-XEmbed
-Protokoll eingebettet zu werden, z.b. um mehrere Instanzen in einem
+Protokoll eingebettet zu werden, z.B. um mehrere Instanzen in einem
 Tab-Manager zu einzubetten.
 
 Dies ermöglicht per Design zwei Vorteile:
 
- - Die WindowID wird auf +stdout+ ausgegeben. +
-   (Kann demzufolge als Parameter an Pluggit übergeben werden.)
+ - Die WindowID von 'surf' wird auf +stdout+ ausgegeben. +
+   (Kann demzufolge einfach als Parameter an Pluggit übergeben werden.)
  - Keine Bedienelemente vorhanden, denn der Browser wird über X11-Properties
    gesteuert -- das erlaubt Scripting.
 
+Im weiteren setzt 'surf' auf WebKit/GTK footnote:[http://webkitgtk.org/], und
+besitzt somit, genauso wie Firefox, auch ein standardkonformes und
+ausgetestetes Framework.
+
 == Test
 
 Getestet wurde jeweils mit der Infoscreen-Website
@@ -233,17 +264,23 @@ des Fachbereichs EuI:
 
 Da während der Entwicklung nicht dauerhaft Philips-Fernseher zur Verfügung
 standen, wurde der durch das 'JointSpace'-Projekt als VMWare-Virtuelle
-Maschine bereitgestellte Simulator mit QEMU verwendet.
+Maschine bereitgestellte Simulator mit QEMU verwendet:
 
+[source,sh]
+----
+qemu-system-x86_64 -enable-kvm -m 256 -hda jointspace.vmdk \
+	-net nic -net tap,ifname=tap0,script=no,downscript=no
+----
 
 Das Anzeigen des Browser-Inhaltes und die korrekte Wiedergabe des Videos
 entscheiden über das Bestehen des Tests.
 
 == HowTo
 
-=== Linux Betriebssystem
-Ein minimales Betriebssystem wie Gentoo Linux oder Arch Linux kann als Client
-genutzt werden.
+Ein auf GNU/Linux basierendes Betriebssystem ist Vorraussetzung für die
+Einrichtung des Clients. Ein minimales System wie Gentoo Linux oder Arch Linux
+eignet sich auf Grund der Konfigurierbarkeit bezüglich erwünschter Packete
+sehr gut.
 
 === System Vorraussetzungen
 
@@ -252,7 +289,7 @@ die dazugehörige 'libX11'.
 Das Utility wmctrl wird zur Positionierung und Größenfestlegung der Browser
 genutzt. Der Browser selbst ist 'surf'.
 
-Die Installationsroutine, beispielhaft für Gentoo Linux:
+Die daraus resultierende Installationsroutine, beispielhaft für Gentoo Linux:
 
 [source,sh]
 ----
@@ -261,7 +298,7 @@ emerge -va xorg-server libX11 xrandr wmctrl surf
 
 === DirectFB
 
-Für diese Arbeit wurde die, zum Zeitpunkt der Bearbeitung, neuste Version von
+Für diese Arbeit wurde die, zum Zeitpunkt der Bearbeitung, neueste Version von
 'DirectFB' verwendet:
 DirectFB141_source_1.3.1beta5.7z
 footnote:[http://sourceforge.net/projects/jointspace/files/remote_applications_SDK/]
@@ -271,11 +308,22 @@ footnote:[http://sourceforge.net/projects/jointspace/files/remote_applications_S
 7z x DirectFB141_source_1.3.1beta5.7z
 ----
 
-Die Sourcen, inklusive benötigter Patches (mit GIT-History), sind auch im
-beiliegenden Archiv enthalten.
+Diese sollte aber nur zum Vergleich herbei gezogen werden, denn die Sourcen,
+inklusive benötigter Patches (mit GIT-History), sind bereits im
+beiliegenden Dokumentationsverzeichnis enthalten.
+
+Bei späteren Updates auf neue DirectFB Versionen sollten die Patches aus dem
+GIT-Repository neu eingespielt werden.
 
 === Pluggit
 
+Dieser Abschnitt beschreibt die eigentliche Kompilierung der Toolchain.
+Das Dokumentationsverzeichnis enthält ein Makefile, welches ein pluggit target
+bereitstellt.
+Dies leitet die Kompilierung von 'DirectFB' ein und führt danach die
+Übersetzunbg von 'pluggit' selbst aus.
+
+
 [source,make]
 -------------------------------------------------------------------------
 .PHONY: pluggit
@@ -286,11 +334,10 @@ pluggit:
 -------------------------------------------------------------------------
 
 <1> In der Entwicklungsphase ist es notwendig, dass pluggit neu gelinkt wird,
-wenn directfb verändert wird.
-<2> Der DirectFB package baut die Bibliothek und kopiert Header an die
+wenn DirectFB verändert wird.
+<2> Das DirectFB-Packet baut die Bibliothek und kopiert Header an die
 benötigten Stellen.
 
-
 Für die Übersetzung von DirectFB und Pluggit muss also außschließlich
 folgender Befehl im Quellverzeichnis des Projekts ausgeführt werden:
 
@@ -302,10 +349,10 @@ make pluggit
 == Bewertung & Ausblick
 
 Die Performanz ist durch das ständige Übertragen kompletter Bilder
-eingeschränkt auf die Übertragungsbandbreite des Kanals.
+beschränkt auf die Übertragungsbandbreite des Kanals.
 Zur Optimierung könnte ein direktes Remote-Rendering des WebBrowsers, bzw
 dessen Backends, verwendet werden.
-Ein weiterführender Ansatz wäre es deshalb, das sich in Entwicklung befindende
+Ein weiterführender Ansatz wäre es deshalb, das, sich in Entwicklung befindende
 -- und deshalb zum Zeitpunkt dieser Arbeit noch nicht verwendbare --
 WebKit-DirectFB footnote:[http://git.directfb.org/?p=libs/WebKitDFB.git;a=summary]
 backend zu diesem Zweck zu nutzen.