                        Neue Funktionen in NVDI 2.50
                        ============================

   Nachfolgend werden in dieser Datei die neuen Funktionen aufgefhrt, die 
   NVDI fr Bildschirmausgaben anbietet.

1. Off-Screen Bitmaps
=====================

   Fr viele Anwendungen ist es sehr ntzlich, wenn Zeichenfunktionen nicht 
   direkt auf den Bildschirm, sondern auf einen nicht sichtbaren Bildschirm 
   angewendet werden knnen. Einen derartigen "versteckten" Bildschirm 
   nennt man Off-Screen-Bitmap.
   Zur Erzeugung von Off-Screen-Bitmaps dient die Funktion OPEN BITMAP.
   Man kann ihr entweder die Gre eines Bitmap angeben, die Sie allozieren 
   soll, oder ihr eine Bitmap bergeben. Die Bitmap wird im gleichen Format 
   wie die des Bildschirms verwaltet, wodurch schnelles Kopieren zwischen 
   beiden mglich ist.
   Die Funktion CLOSE BITMAP schliet eine mit OPEN BITMAP erzeugte Bitmap 
   und  gibt gegebenenfalls deren Speicher zurck.


      OPEN BITMAP (VDI 100, 1)

      void  v_opnbm( WORD *work_in, MFDB *bitmap, WORD *handle, WORD *work_out )
      {
         pb[1] = work_in;
         pb[3] = work_out;
         pb[4] = work_out + 45;

         contrl[0] = 100;
         contrl[1] = 0;
         contrl[3] = 20;
         contrl[5] = 1;
         *(MFDB *)&contrl[7] = bitmap;

         vdi();

         *handle = contrl[6];
         pb[1] = intin;
         pb[3] = intout;
         pb[4] = ptsout;
      }

      Bestckung der VDI-Arrays:

       Feldelement      | Belegung
      ------------------|-------------------------------------------
      contrl[0]         | 100    Funktionsnummer fr v_opnbm()
      contrl[1]         | 0      Anzahl der Eintrge in ptsin
      contrl[2]         | 6      Anzahl der Eintrge in ptsout
      contrl[3]         | 20     Anzahl der Eintrge in intin
      contrl[4]         | 45     Anzahl der Eintrge in intout
      contrl[5]         | 1      Unterfunktionsnummer fr v_opnbm()
      contrl[6]         | handle
      contrl[7..8]      | bitmap Zeiger auf einen MFDB der Bitmap
                        |
      intin[0..19]      | work_in[0..19]
                        |
      intout[0..44]     | work_out[0..44]
                        |
      ptsout[0..11]     | work_out[45..56]


      handle:           graf_handle()

      work_in[0..10]:   wie bei v_opnwk()/v_opnvwk() definiert
      work_in[0]:       Getrez() + 2
      work_in[11]:      Breite -1 (z.B. 1279)
      work_in[12]:      Hhe -1 (z.B. 959)
      work_in[13]:      Breite eines Pixels in Mikrometern
      work_in[14]:      Hhe eines Pixels in Mikrometern
      work_in[15..19]:  reserviert, sollte 0 enthalten

      Achtung: Der Eintrag work_in[11] sollte bei Addition von 1 ohne Rest 
               durch 16 teilbar sein. Andernfalls rundet der VDI-Treiber 
               auf den nchsthheren ohne Rest teilbaren Wert.

      Hinweis: Wird fr Pixelbreite und -Hhe 0 angegeben, so werden die 
               Werte des Bildschirms benutzt.

      work_out[0..1]:   wie bei v_opnwk()/v_opnvwk() definiert
      work_out[2]:      0
      work_out[3..38]:  wie bei v_opnwk()/v_opnvwk() definiert
      work_out[39]      0 (keine Hardware-Palette vorhanden, da Bitmap)
      work_out[39..56]: wie beiv_opnwk()/v_opnvwk() definiert

      bitmap:           Zeiger auf einen MFDB

      Falls bitmap->fd_addr gleich NULL ist, so wird anhand der Gren- 
      angaben in work_in Speicher fr die Bitmap angefordert (die Bitmap 
      wird im Gegensatz zu v_opnvwk() gelscht).

      Um eine Bitmap im gertespezifischen Format zu ffnen, mu 
      bitmap->fd_nplanes eine Null oder die Ebenenanzahl des Schirms 
      enthalten (work_out[4] bei vq_extnd()). Ist bitmap->fd_nplanes 1, 
      wird eine monochrome Bitmap angelegt.

      Die Eintrge des MFDB (fd_addr, fd_w, fd_h, fd_wdwidth, fd_stand, 
      fd_nplanes) werden vom VDI-Treiber gesetzt und an die aufrufende 
      Applikation zurckgegeben. Wenn nicht nicht gengend Speicher 
      vorhanden ist, wird der Inhalt des MFDBs nicht verndert; ein 
      Null-Handle wird zurckgegeben.

      Wenn bitmap->fd_addr ungleich NULL ist, wird dieser Eintrag als 
      Zeiger auf eine Bitmap interpretiert. Wenn die Bitmap im 
      Standardformat vorliegt, wird sie ins gertespezifische Format 
      umgewandelt. Liegt sie schon im gertespezifischen Format vor, so 
      wird sie nicht umgewandelt. Falls die Auflsung der Bitmap (d.h.  
      die Anzahl der Farben und Planes) nicht untersttzt wird, gibt 
      v_opnbm() ein Null-Handle zurck.


      CLOSE BITMAP (VDI 101, 1)

      void  v_clsbm( WORD handle )
      {
         contrl[0] = 101;
         contrl[1] = 0;
         contrl[3] = 0;
         contrl[5] = 1;
         contrl[6] = handle;
         vdi();
      }

      Bestckung der VDI-Arrays:

       Feldelement      | Belegung
      ------------------|-------------------------------------------
      contrl[0]         | 101    Funktionsnummer fr v_clsbm()
      contrl[1]         | 0      Anzahl der Eintrge in ptsin
      contrl[2]         | 0      Anzahl der Eintrge in ptsout
      contrl[3]         | 0      Anzahl der Eintrge in intin
      contrl[4]         | 0      Anzahl der Eintrge in intout
      contrl[5]         | 1      Unterfunktionsnummer fr v_clsbm()
      contrl[6]         | handle

      Die Funktion v_clsbm() schliet die mit handle bezeichnete Bitmap. 
      Wenn der Speicher beim v_opnbm() vom VDI alloziert wurde, gibt sie 
      diesen Speicher wieder frei.


   Rasteroperationen bei Off-Screen-Bitmaps:
   
   Rasteroperationen zwischen Bildschirm und Off-Screen-Bitmap sollten 
   grundstzlich im gertespezifischen Format erfolgen.
   Wenn als Ziel einer Rasteroperation eine Off-Screen-Bitmap mit ihrem 
   MFDB angegeben wird und wenn das zu dieser Bitmap gehrende Handle 
   benutzt wird, so wird beim Blitten anhand der ber vs_clip() auf dieser 
   Workstation eingestellten Koordinaten geclippt. Fr das Kopieren eines 
   Rasters vom Bildschirm in eine Off-Screen-Bitmap sollte man also das 
   VDI-Handle dieser Bitmap benutzen.
   Ist die Bitmap dagegen Quelle und der Bildschirm Ziel, so sollte man das 
   Handle der Bildschirm-Workstaion benutzen, da dann das Raster anhand der 
   Bildschirm-Koordinaten abgeclippt wird.
   Wenn man das von v_opnbm() zurckgelieferte Handle einer Bitmap benutzt 
   und in fd_addr in einem MFDB 0 enthlt, so werden die Daten der Bitmap 
   statt dessen benutzt.

   ESCAPES
   -------
   Die VDI-Escape-Funktionen (VT52) knnen nicht auf einer Bitmap benutzt 
   werden. Ihr Aufruf wid ignoriert.
   
   vs_color()/vq_color()
   ---------------------
   Wenn die Funktion vs_color() mit dem Handle einer Off-Screen-Bitmap 
   aufgerufen wird, werden die Farben nur dann gesetzt, wenn es sich um 
   High- oder True-Color handelt. Vq_color() ist ebenfalls nur in High- 
   oder True-Color sinnvoll - andernfalls ist der Parameter valid -1.

   vst_point()
   -----------
   Die Funktion vst_point() und alle anderen Funktionen, die Texthhen in 
   Punkten einstellen, reagieren bisher nur dann sinnvoll, wenn die Bitmap 
   die Ausmae des Bildschirms hat. 

   v_show_c()/v_hide_c()
   ---------------------
   Beide Funktionen werden ignoriert, falls sie mit dem Handle einer 
   Off-Screen-Bitmap aufgerufen werden. Sie beziehen sich nur auf den 
   Bildschirm und sollten nur vom AES aufgerufen werden.
   
