                           Enhanced NVDI 2.50 Functions
                           ============================

   This document describes the enhanced NVDI 2.50 functions for screen 
   output.

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

   Sometimes  it's  very  useful  to  perform  drawing operations on hidden 
   screens   and  to  use vro_cpyfm() to transfer the complete image to the 
   screen  - you may want to avoid screen flickering or just cache a screen 
   region, etc.. These hidden screens are called `Off-Screen Bitmaps'.
   You can create off-screen bitmaps by calling OPEN BITMAP. You can either 
   pass  the  size  of a bitmap to v_opnbm() which will allocate memory for 
   it,  or  you  can  pass a pointer to a bitmap you have already allocated 
   memory  for. The bitmap will be in device-specific or monochrome format. 
   Therefore  you  can  copy  raster areas from screen to a bitmap and vice 
   versa without using vr_trnfm(). 
   The function CLOSE BITMAP closes a bitmap created with OPEN BITMAP and - 
   if necessary - frees the memory block.


      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;
      }

      VDI arrays:

       Element          | Content
      ------------------|-------------------------------------------
      contrl[0]         | 100    opcode for v_opnbm()
      contrl[1]         | 0      number of parameters in ptsin
      contrl[2]         | 6      number of parameters in ptsout
      contrl[3]         | 20     number of parameters in intin
      contrl[4]         | 45     number of parameters in intout
      contrl[5]         | 1      sub-opcode for v_opnbm()
      contrl[6]         | handle
      contrl[7..8]      | bitmap pointer to the MFDB of 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]:   see v_opnwk()/v_opnvwk()
      work_in[0]:       Getrez() + 2
      work_in[11]:      Width -1 (e.g. 1279)
      work_in[12]:      Height -1 (e.g. 959)
      work_in[13]:      Width of a pixel in 1/1000 mm
      work_in[14]:      Height of a pixel in 1/1000 mm
      work_in[15..19]:  reserved, should contain 0

      Attention:  Work_in[11]  +  1  should  be  divisible  by  16  without 
                  remainder.  Otherwise  the  VDI  driver  will  round  up  
                  (work_in[11] + 1) to the next number which can be divided 
                  by 16 without remainder.
                  If  pixel  width  and  height are 0 the pixel size of the 
                  screen workstation is used.

      work_out[0..1]:   see v_opnwk()/v_opnvwk()
      work_out[2]:      0
      work_out[3..38]:  see v_opnwk()/v_opnvwk()
      work_out[39]      0 (no hardware clut)
      work_out[39..56]: see v_opnwk()/v_opnvwk()

      bitmap:           pointer to MFDB

      If  bitmap->fd_addr  is  zero,  the  VDI will allocate memory for the 
      bitmap and will clear it (in contrast to v_opnvwk() ). 

      To  open a bitmap in device-specific format bitmap->fd_nplanes should 
      be  zero  or  the  number  of  planes of the screen (work_out[4] from 
      vq_extnd()).  If bitmap->fd_nplanes is 1, a monochrome bitmap will be 
      created.
      The   elements   of  the  MFDB  (fd_addr,  fd_w,  fd_h,  fd_wdwidth,  
      fd_stand,fd_nplanes)  are  set  by  the  VDI  before  returning  from 
      v_opnbm().  If  there  is  not  enough  memory to create a bitmap the 
      handle will be zero and the MFDB will not be changed.

      If  bitmap->fd_addr  is  not  zero,  it  will be used as pointer to a 
      bitmap.  If  the bitmap is in standard format, it will be transformed 
      into device-specific format. If the number of planes of the bitmap is 
      not supported by the VDI, a zero handle will be returned.


      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();
      }

      VDI arrays:

       Element          | Content
      ------------------|-------------------------------------------
      contrl[0]         | 101    opcode for v_clsbm()
      contrl[1]         | 0      number of parameter in ptsin
      contrl[2]         | 0      number of parameter in ptsout
      contrl[3]         | 0      number of parameter in intin
      contrl[4]         | 0      number of parameter in intout
      contrl[5]         | 1      sub-opcode for v_clsbm()
      contrl[6]         | handle

      The  function  v_clsbm() closes the bitmap specified with handle. The 
      memory of the bitmap will be freed if the VDI has allocated it.


   Raster Operations and Off-Screen Bitmaps:
   =========================================

   Raster  operations between screen and a bitmap generally have to be done 
   in device-specific format.
   If a bitmap is the destination of a raster operation, you should use the 
   bitmap's  handle.  Otherwise  vro_cpyfm() or vrt_cpyfm() cannot clip the 
   area they have to copy and may overwrite other applications' memory.

   If  you  use  the  handle  of a bitmap created by v_opnbm() for a raster 
   operation  then  a  zero in MFDB->fd_addr is not a pointer to the screen 
   but to the bitmap.
   In  contrast  to  a screen workstation on a bitmap clipping is also done 
   when  MFDB->fd_addr  is  the address of the bitmap returned by v_opnbm() 
   (on  a  screen  workstation  clipping is only done when MFDB->fd_addr is 
   zero).

   See also: BITMAP.C

   ESCAPES
   -------
   VDI  escape functions can't be used on Off-Screen bitmaps. The calls are 
   ignored.

   vs_color()/vq_color()
   ---------------------
   vs_color()  and  vq_color()  can  be used in Hi- or True Color mode on a 
   Off-Screen  bitmap.  Otherwise the calls are ignored (vq_color() returns
   -1 if not used in Hi- or True Color mode).

   vst_point()
   -----------
   vst_point()  and  all  other  functions  that  change the text character 
   height  in  printer points won't set the requested character size if the 
   pixel  height  and  width of the screen is different to the pixel height 
   and width of the Off-Screen bitmap.

   v_show_c()/v_hide_c()
   ---------------------
   v_show_c() and v_hide_c() can't be used on Off-Screen bitmaps. The calls 
   are ignored.


2. vq_scrninfo()
================

   The  funcion  INQUIRE  SCREEN INFORMATION returns additional information 
   about the device-specific screen format.  
   This function is useful for programs which
   -  support Genlock (Overlay)
   -  build  rasters  (also  in  TrueColor)  and  want  to  copy them with 
      vro_cpyfm() to the screen
   -  save rasters (e.g. XIMGs)

      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;
      }

      VDI arrays:

       Element          | Content
      ------------------|-------------------------------------------
      contrl[0]         | 102    opcode for vq_scrninfo()
      contrl[1]         | 0      number of parameters in ptsin
      contrl[2]         | 0      number of parameters in ptsout
      contrl[3]         | 1      number of parameters in intin
      contrl[4]         | 272    number of parameters in intout
      contrl[5]         | 1      sub-opcode for vq_scrninfo()
      contrl[6]         | handle
                        |
      intin[0]          | 2      return additional information
                        |
      intout[0..272]    | work_out[0..272]


      intout[0]:  Device Format
                  0: interleaved planes, word-wide (ATARI graphic)
                  1: whole planes (standard format)
                  2: packed pixels
                 -1: unknown format
      intout[1]:  Supported CLUT:
                  0: no CLUT (e.g. TTM 194)
                  1: hardware CLUT
                  2: software CLUT (HiColor or TrueColor)
      intout[2]:  number of planes (bits) per pixel
      intout[3/4]:number of colors or 0L (more than 2*10^31 colors)
      intout[8]:  number of bits for red intensity
      intout[9]:  number of bits for green intensity
      intout[10]: number of bits for blue intensity
      intout[11]: number of bits for alpha channel
      intout[12]: number of bits for genlock
      intout[13]: number of unused bits

      If a CLUT exists:
      intout[16-271]: pixel value of the corresponding VDI color index

      HiColor or TrueColor:
      intout[16..31]:   association of bit number in the pixel and bit of 
                        the red intensity
      intout[32..47]:   association of bit number in the pixel and bit of 
                        the green intensity
      intout[48..63]:   association of bit number in the pixel and bit of
                        the blue intensity
      intout[64..79]:   association of bit number for alpha channel
      intout[80..95]:   association of bit numbers for genlock
      intout[96..127]:  bit numbers of unused bits
      intout[128..271]: reserved (0)

   Examples:
   ---------

      The following output would be done in 256 colors on the Falcon:

      intout   | Value  | Meaning
      ---------|--------|-----------------------------------------------------
         0     |   0    | interleaved planes
         1     |   1    | hardware CLUT exists
         2     |   8    | 8 bit per pixel
         3/4   | 256    | 256 colors
         8     |   6    | 6 bits for red intensity
         9     |   6    | 6 bits for green intensity
        10     |   6    | 6 bits for blue intensity
        11     |   0    | no bit for alpha channel
        12     |   0    | no bit for genlock
        13     |   0    | no unused bits
               |        |
               |        |
        16     |   0    | pixel value of VDI color index 0
        17     | 255    | pixel value of VDI color index 1
        18     |   2    | pixel value of VDI color index 2
        ...    | ...    |
       271     |  15    | pixel value of VDI color index 255

      The following output would be done in HiColor on the Falcon:

      intout   | Value  | Meaning
      ---------|--------|-----------------------------------------------------
         0     |   2    | packed pixels
         1     |   2    | HiColor/TrueColor
         2     |  16    | 16 bit per pixel
         3/4   | 32768  | 32768 colors
         8     |   5    | 5 bits for red intensity
         9     |   5    | 5 bits for green intensity
        10     |   5    | 5 bits for blue intensity
        11     |   0    | no bit for alpha channel
        12     |   1    | 1 bit for genlock
        13     |   0    | no unused bits
               |        |
               |        |
        16     |  11    | bit 0 of the red intensity (least significant bit)
               |        | is in bit 11 of the pixel
        17     |  12    | bit 1 is in bit 12 of the pixel
        18     |  13    | ...
        19     |  14    | ...
        20     |  15    | bit 4 of the red intensity (most significant bit)
               |        | is in bit 15 of the pixel
        21..31 |  -1    | bits are not used for red intensity
               |        |
               |        |
        32     |   6    | bit 0 of the green intensity (least significant bit)
               |        | is in bit 6 of the pixel
        33     |   7    | bit 1 is in bit 7 of the pixel
        34     |   8    | ...
        35     |   9    | ...
        36     |  10    | bit 4 of the green intensity (most significant bit)
               |        | is in bit 10 of the pixel
        37..37 |  -1    | bits are not used for green intensity
               |        |
               |        |
        48     |   0    | bit 0 of the blue intensity (least significant bit)
               |        | is in bit 0 of the pixel
        49     |   1    | bit 1 is in bit 1 of the pixel
        50     |   2    | ...
        51     |   3    | ...
        52     |   4    | bit 4 of the blue intensity (most significant bit)
               |        | is in bit 4 of the pixel
        53..63 |  -1    | bits are not used for blue intensity
               |        |
               |        |
        64..79 |  -1    | no alpha channel
               |        |
               |        |
        80     |   5    | bit for genlock
        81..95 |  -1    | not used for genlock
               |        |
               |        |
        96..127|  -1    | no unused bits
               |        |
               |        |



3. Recognizing the enhanced VDI functions
=========================================

   NVDI  (and  also  the  ENHANCER  for  the ATARI-VDI) will place a 'EdDI' 
   cookie  in  the  cookie jar containing a dispatcher adress in the cookie 
   value.  The dispatcher uses Turbo C/Pure C calling conventions (register 
   d0  contains the opcode; registers d1-d2/a0-a1 and the stack may be used 
   for additional parameters).

   Till  now  only  opcode 0 is implemented. This opcode returns the 'EdDI' 
   version  number.
   Version  1.00  (retun  value  is $100) supports v_opnbm(), v_clsbm() and 
   vq_scrninfo().
   
