Remote X11 Server und Bibliothek

Inhalt

• EINFÜHRUNG
• INSTALLATION
• VERWENDUNG
• DIE RX11 BIBLIOTHEK
  • KONZEPTE
  • VERFÜGBARE FUNKTIONEN
    • VERBINDUNG ZUM SERVER HERSTELLEN/SCHLIESSEN
    • FENSTER
    • PIXMAPS
    • GRAPHICS CONTEXT
    • FARBEN
    • AUSGABEFUNKTIONEN
• EIN BEISPIEL
  • DER SOURCECODE
  • COMPILIERUNG

Remote X11 (oder kurz RX11) versucht hier Abhilfe zu schaffen, indem es für solche Systeme eine Bibliothek mit den wichtigsten Funktionen der XWindow Bibliothek (Xlib) zur Verfügung stellt. Die Bibliothek leitet die Anforderungen an den ebenfalls mitgelieferten RX11 Server weiter, der auf einer mit X11 ausgestatteten Workstation läuft. Voraussetzung ist natürlich, daß das Client System über ein lokales Netzwerk mit dieser Workstation verbunden ist.

Im folgenden sind Installation und Verwendung der RX11 Bibliothek auf dem Clientsystem, sowie des RX11 Servers auf dem Serversystem beschrieben.

Installation

Die Compilierung auf oben genannten unterstützten System beschränkt sich auf das Auspacken des Archives rx11.tar.gz, dem Wechseln in das Verzeichnis rx11 mit dem eben ausgepackten Archiv, dem Eingeben von configure gefolgt von make all. Auf meinem System sieht das folgendermaßen aus:

 $ uname
 SunOS
 $ ls -l
 -rw-r-----   1 roemer   w93        65279 Jun 21 08:47 rx11-0.5.tar.gz
 $ gzip -dc rx11-0.5.tar.gz | tar xf -
 $ cd rx11
 $ ./configure
 configuring for SunOS...
 done. Now type make all.
 $ make all

Nachdem die Compilierung abgeschlossen ist, sollten folgende Dateien auf dem Clientsystem vorhanden sein:

libRX11.a

Die RX11 Bibliothek.

RXlib.h

RX11 Include Datei.

X.h

Eine weitere Include Datei, die von Rxlib.h benutzt wird.

client

Ein kleines Testprogramm, daß die RX11 Bibliothek verwendet.

Auf der Serverseite sollte zusätzlich im Unterverzeichnis server folgende Datei vorhanden sein:

rx11serv

Der RX11 Server.

Auf dem Serversystem sind folgende Schritte notwendig:

1. Feststellen des Rechnernames:

    $ uname -n
    tisu1
          

2. Setzen der DISPLAY Umgebungsvariable:

    $ setenv DISPLAY localhost:0
          

3. Starten des RX11 Servers:

    $ rx11serv
    Remote X11 server 0.5, Copyright (C) 1995 Kay Roemer.
          

1. Setzen der DISPLAY Umgebungsvariable. Als Hostname muß der Rechner angegeben werden, auf dem der RX11 Server läuft, im Beispiel also tisu1. Aber Vorsicht, wenn Client und Serversystem nicht in der gleichen DNS Domain liegen, muß der vollständige Rechnername angegeben werden. Hier wäre das tisu1.ti.informatik.uni-frankfurt.de.

    $ setenv DISPLAY tisu1:0
          

2. Starten des Client Programms.

    $ cd rx11
    $ ./client points
          

Wissenswert ist auch noch, daß der Server gleichzeitig mehrere Clients bedienen kann, selbst wenn diese auf verschiedenen Rechnern (z.B. auf verschiedenen Transputern) laufen.

Das oben verwendete Testprogramm kann noch andere Ausgaben erzeugen. Rufen Sie es nacheinander mit den Parametern lines, text und xlogo auf und beobachten Sie die Ausgaben.

Die RX11 Bibliothek

Die Funktionen der RX11 Bibliothek entsprechen in Parametern und Funktion soweit es geht den Funktionen in der Xlib. Deshalb ist ein Grundverständnis der Xlib Funktionalität von Nutzen bei der RX11 Programmierung. Ich verweise hier auf Band 1 der XWindow Serie von O'Reilly und Associates.

Allerdings ist die Programmierung von RX11 Anwendungen um vieles einfacher als das Entwickeln von gleichwertigen Xlib Anwendungen, da der Programmierer sich nicht um Events kümmern muß. So braucht man beispielsweise niemals Fensterinhalte neu zeichnen (Redraw), nachdem sie verdeckt waren, da der RX11 Server die Fensterinhalte zwischenspeichert und von selbst neu zeichnet.

