ͻ
                                                                            
  MACH64 PGL APPLICATION NOTES                                              
                                                                            
  (c) Copyright 1992-1995 ATI Technologies Inc.                             
                                                                            
  For version 3.34, January 26, 1995                                        
                                                                            
ͼ

Ŀ
  Introduction                                                              


This document describes the functions found in the Programmer's Graphics
Library (PGL) for the ATI Mach64. The examples are written in C and were
developed using Microsoft's version 6.0 C compiler and version 5.1 macro
assembler. It is assumed that you are an experienced C programmer.

The purpose of the PGL library is to provide a straight forward way of
quickly making use of the powerful Mach64 Graphics Engine. Functions are
included for mode setting, line drawing, filled polygon drawing, text display
and blit operations. Most simple graphics tasks can be accomplished with a
couple of PGL function calls.

The functions are grouped into one library: PGL.LIB. The functions that make
up the library are discussed in detail in the "PGL Function Reference"
section of this document.

In addition to PGL.LIB, the PGL diskette also contains .c source for all of
the functions found in the PGL library as well as a demonstration program
that makes use of the PGL functions. A full description of the files on the
PGL diskette is found in the "Contents of the PGL Diskette" section of
this document.


Ŀ
  Installing the PGL Diskette                                               


To install the contents of the PGL diskette on a hard drive, simply create a
PGL directory and copy the contents of the PGL diskette to that directory
using xcopy with the /s and /e switches. For example, to copy the PGL
diskette in drive A: to a PGL directory off the root of hard drive C:, use
the following command:

     XCOPY A:\*.* C:\PGL /S /E

This will copy the entire contents of the PGL diskette to the hard drive,
including any empty directories required to build the programs and library
found on the diskette. After this is done, change to the PGLDEMO directory
of the copied directories and run TARGA.COM to uncompress TEST.TGA. This
file is used by the PGLDEMO.EXE program.


Ŀ
  Building PGLDEMO.EXE and PGL.LIB                                          


To build any of these files, run Microsoft's make utility "nmake" or
a similiar make utility in the appropriate directory. PGL.LIB must be built
first since PGLDEMO.EXE depends on this. To build PGL.LIB, change to the LIB
directory, and run your make utility. To build PGLDEMO.EXE, change to the
PGLDEMO directory, and run your make utility.


Ŀ
  Using the PGL Functions                                                   


PGL_detectmach64() is the primary entry function of the PGL. It must be
called before any other PGL function. If successful, PGL_close() must be
called before exiting the application. This will allow use of the I/O
register PGL functions. To use the memory mapped register PGL functions or
any other non-drawing PGL functions, PGL_initaperture() must be called. This
enables the appropriate aperture depending on the given access method (VGA or
linear). To set an accelerator mode and to use drawing PGL functions,
PGL_initmode() must be called in addition to the above functions. If
successful, PGL_closemode() must be called to disable the accelerator mode
and switch back to VGA. In all cases, PGL_close() should be called before
exiting the application. A typical application template shows the call
structure:

void sample(void)
{
    PGL_modeconfig modeinfo;
    int instance;

    // 'instance' is for multiple card installations only; use zero
    instance = 0;

    // check if Mach64 card is installed
    if (PGL_detectmach64(instance) != NO_ERROR)
    {
        printf("This program requires an ATI Mach64 based video adapter.\n");
        return;
    }

    //
    // setup memory mapped register access method
    //
    //    AUTO_APERTURE, USE_VGA_APERTURE, or USE_LINEAR_APERTURE
    //
    if (PGL_initaperture(AUTO_APERTURE) != NO_ERROR)
    {
        printf("Error initializing Mach64 aperture.\n");
        return;
    }

    // set an accelerator mode - 640x480 8 bpp
    if (PGL_initmode(640,            // x resolution
                     480,            // y resolution
                     8,              // bpp
                     0,              // color depth
                     640,            // pitch
                     0,              // memory offset
                     NO_ATTRIBUTES,
                     MODE_640x480,   // standard rom mode number
                     NO_CRT_TABLE,
                     NO_EEPROM_OFFSET) != MODE_SUPPORTED)
    {
        // if error, disable apertures set by PGL_initaperture()
        PGL_close();
        printf("Error setting Mach64 accelerator mode.\n");
        return;
    }

    // get mode information from PGL
    PGL_getmodeconfig(&modeinfo);

    // do some draw operations ...

    // close the accelerator mode
    PGL_closemode();

    // prepare PGL for exit - disables apertures and engine
    PGL_close();
}

PGL_initmode() must be called before any other PGL function that uses the
engine. This function will set an accelerator graphics mode, initialize the
engine to a known state, and initialize the palette if applicable. The
pgldemo.c source for the pgldemo.exe program provides examples for using this
function, and for using most of the other functions found in the library. A
review of pgldemo.c is a good starting point when beginning to create a
program that makes use of the PGL library functions.

In addition, any source module that calls a PGL function must include the
file PGL.H, and the PGL.LIB library must also be linked with the .exe file.
See the makefile command lines for the compiler and linker used to build
pgldemo.exe as examples for building a program that uses PGL functions. The
PGL functions found in the library are listed in the reference section of
this document "PGL.LIB Function Reference".


Ŀ
  Contents of the PGL Diskette                                              


The PGL diskette contains the following directories:

    DOC     -- Contains documents files for the PGL.

    INC     -- Contains PGL.H and other include files needed to build
               PGL.LIB. This directory also contains PGLDEMO.H.

    LIB     -- Contains PGL.LIB and the source files needed to build PGL.LIB.

    PGLDEMO -- Contains PGLDEMO.EXE, the font files, and the source files
               needed to build PGLDEMO.EXE. This directory also contains
               the four bit-mapped font files (BITM0715.FNT, BITM0814.FNT,
               BITM1220.FNT, and BITM0808.FNT).

Directories LIB and PGLDEMO also have empty OBJ sub-directories to hold the
object files during the build process.


Ŀ
  Color Depth Support                                                       


All functions in the PGL support color depths of 4, 8, 16, 32 bits per pixel
(bpp). There is limited support for 24 bpp modes. Polygons and patterned
lines are not supported. Also, since the engine does not directly support
lines, 24 bpp bressenham lines are drawn by software and are slow as a
result. Therefore, for applications using 24 bpp modes, it is not recommended
that a large number of lines be drawn unless they are vertical or horizontal.
These type of lines have been optimized. The following functions do not
support 24 bpp:

    PGL_drawpolygon()
    PGL_drawline() - for patterned lines only (solid lines are emulated)


Ŀ
  PGL.LIB Function Reference - Standard functions                           


This section describes each function in detail. Each function is described
in terms of inputs, outputs, setup functions that must be called before using
the function, and description of what the function does. The following is a
quick reference list of standard PGL functions. They are described in detail
afterwards.

int              ior8(unsigned int ioindex);
unsigned int     ior16(unsigned int ioindex);
unsigned long    ior32(unsigned int ioindex);
void             iow8(unsigned int ioindex, int iodata);
void             iow16(unsigned int ioindex, unsigned int iodata);
void             iow32(unsigned int ioindex, unsigned long iodata);
void             PGL_blankscreen(void);
void             PGL_buffertoscreenblit(unsigned long huge *bufferptr,
                                        int dstleft, int dsttop,
                                        int recwidth, int recheight);
void             PGL_clearscreen(int x, int y, int width, int height);
void             PGL_close(void);
void             PGL_closeaperture(void);
void             PGL_closemode(void);
int              PGL_detectmach64(int instance);
void             PGL_disableblockwrite(void);
void             PGL_disablehwcursor(void);
void             PGL_disablelinearaperture(void);
void             PGL_disableoverscan(void);
void             PGL_disablevgaaperture(void);
void             PGL_drawline(int x1, int y1, int x2, int y2);
void             PGL_drawpixel(int x, int y);
void             PGL_drawpolyline(int n, PGL_point *vertices);
int              PGL_drawpolygon(int n, PGL_point *vertices);
void             PGL_drawrect(int x, int y, int width, int height);
void             PGL_drawto(int x, int y);
void             PGL_enableblockwrite(void);
void             PGL_enablehwcursor(void);
void             PGL_enablelinearaperture(int aperture_size);
void             PGL_enableoverscan(unsigned long color,
                                    int leftwidth, int rightwidth,
                                    int topsizewidth, int bottomwidth);
void             PGL_enablevgaaperture(void);
unsigned long    PGL_getapertureaddress(void);
PGL_attribute   *PGL_getattributeptr(void);
unsigned long    PGL_getbgcolor(void);
int              PGL_getbgmix(void);
unsigned long    PGL_getbuffersize(int recwidth, int recheight);
unsigned long    PGL_getcolorcode(int generic_color);
void             PGL_getclipsize(PGL_scissor *scissor);
PGL_crttable    *PGL_getcrttable(int table_selection);
unsigned long    PGL_getfgcolor(void);
int              PGL_getfgmix(void);
PGL_font        *PGL_getfixedfont8x8(void);
PGL_font        *PGL_getfixedfont8x14(void);
PGL_font        *PGL_getfixedfont7x15(void);
PGL_font        *PGL_getfixedfont12x20(void);
void             PGL_gethwcursorpos(PGL_point *position);
void             PGL_getmodeconfig(PGL_modeconfig *modeconfig);
PGL_modeconfig  *PGL_getmodeconfigptr(void);
int              PGL_getnpolylines(int n, PGL_point *vertices);
PGL_palette      PGL_getpalette(int index);
unsigned long    PGL_getpixel(int x, int y);
void             PGL_getposition(PGL_point *position);
unsigned long    PGL_getprimarycolor(PGL_primarycolor primarycolor,
                                     unsigned long color);