2. vq_scrninfo()
=================

   Genauere Angaben ber das Bildschirmformat liefert die Funktion INQUIRE 
   SCREEN INFORMATION implementiert. Im workout-Array wird angeben, wie das 
   gertespezifische Format aufgebaut ist. 
   Diese Informationen sind in erster Linie interessant fr Programme, die
   -  schnell Raster aufbauen (auch in TrueColor) und diese mit vro_cpyfm() 
      auf den Schirm kopieren mchten.
   -  Raster speichern (z.B. XIMGs).
   -  Raster anzeigen.
   
      VQ_SCRNINFO( 102, 1 )

      void  vq_scrninfo( WORD handle, WORD *work_out )
      {
         pb[3] = work_out;

         intin[0] = 2;
         contrl[0] = 102;
         contrl[1] = 0;
         contrl[3] = 1;
         contrl[5] = 1;
         contrl[6] = handle;
         
         vdi();

         pb[3] = intout;
      }

      Bestckung der VDI-Arrays:

       Feldelement      | Belegung
      ------------------|-------------------------------------------
      contrl[0]         | 102    Funktionsnummer von vq_scrninfo()
      contrl[1]         | 0      Anzahl der Eintrge in ptsin
      contrl[2]         | 0      Anzahl der Eintrge in ptsout
      contrl[3]         | 1      Anzahl der Eintrge in intin
      contrl[4]         | 272    Anzahl der Eintrge in intout
      contrl[5]         | 1      Unterfunktionsnummer von vq_scrninfo()
      contrl[6]         | handle
                        |
      intin[0]          | 2      erweiterte Informationen ausgeben
                        |
      intout[0..272]    | work_out[0..272]
      

      intout[0]:  Formatangabe:
                  0: Interleaved Planes, wortweise (ATARI Grafik)
                  1: Standardformat (komplette Planes)
                  2: Packed Pixels
                 -1: unbekanntes Format; nicht direkt beschreibbar
      intout[1]:  Verfgbarkeit einer CLUT:
                  0: keine CLUT (z.B. TTM 194)
                  1: Hardware-CLUT
                  2: Software-CLUT (HiColor oder TrueColor)
      intout[2]:  Anzahl der Ebenen (Bits) pro Pixel
      intout[3/4]:Farbanzahl oder 0L (mehr als 2*10^31 Farben)
      intout[8]:  Anzahl der Bits fr die Rot-Intensitt
      intout[9]:  Anzahl der Bits fr die Grn-Intensitt
      intout[10]: Anzahl der Bits fr die Blau-Intensitt
      intout[11]: Anzahl der Bits fr den Alpha-Channel oder hnliches
      intout[12]: Anzahl der Bits fr Genlock
      intout[13]: Anzahl der nicht benutzen Bits

      Falls eine Hardware-CLUT (intout[1] == 1) vorhanden ist:
      intout[16-271]: Pixelwert des zugehrigen VDI-Farbindexes

      Falls HiColor, TrueColor oder hnliches vorhanden ist:
      intout[16..31]: Zuordnung von Bitnummer im Pixel zum Bit der Rotintensitt
      intout[32..47]: Zuordnung von Bitnummer im Pixel zum Bit der Grnintens.
      intout[48..63]: Zuordnung von Bitnummer im Pixel zum Bit der Blauintensitt
      intout[64..79]: Zuordnung der Bitnummer fr Alpha-Channel
      intout[80..95]: Zuordnung der Bitnummer fr Genlock
      intout[96..127]: unbenutzte Bits
      intout[128..271]: reserviert (0)
      
   Beispiele:
   ----------

      In 256 Farben auf dem Falcon wrden folgende Ausgaben erfolgen:

      intout   | Wert   | Bedeutung
      ---------|--------|-----------------------------------------------------
         0     |   0    | Interleaved Planes, wortweise
         1     |   1    | Hardware-CLUT vorhanden
         2     |   8    | 8 Bit pro Pixel
         3/4   | 256    | 256 verschiedene Farben gleichzeitig mglich
         8     |   6    | 6 Bits fr die Rot-Intensitt
         9     |   6    | 6 Bits fr die Grn-Intensitt
        10     |   6    | 6 Bits fr die Blau-Intensitt
        11     |   0    | kein Bit fr Alpha-Channel
        12     |   0    | kein Bit fr Genlock
        13     |   0    | kein unbenutzes Bit
               |        |
               |        |
        16     |   0    | Pixelwert fr VDI-Farbindex 0
        17     | 255    | Pixelwert fr VDI-Farbindex 1
        18     |   2    | Pixelwert fr VDI-Farbindex 2
        ...    | ...    |
       271     |  15    | Pixelwert fr VDI-Farbindex 255

      In HiColor auf dem Falcon wrden folgende Ausgaben erfolgen:

      intout   | Wert   | Bedeutung
      ---------|--------|-----------------------------------------------------
         0     |   2    | Packed Pixels
         1     |   2    | HiColor bzw. TrueColor
         2     |  16    | 16 Bit pro Pixel
         3/4   | 32768  | 32768 verschiedene Farben gleichzeitig mglich
         8     |   5    | 5 Bits fr die Rot-Intensitt
         9     |   5    | 5 Bits fr die Grn-Intensitt
        10     |   5    | 5 Bits fr die Blau-Intensitt
        11     |   0    | kein Bit fr Alpha-Channel
        12     |   1    | ein Bit fr Genlock
        13     |   0    | kein unbenutzes Bit
               |        |
               |        |
        16     |  11    | Bit 0 der Rot-Intensitt (niederwertigstes Bit)
               |        | befindet sich in Bit 11 des Pixels
        17     |  12    | Bit 1 befindet sich in Bit 12 des Pixels
        18     |  13    | ...
        19     |  14    | ...
        20     |  15    | Bit 4 der Rot-Intensitt (hchstwertigstes Bit)
               |        | befindet sich in Bit 15 des Pixels
        21..31 |  -1    | Bits werden nicht fr Rot-Intensitt benutzt
               |        |
               |        |
        32     |   6    | Bit 0 der Grn-Intensitt (niederwertigstes Bit)
               |        | befindet sich in Bit 6 des Pixels
        33     |   7    | Bit 1 befindet sich in Bit 7 des Pixels
        34     |   8    | ...
        35     |   9    | ...
        36     |  10    | Bit 4 der Grn-Intensitt (hchstwertigstes Bit)
               |        | befindet sich in Bit 10 des Pixels
        37..37 |  -1    | Bits werden nicht fr Grn-Intensitt benutzt
               |        |
               |        |
        48     |   0    | Bit 0 der Blau-Intensitt (niederwertigstes Bit)
               |        | befindet sich in Bit 0 des Pixels
        49     |   1    | Bit 1 befindet sich in Bit 1 des Pixels
        50     |   2    | ...
        51     |   3    | ...
        52     |   4    | Bit 4 der Blau-Intensitt (hchstwertigstes Bit)
               |        | befindet sich in Bit 4 des Pixels
        53..63 |  -1    | Bits werden nicht fr Blau-Intensitt benutzt
               |        |
               |        |
        64..79 |  -1    | kein Alpha-Channel
               |        |
               |        |
        80     |   5    | Bit fr Genlock
        81..95 |  -1    | nicht fr Genlock benutzt
               |        |
               |        |
        96..127|  -1    | keine unbenutzten Bits
               |        |
               |        |

3. Wie erkennt man, ob die neuen Funktionen vorhanden sind?
===========================================================

   NVDI installiert (ebenso wie der nur frs ATARI-VDI gedachte Enhancer) 
   einen Cookie mit der Kennung 'EdDI'. Das auf diese Kennung folgende  
   Langwort ist die Adresse eines Funktionsdispatchers, der mit der 
   Funktionsnummer in Register d0 aufgerufen wird. Der Aufruf erfolgt nach 
   den Pure C-Konventionen (Register d0-d2/a0-a1 und der Stack werden zur 
   Parameterbergabe benutzt). 

   Bisher existiert nur die Funktion 0, die als Funktionsresultat eine 
   Versionsnummer zurckliefert, anhand er man auf die untersttzten 
   Funktionen schlieen kann. 

   Ab Version 1.00 ($100 wird zurckgeliefert) sind die Funktionen 
   v_opnbm(), v_clsbm() und vq_scrninfo() vorhanden. 