Alle Funktionen sind in der Include Datei RXlib.h deklariert, d.h. in jedem RX11 benutzendem Programm muß diese Datei includiert werden. Der Programmcode der Bibliothek befindet sich in der Datei libRX11.a, d.h. jedes RX11 benutzende Programm muß mit dieser Bibliothek gelinkt werden.

Verfügbare Funktionen

 RXDisplay *RXOpenDisplay (char *display_name)
       

Diese Funktion taucht in jedem RX11 Programm als nahezu erste auf. Sie stellt eine Verbindung zum durch display_name spezifizierten RX11 Server her und liefert einen Zeiger auf eine RXDisplay Struktur (bzw. NULL im Fehlerfall), die in fast allen weiteren Funktionen als Parameter angegeben werden muß.

Üblicherweise wird NULL als Parameter übergeben. In diesem Fall wird der Wert der Umgebungsvariable DISPLAY verwendet.

 int RXCloseDisplay (RXDisplay *display)
       

RXCloseDisplay ist einer der letzten Funktionsaufrufe in jedem RX11 Programm. Er dient dazu, die Verbindung zum RX11 Server zu beenden.

 void RXFlush (RXDisplay *display)
       

RX11 puffert Graphikausgaben normalerweise solange, bis 100ms seit der letzten Ausgabeoperation vergangen sind. Will man die Ausgaben aber sofort sichtbar machen, kann man RXFlush aufrufen, allerdings sollte man sehr sparsam damit umgehen, da die Ausgabegeschwindigkeit unter Umständen darunter leidet.

Auf die Mitglieder der RXDisplay Struktur sollte niemals direkt zugegriffen werden. Sie enthalten aber eine Reihe nützlicher Informationen, die über vordefinierte Macros abgefragt werden können:

 int RXConnectionNumber (RXDisplay *display)
       

Liefert das Filehandle der Netzwerkverbindung zum RX11 Server.

 int RXDefaultScreen (RXDisplay *display)
       

Liefert die Nummer des Default Screens. X11 unterstützt mehere logische Screens auf einem Ausgabegerät. wenn man die Nummer eines Screens benötigt, sollte man immer die durch RXDefaultScreen gelieferte verwenden.

 Window RXRootWindow (RXDisplay *display, int screen)
       

Liefert das Handle des Root Fensters auf einem Screen.

 Window RXDefaultRootWindow (RXDisplay *display)
       

Liefert das Handle des Root Fensters aud dem Default Screen.

 RXVisual *RXDefaultVisual (RXDisplay *display, int screen)
       

Liefert einen Zeiger auf die Default RXVisual Struktur für den angegebenen Screen. Visuals geben Auskunft über die unterstützte Farbauflösung.

 RXGC RXDefaultGC (RXDisplay *display, int screen)
       

Liefert das Handle des Default Graphics Contexts für den angegebenen Screen. Ein Graphics Context (GC) speichert Informationen wie Zeichenfarbe, Füllmuster, Font, usw. und wird bei allen Zeichenfunktionen zur Festlegung der zu verwendenden Zeichenattribute angegeben.

  
 u_long RXBlackPixel (RXDisplay *display, int screen)
 u_long RXWhitePixel (RXDisplay *display, int screen)
       

Liefern die Pixel IDs zweier kontrastreicher Farben auf dem angegebenen Screen. Die tatsächlichen zugehörigen Farben sind nicht notwending schwarz und weiß.

 int RXDisplayWidth (RXDisplay *display, int screen)
 int RXDisplayHeight (RXDisplay *display, int screen)
       

Liefern Höhe und Breite des Root Fensters auf dem angegebenen Screen in Pixeln.

 int RXDisplayWidthMM (RXDisplay *display, int screen)
 int RXDisplayHeightMM (RXDisplay *display, int screen)
       

Liefern Höhe und Breite des Root Fensters auf dem angegebenen Screen in Millimetern.

 int RXDisplayPlanes (RXDisplay *display, int screen)
 int RXDisplayCells (RXDisplay *display, int screen)
       

Liefern Anzahl der Bitplanes bzw. Anzahl gleichzeitig darstellbarer verschiedener Farben (bzw. Graustufen) auf dem angegebenen Screen.

 int RXScreenCount (RXDisplay *display)
       

Liefert die Anzahl der Screens auf dem angegebenen Display.

  
 int RXDefaultDepth (RXDisplay *display, int screen)
       

Liefert die Anzahl der Bitplanes auf dem angegebenen Screen.

 Colormap RXDefaultColormap (RXDisplay *display, int screen)
       