void             PGL_getqueryheader(PGL_queryheader *queryinfo);
PGL_queryheader *PGL_getqueryheaderptr(void);
int              PGL_getquerysize(int fill_type);
int              PGL_getsrcline(void);
int              PGL_getsrcpoly(void);
int              PGL_getsrcrect(void);
PGL_version      PGL_getversion(void);
unsigned long    PGL_getwritemask(void);
int              PGL_initaperture(int register_access);
void             PGL_initengine(void);
int              PGL_initmode(int x,
                              int y,
                              int bpp,
                              int depth,
                              int pitch,
                              unsigned long offset,
                              int attribute_flags,
                              int mode_number,
                              PGL_crttable far *tableinfo,
                              int eeprom_offset);
void             PGL_initpalette(void);
void             PGL_initpalettized(void);
void             PGL_loadcontext(unsigned int loadpointer,
                                 unsigned long attribute);
int              PGL_loadfont(char *fontfile, PGL_font *font);
PGL_modedef     *PGL_loadmodelist(int *modes);
unsigned long    PGL_makecolor(unsigned long r,
                               unsigned long g,
                               unsigned long b);
void             PGL_monoexpandblit(int srcleft, int srctop,
                                    int dstleft, int dsttop,
                                    int recwidth, int recheight);
void             PGL_monotoscreenblit(unsigned long huge *bufferptr,
                                      int dstleft, int dsttop,
                                      int recwidth, int recheight);
void             PGL_moveto(int x, int y);
PGL_point        PGL_ncscreentoscreenblit(int recleft, int rectop,
                                          int recwidth, int recheight,
                                          int x, int y,
                                          int saveflag);
int              PGL_queryhardware(int fill_type, void far *queryptr);
void             PGL_resetengine(void);
void             PGL_restorepalette(PGL_palette *paletteBuffer);
void             PGL_savepalette(PGL_palette *paletteBuffer);
void             PGL_screentobufferblit(unsigned long huge *bufferptr,
                                        int srcleft, int srctop,
                                        int recwidth, int recheight);
void             PGL_screentoscreenblit(int srcleft, int srctop,
                                        int dstleft, int dsttop,
                                        int recwidth, int recheight);
void             PGL_setapertureaddress(unsigned long address);
void             PGL_setbgcolor(unsigned long color);
void             PGL_setbgmix(int mix);
void             PGL_setclipsize(int left, int top, int right, int bottom);
void             PGL_setcolordepth(int depth);
void             PGL_setfgcolor(unsigned long color);
void             PGL_setfgmix(int mix);
void             PGL_setfifocontrol(int check_control, int action_control);
void             PGL_setfillpattern(int width, int height,
                                    unsigned long *fillpattern);
void             PGL_setfilltype(int type);
int              PGL_sethwcursor(int y, int width, int height,
                                 int hot_x, int hot_y,
                                 unsigned long color0, unsigned long color1,
                                 unsigned int *bitmap);
void             PGL_sethwcursorpos(int x, int y);
void             PGL_setlinepattern(unsigned long linepattern, int length);
void             PGL_setlinetype(int type);
void             PGL_setpalette(int index, PGL_palette entry);
void             PGL_setsrcline(int y);
void             PGL_setsrcpoly(int y);
void             PGL_setsrcrect(int y);
void             PGL_setwritemask(unsigned long mask);
void             PGL_text(int x, int y, char *string, PGL_font *font);
void             PGL_unblankscreen(void);
void             PGL_updateaperturestatus(void);
void             PGL_uploadcontext(unsigned int loadpointer,
                                   PGL_context far *context);
void             PGL_unloadfont(PGL_font *font);
void             PGL_unloadmodelist(PGL_modedef *modelist);
int              PGL_vgafont(int vgafontsize, PGL_font *font);
int              PGL_waitforemptyfifo(void);
int              PGL_waitforfifo(int entries);
int              PGL_waitforidle(void);
void             PGL_waitforvblank(int frames);
void             PGL_waitforvblankst(int frames);
unsigned long    regr(unsigned int regindex);
int              regw(unsigned int regindex, unsigned long regdata);

// --------------------------------------------------------------------------
int              ior8(unsigned int ioindex);
unsigned int     ior16(unsigned int ioindex);
unsigned long    ior32(unsigned int ioindex);

    Inputs      : ioindex - XX00 + 0,1,2,3 = byte offset symbolic from ATIM64.H
                            XXEC + 0,1,2,3 = 2ECh based address
                            XXC8 + 0,1,2,3 = 1C8h based address
                            XXCC + 0,1,2,3 = 1CCh based address

    Outputs     : value of 8, 16, or 32 bit register

    Setup       : PGL_detectmach64()

    Description : Reads an 8, 16, or 32 bit value from an I/O mapped register.
                  Offsets are allowed from 0 to 3. These functions are
                  designed only for accelerator I/O registers.

// --------------------------------------------------------------------------
void             iow8(unsigned int ioindex, int iodata);
void             iow16(unsigned int ioindex, unsigned int iodata);
void             iow32(unsigned int ioindex, unsigned long iodata);

    Inputs      : ioindex - XX00 + 0,1,2,3 = byte offset symbolic from ATIM64.H
                            XXEC + 0,1,2,3 = 2ECh based address
                            XXC8 + 0,1,2,3 = 1C8h based address
                            XXCC + 0,1,2,3 = 1CCh based address
                  iodata  - 8, 16, or 32 bit to write to register

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Writes an 8, 16, or 32 bit value to an I/O mapped register.
                  Offsets are allowed from 0 to 3. These functions are
                  designed only for accelerator I/O registers.

