home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / gnu / djgpp / contrib / libgrx / docs / drivers.doc < prev    next >
Encoding:
Text File  |  1993-12-06  |  17.9 KB  |  309 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.             Abstract
  9.  
  10.             This document  describes the  graphics driver  format used  for DJGPP and  the
  11.             LIBGRX  graphics library.  It also gives  hints for  creating a  driver for an
  12.             unsupported display adapter. 
  13.  
  14.             Introduction
  15.  
  16.             The DJGPP graphics drivers do two things:
  17.  
  18.               (1) Invoke the BIOS INT 10 routine for setting up the desired graphics mode.
  19.                   Different boards  support different  resolutions and use  different mode
  20.                   numbers -- that's why different drivers are needed for different boards.
  21.  
  22.               (2) Implement page  mapping for video modes which use more than 64K of video
  23.                   memory. This is again board dependent.
  24.  
  25.             Old driver format
  26.  
  27.             The  following C  declarations  describe the  header of  an  old format  DJGPP
  28.             graphics driver. Of course, real drivers are coded in assembly. 
  29.  
  30.             typedef unsigned short u_short;
  31.                  typedef unsigned char  u_char;
  32.  
  33.                  struct old_driver_header {
  34.                      u_short      mode_set_routine_offset;
  35.                      u_short      paging_routine_offset;
  36.                      u_short      paging_mode_flag;                          /* 0 if no separate R/W, 1 if yes */
  37.                      u_short      default_text_width;
  38.                      u_short      default_text_height;
  39.                      u_short      default_graphics_width;
  40.                      u_short      default_graphics_height;
  41.                  };
  42.  
  43.             The mode set routine does the following:
  44.  
  45.             ;--------------------------------------------------------------------------
  46.                  ; Entry: AX=mode selection
  47.                  ;                0=80x25 text
  48.                  ;                1=default text
  49.                  ;                2=text CX cols by DX rows
  50.                  ;                3=biggest text
  51.                  ;                4=320x200 graphics
  52.                  ;                5=default graphics
  53.                  ;                6=graphics CX width by DX height
  54.                  ;                7=biggest non-interlaced graphics
  55.                  ;                8=biggest graphics
  56.                  ;         CX=width (in pixels or characters) (not always used -- depends on AX)
  57.                  ;         DX=height
  58.                  ;
  59.                  ; NOTE: This runs in real mode, but don't mess with the segment registers.
  60.                  ;
  61.                  ; Exit:  CX=width (in pixels or characters)
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.                  ;         DX=height
  70.                  ;--------------------------------------------------------------------------
  71.  
  72.             The paging routine does the following:
  73.  
  74.             ;--------------------------------------------------------------------------
  75.                  ; Entry: AH=read page
  76.                  ;         AL=write page
  77.                  ;
  78.                  ; NOTE: This runs in protected mode!  Don't mess with the segment registers!
  79.                  ; This code must be relocatable and may not reference any data!
  80.                  ;
  81.                  ; Exit: VGA configured.
  82.                  ;        AX,BX,CX,DX,SI,DI may be trashed
  83.                  ;--------------------------------------------------------------------------
  84.  
  85.             The old style  graphics driver structure  remained unchanged for the  first 16
  86.             color drivers developed for LIBGRX. The only difference is that the additional
  87.             15  bits in the  third word of  the header were  given new meanings.  (The 256
  88.             color  DJGPP  library only  used  one  bit to  encode  the  capability to  map
  89.             different pages for  reading and writing.) The  values of these new  bitfields
  90.             were assigned as to stay compatible with the existing 256 color drivers. (I.e.
  91.             the  0  value  in every  bitfield  selects  the  256  color VGA  option.)  The
  92.             definition of these bits (from "grdriver.h"):
  93.  
  94.             #define GRD_NEW_DRIVER  0x0008             /* NEW FORMAT DRIVER IF THIS IS SET */
  95.  
  96.                  #define GRD_PAGING_MASK   0x0007           /* mask for paging modes */
  97.                  #define GRD_NO_RW         0x0000           /* standard paging, no separate R/W */
  98.                  #define GRD_RW_64K        0x0001           /* two separate 64K R/W pages */
  99.                  /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
  100.                  /* THE FOLLOWING THREE OPTIONS ARE NOT SUPPORTED AT THIS TIME             */
  101.                  #define GRD_RW_32K        0x0002           /* two separate 32Kb pages */
  102.                  #define GRD_MAP_128K      0x0003           /* 128Kb memory map -- some Tridents
  103.                                                                can do it (1024x768x16 without
  104.                                                                paging!!!)
  105.                  #define GRD_MAP_EXTMEM    0x0004           /* Can be mapped extended, above 1M.
  106.                                                                Some Tseng 4000-s can do it, NO
  107.                                                                PAGING AT ALL!!!! */
  108.                  /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */
  109.  
  110.                  #define GRD_TYPE_MASK     0xf000           /* adapter type mask */
  111.                  #define GRD_VGA           0x0000           /* vga */
  112.                  #define GRD_EGA           0x1000           /* ega */
  113.                  #define GRD_HERC          0x2000           /* hercules */
  114.                  #define GRD_8514A         0x3000           /* 8514/A or compatible */
  115.                  #define GRD_S3            0x4000           /* S3 graphics accelerator */
  116.  
  117.                  #define GRD_PLANE_MASK    0x0f00           /* bitplane number mask */
  118.                  #define GRD_8_PLANES      0x0000           /* 8 planes = 256 colors */
  119.                  #define GRD_4_PLANES      0x0100           /* 4 planes = 16 colors */
  120.                  #define GRD_1_PLANE       0x0200           /* 1 plane  = 2 colors */
  121.                  #define GRD_16_PLANES     0x0300           /* VGA with 32K colors */
  122.                  #define GRD_8_X_PLANES    0x0400           /* VGA in mode X w/ 256 colors */
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                  #define GRD_MEM_MASK      0x00f0           /* memory size mask */
  131.                  #define GRD_64K           0x0010           /* 64K display memory */
  132.                  #define GRD_128K          0x0020           /* 128K display memory */
  133.                  #define GRD_256K          0x0030           /* 256K display memory */
  134.                  #define GRD_512K          0x0040           /* 512K display memory */
  135.                  #define GRD_1024K         0x0050           /* 1MB display memory */
  136.                  #define GRD_192K          0x0060           /* 192K -- some 640x480 EGA-s */
  137.                  #define GRD_M_NOTSPEC     0x0000           /* memory amount not specified */
  138.  
  139.             An old style  driver has the  'GRD_NEW_DRIVER' bit cleared.  It can work  with
  140.             previous versions of GO32. Of course  for 16 color support the application has
  141.             to be  linked  with the  LIBGRX  library instead  of  the original  256  color
  142.             library.
  143.  
  144.             The following additional  old format  graphics drivers are  supplied with  the
  145.             LIBGRX graphics library:
  146.  
  147.                   EGA16.GRD         16 color EGA driver (640x350x16 max. resolution)
  148.                   VGA16.GRD         16   color  standard   VGA  driver   (640x480x16  max.
  149.                                     resolution)
  150.                   TSENG4KN.GRD      same as  DJGPP's Tseng ET  4000 256 color  driver, but
  151.                                     with  added support  for the  100x40 text  mode. (max:
  152.                                     1024x768x256)
  153.                   TSENG416.GRD      Tseng ET 4000 16 color driver. (max: 1024x768x16)
  154.                   TRID89N.GRD       Trident  8900 256  color  driver. This  driver has  an
  155.                                     updated  paging  routine  which  seems   to  fix  some
  156.                                     previous   problems  on  boards   with  recent  enough
  157.                                     chipsets. (max: 1024x768x256)
  158.                   TRID8916.GRD:     Trident 8900 16 color driver (max: 1024x768x16)
  159.  
  160.  
  161.             New driver format
  162.  
  163.             The disadvantage of the old  driver format is that the number of colors is not
  164.             programmable. The new driver format solves  this problem and it also gives the
  165.             application program a way to query the driver for a list of the supported text
  166.             and graphics modes. For this the driver header was extended as follows:
  167.  
  168.             struct new_driver_header {
  169.                      u_short      mode_set_routine_offset;
  170.                      u_short      paging_routine_offset;
  171.                      u_short      driver_mode_flag;                 /* flag word, see bits below */
  172.                      u_short      default_text_width;
  173.                      u_short      default_text_height;
  174.                      u_short      default_graphics_width;
  175.                      u_short      default_graphics_height;
  176.                      u_short      default_color_number;             /* NEW, may be set from environment */
  177.                      u_short      init_routine_offset;              /* NEW, call once after drvr loaded */
  178.                      u_short      text_mode_table_offset;           /* NEW, table of supported text modes */
  179.                      u_short      graphics_mode_table_offset;       /* NEW, table of supported graphics modes */
  180.                  };
  181.  
  182.             'text_mode_table_offset' points to a table with entries as follows:
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.                  struct text_mode_entry {
  191.                      u_short      columns;
  192.                      u_short      rows;
  193.                      u_short      number_of_colors;                 /* in text mode it is mainly here to make
  194.                                                                        GCC happy with the alignments */
  195.                      u_char       BIOS_mode;                        /* BIOS mode number. Mode not available on
  196.                                                                        the current card if this field is 0xff. */
  197.                      u_char       special;                          /* if non zero then the driver does some
  198.                                                                        special hacks to set it up (like
  199.                                                                        the 50 row mode on a standard VGA) */
  200.                  };
  201.  
  202.             The end of the table is marked by an all 0 entry. The table entries are sorted
  203.             by  increasing size. The field 'graphics_mode_table_offset'  points to a table
  204.             with entries as follows:
  205.  
  206.             struct graphics_mode_entry {
  207.                      u_short      width;
  208.                      u_short      height;
  209.                      u_short      number_of_colors;
  210.                      u_char       BIOS_mode;                        /* BIOS mode number. Mode not available on
  211.                                                                        the current card if this field is 0xff.
  212.                                                                        (This may happen for example if the card
  213.                                                                        is not fully populated with RAM) */
  214.                      u_char       special;                          /* if non zero then the driver does some
  215.                                                                        special hacks to set it up (like
  216.                                                                        setting up the 32768 color mode on
  217.                                                                        some ET4000 cards) */
  218.                  };
  219.  
  220.             The end  of the  table is marked  by an all  0 entry.  The table is  sorted by
  221.             increasing color number and within the same color modes by increasing size.
  222.  
  223.             If  the driver  is of  the new type  then it  also supports  an initialization
  224.             routine. This  is called once after  the driver is  loaded. The initialization
  225.             routine can do one or more of the following:
  226.  
  227.               (1) Check whether the video card is of the expected type
  228.  
  229.               (2) Determine the amount of video memory on board.
  230.  
  231.               (3) Determine which  of the modes in  the text and graphics  mode tables are
  232.                   actually available (due to  video RAM and possibly DAC  [32768 colors!!]
  233.                   limitations) and mark the unavailable entries in the tables.
  234.  
  235.             To use the new format drivers a recent version of GO32 (1.06, after the middle
  236.             of  April  1992) has  to  be  used. Such  versions  should  recognize the  "nc
  237.             <number>"  option field in the  GO32 environment variable  which specifies the
  238.             default number of colors for the driver.
  239.  
  240.             The  following new format drivers  have been included  with the LIBGRX library
  241.             (new drivers have the ".GRN" extension):
  242.  
  243.                   STDEGA.GRN        standard EGA 16 color driver
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.                   STDVGA.GRN        standard VGA 16 and 256 color driver
  252.                   ET4000.GRN        Tseng ET 4000 16 256 and 32768 color driver
  253.                   TR8900.GRN        Trident 8900 16 and 256 color driver
  254.                   ATIULTRA.GRN      Driver for  the ATI  ULTRA board. This  board actually
  255.                                     contains two graphics adapters: a 512 KByte SVGA board
  256.                                     and a  8514/A compatible  accelerator. The driver  was
  257.                                     programmed  to use  the VGA  part for  text,  16 color
  258.                                     graphics, and low resolution  256 color graphics modes
  259.                                     and  the 8514/A  part  for high  resolution 256  color
  260.                                     modes.  This driver  should work  with any  VGA+8514/A
  261.                                     (the  8514/A  MUST   have  1MB  memory   for  1024x768
  262.                                     resolution)  combination as  long as  the ATI-specific
  263.                                     modes of the VGA part are not used.
  264.                   STEALTH.GRN Driver  for  the  Diamond  Stealth  S3 graphics  accelerator
  265.                               board.  The driver was programmed to use VGA-style video RAM
  266.                               access  for text, 16 color  graphics, and low resolution 256
  267.                               color graphics  modes and  the S3 accelarator  functions for
  268.                               high resolution  256 color  modes. Currently no  32768 color
  269.                               modes are supported  on S3 boards.  This driver should  work
  270.                               with other S3-based boards which have a VESA BIOS.
  271.  
  272.  
  273.             Creating a driver for an unsupported board
  274.  
  275.             You can  only use EGA or  VGA boards in 16  256 or 32768 color  modes with the
  276.             graphics library. In the near future there will be support for Hercules boards
  277.             as well. SUPPORT IS NOT PLANNED FOR: BOARDS  WITH ON-BOARD GRAPHICS PROCESSORS
  278.             (TIGA, 8514A, etc...) To create a  driver for an unsupported EGA or  VGA board
  279.             you will need the followings:
  280.  
  281.               (1) An  assembler (TASM or MASM), a linker (TLINK  or LINK) and a utility to
  282.                   convert .EXE files to the .COM format (EXE2BIN). See also the 'makefile'
  283.                   in the 'drivers' sub-directory.
  284.               (2) A  documentation of the board containing the supported BIOS mode numbers
  285.                   and resolutions. 
  286.               (3) If the driver needs to support modes which use a  memory map bigger than
  287.                   64K then you also need a piece of code which does page switching on your
  288.                   board. (Any  mode above 800x600  in 16 colors  or 320x200 in  256 colors
  289.                   DOES USE paging.) Possible sources:
  290.                       - a working, tested  256 color  original DJGPP driver  (if you  just
  291.                         want to convert it to the new format).
  292.                       - VGAKIT.ZIP (available from various archive sites,  like wuarchive,
  293.                         simtel, etc...)
  294.                       - various books on the subject.
  295.  
  296.             It is best to start with the source of a driver supporting similar resolutions
  297.             as your board.  Use the proper format  driver, i.e. if  you want a new  format
  298.             driver start  with a  new original,  etc... Typically  the driver  sources are
  299.             relatively well commented. What you need to do is:
  300.  
  301.               (1) possibly change  the option word at  the head of the  driver to indicate
  302.                   the  number of colors (old format only),  the amount of memory on board,
  303.                   the memory mapping capabilities of the board. 
  304.               (2) change the mode setting code to use the proper BIOS mode numbers. In the
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.                   old  format drivers these are somewhat scattered throughout the code, in
  313.                   the new format drivers you need to edit a few tables only.
  314.               (3) Replace the paging routine with the one suitable for your board. If your
  315.                   driver supports 16  color resolutions  beyond 800x600 then  you have  to
  316.                   make sure that upon exit from the paging routine the graphics controller
  317.                   port's (0x3ce)  index register is reset to 8. (See the paging routine in
  318.                   "TR8900.ASM".)  If  the paging  mechanism  does  not  use  any  register
  319.                   accessed  through the graphics controller  port, then you  don't need to
  320.                   worry about this.
  321.