Liefert die ID der Default Farbtabelle für den angegebenen Screen.

 Window RXCreateSimpleWindow (RXDisplay *display, Window parent,
       int xpos, int ypos, u_int width, u_int height,
       u_int border_width,
       u_long border_pixel, u_long background_pixel)
       

Diese Funktion erzeugt ein neues Fenster, daß im Vater- Fenster parent enthalten ist. Das Fenster wird sofort an Position (xpos,ypos) relativ zu parent mit der Breite width, der Höhe height, der Randbreite border_width sowie dem Hintergrundpixel background_pixel und dem Randpixel border_pixel auf den Bildschirm gebracht (gemappt).

 void RXStoreName (RXDisplay *display, Window win, char *name)
       

Ist ein Fenster ein direkter Nachkomme des Root Fensters, so erhält es vom Windowmanager einen Rahmen, eine Titelzeile und Elemente zum Verändern der Grösse und Position. Mit der Funktion RXStoreName kann der Text in der Titelzeile eines solchen Fensters win gesetzt werden.

 void RXDestroyWindow (RXDisplay *display, Window win)
       

Diese Funktion zerstört ein vorher mit RXCreateSimpleWindow erzeugtes Fenster und entfernt es vom Bildschirm.

 Pixmap RXCreatePixmap (RXDisplay *display, Drawable drawable,
       int width, int height, int depth)
       

Diese Funktion erzeugt eine Pixmap mit der Breite width, der Höhe height und depth Bits pro Pixel, die auf dem gleichen Screen wie drawable liegt. Drawable ist entweder ein Fensterhandle oder eine andere Pixmap. Der anfängliche Inhalt der Pixmap ist nicht definiert.

 void RXFreePixmap (RXDisplay *display, Pixmap pixmap)
       

RXFreePixmap zerstört die angegebene Pixmap.

• In einem Byte sind 8 Pixel untergebracht.
• Jede Zeile beginnt mit einem neuen Byte.
• Die Bitorder in einem Byte ist Little Endian, d.h. das niederwertigste Bit entspricht dem am weitesten links stehenden, das höchstwertigste dem am weitesten rechts stehenden Pixels in einem Block von acht Pixeln.

 Pixmap RXCreateBitmapFromData (RXDisplay *display, Drawable drawable,
       char *bitmap_data, int width, int height)
       

Diese Funktion erzeugt ähnlich RXCreatePixmap eine Pixmap mit Breite width und Höhe height, die aber die Tiefe 1 hat (d.h. ein Bit pro Pixel). Der Inhalt der Pixmap wird aus den XBM Daten erzeugt, die per bitmap_data übergeben werden.

 Pixmap RXCreatePixmapFromBitmapData (RXDisplay *display,
       Drawable drawable,
       char *bitmap_data, int width, int heigth,
       u_long fg_pixel, u_long bg_pixel,
       int depth);
       

RXCreatePixmapFromBitmapData erzeugt eine Pixmap mit der Breite width, der Höhe height und der Tiefe depth aus den per bitmap_data angegebenen XBM Daten. In der Pixmap werden in den XBM Daten gesetzte Bits durch das Pixel fg_pixel, nicht gesetzte Bits durch bg_pixel repräsentiert.

    
 char *RXReadXbmFile (RXDisplay *display, Drawable drawable,
       char *file_name, u_int *width_ret, u_int *height_ret,
       u_int *xhot_ret, u_int *yhot_ret)
       

Diese Funktion liest die XBM Datei file_name ein und liefert einen Zeiger auf die XBM Daten zurück. In width_ret und height_ret werden Breite und Höhe der Bitmap, in xhot_ret und yhot_ret (wenn definiert) die Koordinaten des Hotspots zurückgeliefert. Der Rückgabewert diese Funktion ist u.a. als Parameter für RXCreateBitmapFromData, RXCreatePixmapFromBitmapData usw. geeignet.

 int RXReadBitmapFile (RXDisplay *display, Drawable drawable,
       char *file_name, u_int *width_ret, u_int *height_ret,
       Pixmap *pixmap_ret,
       u_int *xhot_ret, u_int *yhot_ret)
       

Diese Funktion kombiniert RXReadXbmFile und RXCreateBitmapFromData. In pixmap_ret wird die ID der erzeugten Pixmap zurückgeliefert.

 char *RXScaleBitmapData (RXDisplay *display, char *bitmap_data,
       u_int *width_ret, u_int *height_ret,
       u_int scale_x, u_int scale_y)
       