// --------------------------------------------------------------------------
void             PGL_blankscreen(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Blanks the screen using a ROM DPMS call. This function is
                  usually called to blank the screen in accelerator mode.

// --------------------------------------------------------------------------
void             PGL_buffertoscreenblit(unsigned long huge *bufferptr,
                                        int dstleft, int dsttop,
                                        int recwidth, int recheight);

    Inputs      : bufferptr - pointer to CPU buffer
                  dstleft   - starting pixel X coordinate
                  dsttop    - starting pixel Y coordinate
                  recwidth  - width of rectangle in pixels
                  recheight - width of rectangle in pixels

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Copies a regtangular area of data from a CPU buffer to the
                  screen. 'bufferptr' is a pointer to the CPU buffer.
                  (dstleft, dsttop) is the starting pixel coordinate to begin
                  copying. (recwidth, recheight) are the size of the
                  rectangle to copy in pixels. Note that the CPU buffer data
                  must be packed to the active color depth (bits per pixel)
                  since this is a color copy.

// --------------------------------------------------------------------------
void             PGL_clearscreen(int x, int y, int width, int height);

    Inputs      : x      - starting pixel X coordinate
                  y      - starting pixel Y coordinate
                  width  - width of rectangle in pixels
                  height - width of rectangle in pixels

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Clears the screen to BLACK starting at (x, y) of size
                  (width, height). The mix is restored to its previously
                  value after the operation.

// --------------------------------------------------------------------------
void             PGL_close(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Turns off both apertures (VGA and linear) and disables the
                  engine.

// --------------------------------------------------------------------------
void             PGL_closeaperture(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Turns off both apertures (VGA and linear). This function is
                  called by PGL_close(). This is the counterpart function to
                  PGL_initaperture().

// --------------------------------------------------------------------------
void             PGL_closemode(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Turns off the current accelerator mode and switches back to
                  VGA. The current aperture setting is not affected. This
                  allows PGL_initmode() and PGL_closemode() to be called
                  multiple times without calling PGL_initaperture() again.

// --------------------------------------------------------------------------
int              PGL_detectmach64(int instance);

    Inputs      : instance - 0 = detect first card, 1 = detect second, ...

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : none

    Description : Detects if a Mach64 card is installed. This function is the
                  main entry point all PGL functions and must be called
                  before using any PGL function. The 'instance' input
                  parameter allows the application to detect for a specific
                  Mach64 based card in a multiple card installation. Normally,
                  this value is set to zero.

// --------------------------------------------------------------------------
void             PGL_disableblockwrite(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Disables the 'block write' feature if the Mach64 hardware
                  supports it. This feature allows faster drawing operation
                  if the Mach64 variant supports it and the video memory
                  type is VRAM. Using the 'block write' feature for DRAM
                  will produce extraneous results.

// --------------------------------------------------------------------------
void             PGL_disablehwcursor(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Disables and turns off the hardware cursor.


// --------------------------------------------------------------------------
void             PGL_disablelinearaperture(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Turns off the linear aperture. Caution should be used to
                  insure that at least one aperture (VGA or linear) is
                  enabled at all times during drawing operations to prevent
                  a lockup condition.

// --------------------------------------------------------------------------
void             PGL_disableoverscan(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Turns off the overscan border.

// --------------------------------------------------------------------------
void             PGL_disablevgaaperture(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Turns off the VGA aperture. Caution should be used to
                  insure that at least one aperture (VGA or linear) is
                  enabled at all times during drawing operations to prevent
                  a lockup condition.

// --------------------------------------------------------------------------
void             PGL_drawline(int x1, int y1, int x2, int y2);

    Inputs      : x1 - starting pixel X coordinate
                  y1 - starting pixel Y coordinate
                  x2 - ending pixel X coordinate
                  y2 - ending pixel Y coordinate

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Draws a bresenham one pixel thick line from (x1, y1) to
                  (x2, y2) using the current foreground color, mix, and line
                  pattern. The drawing of the last pixel is determined by the
                  current setting in the DST_CNTL register.

// --------------------------------------------------------------------------
void             PGL_drawpixel(int x, int y);

    Inputs      : x - pixel X coordinate
                  y - pixel Y coordinate

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Draws a single pixel at the given coordinate (x, y) using
                  the current color and mix. The pixel will not be drawn if
                  the current setting of the DST_CNTL register disables the
                  last pixel drawn.

// --------------------------------------------------------------------------
void             PGL_drawpolyline(int n, PGL_point *vertices);

    Inputs      : n        - number of lines to draw (1 based)
                  vertices - list of coordinate pairs that join the lines

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Draws multiple one pixel thick bresenham lines from a list
                  of 'n' lines using the current array of points referenced
                  by 'vertices'. The current foreground color, mix, and line
                  pattern are used. The drawing of the last pixel is
                  determined by the current setting in the DST_CNTL register.

// --------------------------------------------------------------------------
int              PGL_drawpolygon(int n, PGL_point *vertices);

    Inputs      : n        - number of sides of polygon (1 based)
                  vertices - coordinate pairs that outline the polygon

    Outputs     : NO_ERROR, YES_ERROR

    Setup       : PGL_initmode()

    Description : Draws an 'n' sided polygon, filled with the current
                  foreground color, mix, and fill pattern. The vertices given
                  should form an enclosed shape outline. Note that an 'n'
                  sided polygon requires 'n+1' point pairs. A polygon fill
                  requires that the outline be drawn in off-screen memory,
                  followed by a blit & fill to on-screen memory. If there is
                  not enough memory to permit the fill or there is less than
                  3 sides, nothing will be drawn and an error will be
                  returned.

// --------------------------------------------------------------------------
void             PGL_drawrect(int x, int y, int width, int height);

    Inputs      : x      - pixel X coordinate
                  y      - pixel Y coordinate
                  width  - width of rectangle
                  height - height of rectangle

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Draws a rectangle in the region specified by the input
                  parameters using the current color, mix, and fill pattern.

// --------------------------------------------------------------------------
void             PGL_drawto(int x, int y);

    Inputs      : x      - pixel X coordinate
                  y      - pixel Y coordinate

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Draws a one pixel thick bresenham line from the current
                  position to (x, y) using the current foreground color, mix,
                  and line pattern. The drawing of the last pixel is
                  determined by the current setting in the DST_CNTL register.

// --------------------------------------------------------------------------
void             PGL_enableblockwrite(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Enables the 'block write' feature if the Mach64 hardware
                  supports it. This feature allows faster drawing operation
                  if the Mach64 variant supports it and the video memory
                  type is VRAM. Using the 'block write' feature for DRAM
                  will produce extraneous results.

// --------------------------------------------------------------------------
void             PGL_enablehwcursor(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode(), PGL_sethwcursor(), PGL_sethwcursorpos()

    Description : Enables the hardware cursor. PGL_sethwcursor() and
                  PGL_sethwcursorpos() should called before this function to
                  prevent display of a extraneous cursor shape and position.

// --------------------------------------------------------------------------
void             PGL_enablelinearaperture(int aperture_size);

    Inputs      : aperture_size - APERTURE_4M_ENABLE
                                  APERTURE_8M_ENABLE

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Enables the linear aperture. If the VGA aperture is
                  disabled, all accesses to the memory mapped registers will
                  use the linear aperture. Some Mach64 variants only allow
                  the 8Meg size aperture. If this is case, APERTURE_4M_ENABLE
                  will be converted to APERTURE_8M_ENABLE. To force linear
                  aperture usage, enable the linear aperture then disable
                  the VGA aperture.

// --------------------------------------------------------------------------
void             PGL_enableoverscan(unsigned long color,
                                    int leftwidth, int rightwidth,
                                    int topsizewidth, int bottomwidth);

    Inputs      : color        - color of border
                  leftwidth    - left width in pixels * 8
                  rightwidth   - right width in pixels * 8
                  topsizewidth - top width in lines
                  bottomwidth  - bottom width in lines

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Enables the overscan border using the given color and
                  sizes.

// --------------------------------------------------------------------------
void             PGL_enablevgaaperture(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Enables the VGA aperture. Since the VGA aperture is the
                  primary method to access the memory mapped registers, it
                  becomes the usable aperture when it is enabled.

// --------------------------------------------------------------------------
unsigned long    PGL_getapertureaddress(void);

    Inputs      : none

    Outputs     : aperture address in bytes

    Setup       : PGL_initaperture()

    Description : Reads the current physical linear aperture address from
                  the hardware.

// --------------------------------------------------------------------------
PGL_attribute   *PGL_getattributeptr(void);

    Inputs      : none

    Outputs     : pointer to the PGL_attribute structure

    Setup       : none

    Description : Returns a pointer to the PGL internal attribute structure.
                  This allows an application to change elements in the
                  structure directly. This is intended for special purposes
                  use only. See PGL.H for structure elements.

// --------------------------------------------------------------------------
unsigned long    PGL_getcolorcode(int generic_color);

    Inputs      : generic color - BLACK
                                  DARKBLUE
                                  DARKGREEN
                                  DARKCYAN
                                  DARKRED
                                  DARKMAGENTA
                                  BROWN
                                  LIGHTGRAY
                                  DARKGRAY
                                  LIGHTBLUE
                                  LIGHTGREEN
                                  LIGHTCYAN
                                  LIGHTRED
                                  LIGHTMAGENTA
                                  YELLOW
                                  WHITE

    Outputs     : actual color value converted from the 'generic' color

    Setup       : PGL_initmode()

    Description : Returns the actual color value used by the hardware based
                  on the 'generic' color. This allows an application to set
                  a color that is color depth (bits per pixel) independent.
                  This function is primarly used with PGL_setfgcolor() and
                  PGL_setbgcolor(). Also see PGL_setcolordepth() as this
                  function can be used to affect the returned result in
                  24 and 32 bpp modes.

// --------------------------------------------------------------------------
PGL_crttable    *PGL_getcrttable(int table_selection);

    Inputs      : table_selection - CRT_640x480_60
                                    CRT_640x480_72
                                    CRT_640x480_75
                                    CRT_800x600_56
                                    CRT_800x600_60
                                    CRT_800x600_72
                                    CRT_800x600_75
                                    CRT_1024x768_60
                                    CRT_1024x768_70
                                    CRT_1024x768_75
                                    CRT_1280x1024_75

    Outputs     : pointer to a VESA CRT table

    Setup       : PGL_detectmach64()

    Description : Returns a pointer to a VESA CRT table based on the table
                  selection that can be directly used in PGL_initmode(). This
                  should only be used if the Mach64 hardware and monitor are
                  capable of supporting the selected mode.

// --------------------------------------------------------------------------
unsigned long    PGL_getbgcolor(void);

    Inputs      : none

    Outputs     : current background color value

    Setup       : PGL_initmode()

    Description : Returns the current background color value. Please note
                  the returned value will be the last value used in
                  PGL_setbgcolor().

// --------------------------------------------------------------------------
int              PGL_getbgmix(void);

    Inputs      : none

    Outputs     : current background mix value

    Setup       : PGL_initmode()

    Description : Returns the current background mix value. Please note
                  the returned value will be the last value used in
                  PGL_setbgmix().

// --------------------------------------------------------------------------
unsigned long    PGL_getbuffersize(int recwidth, int recheight);

    Inputs      : recwidth  - width of rectangle in pixels
                  recheight - height of rectangle in pixels

    Outputs     : number of dwords to allocate when using
                  PGL_buffertoscreenblit() or PGL_screentobufferblit()

    Setup       : none

    Description : Returns number of dwords to allocate for the above listed
                  functions. The calculation takes into consideration the
                  current color depth (bits per pixel).

// --------------------------------------------------------------------------
void             PGL_getclipsize(PGL_scissor *scissor);

    Inputs      : pointer to scissor structure to be filled by function

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Fills the given structure with the current clip size

// --------------------------------------------------------------------------
unsigned long    PGL_getfgcolor(void);

    Inputs      : none

    Outputs     : current background color value

    Setup       : PGL_initmode()

    Description : Returns the current foreground color value. Please note
                  the returned value will be the last value used in
                  PGL_setfgcolor().

// --------------------------------------------------------------------------
int              PGL_getfgmix(void);

    Inputs      : none

    Outputs     : current foreground mix value

    Setup       : PGL_initmode()

    Description : Returns the current foreground mix value. Please note
                  the returned value will be the last value used in
                  PGL_setfgmix().

// --------------------------------------------------------------------------
PGL_font        *PGL_getfixedfont8x8(void);

    Inputs      : none

    Outputs     : pointer to internal PGL fixed 8x8 font structure

    Setup       : PGL_detectmach64()

    Description : Returns a pointer to the PGL's internal fixed 8x8 font
                  structure. This function has the advantage of always being
                  available without loading a .FNT file (i.e. PGL_loadfont()).
                  It should be noted, however, that the structure is added to
                  the application's size when this function is called.

// --------------------------------------------------------------------------
PGL_font        *PGL_getfixedfont8x14(void);

    Inputs      : none

    Outputs     : pointer to internal PGL fixed 8x14 font structure

    Setup       : PGL_detectmach64()

    Description : See PGL_getfixedfont8x8() for description.

// --------------------------------------------------------------------------
PGL_font        *PGL_getfixedfont7x15(void);

    Inputs      : none

    Outputs     : pointer to internal PGL fixed 7x15 font structure

    Setup       : PGL_detectmach64()

    Description : See PGL_getfixedfont8x8() for description.

// --------------------------------------------------------------------------
PGL_font        *PGL_getfixedfont12x20(void);

    Inputs      : none

    Outputs     : pointer to internal PGL fixed 12x20 font structure

    Setup       : PGL_detectmach64()

    Description : See PGL_getfixedfont8x8() for description.

// --------------------------------------------------------------------------
void             PGL_gethwcursorpos(PGL_point *position);

    Inputs      : pointer to position structure to be filled by the function

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Returns the current position of the hardware cursor.

// --------------------------------------------------------------------------
void             PGL_getmodeconfig(PGL_modeconfig *modeconfig);

    Inputs      : none

    Outputs     : pointer to the PGL_modeconfig structure

    Setup       : PGL_detectmach64(), PGL_initaperture(), or PGL_initmode()

    Description : Fills the given modeconfig structure. Typically, this
                  function is called after an accelerator mode is set to get
                  the modal information about the current mode. However, if
                  only some structure elements are required, this function
                  can be called after PGL_detectmach64() for the chip ID or
                  after PGL_initaperture() for the linear aperture address.
                  See PGL.H for structure elements.

// --------------------------------------------------------------------------
PGL_modeconfig  *PGL_getmodeconfigptr(void);

    Inputs      : none

    Outputs     : pointer to the PGL internal modeconfig structure

    Setup       : none

    Description : Returns a pointer to the PGL internal modeconfig structure.
                  This allows an application to change elements in the
                  structure directly. This is intended for special purposes
                  use only. See PGL.H for structure elements.

// --------------------------------------------------------------------------
int              PGL_getnpolylines(int n, PGL_point *vertices);

    Inputs      : n        - number of sides of the polygon
                  vertices - list of polygon outlines

    Outputs     : number of required off-screen lines for polygon outline

    Setup       : PGL_initmode()

    Description : Returns the number of off-screen lines (in the current mode
                  and color depth) that PGL_drawpolygon() would require to
                  draw the polygon.

// --------------------------------------------------------------------------
PGL_palette      PGL_getpalette(int index);

    Inputs      : index - palette index of desired palette entry

    Outputs     : palette entry at the given index

    Setup       : PGL_initmode()

    Description : Return a specific palette entry.

// --------------------------------------------------------------------------
unsigned long    PGL_getpixel(int x, int y);

    Inputs      : x - pixel X coordinate
                  y - pixel Y coordinate

    Outputs     : pixel value at (x, y)

    Setup       : PGL_initmode()

    Description : Returns the value of a pixel at (x, y).

// --------------------------------------------------------------------------
void             PGL_getposition(PGL_point *position);

    Inputs      : pointer to the return point structure

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Fills the given structure with the current engine position.

// --------------------------------------------------------------------------
unsigned long    PGL_getprimarycolor(PGL_primarycolor primarycolor,
                                     unsigned long color);

    Inputs      : primarycolor - RED
                                 GREEN
                                 BLUE
                  color        - actual color value

    Outputs     : color component (RED, GREEN, or BLUE) of given color

    Setup       : PGL_initmode()

    Description : Returns color component (RED, GREEN, or BLUE) of the given
                  actual color.


void             PGL_getqueryheader(PGL_queryheader *queryinfo);

// --------------------------------------------------------------------------
PGL_queryheader *PGL_getqueryheaderptr(void);

    Inputs      : none

    Outputs     : pointer to the PGL_queryheader structure

    Setup       : none

    Description : Returns a pointer to the PGL internal queryheader structure.
                  This allows an application to change elements in the
                  structure directly. This is intended for special purposes
                  use only. See PGL.H for structure elements.

// --------------------------------------------------------------------------
int              PGL_getquerysize(int fill_type);

    Inputs      : fill_type - HEADER_ONLY
                              HEADER_AND_MODE

    Outputs     : buffer size in bytes

    Setup       : PGL_detectmach64()

    Description : Returns the buffer size required to hold the query
                  information filled by PGL_queryhardware(). There are two
                  fill types: HEADER_ONLY and HEADER_AND_MODE. Zero is
                  returned if an error occurs.

// --------------------------------------------------------------------------
int              PGL_getsrcline(void);

    Inputs      : none

    Outputs     : line for storage of pattern for patterned lines

    Setup       : PGL_initmode()

    Description : Returns the current line for pattern storage. The pattern
                  is used when drawing lines with patterns.

// --------------------------------------------------------------------------
int              PGL_getsrcpoly(void);

    Inputs      : none

    Outputs     : starting line for polygon outlines.

    Setup       : PGL_initmode()

    Description : Returns the current starting line for polygon outlines.
                  When polygons are drawn, their outlines are drawn in
                  monochrome in off-screen memory. The outline image is
                  expanded to the current color depth in on-screen memory
                  during the fill process.

// --------------------------------------------------------------------------
int              PGL_getsrcrect(void);

    Inputs      : none

    Outputs     : starting line for storage of pattern for patterned
                  rectangles

    Setup       : PGL_initmode()

    Description : Returns the current starting line for pattern storage. The
                  pattern is used when drawing rectangles with patterns.

// --------------------------------------------------------------------------
PGL_version      PGL_getversion(void);

    Inputs      : none

    Outputs     : current version of the PGL

    Setup       : none

    Description : Returns the current version of the PGL in structure format.

// --------------------------------------------------------------------------
unsigned long    PGL_getwritemask(void);

    Inputs      : none

    Outputs     : current version of the PGL

    Setup       : PGL_initmode()

    Description : Returns the current engine pixel mask value. Please note
                  the returned value will be the last value used in
                  PGL_setwritemask().

// --------------------------------------------------------------------------
int              PGL_initaperture(int register_access);

    Inputs      : register_access - AUTO_APERTURE
                                    USE_VGA_APERTURE
                                    USE_LINEAR_APERTURE

    Outputs     : NO_ERROR
                  NO_APERTURE
                  QUERY_FAILED
                  FAILED_REG_TEST

    Setup       : PGL_detectmach64()

    Description : This function MUST be called before any memory mapped
                  register PGL functions since they depend on internal
                  structures filled by this function. 'register_access'
                  determines which aperture to turn on. The VGA aperture
                  is the primary access method and will be used if it is
                  enabled. The return code should be checked before
                  proceeding.

// --------------------------------------------------------------------------
void             PGL_initengine(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function initializes the Mach64 engine to a known
                  state. The clipping rectangle is set to the size of the
                  active mode, foreground mixes are set to overpaint,
                  background mix are set to destination, color compare
                  functions are set to false, and the write mask is set to
                  affect all planes. This function also initiatizes the data
                  structure with the engine context values. This function is
                  called when a mode is set (PGL_initmode()).

// --------------------------------------------------------------------------
int              PGL_initmode(int x,
                              int y,
                              int bpp,
                              int depth,
                              int pitch,
                              unsigned long offset,
                              int attribute_flags,
                              int mode_number,
                              PGL_crttable far *tableinfo,
                              int eeprom_offset);

    Inputs      : x               - X resolution in pixels
                  y               - Y resolution in pixels
                  bpp             - bits per pixel (4, 8, 15, 16, 24, 32)
                  depth           - set to zero
                  pitch           - pitch in pixels
                  offset          - starting offset into video memory (qwords)
                  attribute_flags - NO_ATTRIBUTES
                                    PALETTIZED_MODE
                                    BYPASS_MODE
                                    CLOSE_MODE
                                    NO_CLEAR_SCREEN
                                    NO_PACKED_PIXEL
                                    NO_AUTO_DEPTH
                  mode_number     - MODE_640x480
                                    MODE_800x600
                                    MODE_1024x768
                                    MODE_1280x1024
                                    MODE_1600x1200
                                    MODE_OTHER
                                    USE_CRT_TABLE
                                    USE_EEPROM_OFFSET
                  crttable        - pointer to CRT table
                  eeprom_offset   - eeprom offset in bytes for mode table

    Outputs     : MODE_SUPPORTED
                  MODE_NOT_SUPPORTED
                  NO_APERTURE

    Setup       : PGL_initaperture()

    Description : This function sets an accelerator mode and initializes the
                  Mach64 engine according to the given input parameters.
                  Typically, the application retrieves the query information
                  from the ROM which contains the available modes. However, a
                  mode can be quickly set by using one of the standard
                  defined ROM mode numbers. The return code should be checked
                  The 'depth' parameter is useful for 24 or 32 bpp modes and
                  will not be used unless the NO_AUTO_DEPTH flag is set.
                  Normally, this function will automatically select a color
                  depth based on a support byte in the ROM query header. The
                  'depth' value is normally set to zero.

// --------------------------------------------------------------------------
void             PGL_initpalette(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Initializes the palette after an accelerator mode has been
                  set for 4 and 8 bpp modes.

// --------------------------------------------------------------------------
void             PGL_initpalettized(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Initializes the palette after an accelerator mode has been
                  set for 15, 16, 24, and 32 bpp modes where the hardware
                  supports palettized modes in these color depths.

// --------------------------------------------------------------------------
void             PGL_loadcontext(unsigned int loadpointer,
                                 unsigned long attribute);

    Inputs      : loadpointer - 0 = top of memory, n = top - (256 * (n + 1))
                  attribute   - CONTEXT_NO_LOAD
                                CONTEXT_LOAD
                                CONTEXT_LOAD_AND_DO_FILL
                                CONTEXT_LOAD_AND_DO_LINE
                                CONTEXT_CMD_DISABLE

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Loads a context into the Mach64 GUI registers from a
                  previously uploaded context array to video memory using
                  PGL_uploadcontext(). The context load pointer should be set
                  to the desired context array in video memory to load. The
                  attributes determine the action after the register load
                  takes place. These are mutually exclusive except
                  CONTEXT_CMD_DISABLE which can be ORed in with the other
                  attribute values. Note that the upper 16 bits of the
                  CONTEXT_LOAD_CNTL register is used for the context load
                  attribute.

// --------------------------------------------------------------------------
int              PGL_loadfont(char *fontfile, PGL_font *font);

    Inputs      : fontfile - name of .FNT file to load in
                  font     - structure to be filled with font information

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_detectmach64()

    Description : This function loads the font file and fills the PGL_font
                  structure with the appropriate font information. Since
                  memory is allocated in this function, PGL_unloadfont()
                  should be called to release the memory before exiting the
                  application.

// --------------------------------------------------------------------------
PGL_modedef     *PGL_loadmodelist(int *modes);

    Inputs      : modes - filled with the number of available modes

    Outputs     : returns a list of available modes

    Setup       : PGL_initaperture()

    Description : Returns a list of available modes supported by the hardware.
                  The structure elements correspond to the input parameters
                  of PGL_initmode(). If 'modes' is filled with zero, no
                  available modes exist. This means that the hardware has not
                  be installed properly.

// --------------------------------------------------------------------------
unsigned long    PGL_makecolor(unsigned long r,
                               unsigned long g,
                               unsigned long b);

    Inputs      : r - red component of color
                  g - green component of color
                  b - blue component of color

    Outputs     : returns actual color made up of input color components or
                  NOCOLORMATCH

    Setup       : PGL_initmode()

    Description : This function takes the given color components (RED, GREEN,
                  and BLUE) and combines them into a single color value (15,
                  16, 24, and 32 bpp modes). For palettized modes (4 and 8
                  bpp), the color components will be matched with the current
                  palette and the matching index will be returned. If no
                  match is found, NOCOLORMATCH is returned (0xffff).

// --------------------------------------------------------------------------
void             PGL_monoexpandblit(int srcleft, int srctop,
                                    int dstleft, int dsttop,
                                    int recwidth, int recheight);

    Inputs      : srcleft   - source X coordinate in pixels
                  srctop    - source Y coordinate in pixels
                  dstleft   - destination X coordinate in pixels
                  dsttop    - destination Y coordinate in pixels
                  recwidth  - rectangle width in pixels
                  recheight - rectangle height in lines

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function blits monochrome data in screen memory
                  (SRCLEFT, SRCTOP) and color expands the data to another
                  region in screen memory (DSTLEFT, DSTTOP). The monochrome
                  data must be in linear format (this data is usually
                  uploaded to screen memory by function PGL_monotoscreenblit().
                  The color expansion operation uses the current engine mix
                  and colors. A "1" in the monochrome data is expanded using
                  the foreground color path and a "0" in the monochrome data
                  is expanded using the background color path.

// --------------------------------------------------------------------------
void             PGL_monotoscreenblit(unsigned long huge *bufferptr,
                                      int dstleft, int dsttop,
                                      int recwidth, int recheight);

    Inputs      : bufferptr - pointer to monochrome bitmap to copy
                  dstleft   - destination X coordinate in pixels
                  dsttop    - destination Y coordinate in pixels
                  recwidth  - rectangle width of bitmap
                  recheight - rectangle height of bitmap

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function takes a monochrome bitmap contained in the
                  given buffer and copies it to (DSTLEFT, DSTTOP) in linear
                  format. RECWIDTH * RECHEIGHT describes the total number of
                  bits to transfer from the buffer to screen memory. Function
                  PGL_monoexpandblit() is normally used to color expand the
                  monochrome data to on-screen memory.

// --------------------------------------------------------------------------
void             PGL_moveto(int x, int y);

    Inputs      : x - X coordinate in pixels
                  y - Y coordinate in pixels

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function changes the current drawing position using
                  the CUR_X and CUR_Y registers. The parameters x and y hold
                  the x and y coordinates of the new drawing position.

// --------------------------------------------------------------------------
PGL_point        PGL_ncscreentoscreenblit(int recleft, int rectop,
                                          int recwidth, int recheight,
                                          int x, int y,
                                          int saveflag);

    Inputs      : recleft   - on-screen X coordinate in pixels
                  rectop    - on-screen Y coordinate in pixels
                  recwidth  - rectangle width in pixels
                  recheight - rectangle height in lines
                  x         - off-screen X coordinate in pixels
                  y         - off-screen Y coordinate in pixels
                  saveflag  - SAVE_BLIT    (on-screen = source)
                              RESTORE_BLIT (on-screen = destination)

    Outputs     : returns ending coordinate in reference to (x, y)

    Setup       : PGL_initmode()

    Description : This function is similiar to PGL_screentoscreenblit()
                  except that the region copied is stored in a linear format
                  thus making efficient use of off-screen memory. The
                  rectanglar parameters describe the on-screen memory
                  non-linearized region and (x, y) points to the linearized
                  off-screen starting coordinate. The 'saveflag' parameter
                  determines if the rectangle region is the source or
                  destination (SAVE_BLIT, RESTORE_BLIT). The returned
                  coordinate points to the end position of the linearized
                  data region. If the end position exceeds the top of memory
                  (PGL_modecfg.maxy), nothing is copied.

// --------------------------------------------------------------------------
int              PGL_queryhardware(int fill_type, void far *queryptr);

    Inputs      : fill_type - HEADER_ONLY
                              HEADER_AND_MODE
                  queryptr  - pointer to buffer to fill with query info

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_detectmach64()

    Description : This function queries the Mach64 hardware and fills the
                  given query buffer. As in PGL_getquerysize(), two fill
                  types are available: HEADER_ONLY and HEADER_AND_MODE.

// --------------------------------------------------------------------------
void             PGL_resetengine(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function resets the engine. This is useful if the
                  engine fifo has overflowed, or if it has entered an unknown
                  state.

// --------------------------------------------------------------------------
void             PGL_restorepalette(PGL_palette *paletteBuffer);

    Inputs      : paletteBuffer - pointer to buffer to restore palette

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function restores the 256 palette entries from the
                  given buffer filled by a previous call to PGL_savepalette().

// --------------------------------------------------------------------------
void             PGL_savepalette(PGL_palette *paletteBuffer);

    Inputs      : paletteBuffer - pointer to buffer to fill with palette data

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function reads and saves the 256 palette entries into
                  the given buffer. The buffer must be large enough to hold
                  the data.

// --------------------------------------------------------------------------
void             PGL_screentobufferblit(unsigned long huge *bufferptr,
                                        int srcleft, int srctop,
                                        int recwidth, int recheight);

    Inputs      : bufferptr - pointer to buffer to fill with screen data
                  srcleft   - source X coordinate in pixels
                  srctop    - source Y coordinate in pixels
                  recwidth  - rectangle width in pixels
                  recheight - rectangle height in lines

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function copies a regtangular area of data from the
                  screen to a ram buffer. The bufferptr parameter is a
                  pointer to a buffer in ram which is used as the destination
                  for the transfer. The srcleft parameter contains the
                  leftmost x coordinate of the source rectangle. The srctop
                  parameter contains topmost y coordinate of the source
                  rectangle. The recwidth and recheight parameters define the
                  height and width of the rectangle in pixels.

// --------------------------------------------------------------------------
void             PGL_screentoscreenblit(int srcleft, int srctop,
                                        int dstleft, int dsttop,
                                        int recwidth, int recheight);

    Inputs      : srcleft   - source X coordinate in pixels
                  srctop    - source Y coordinate in pixels
                  dstleft   - destination X coordinate in pixels
                  dsttop    - destination Y coordinate in pixels
                  recwidth  - rectangle width in pixels
                  recheight - rectangle height in lines

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function copies a regtangular area of data from one
                  area of video memory to another. A color screen to screen
                  blit is performed by copying the contents of the source
                  rectangle to the destination rectangle, using the current
                  mixes. The srcleft parameter contains the leftmost x
                  coordinate of the source rectangle. The srctop parameter
                  contains topmost y coordinate of the source rectangle. The
                  dstleft and dsttop parameters contain the same for the
                  destination rectangle. The recwidth and recheight
                  parameters define the height and width of the rectangle in
                  pixels. This function supports overlapping blit regions.

// --------------------------------------------------------------------------
void             PGL_setapertureaddress(unsigned long address);

    Inputs      : aperture address in bytes

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Sets the current physical linear aperture address of the
                  hardware.

// --------------------------------------------------------------------------
void             PGL_setclipsize(int left, int top, int right, int bottom);

    Inputs      : left   - left scissor in pixels
                  top    - top scissor in pixels
                  right  - right scissor in pixels
                  bottom - bottom scissor in pixels

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the clipping rectangle size using the
                  four scissor registers: SCISSOR_LEFT, SCISSOR_TOP,
                  SCISSOR_RIGHT, SCISSOR_BOTTOM. The four parameters specify
                  the x and y coordinates of the upper left corner and lower
                  right corner of the clipping rectangle. The input values
                  are inclusive.

// --------------------------------------------------------------------------
void             PGL_setcolordepth(int depth);

    Inputs      : depth = 0             - 4 & 8 bpp modes
                          555           - 15 bpp modes
                          565           - 16 bpp modes
                          DEPTH_24_RGB  - RGB 24 bpp modes
                          DEPTH_24_BGR  - BGR 24 bpp modes
                          DEPTH_32_RGBA - RGBa 32 bpp modes
                          DEPTH_32_ARGB - aRGB 32 bpp modes
                          DEPTH_32_BGRA - BGRa 32 bpp modes
                          DEPTH_32_ABGR - aBGR 32 bpp modes

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function can be used to change the default color
                  weight used by PGL_getcolorcode() to return a real color
                  value. This function is useful for the color weight where
                  more than one choice exists. This function should only be
                  called if your application has setup the RAMDAC correctly
                  and the RAMDAC supports the selected color weight,
                  otherwise unexpected result will occur.

// --------------------------------------------------------------------------
void             PGL_setbgcolor(unsigned long color);

    Inputs      : color

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function is used to set the background color. The
                  parameter 'color' must be a value that falls within the
                  possible values for the current pixel depth. Function
                  PGL_getcolorcode() can be used as an input to get a legal
                  value from a given generic color.

// --------------------------------------------------------------------------
void             PGL_setbgmix(int mix);

    Inputs      : mix - NOT_D_MIX
                        ZERO_MIX
                        ONE_MIX
                        D_MIX
                        NOT_S_MIX
                        D_XOR_S_MIX
                        NOT_D_XOR_S_MIX
                        S_MIX
                        NOT_D_OR_NOT_S_MIX
                        D_OR_NOT_S_MIX
                        NOT_D_OR_S_MIX
                        D_OR_S_MIX
                        D_AND_S_MIX
                        NOT_D_AND_S_MIX
                        D_AND_NOT_S_MIX
                        NOT_D_AND_NOT_S_MIX
                        D_PLUS_S_DIV2_MIX

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the background mix value in the DP_MIX
                  register.

// --------------------------------------------------------------------------
void             PGL_setfgcolor(unsigned long color);

    Inputs      : color

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function is used to set the foreground color. The
                  parameter color must be a value that falls within the
                  possible values for the current pixel depth. Function
                  PGL_getcolorcode() can be used to get a legal value from a
                  given generic color.

// --------------------------------------------------------------------------
void             PGL_setfgmix(int mix);

    Inputs      : mix - NOT_D_MIX
                        ZERO_MIX
                        ONE_MIX
                        D_MIX
                        NOT_S_MIX
                        D_XOR_S_MIX
                        NOT_D_XOR_S_MIX
                        S_MIX
                        NOT_D_OR_NOT_S_MIX
                        D_OR_NOT_S_MIX
                        NOT_D_OR_S_MIX
                        D_OR_S_MIX
                        D_AND_S_MIX
                        NOT_D_AND_S_MIX
                        D_AND_NOT_S_MIX
                        NOT_D_AND_NOT_S_MIX
                        D_PLUS_S_DIV2_MIX

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the foreground mix value in the DP_MIX
                  register.

// --------------------------------------------------------------------------
void             PGL_setfifocontrol(int check_control, int action_control);

    Inputs      : check_control -  FIFO_CHECK_NORMAL
                                   FIFO_CHECK_TIMEOUT
                  action_control - FIFO_ACTION_NONE
                                   FIFO_ACTION_TERMINATE

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function allows the application to control the
                  behaviour of the PGL fifo and idle functions if an engine
                  error occurs. 'check_control' indicates what errors to
                  check for. 'action_control' indicates what to do if an
                  error occurs. The FIFO_ACTION_TERMINATE value will cause
                  termination of the ENTIRE application if an errors occurs.
                  The main purpose for this function is for debugging since
                  an error should never happen in a correctly programmed
                  application.

// --------------------------------------------------------------------------
void             PGL_setfillpattern(int width, int height,
                                    unsigned long *fillpattern);

    Inputs      : width       - width of pattern
                  height      - height of pattern
                  fillpattern - pointer to pattern bitmap

    Outputs     : none

    Setup       : PGL_initmode(), PGL_setfilltype()

    Description : This function sets the pattern used when pattern filled
                  shapes are drawn. The fill pattern can be upto 32 x 32 bits.
                  The input parameters 'width' and 'height' must not exceed
                  32 or the fill pattern will remain unchanged. The given
                  'fillpattern' is interpreted as a mono bitmap using the
                  mono pattern registers to implement the fill. The pattern
                  is drawn from the most significant bit to the least
                  significant bit. The function PGL_setfilltype() must be
                  called to enable user defined pattern fills.

// --------------------------------------------------------------------------
void             PGL_setfilltype(int type);

    Inputs      : type - USERDEFINED_FILL
                         SOLID_FILL

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the fill type to either a solid fill or
                  a user defined fill pattern of upto 32x32 bits. The
                  parameter type determines which type of fill will be used.
                  If the type is USERDEFINED_FILL, the pattern is defined by
                  a call to function PGL_setfillpattern().

// --------------------------------------------------------------------------
int              PGL_sethwcursor(int y, int width, int height,
                                 int hot_x, int hot_y,
                                 unsigned long color0, unsigned long color1,
                                 unsigned int *bitmap);

    Inputs      : y      - Y line to place cursor data (X = 0)
                  width  - width of visible cursor (1 to 64)
                  height - height of visible cursor (1 to 64)
                  hot_x  - X offset in cursor pixels from left-top corner
                  hot_y  - Y offset in cursor pixels from left-top corner
                  color0 - color value of cursor color 0
                  color1 - color value of cursor color 1
                  bitmap - pointer to cursor bitmap

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function uploads the bitmap to the cursor data region
                  at (0, y) in video memory. If the DAC type is a TVP3026 or
                  an IBM514, the data is loaded directly to the on-chip
                  cursor data registers. The cursor colors and hot spot is
                  also defined in this function. The hot spot must be within
                  the visible cursor area (width & height). The hot spot is
                  referenced to the left-top corner of the visible cursor.
                  The cursor data is organized in packed contigious data
                  where each 2 bit quantity corresponds to a cursor pixel:

                    00 - Cursor color 0
                    01 - Curosr color 1
                    10 - Transparent (current display pixel)
                    11 - Complement (1's complement of current display pixel)

                  Since the cursor size is 64x64, the total data size is
                  1024 bytes.

// --------------------------------------------------------------------------
void             PGL_sethwcursorpos(int x, int y);

    Inputs      : x - X position of cursor
                  y - Y position of cursor

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the position of the hardware cursor.

// --------------------------------------------------------------------------
void             PGL_setlinepattern(unsigned long linepattern, int length);

    Inputs      : width       - width of pattern
                  height      - height of pattern
                  fillpattern - pointer to pattern bitmap

    Outputs     : none

    Setup       : PGL_initmode(), PGL_setlinetype()

    Description : This function sets the current line pattern by user
                  definition. Calling this function will replace the line
                  pattern type selected in PGL_setlinetype(). The line
                  pattern can be upto 32 bits long. The pattern is interpreted
                  from bit['length'] to bit[0'] of 'linepattern'. The 'length'
                  parameter must be 1 to 32. The pattern will remain unchanged
                  if the 'length' parameter is invalid. The function
                  PGL_setlinetype() must be called to enable user defined
                  line patterns.

// --------------------------------------------------------------------------
void             PGL_setlinetype(int type);

    Inputs      : type - USERDEFINED_LINE
                         DOTTED_LINE
                         SHORT_DASHED_LINE
                         DASH_DOT_LINE
                         DOUBLE_DOTTED_LINE
                         LONG_DASH_LINE
                         DASH_DOUBLE_DOT_LINE
                         SOLID_LINE
                         INVISIBLE_LINE

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the current line pattern. The line
                  pattern used is determined by the line pattern type given
                  or by a user defined line pattern of up to 32 bits long.
                  The line pattern will remain unchanged if the 'type' in
                  invalid.

// --------------------------------------------------------------------------
void             PGL_setpalette(int index, PGL_palette entry);

    Inputs      : index - palette index of desired palette entry
                  entry - new palette value

    Outputs     : palette entry at the given index

    Setup       : PGL_initmode()

    Description : This function sets a specific palette entry to the red,
                  green and blue values passed in the parameters of the same
                  names. Each of the color components has a range of 0 to 63.
                  The index parameter has a range of 0 to 255.

// --------------------------------------------------------------------------
void             PGL_setsrcline(int y);

    Inputs      : y - line storage for line pattern usage

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Sets the current line for line pattern storage. This
                  pattern is used when calling PGL_drawline() or PGL_drawto()
                  with the line type set to a pattern other than solid. The
                  line is preset since the function is called by
                  PGL_initmode().

// --------------------------------------------------------------------------
void             PGL_setsrcpoly(int y);

    Inputs      : y - starting line to use when polygon outlines are drawn

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Sets the current starting line for polyline outline use.
                  The area is used for drawing polygon outlines when function
                  PGL_drawpolygon() is called. The line is preset since the
                  function is called by PGL_initmode().

// --------------------------------------------------------------------------
void             PGL_setsrcrect(int y);

    Inputs      : y - line storage for rectangle pattern usage

    Outputs     : none

    Setup       : PGL_initmode()

    Description : Sets the current starting line for rectangle pattern
                  storage. This pattern is used when calling PGL_drawrect()
                  with the fill type set to user-defined. The line is preset
                  since the function is called by PGL_initmode().

// --------------------------------------------------------------------------
void             PGL_setwritemask(unsigned long mask);

    Inputs      : mask - AND mask of engine output to video memory

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function sets the engine pixel write mask by writing
                  to the DP_WRITE_MASK register. Data is passed for '1' bits,
                  blocked for '0' bits.

// --------------------------------------------------------------------------
void             PGL_text(int x, int y, char *string, PGL_font *font);

    Inputs      : x      - X coordinate in pixels
                  y      - Y coordinate in pixels
                  string - pointer to a NULL terminated string
                  font   - pointer to a valid font buffer

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function prints a string starting at position (x,y)
                  using the font data contained in the given font structure.
                  (x, y) is interpreted as the top-left point to start
                  drawing. A previous successful call to a function that
                  properly fills a font buffer is mandatory for this function
                  is work. If the font structure contains invalid information,
                  nothing is displayed. The string is assumed to be '\0' or
                  NULL terminated. The following functions can be used to
                  fill a font buffer before using this function:

                        PGL_loadfont()/PGL_unloadfont(),
                        PGL_vgafont(),
                        PGL_getfixedfont8x8(),
                        PGL_getfixedfont8x14(),
                        PGL_getfixedfont7x15(),
                        PGL_getfixedfont12x20()

// --------------------------------------------------------------------------
void             PGL_unblankscreen(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Unblanks the screen using a ROM DPMS call. This function is
                  usually called after a previous call to PGL_blankscreen()
                  when it is desired to allow the screen contents to be
                  viewed.

// --------------------------------------------------------------------------
void             PGL_updateaperturestatus(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : This function updates the PGL by reading the hardware
                  aperture information. It should be called if the aperture
                  state is changed without using PGL functions to perform the
                  change.

// --------------------------------------------------------------------------
void             PGL_uploadcontext(unsigned int loadpointer,
                                   PGL_context far *context);

    Inputs      : loadpointer - 0 = top of memory, n = top - (256 * (n + 1))
                  context     - pointer to context buffer

    Outputs     : none

    Setup       : PGL_initmode()

    Description : This function uploads the given context array to video
                  memory. Each context pointer represents 256 bytes of video
                  memory. The context load address decreases toward the start
                  of video memory as the context load pointer increases. The
                  video address is calculated as follows:

                    top_of_video_memory - ((load_pointer + 1) * 256)

                  If the linear aperture is being used, the video address is
                  added to the linear aperture base address. Also, do not use
                  load pointers 0-3 if the linear aperture size equals the
                  video memory size since this will cause an overwrite of the
                  GUI registers.

// --------------------------------------------------------------------------
void             PGL_unloadfont(PGL_font *font);

    Inputs      : font     - valid font structure

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : This function unloads a font loaded previously by
                  PGL_loadfont(). The memory allocated by a successful call
                  to PGL_loadfont() is released by this function. For
                  multiple font loads, releasing them should be done in the
                  reverse order of loading. This method will insure minimum
                  memory fragmentation.

// --------------------------------------------------------------------------
void             PGL_unloadmodelist(PGL_modedef *modelist);

    Inputs      : modelist - pointer to a valid modelist buffer

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : This function should be called before exiting the
                  application if a successful call was made to
                  PGL_loadmodelist().

// --------------------------------------------------------------------------
int              PGL_vgafont(int vgafontsize, PGL_font *font);

    Inputs      : vgafontsize - VGAFONT_8x8
                                VGAFONT_8x14
                                VGAFONT_8x16
                  font        - pointer to a font buffer to be filled

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_initaperture()

    Description : The given font structure is filled so that text (through
                  PGL_text) may be displayed without loading any external
                  font files. The font size is determined by the 'vgafontsize'
                  input parameter. Three sizes are available. NO_ERROR is
                  returned for a successful call, otherwise YES_ERROR is
                  returned.

// --------------------------------------------------------------------------
int              PGL_waitforemptyfifo(void);

    Inputs      : none

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_initmode()

    Description : This is a fast version of PGL_waitforfifo(16). The return
                  code is only meaningful if PGL_fifocontrol() was called
                  to detect errors.

// --------------------------------------------------------------------------
int              PGL_waitforfifo(int entries);

    Inputs      : none

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_initmode()

    Description : This function waits until the Mach64 engine has a minimum
                  number of empty fifo entries by reading the value of the
                  FIFO_STAT register. The entries parameter must be 1 to 16.
                  The return code is only meaningful if PGL_fifocontrol()
                  was called to detect errors.

// --------------------------------------------------------------------------
int              PGL_waitforidle(void);

    Inputs      : none

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_initmode()

    Description : This function waits for the Mach64 engine to reach the idle
                  state by waiting the engine idle bit to clear (GUI_STAT).
                  It also waits for the fifo is become completely empty. The
                  return code is only meaningful if PGL_fifocontrol() was
                  called to detect errors.

// --------------------------------------------------------------------------
void             PGL_waitforvblank(int frames);

    Inputs      : frames - number of frames to wait for (1 to n).

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Waits for 'frame' vertical blanks. The function waits for
                  the trailing edge of the vsync pulse.

// --------------------------------------------------------------------------
void             PGL_waitforvblankst(int frames);

    Inputs      : frames - number of frames to wait for (1 to n).

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Waits for 'frame' vertical blanks. The function waits for
                  the starting edge of the vsync pulse.

// --------------------------------------------------------------------------
unsigned long    regr(unsigned int regindex);

    Inputs      : regindex - byte offset to a memory mapped register

    Outputs     : none

    Setup       : PGL_initaperture()

    Description : Reads a 32 bit value from a memory mapped register. The
                  'regindex' is a byte offset. See ATIM64.H for values.

// --------------------------------------------------------------------------
int              regw(unsigned int regindex, unsigned long regdata);

    Inputs      : regindex - byte offset to a memory mapped register

    Outputs     : NO_ERROR
                  YES_ERROR

    Setup       : PGL_initaperture()

    Description : Writes a 32 bit value to a memory mapped register. The
                  'regindex' is a byte offset. See ATIM64.H for values. In
                  general, the return code is ignored since a register check
                  is done in PGL_initaperture().

Ŀ
  PGL.LIB Function Reference - Special functions                            


This section describes each function in detail. Each function is described
in terms of inputs, outputs, setup functions that must be called before using
the function, and description of what the function does. The following is a
quick reference list of special PGL functions. They are described in detail
afterwards.

void             pgl_blankvgascreen(void);
unsigned int     pgl_getrombase(void);
unsigned int     pgl_getvideomode(void);
unsigned long    pgl_getxyoffset(int x, int y);
void             pgl_initioreg(unsigned int iobase, int iotype);
void             pgl_initmemreg(int vga_app_status,
                                unsigned long aperture_base_address,
                                unsigned long register_memory_offset);
int              pgl_movemem(void far *src, unsigned long dest,
                             unsigned int nwords,
                             int direction);
void             pgl_setrombase(unsigned int rom_segment);
void             pgl_setvideomode(unsigned int vmode);
void             pgl_unblankvgascreen(void);
void             pgl_updateappvars(void);
int              ROM_aperturecontrol(int aperture_control);
int              ROM_fillquerystructure(int info_type, void far *ptr);
int              ROM_getiobase(PGL_iobasequery far *iobaseinfo);
int              ROM_getquerysize(int info_type);
int              ROM_loadandsetmode(int resolution_code,
                                    int pitch_code,
                                    int color_depth_code,
                                    int palettized_flag,
                                    PGL_crttable far *tableinfo,
                                    int eeprom_offset);
int              ROM_loadmodeparms(int resolution_code,
                                   int pitch_code,
                                   int color_depth_code,
                                   int palettized_flag,
                                   PGL_crttable far *tableinfo,
                                   int eeprom_offset);
int              ROM_readeeprom(unsigned int index, unsigned int far *data);
int              ROM_setdisplaymode(int display_mode, int palettized_flag);
int              ROM_setdpmscontrol(int service_code);
int              ROM_shortquery(PGL_shortquery far *shortqueryinfo);
int              ROM_DDCquery(unsigned int far *rom_support,
                              unsigned int far *monitor_support);
int              ROM_DDCreadEDID(unsigned int bufsize,
                                 PGL_DDC_EDID far *packet);
int              ROM_writeeeprom(unsigned int index, unsigned int data);

// --------------------------------------------------------------------------
void             pgl_blankvgascreen(void);

    Inputs      : none

    Outputs     : none

    Setup       : none

    Description : Blanks the screen in VGA mode.

// --------------------------------------------------------------------------
unsigned int     pgl_getrombase(void);

    Inputs      : none

    Outputs     : ROM segment

    Setup       : PGL_detectmach64()

    Description : Low-level function that returns the ROM segment.

// --------------------------------------------------------------------------
unsigned int     pgl_getvideomode(void);

    Inputs      : none

    Outputs     : current video mode - upper 8 bits = text mode height - 1
                                       lower 8 bits = actual video mode

    Setup       : PGL_detectmach64()

    Description : Low-level function that returns the current video mode.


// --------------------------------------------------------------------------
unsigned long    pgl_getxyoffset(int x, int y);
void             pgl_initioreg(unsigned int iobase, int iotype);
void             pgl_initmemreg(int vga_app_status,
                                unsigned long aperture_base_address,
                                unsigned long register_memory_offset);
int              pgl_movemem(void far *src, unsigned long dest,
                             unsigned int nwords,
                             int direction);
void             pgl_setrombase(unsigned int rom_segment);

// --------------------------------------------------------------------------
void             pgl_setvideomode(unsigned int vmode);

    Inputs      : current video mode - upper 8 bits = text mode height - 1
                                       lower 8 bits = actual video mode

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Low-level function that sets current video mode based on
                  the value returned from pgl_getvideomode(). For text modes,
                  the upper 8 bits of 'vmode' should be 0x18 for 25 lines,
                  0x2a for 43 lines, and 0x31 for 50 lines. For graphics
                  modes, it should be zero.

// --------------------------------------------------------------------------
void             pgl_unblankvgascreen(void);

    Inputs      : none

    Outputs     : none

    Setup       : none

    Description : Unblanks the screen in VGA mode.

// --------------------------------------------------------------------------
void             pgl_updateappvars(void);

    Inputs      : none

    Outputs     : none

    Setup       : PGL_detectmach64()

    Description : Low-level function that updates functions REGW() and
                  REGR() for aperture usage depending on the current state
                  of the PGL. This function is called by all PGL functions
                  that change or effect the apertures or their state.

// --------------------------------------------------------------------------
int              ROM_aperturecontrol(int aperture_control);

    Inputs      : aperture_control - DISABLE_APERTURE (both)
                                   - ENABLE_LINEAR_APERTURE
                                   - ENABLE_VGA_APERTURE

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 05h. It controls enabling or disabling of the
                  VGA or Linear aperture. Refer to the Mach64 BIOS
                  specification for more details.

// --------------------------------------------------------------------------
int              ROM_fillquerystructure(int info_type, void far *ptr);

    Inputs      : info_type - HEADER_ONLY
                              HEADER_AND_MODE
                  ptr       - pointer to query buffer to fill

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 09h. It fills a given buffer with query
                  information about the hardware. The type of information
                  requested determines the size of the buffer. Call
                  ROM_getquerysize() to get the size of query buffer to be
                  allocated. Refer to the Mach64 BIOS specification for more
                  details.

// --------------------------------------------------------------------------
int              ROM_getiobase(PGL_iobasequery far *iobaseinfo);

    Inputs      : iobaseinfo - pointer to I/O base structure to be filled

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 12h. This function returns the I/O base
                  address and type for the hardware. This function is called
                  by PGL_detectmach64() after the rom segment has been
                  identified to retrieve the I/O base address. This is
                  required information for the IOR() and IOW() functions.
                  Refer to the Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_getquerysize(int info_type);

    Inputs      : info_type - HEADER_ONLY
                              HEADER_AND_MODE

    Outputs     : 0 if error,
                  size of query buffer in bytes if no error

    Setup       : PGL_detectmach64()

    Description : ROM function 08h. It returns the size of the query buffer
                  required to be filled by a call to ROM_fillquerystructure().
                  Refer to the Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_loadandsetmode(int resolution_code,
                                    int pitch_code,
                                    int color_depth_code,
                                    int palettized_flag,
                                    PGL_crttable far *tableinfo,
                                    int eeprom_offset);

    Inputs      : resolution_code  - MODE_640x480
                                     MODE_800x600
                                     MODE_1024x768
                                     MODE_1280x1024
                                     MODE_1600x1200
                                     MODE_OTHER
                                     USE_CRT_TABLE
                                     USE_EEPROM_OFFSET
                  pitch_code       - PITCH_1024
                                     PITCH_NOCHANGE
                                     PITCH_XRES
                  color_depth_code - COLOR_DEPTH_4
                                     COLOR_DEPTH_8
                                     COLOR_DEPTH_15
                                     COLOR_DEPTH_16
                                     COLOR_DEPTH_24
                                     COLOR_DEPTH_32
                  palettized_flag  - PALETTIZE_DISABLE
                                     PALETTIZE_ENABLE
                  tableinfo        - segment:offset pointer if
                                     resolution_code = USE_CRT_TABLE
                  eeprom_offset    - byte offset into eeprom if
                                     resolution_code = USE_EEPROM_OFFSET

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 02h. This function loads and sets an
                  accelerator mode using the given inputs. Refer to the
                  Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_loadmodeparms(int resolution_code,
                                   int pitch_code,
                                   int color_depth_code,
                                   int palettized_flag,
                                   PGL_crttable far *tableinfo,
                                   int eeprom_offset);

    Inputs      : resolution_code  - MODE_640x480
                                     MODE_800x600
                                     MODE_1024x768
                                     MODE_1280x1024
                                     MODE_1600x1200
                                     MODE_OTHER
                                     USE_CRT_TABLE
                                     USE_EEPROM_OFFSET
                  pitch_code       - PITCH_1024
                                     PITCH_NOCHANGE
                                     PITCH_XRES
                  color_depth_code - COLOR_DEPTH_4
                                     COLOR_DEPTH_8
                                     COLOR_DEPTH_15
                                     COLOR_DEPTH_16
                                     COLOR_DEPTH_24
                                     COLOR_DEPTH_32
                  palettized_flag  - PALETTIZE_DISABLE
                                     PALETTIZE_ENABLE
                  tableinfo        - segment:offset pointer if
                                     resolution_code = USE_CRT_TABLE
                  eeprom_offset    - byte offset into eeprom if
                                     resolution_code = USE_EEPROM_OFFSET

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 00h. This function loads the CRT parameters
                  in preparation for switching to an accelerator mode.
                  Function ROM_setdisplaymode() is required to actually set
                  the mode. Refer to the Mach64 BIOS specification for more
                  details.

// --------------------------------------------------------------------------
int              ROM_readeeprom(unsigned int index, unsigned int far *data);

    Inputs      : index - byte index of eeprom entry to read
                  data  - pointer to word buffer to fill

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 03h. This function reads an eeprom entry.
                  Refer to the Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_setdisplaymode(int display_mode,
                                    int palettized_flag
                                    (int far *)(&doubleclock_flag));

    Inputs      : display_mode         - VGA_MODE
                                         ACCELERATOR_MODE
                  palettized_flag      - PALETTIZE_DISABLE
                                         PALETTIZE_ENABLE
                  doubleclock_flag ptr - filled with STANDARD_CLOCK or
                                         DOUBLE_CLOCK

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 01h. This function either sets an accelerator
                  or VGA mode. Refer to the Mach64 BIOS specification for
                  more details. The double clock flag is returned from the
                  ROM to identify if the mode has been double clocked -- this
                  means that the actual xres value is half of what it should
                  be. The PGL will double the value in this case.

// --------------------------------------------------------------------------
int              ROM_setdpmscontrol(int service_code);

    Inputs      : service_code - DPMS_ACTIVE
                                 DPMS_STANDBY
                                 DPMS_SUSPEND
                                 DPMS_OFF

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 0Ch. This function sets the DPMS mode.
                  Refer to the Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_shortquery(PGL_shortquery far *shortqueryinfo);

    Inputs      : shortqueryinfo - pointer to buffer to be filled

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 06h. This function fills a given buffer the
                  "short" query hardware information such as linear aperture
                  configuration, aperture address, color depth support, and
                  asic ID. Refer to the Mach64 BIOS specification for more
                  details.

// --------------------------------------------------------------------------
int              ROM_DDCquery(unsigned int far *rom_support,
                              unsigned int far *monitor_support);

    Inputs      : rom_support     - variable pointer to be filled
                  monitor_support - variable pointer to be filled

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 13h, sub-function 00h. This function fills the
                  given variables with DDC support information. Refer to the
                  Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_DDCreadEDID(unsigned int bufsize,
                                 PGL_DDC_EDID far *packet);

    Inputs      : bufsize - set to 128
                  packet  - pointer to buffer to hold DDC packet information

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 13h, sub-function 01h. This function retrieves
                  the DDC EDID packet from a DDC compliant monitor which
                  contains information about monitor mode support.
                  Refer to the Mach64 BIOS specification for more details.

// --------------------------------------------------------------------------
int              ROM_writeeeprom(unsigned int index, unsigned int data);

    Inputs      : index - byte index of eeprom entry to read
                  data  - word data to write to the eeprom entry

    Outputs     : NOERROR
                  YESERROR
                  NOSUPPORT

    Setup       : PGL_detectmach64()

    Description : ROM function 04h. This function writes to an eeprom entry.
                  Refer to the Mach64 BIOS specification for more details.