Diese Funktion vergrößert Bitmapdaten im XBM Format. Die Vergrößerung in X Richtung wird duch scale_x, in Y Richtung durch scale_y angegeben. Beide Faktoren müssen im Bereich 1 bis 8 liegen. Die Funktion liefert einem Zeiger auf die vergößerten Bitmapdaten, sowie Breite und Höhe der vergrößerten Bitmap in width_ret bzw. height_ret zurück.

    
 void RXFree (void *data)
       

Wenn die von RXReadXbmFile oder RXScaleBitmapData gelieferten Bitmaps nicht mehr benötigt werden, müssen sie durch RXFree wieder freigegeben werden.

Bei den Funktionen zum Erzeugen und Manipulieren von GCs wird eine RXGCValues Struktur angegeben, in die man vorher die zu ändernden bzw. zu setzenden Attribute eintragen muß. Beim Funktionsaufruf wird dann die Struktur zusammen mit einer Maske angegeben, die spezifiziert, welche Felder der RXGCValues Struktur gültig sind.

 RXGC  RXCreateGC (RXDisplay *display, u_long mask, RXGCValues *gcvalues)
       

Diese Funktion erzeugt einen neuen GC mit den in gcvalues und mask angegebenen Zeichenattributen. Als Funktionswert liefert sie die ID des neu erzeugten GCs.

 void RXChangeGC (RXDisplay *display, RXGC gc, u_long mask,
       RXGCValues *gcvalues)
       

RXChangeGC ändert die durch mask angegebenen Attribute des GC gc auf die in gcvalues angegebenen Werte.

 void RXFreeGC (RXDisplay *display, RXGC gc)
       

Gibt den vorher mit RXCreateGC erzeugten GC gc wieder frei.

Im Moment kann man nur mir einer einzigen Farbtabelle arbeiten, nämlich mit der von RXDefaultColormap gelieferten.

Mit den folgenden Funktionen kann man Einträge in dieser Farbtabelle allokieren und abfragen, welche Farbe einer Pixel ID in dieser Farbtabelle zugeordnet ist. Von zentraler Bedeutung ist dabei die Struktur RXColor, die Felder für Rot-, Grün- und Blauanteile einer Farbe, sowie eine Pixel ID enthält.

 int  RXAllocColor (RXDisplay *display, Colormap cmap, RXColor *color)
       

Allokiert in der Farbtabelle cmap einen Eintrag mit der in color angegebenen Farbe (bzw. der Farbe, die der angegebenen am nächsten kommt). Man muß also vorher die Felder color.red, color.green sowie color.blue mit den RGB Werten der gewünschten Farbe ausfüllen. Liefert die Funktion einen Wert != 0 zurück, so steht nach dem Funktionsaufruf die Pixel ID des allokierten Farbtabelleneintrages in color.pixel.

 int RXAllocNamedColor (RXDisplay *display, Colormap cmap,
         char *color_name, RXColor *screen_ret, RXColor *exact_ret)
       

Diese Funktion hat den gleichen Zweck wie RXAllocColor, nur daß die gewünschte Farbe nicht als RGB Wert, sondern als Name in color_name angegeben wird. Zu diesem Zweck unterhält X11 eine große Datenbank mit allen möglichen Namen von Farben, wie zum Beispiel "white" oder "steel blue". Wenn die Funktion einen Wert != 0 zurückliefert, dann stehen nach dem Funktionsaufruf in exact_ret die exakten RGB Werte des angegebenen Names, in screen_ret die auf dem Bildschirm darstellbare Farbe, die der gewünschten am nächsten kommt. In screen_ret.pixel ist die Pixel ID des allokierten Farbtabelleneintrages zu finden.

 void RXDrawPoint (RXDisplay *display, Drawable drawable, RXGC gc,
       int x, int y)
       

Zeichnet einen Punkt in der Vordergrundfarbe an Position (x,y) in drawable.

 void  RXDrawLine (RXDisplay *display, Drawable drawable, RXGC gc,
       int x1, int y2, int x2, int y2)
       

Zeichnet eine Linie in Vordergrundfarbe von (x1,y1) nach (x2,y2) in drawable.

    
 void  RXDrawRectangle (RXDisplay *display, Drawable drawable, RXGC gc,
       int x, int y, u_int width, u_int height)
       

Zeichnet ein Recheck in Vordergrundfarbe mit Breite width+1 und Höhe height+1 an Position (x,y) in drawable.

    
 void  RXFillRectangle (RXDisplay *display, Drawable drawable, RXGC gc,
       int x, int y, u_int width, u_int height)
       

Zeichnet ein gefülltes Recheck mit aktuellem Füllmuster und Farbe mit Breite width und Höhe height an Position (x,y) in drawable.

 void  RXDrawArc (RXDisplay *display, Drawable drawable,  RXGC gc,
       int x, int y, i_int width, u_int height,
       short start_angle, short end_angle)
       

Zeichnet einen Ellipsensektor beginnend beim Startwinkel start_angle bis zum Endwinkel end_angle in Vordergrundfarbe, der in ein Rechteck mit Breite width+1 und Höhe height+1 paßt an Position (x,y) in drawable. Die Winkel werden in 64tel Grad mit negativen Werten in Urzeigersinn gemessen.

 void  RXFillArc (RXDisplay *display, Drawable drawable,  RXGC gc,
       int x, int y, i_int width, u_int height,
       short start_angle, short end_angle)
       

Zeichnet einen gefüllten Ellipsensektor beginnend beim Startwinkel start_angle bis zum Endwinkel end_angle in aktuellem Füllmuster und Farbe, der in ein Rechteck mit Breite width und Höhe height paßt an Position (x,y) in drawable. Die Winkel werden in 64tel Grad mit negativen Werten in Urzeigersinn gemessen.

 void RXDrawString (RXDisplay *display, Drawable drawable, RXGC gc,
       int x, int y, char *text, int length)
       

Zeichnet den in text angegebenen String der Länge length an Position (x,y) in drawable.

 void RXDrawImageString (RXDisplay   *display,   Drawable drawable,
       RXGC gc, int x, int y, char *text, int length)
       

Zeichnet den in text angegebenen String der Länge length an Position (x,y) in drawable. Der Text wird durch ein Rechteck in Hintergrundfarbe hinterlegt.

 void RXCopyArea (RXDisplay *display, Drawable source,
         Drawable dest, RXGC gc,
         int source_x, int source_y, u_int  width, u_int height,
         int dest_x, int dest_y)
       

Als Quelle dient ein Drawable mit gleicher Tiefe wie das Ziel.

 void RXCopyPlane (RXDisplay *display, Drawable source,
         Drawable dest, RXGC gc,
         int source_x, int source_y, u_int width, u_int height,
         int dest_x, int dest_y,
         int plane)
       

Als Quelle dient ein Drawable beliebiger Tiefe. Eine durch plane angegebene Bitplane wird daraus extrahiert und ins Ziel kopiert. In der Quellbitplane gesetzte Bits werden im Ziel durch die Vordergrundfarbe, gelöschte Bits durch die Hintergrundfarbe repräsentiert.

    
 void RXCopyBitmap (RXDisplay *display, Drawable  dest,  RXGC gc,
          char *bitmap_data, u_int bitmap_width,
          u_int bitmap_height,
          int source_x, int source_y, u_int width, u_int height,
          int dest_x, int dest_y)
       

Als Quelle dienen Bitmapdaten im XBM Format. Daraus wird mittels RXCreateBitmapFromData eine Pixmap der Tiefe 1 erzeugt und daraus dann ein Recheck mittels RXCopyPlane ins Ziel- Drawable kopiert.

 /*
  * Ein Hello World mit RX11
  */
 
 #include 
 #include 
 #include "RXlib.h"
 
 
 /*
  * Zeiger auf Display Struktur, Screen Nummer und Fenster ID
  */
 RXDisplay *dpy;
 int screen;
 Window win;
 
 int
 main (int argc, char *argv[])
 {
   RXGC gc;
 
   /*
    * Display öffnen
    */
   dpy = RXOpenDisplay (NULL);
   if (!dpy) {
       printf ("kann Display nicht oeffnen\n");
       return 0;
   }
   screen = RXDefaultScreen (dpy);
   /*
    * Default GC
    */
   gc = RXDefaultGC (dpy, screen);
 
   /*
    * Fenster erzeugen und Titel setzen
    */
   win = RXCreateSimpleWindow (dpy,  RXRootWindow  (dpy, screen),
           20, 20, 100, 100,
           2,
           RXBlackPixel (dpy, screen),
           RXWhitePixel (dpy, screen));
   RXStoreName (dpy, win, "RX11 Hello");
 
   /*
    * Text ausgeben
    */
   RXDrawString (dpy, win, gc, 5, 20, "Hello, world!",
           strlen ("Hello, world!"));
 
   /*
    * etwas warten
    */
   sleep (20);
 
   /*
    * und cleanup
    */
   RXDestroyWindow (dpy, win);
   RXCloseDisplay (dpy);
   return 0;
 }

 $ cc -I/helios/include/ -D__ARM=1 -t8 -s hello.s hello.c
 $ asm -p -o hello.o hello.s
 $ asm -f /helios/lib/cstart.o hello.o -L/helios/lib/ -llibRX11.a -o hello