








                                                         C H A P T E R
                                                                     1

                                                          Introduction

            The MegaGraph Graphics Library (MGL) is a full featured
            graphics library for displaying high performance graphics
            on personal computers. It provides fast, low level 2D
            drawing primitives that can be used to implement video
            games, user interface software and even real-time 3D
            animation. It will work in any video mode that has 16 or
            more colors, including the new HiColor and TrueColor
            modes available on PC's.

            The MGL is aimed at the experienced programmer, so no
            tutorial documentation or information on generally using
            libraries to write and successfully compile programs is
            given. For more information you will need to consult the
            documentation that came with your compiler.

            This document does not provide any information on
            graphics programming concepts, or general programming
            information about the MGL. Consult the MGL Programmers
            Guide for this information.

































            Chapter 1 - Introduction                                   1


































































            2                       MegaGraph Graphics Library Reference









                                                         C H A P T E R
                                                                     2

                                           About the Library Reference

            The following chapters provide a detailed reference to
            the routines in the MGL. All of the routines in the MGL
            are grouped in alphabetical order within this chapter.
            There is an individual entry for every function in the
            library. If you wanted to know what the MGL_lineCoord()
            function does, you would look it up in the library
            reference where you would find an entry that:

                 Summarises what MGL_lineCoord does

                 Gives the syntax for calling the MGL_lineCoord
                 routine

                 Tells you which header file(s) contain the prototype
                 for MGL_lineCoord

                 Gives a detailed description of how MGL_lineCoord
                 is implemented and how it relates to other line
                 drawing routines.

                 Makes a reference to other related library routines

            The following sample library entry explains how to find
            out such details about the routines in the MGL.




























            Chapter 6 - Console Library                                3






            How to use reference entries

            Function    Summary of what the function does

            Syntax      function(modifier parameter[, ... ]);

                        This gives you the declaration syntax for the
                        function. The [, ... ] indicates that other
                        parameters and modifiers may follow.

            Prototype   header.h
            in
                        This lists the header file(s) containing the
                        prototype for the function. The prototype of
                        a function may be contained in more than one
                        header file, in which case all the files
                        would be listed, so use whichever one is more
                        appropriate.

            Parameters  Briefly describes each of the function
                        parameters.

            Remarks     This section describes what the function
                        does, the parameters it takes and any details
                        that you might need to know in order to get
                        full use out of the function.

            Return      This section describes the value returned by
            value       the function (if any).

            See also    This sections gives a list of other related
                        functions in the library that may be of
                        interest.



























            4                       MegaGraph Graphics Library Reference






            MGL_availableFont

            Function    Determines if a specific font file is
                        available for use.

            Syntax      bool MGL_availableFont(const char *fontname);

            Prototype   mgraph.h
            in

            Parameters  fontname - Relative filename of the required
                        font file

            Remarks     MGL_availableFont() is used to determine if a
                        particular font file exists and is available
                        for use. It will check first in the directory
                        where the MGL driver files were located, and
                        then in the current directory. If the font
                        file is found it will return true, otherwise
                        it will return false.

            Return      True if font file is available, false if not.
            value

            See also    MGL_loadFont()


            MGL_availableModes

            Function    Returns a list of all available video modes.

            Syntax      int * MGL_availableModes(int driver);

            Prototype   mgraph.h
            in

            Parameters  driver - Detected video device driver ID.

            Remarks     MGL_availableModes() will return a list of
                        all the currently available video modes given
                        a specific video device driver ID. The value
                        for the video device driver ID should be
                        obtained via the MGL_detectGraph or MGL_init
                        routines prior to calling this function.

                        You may call this routine before MGL_init()
                        is called to determine what video modes are
                        available before actually initialising a
                        particular video mode. You must ensure
                        however that the MGL_detectGraph() routine is
                        called before you call the
                        MGL_availableModes() routine.

                        The list of available video modes is returned
                        as a table of integer values. The table is
                        terminate with a -1.




            Chapter 6 - Console Library                                5






            Return      Pointer to list of available video modes
            value

            See also    MGL_detectGraph(), MGL_init(),
                        MGL_availablePages()


            MGL_availablePages

            Function    Determine the number of available video pages
                        for a specific video mode.

            Syntax      int MGL_availablePages(int driver,int mode);

            Prototype   mgraph.h
            in

            Parameters  driver - Detected video device driver ID.
                        mode - MGL mode number to query.

            Remarks     MGL_availablePages() will return the number
                        of pages of pysical video memory available
                        for a specific MGL video mode and video
                        device driver. The value for the video device
                        driver ID should be obtained via the
                        MGL_detectGraph() or MGL_init() routines
                        prior to calling this function.

                        You may call this routine before the MGL_init
                        routine is used to intialise a particular
                        video modes. Thus you can filter out support
                        for modes that do not have the require number
                        of hardware video pages available for use.

            Return      Number of available video pages for mode, -1
            value       on error.

            See also    MGL_detectGraph(), MGL_init(),
                        MGL_availableMode()


            MGL_beginDrawing

            Function    Setup for high performance drawing operation.

            Syntax      void MGL_beginDrawing(void);

            Prototype   mgraph.h
            in











            6                       MegaGraph Graphics Library Reference






            Remarks     MGL_beginDrawing() must be called before
                        calling any of the special high performance
                        drawing routines, such as the MGL_lineFast()
                        and associated routines. MGL_beginDrawing
                        will put the video hardware into a state that
                        can be used to render the primitives much
                        faster than otherwise possible.

                        All high performance drawing primitives end
                        the word 'Fast', and must be bracketed
                        between calls to MGL_beginDrawing() and
                        MGL_endDrawing(). You may mix and match any
                        of the fast drawing routines and normal
                        library functions within an
                        MGL_beginDrawing() and MG_endDrawing() block.
                        You can also nest calls to MGL_beginDrawing()
                        and MGL_endDrawing() (hence you can write
                        your own functions that use the fast
                        rendering routines but do not require the
                        user to call MGL_beginDrawing() before
                        calling your routine).

                            must
                        You      ensure that you call the
                        MGL_endDrawing() routine after drawing a set
                        of high performance primitives.

            See also    MGL_endDrawing(), MGL_*fast()


            MGL_beginGouraud

            Function    Setup for Gouraud Shaded drawing operation.

            Syntax      void MGL_beginGouraud(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_beginGouraud() must be called before any
                        of the gouraud shading routines are called,
                        such as the MGL_fillGouraudPolygon() routine.
                        This will put the video hardware into a
                        special mode for doing high peformance
                        gouraud shaded rendering.

                        You should not call any other routines except
                        the gouraud shading routines between calls to
                        MGL_beginGouraud() and MGL_endGouraud(), and
                        you should not nest calls to this routine.

            See also    MGL_endGouraud()









            Chapter 6 - Console Library                                7






            MGL_beginPixel

            Function    Setup for high speed pixel drawing.

            Syntax      void MGL_beginPixel(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_beginPixel() sets up the video hardware
                        for plotting single pixels as fast a
                        possible. You must call this routine before
                        calling any of the MGL_*Pixel() routines to
                        ensure correct operation, and you must call
                        the MGL_endPixel() routine after you have
                        finished.

                        This routine is intended primarily to ensure
                        fast operation if you intend to plot more
                        than a single pixel at a time, so it will be
                        done as fast as possible.

            See also    MGL_endPixel()


            MGL_charWidth

            Function    Returns the width of a character in pixels.

            Syntax      int MGL_charWidth(char ch);

            Prototype   mgraph.h
            in

            Parameters  ch - Character to measure.

            Remarks     MGL_charWidth() will return the width of the
                        specified character, given the currently
                        active font and attribute settings.

            Return      Width of the character in pixels (will depend
            value       on currently active font)

            See also    MGL_textWidth(), MGL_useFont()


            MGL_clearDevice

            Function    Clears the currently active display page on
                        the active device..

            Syntax      void MGL_clearDevice(void);

            Prototype   mgraph.h
            in





            8                       MegaGraph Graphics Library Reference






            Remarks     MGL_clearDevice() will clear the entire
                        currently active display page in the current
                        background color. This is the fastest way to
                        clear an entire display page, but if you wish
                        to only clear a portion of the page, use the
                        MGL_clearViewport() routine instead.

            See also    MGL_clearViewport()


            MGL_clearViewport

            Function    Clears the currently active viewport.

            Syntax      void MGL_clearViewport(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_clearViewport() will clear the currently
                        active display page viewport in the current
                        background color. This is the fastest way to
                        clear a rectangular viewport, but you may
                        also wish to use the MGL_fillRect() routine
                        to fill in an arbitrary pattern instead, as
                        the MGL_clearViewport() always clears the
                        viewport in a solid color.

            See also    MGL_clearDevice()


            MGL_clipLine

            Function    Clips a line to a specified clipping
                        rectangle.

            Syntax      bool MGL_clipLine(point *p1,point *p2,rect
                        r);

            Prototype   mgraph.h
            in

            Parameters  p1,p2 - Endpoints of line to clip.
                        r - Rectangle to clip the line to

            Remarks     MGL_clipLine() will clip the line from point
                        p1(x,y) to point p2(x.y) to the specified
                        clipping rectangle. If the line is accepted
                        (ie: it intersects with the clipping
                        rectangle) then the routine will return true
                        and the line enpoints will be updated to
                        reflect the clipped lines new endpoints. If
                        the line is completely outside of the
                        clipping rectangle, the routine will return
                        false.

            Return      True if line is visible, false if completely
            value       outside rectangle.


            Chapter 6 - Console Library                                9








            MGL_copyImage

            Function    Copies of block of video memory.

            Syntax      void MGL_copyImage(rect r,int dl,int dt,int
                        sp,int dp)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle specifying the region to copy
                        dl - Left coordinate of destination location
                        dt - Top coordinate of destination location
                        sp - Source image page
                        dp - Destination image page

            Remarks     MGL_copyImage() copies the data of a
                        rectangular region of the specified display
                        page to another location, either on the same
                        page or on a different page. If the source
                        and destination regions overlap, the image
                        will be correctly copied.

                        NOTE: No clipping is done in this routine, so
                        you can copy data outside of the
                        current viewport.

            See also    MGL_copyImageCoord()


            MGL_copyImageCoord

            Function    Copies of block of video memory.

            Syntax      void MGL_copyImageCoord(int left,int top,int
                        right,int bottom,int dl,int dt,int sp,int dp)

            Prototype   mgraph.h
            in

            Parameters  left - Left coordinate of source region
                        top - Top coordinate of source region
                        right - Right coordinate of source region
                        bottom - Bottom coordinate of source region
                        dl - Left coordinate of destination location
                        dt - Top coordinate of destination location
                        sp - Source image page
                        dp - Destination image page










            10                      MegaGraph Graphics Library Reference






            Remarks     MGL_copyImageCoord() copies the data of a
                        rectangular region of the specified display
                        page to another location, either on the same
                        page or on a different page. If the source
                        and destination regions overlap, the image
                        will be correctly copied.

                        NOTE: No clipping is done in this routine, so
                        you can copy data outside of the
                        current viewport.

            See also    MGL_copyImage()


            MGL_defaultAttributes

            Function    Reset global attributes to their default
                        values.

            Syntax      void MGL_defaultAttributes(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_defaultAttributes() resets all of the
                        global attributes to their default values.
                        MGL_defaultAttributes() does not reset the
                        current palette.

            See also    MGL_getAttributes(), MGL_setAttributes(),
                        MGL_getDefaultPalette()


            MGL_defaultColor

            Function    Returns the default color value for the video
                        mode.

            Syntax      color_t MGL_defaultColor(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_defaultColor() returns a default color
                        values for the current video mode. This color
                        value is white if the palette has not been
                        changed, and will always be white in direct
                        color modes.

            Return      Default color value for current video mode.
            value

            See also    MGL_setColor(), MGL_getColor()







            Chapter 6 - Console Library                               11






            MGL_detectGraph

            Function    Detects the currently installed video
                        hardware.

            Syntax      void MGL_detectGraph(int far *graphdriver,int
                        far *graphmode);

            Prototype   mgraph.h
            in

            Parameters  graphdriver - Pointer to graphics device
                        driver id
                        graphmode - Pointer to default video mode for
                        device

            Remarks     MGL_detectGraph() autodetects the presence of
                        all the standard graphics adapters supported
                        by the MGL. If no suitable hardware is
                        detected, it returns grNONE in the
                        graphdriver parameter. If suitable hardware
                        is detected, it will return an appropriate
                        device driver id number in the graph driver
                        parameter and a suggested default video mode
                        in the graphmode parameter.

                        The video device drivers currently supported
                        by the MGL are:

                        grDETECT  - Auto detect the graphics
                        subsystem
                        grNONE    - No graphics hardware detected
                        grEGA     - Standard EGA with 256k RAM
                        grVGA     - Standard VGA
                        grSVGA    - VESA VBE compliant Super VGA
                        grSVGA_S3 - S3 accelerated SuperVGA

                        The MGL supports a number of different video
                        mode resolutions, ranging from 320x200 up to
                        1280x1024 with color ranges from 16 colors up
                        to 16.7 million colors. Thus the video mode
                        id for 320x200 16 color EGA graphics mode is
                        grEGA_320x200x16, and the 1280x1024 16.7
                        million color mode is grSVGA_1280x1024x16m.
                        Please consult the MGRAPH.H header file for a
                        full list of defined video modes (to large to
                        list here).

                        Once you have called MGL_detectGraph(), you
                        can then call the MGL_availableModes and
                        MGL_availablePages to determine all the
                        available video modes for the currently
                        installed driver and the number of available
                        video pages for each video mode.

            See also    MGL_init()




            12                      MegaGraph Graphics Library Reference






            MGL_disjointRect

            Function    Determines if two rectangles are disjoint.

            Syntax      bool MGL_disjointRect(recy r1,rect r2)

            Prototype   mgraph.h
            in

            Parameters  r1 - First rectangle to test
                        r2 - Second rectangle to test

            Remarks     MGL_disjointRect() will determine if two
                        rectangles are non-overlapping (ie: the
                        intersection between the rectangles is zero).
                        If they are disjoint, it will return true,
                        otherwise it will return false.

            Return      True if the rectangles are disjoint, false if
            value       not.

            See also    MGL_emptyRect(), MGL_equalRect(),
                        MGL_offsetRect(), MGL_insetRect(),
                        MGL_ptInRect().


            MGL_divotSize

            Function    Number of bytes required to store the divot.

            Syntax      long MGL_divotSize(rect r)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the divot area.

            Remarks     MGL_divotSize() determines the number of
                        bytes required to store a particular video
                        memory divot.

            Return      Size of the specified divot in bytes.
            value

            See also    MGL_getDivot(), MGL_getDivotCoord(),
                        MGL_putDivot()














            Chapter 6 - Console Library                               13






            MGL_divotSizeCoord

            Function    Number of bytes required to store the divot.

            Syntax      long MGL_divotSizeCoord(int left,int top,int
                        right,int bottom)

            Prototype   mgraph.h
            in

            Parameters  left - Left coordinate of divot area
                        top - Top coordinate of divot area
                        right - Right coordinate of divot area
                        bottom - Bottom coordinate of divot area

            Remarks     MGL_divotSizeCoord() determines the number of
                        bytes required to store a particular video
                        memory divot.

            Return      Size of the specified divot in bytes.
            value

            See also    MGL_getDivot(), MGL_getDivotCoord(),
                        MGL_putDivot()


            MGL_doubleBuffer

            Function    Sets up for double buffering if possible.

            Syntax      bool MGL_doubleBuffer(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_doubleBuffer() will attempt to enable
                        double buffering for the current video mode.
                        If double buffering is enabled, then the
                        routine will return true, otherwise it will
                        return false and single buffer mode will
                        still be enabled.

                        MGL_doubleBuffer() will attempt to perform
                        double buffering using an offscreen memory
                        buffer if only one video memory page is
                        supported by the hardware, so it is a
                        transparent method of enabling simple double
                        buffered animation.

                        NOTE: The current version of the MGL does not
                        yet support off screen memory buffers (mostly
                        because of memory requirements in real mode -
                        the protected mode version of the library
                        will, and limited support will be provided in
                        real mode for the next version).

            Return      True if double buffering is now enabled.
            value


            14                      MegaGraph Graphics Library Reference







            See also    MGL_singleBuffer(), MGL_swapBuffers()


            MGL_drawBorder

            Function    Draws a 3D border around the specified
                        rectangle.

            Syntax      void MGL_drawBorder(rect r,int style,int
                        thickness)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the region to draw the
                        border around
                        style - Type of border to draw
                        thickness - Thickness of the border in pixels

            Remarks     MGL_drawBorder() draws a 3D style border
                        around the specified rectangle in the
                        specified border style and thickness. The
                        different border styles are defined in the
                        MGRAPH.H header file as:

                        BDR_INSET    - Interior is inset into display
                        BDR_OUTSET   - Interior is outset from
                        display
                        BDR_OUTLINE  - Border is a 3D outline

                        Thus if you wish to create the effect of a 3D
                        style push button, you would use the
                        BDR_OUTSET style to make it appear to be
                        protruding from the display screen. To make
                        it look like it is depressed, use the
                        BDR_INSET style to make it appear to be inset
                        into the display. The BDR_OUTLINE style is
                        used to create a 3D looking rectangle just
                        inside the rectangle boundaries for grouping
                        things together in a user interface dialog
                        box.

                        The border is completely contained within the
                        specified bounding rectangle.

                        The color of the border's highlights are
                        determined by the currently active border
                        color values.

            See also    MGL_drawBorderCoord(), MGL_drawHDivider(),
                        MGL_drawVDivider(), MGL_setBorderColors()








            Chapter 6 - Console Library                               15






            MGL_drawBorderCoord

            Function    Draws a 3D border around the specified
                        rectangle.

            Syntax      MGL_drawBorderCoord(int left,int top,int
                        right,int bottom,int style,int thickness);

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the region to draw the
                        border around
                        style - Type of border to draw
                        thickness - Thickness of the border in pixels

            Remarks     MGL_drawBorderCoord() draws a 3D style border
                        around the specified rectangle in the
                        specified border style and thickness. The
                        different border styles are defined in the
                        MGRAPH.H header file as:

                        BDR_INSET    - Interior is inset into display
                        BDR_OUTSET   - Interior is outset from
                        display
                        BDR_OUTLINE  - Border is a 3D outline

                        Thus if you wish to create the effect of a 3D
                        style push button, you would use the
                        BDR_OUTSET style to make it appear to be
                        protruding from the display screen. To make
                        it look like it is depressed, use the
                        BDR_INSET style to make it appear to be inset
                        into the display. The BDR_OUTLINE style is
                        used to create a 3D looking rectangle just
                        inside the rectangle boundaries for grouping
                        things together in a user interface dialog
                        box.

                        The border is completely contained within the
                        specified bounding rectangle.

                        The color of the border's highlights are
                        determined by the currently active border
                        color values.

            See also    MGL_drawBorder(), MGL_drawHDivider(),
                        MGL_drawVDivider(), MGL_setBorderColors()












            16                      MegaGraph Graphics Library Reference






            MGL_drawHDivider

            Function    Draws a 3D looking horizontal dividing line

            Syntax      void MGL_drawHDivider(int y,int x1,int x2);

            Prototype   mgraph.h
            in

            Parameters  y - Y coordinate to draw the line at
                        x1 - Starting X coordinate
                        x2 - Ending X coordinate

            Remarks     MGL_drawHDivider() draws a 3D horizontal
                        dividing line beginning at the position
                        (x1,y) and ending at the position (x2,y).

                        The color of the dividing line is determine
                        by the currently active border colors values.

            See also    MGL_drawVDivider(), MGL_drawBorder(),
                        MGL_setBorderColors()


            MGL_drawStr

            Function    Draws a text string on the display.

            Syntax      void MGL_drawStr(const char *str);

            Prototype   mgraph.h
            in

            Parameters  str - String to display

            Remarks     MGL_drawStr() draws the specified string at
                        the current position (CP) in the current
                        drawing color, write mode, font, text
                        direction and justification. The CP is moved
                        so that drawing will begin directly after the
                        end of the string, only if the horizontal
                        justification is set to LEFT_TEXT, otherwise
                        the CP is not moved.

            See also    MGL_drawStrXY(), MGL_textHeight(),
                        MGL_textWidth(), MGL_useFont()














            Chapter 6 - Console Library                               17






            MGL_drawStrXY

            Function    Draws a text string on the display.

            Syntax      void MGL_drawStrXY(int x,int y,const char
                        *str);

            Prototype   mgraph.h
            in

            Parameters  x - X coordinate to begin rendering the
                        string at
                        y - Y coordinate to begin rendering the
                        string at
                        str - String to display

            Remarks     MGL_drawStrXY   draws the specified string at
                                     ()
                        the specified (x,y) position in the current
                        drawing color, write mode, font, text
                        direction and justification.

            See also    MGL_drawStrXY(), MGL_textHeight(),
                        MGL_textWidth(), MGL_useFont()


            MGL_drawVDivider

            Function    Draws a 3D looking vertical dividing line

            Syntax      void MGL_drawVDivider(int x,int y1,int y2);

            Prototype   mgraph.h
            in

            Parameters  x - X coordinate to begin drawing divider
                        y1 - Starting Y coordinate
                        y2 - Ending Y coordinate

            Remarks     MGL_drawVDivider() draws a 3D vertical
                        dividing line beginning at the position
                        (x,y1) and ending at the position (x,y2).

                        The color of the dividing line is determine
                        by the currently active border colors values.

            See also    MGL_drawHDivider(), MGL_drawBorder(),
                        MGL_setBorderColors()













            18                      MegaGraph Graphics Library Reference






            MGL_driverName

            Function    Returns a string describing the name of the
                        device driver.

            Syntax      char *MGL_driverName(int driver);

            Prototype   mgraph.h
            in

            Parameters  driver - Device driver id number.

            Remarks     MGL_driverName() returns a string describing
                        the a device driver given a device driver
                        number.

            Return      Pointer to device driver name string.
            value

            See also    MGL_modeName()


            MGL_ellipse

            Function    Draws an ellipse outline defined by a
                        bounding rectangle.

            Syntax      bool MGL_ellipse(rect extentRect);

            Prototype   mgraph.h
            in

            Parameters  extentRect - Bounding rectangle defining the
                        ellipse.

            Remarks     MGL_ellipse() draws the outline of an ellipse
                        just inside the mathematical boundary of
                        extentRect. The ellipse outline is drawn in
                        the current pen color, style and size.

                        Note: This routine is more versatile than the
                        equivalent MGL_ellipseCoord() routine, as you
                        can have an ellipse with odd diameters
                        values, which you cannot get with the
                        MGL_ellipseCoord() routine.

            Return      True if ellipse was scan converted, false if
            value       an error occured (MGL_buf too small)..

            See also    MGL_ellipseCoord(), MGL_fillEllipse(),
                        MGL_fillEllipseCoord()









            Chapter 6 - Console Library                               19






            MGL_ellipseArc

            Function    Draws an elliptical arc outline defined by a
                        bounding rectangle.

            Syntax      bool MGL_ellipseArc(rect extentRect,int
                        startAngle,int endAngle);

            Prototype   mgraph.h
            in

            Parameters  extentRect - Bounding rectangle defining the
                        arc.
                        startAngle - Starting angle for arc (in
                        degrees)
                        endAngle - Ending angle for arc (in degrees).

            Remarks     MGL_ellipseArc() draw the outline of an
                        elliptical arc just inside the mathematical
                        boundary of extentRect. StartAngle specifies
                        where the arc begins and is treated MOD 360.
                        EndAngle specifies where the arc ends and is
                        treated MOD 360 also. The angles are given in
                        positive or negative degrees. Zero degrees is
                        at 3 o'clock, 90 is at 12 o'clock high, 180
                        is at 9 o'clock and 270 is at 6 o'clock.
                        Other angles are measured relative to the
                        enclosing rectangle. Thus an angle of 45
                        degrees always defines a line from the centre
                        of the rectangle through it's top right
                        corner, even if the rectangle isn't square.

                        The ellipse outline if drawn in the current
                        pen color, style and size (note that the
                        current version of the MGL only works with a
                        1x1 pen size with a solid pattern for
                        elliptical arcs).

                        Note: This routine is more versatile than the
                        equivalent MGL_ellipseArcCoord() routine, as
                        you can have an elliptical arc with odd
                        diameters values, which you cannot get with
                        the MGL_ellipseArcCoord() routine.

            Return      True if the ellipse arc was scan converted,
            value       false if an error occurred (MGL_buf too
                        small).

            See also    MGL_ellipseArcCoord(), MGL_fillEllipseArc(),
                        MGL_fillEllipseArcCoord()










            20                      MegaGraph Graphics Library Reference






            MGL_ellipseArcCoord

            Function    Draws an elliptical arc outline defined by a
                        centre and radii.

            Syntax      bool MGL_ellipseArcCoord(int x,int y,int
                        xradius,int yradius,int startAngle,int
                        endAngle);

            Prototype   mgraph.h
            in

            Parameters  x,y - Centre of the elliptical arc.
                        xradius - X radius for the elliptical arc
                        yradius - Y radius for the elliptical arc
                        startAngle - Starting angle for arc (in
                        degrees)
                        endAngle - Ending angle for arc (in degrees).

            Remarks     MGL_ellipseArcCoord() draws the outline of an
                        elliptical arc given the centre, radii and
                        starting and endling angles. StartAngle
                        specifies where the arc begins and is treated
                        MOD 360. EndAngle specifies where the arc
                        ends and is treated MOD 360 also. The angles
                        are given in positive or negative degrees.
                        Zero degrees is at 3 o'clock, 90 is at 12
                        o'clock high, 180 is at 9 o'clock and 270 is
                        at 6 o'clock. Other angles are measured
                        relative to the enclosing rectangle. Thus an
                        angle of 45 degrees always defines a line
                        from the centre of the rectangle through it's
                        top right corner, even if the rectangle isn't
                        square.

                        The ellipse outline if drawn in the current
                        pen color, style and size (note that the
                        current version of the MGL only works with a
                        1x1 pen size with a solid pattern).

                        Note: This routine can only work with integer
                        semi-major and semi-minor axes, but can
                        sometimes be easier to work with (and it
                        provided for compatabilty with other graphics
                        packages).

            Return      True if the ellipse arc was scan converted,
            value       false if an error occurred (MGL_buf too
                        small).

            See also    MGL_ellipseArc(), MGL_fillEllipseArc(),
                        MGL_fillEllipseArcCoord()








            Chapter 6 - Console Library                               21






            MGL_ellipseCoord

            Function    Draws an ellipse outline defined by a
                        bounding rectangle.

            Syntax      bool MGL_ellipseCoord(int x,int y,int
                        xradius,int yradius);

            Prototype   mgraph.h
            in

            Parameters  x,y - Centre of the ellipse
                        xradius - X radius for the ellipse
                        yradius - Y radius for the ellipse

            Remarks     MGL_ellipse() draws the outline of an ellipse
                        given the centre and radii for the ellipse.
                        The ellipse outline if drawn in the current
                        pen color, style and size.

                        Note: This routine can only work with integer
                        semi-major and semi-minor axes, but can
                        sometimes be easier to work with (and it
                        provided for compatability with other
                        graphics packages).

            Return      True if ellipse was scan converted, false if
            value       an error occured (MGL_buf too small)..

            See also    MGL_ellipse(), MGL_fillEllipse(),
                        MGL_fillEllipseCoord()


            MGL_ellipseEngine

            Function    Generates the set of points on an ellipse.

            Syntax      void MGL_ellipseEngine(rect extentRect,void
                        (*setup)(int topY,int botY,int left,int
                        right),void (*set4pixels)(bool inc_x,bool
                        inc_y,bool region1),void (*finished)(void));

            Prototype   mgraph.h
            in

            Parameters  extentRect - Bounding rectangle defining the
                        ellipse.
                        setup - Routine called to intialise pixel
                        plotting routines.
                        set4pixels - Routine called repeatedly for
                        each set of 4 pixels.
                        finished - Routine called to complete
                        plotting pixels.







            22                      MegaGraph Graphics Library Reference






            Remarks     MGL_ellipseEngine() is the same engine used
                        to generate all ellipse's and elliptical arc
                        in the MGL. You can call it to generate the
                        set of points on an ellipse, calling your own
                        user defined plotting routines.

                        The setup routine is called before any pixel
                        are plotted with the coordinates of the 4
                        seed points in the four ellipse quadrants.

                            set4pixels
                        The            routine is called repeatedly
                        for each set of 4 pixels to be plotted, and
                        specified whether the coordinates in the x
                        and y directions should be incremented or
                        remain the same. This state of the 4 pixel
                        coordinates will need to be maintained by the
                        user supplied routines.

                            finished
                        The          routine is called to clean up
                        after generating all the points on the
                        ellipse, such as releasing memory and
                        rendering the ellipse if the rendering was
                        deferred.


            MGL_emptyRect

            Function    Determines if a rectangle is empty.

            Syntax      bool MGL_emptyRect(rect r)

            Prototype   mgraph.h
            in

            Parameters  r - rectangle to test

            Remarks     MGL_emptyRect() determine if a rectangle is
                        empty. A rectangle is defined as being empty
                        if the right coordinate is less than or equal
                        to the left coordinate, or if the bottom
                        coordinate is less than or equal to the top
                        coordinate.

            Return      True if rectangle is empty, false if not.
            value

            See also    MGL_disjointRect(), MGL_equalRect(),
                        MGL_offsetRect(), MGL_insetRect(),
                        MGL_ptInRect().











            Chapter 6 - Console Library                               23






            MGL_endDrawing

            Function    Finish high performance drawing operation.

            Syntax      void MGL_endDrawing(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_endDrawing() is called to end a set of
                        high performance drawing operations that we
                        started with the MGL_beginDrawing()
                        operation.

                        All high performance drawing primitives end
                        the word 'Fast', and must be bracketed
                        between calls to MGL_beginDrawing() and
                        MGL_endDrawing(). You may mix and match any
                        of the fast drawing routines and normal
                        library functions within an
                        MGL_beginDrawing() and MG_endDrawing() block.
                        You can also nest calls to MGL_beginDrawing()
                        and MGL_endDrawing() (hence you can write
                        your own functions that use the fast
                        rendering routines but do not require the
                        user to call MGL_beginDrawing() before
                        calling your routine).

                            must
                        You      ensure that you call the
                        MGL_endDrawing routine after drawing a set of
                        high performance primitives.

            See also    MGL_beginDrawing(), MGL_*fast()


            MGL_endGouraud

            Function    Complete Gouraud Shaded drawing operation.

            Syntax      void MGL_endGouraud(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_endGouraud() is called to end the
                        rendering of gouraud shaded primitives, such
                        as the MGL_fillGouraudPolygon() routine.

                        You should not call any other routines except
                        the gouraud shading routines between calls to
                        MGL_beginGouraud and MGL_endGouraud, and you
                        should not nest calls to this routine.

            See also    MGL_beginGouraud()






            24                      MegaGraph Graphics Library Reference






            MGL_endPixel

            Function    End high speed pixel drawing operation.

            Syntax      void MGL_endPixel(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_endPixel() ends a set of high speed pixel
                        drawing operations.

                        This routine is intended primarily to ensure
                        fast operation if you intend to plot more
                        than a single pixel at a time, so it will be
                        done as fast as possible.

            See also    MGL_beginPixel()


            MGL_equalPoint

            Function    Determines if two points are equal.

            Syntax      bool MGL_equalPoint(point p1,point p2);

            Prototype   mgraph.h
            in

            Parameters  p1 - First point to compare
                        p2 - Second point to compare

            Remarks     MGL_equalPoint() determines if the value of
                        two coordinates are equal, returning true if
                        they are.

            Return      True if the points are equal, false if not.
            value


            MGL_equalRect

            Function    Determines if two rectangles are equal.

            Syntax      bool MGL_equalRect(rect r1,rect r2);

            Prototype   mgraph.h
            in

            Parameters  r1 - First rectangle to compare
                        r2 - Second rectangle to compare

            Remarks     MGL_equalRect() compares the values of two
                        rectangles and determines if they are equal,
                        returning true if they are.

            Return      True if the rectangles are equal.
            value


            Chapter 6 - Console Library                               25







            See also    MGL_disjointRect(), MGL_emptyRect(),
                        MGL_offsetRect(), MGL_insetRect(),
                        MGL_ptInRect().


            MGL_errorMsg

            Function    Returns a string describing an error
                        condition.

            Syntax      char *MGL_errorMsg(int err);

            Prototype   mgraph.h
            in

            Parameters  err - Error code to obtain string for.

            Remarks     MGL_errorMsg() returns a pointer to a string
                        describing a specified error condition. You
                        can use this to convert the error codes from
                        a numerical id return by MGL_result() to a
                        string which you can display for the users of
                        your programs.

            Return      Pointer to string describing the error
            value       condition.

            See also    MGL_result().


            MGL_exit

            Function    Closes down the graphics subsystem.

            Syntax      void MGL_exit(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_exit() closes down the graphics
                        subsystem, deallocating any memory allocated
                        for use by the MGL, and restoring the system
                        back into the original text mode active
                        before the MGL was started.

            See also    MGL_init()













            26                      MegaGraph Graphics Library Reference






            MGL_fadePalette

            Function    Fades the values for programming the palette.

            Syntax      bool MGL_fadePalette(palette *dest,palette
                        *src,int numColors,uchar intensity);

            Prototype   mgraph.h
            in

            Parameters  dest - Pointer to destination palette
                        structure.
                        src - Pointer to source palette structure.
                        numColors - Number of colors in palette to
                        fade
                        intensity - Intensity value for the output
                        palette values.

            Remarks     MGL_fadePalette() will take the values from
                        one palette structure, fade the values and
                        store them into a second palette structure.
                        The actual hardware palette will not be
                        programmed, so you will then need to make a
                        call to MGL_setPalette() to make the changes
                        visiable.

                            intensity
                        The           value is a number between 0 and
                        255 that defines the intensity of the output
                        values. An intensity of 255 will produce the
                        same output values as the input values. An
                        intensity of 128 will product values in the
                        output palette that are half the intensity of
                        the input palette.

                        The palette values are manipulated as arrays
                        of the         structure, defined as:
                               palette

                        typedef struct {
                            uchar   red;
                            uchar   green;
                            uchar   blue;
                            } palette;

                        where red, green and blue define the color
                        components for that entry. Each color
                        component is defined as an 8 bit value with a
                        range of 0-255.

                        If the entire output palette is zero, then
                        the routine will return true, otherwise it
                        will return true.

            Return      True if the entire output palette is zero,
            value       false if not.

            See also    MGL_setPalette(), MGL_getPalette(),
                        MGL_rotatePalette()



            Chapter 6 - Console Library                               27






            MGL_fillEllipse

            Function    Fills an ellipse outline defined by a
                        bounding rectangle.

            Syntax      bool MGL_fillEllipse(rect extentRect);

            Prototype   mgraph.h
            in

            Parameters  extentRect - Bounding rectangle defining the
                        ellipse.

            Remarks     MGL_fillEllipse() fills an ellipse just
                        inside the mathematical boundary of
                        extentRect. The ellipse is filled in the
                        current pen color and style.

                        Note: This routine is more versatile than the
                        equivalent MGL_fillEllipseCoord() routine, as
                        you can have an ellipse with odd diameters
                        values, which you cannot get with the
                        MGL_fillEllipseCoord() routine.

            Return      True if ellipse was scan converted, false if
            value       an error occured (MGL_buf too small)..

            See also    MGL_ellipse(), MGL_ellipseCoord(),
                        MGL_fillEllipseCoord()


            MGL_fillEllipseArc

            Function    Fills an elliptical arc defined by a bounding
                        rectangle.

            Syntax      bool MGL_fillEllipseArc(rect extentRect,int
                        startAngle,int endAngle);

            Prototype   mgraph.h
            in

            Parameters  extentRect - Bounding rectangle defining the
                        arc.
                        startAngle - Starting angle for arc (in
                        degrees)
                        endAngle - Ending angle for arc (in degrees).













            28                      MegaGraph Graphics Library Reference






            Remarks     MGL_fillEllipseArc() fills an elliptical arc
                        forming a wedge, just inside the mathematical
                        boundary of extentRect. StartAngle specifies
                        where the arc begins and is treated MOD 360.
                        EndAngle specifies where the arc ends and is
                        treated MOD 360 also. The angles are given in
                        positive or negative degrees. Zero degrees is
                        at 3 o'clock, 90 is at 12 o'clock high, 180
                        is at 9 o'clock and 270 is at 6 o'clock.
                        Other angles are measured relative to the
                        enclosing rectangle. Thus an angle of 45
                        degrees always defines a line from the centre
                        of the rectangle through it's top right
                        corner, even if the rectangle isn't square.

                        The elliptical arc is filled in the current
                        pen color and style.

                        Note: This routine is more versatile than the
                        equivalent MGL_fillEllipseArcCoord() routine,
                        as you can have an elliptical arc with odd
                        diameter values, which you cannot get with
                        the MGL_fillEllipseArcCoord() routine.

            Return      True if the ellipse arc was scan converted,
            value       false if an error occurred (MGL_buf too
                        small).

            See also    MGL_fillEllipseArcCoord(), MGL_ellipseArc(),
                        MGL_ellipseArcCoord()


            MGL_fillEllipseArcCoord

            Function    Fills an elliptical arc defined by a centre
                        and radii.

            Syntax      bool MGL_fillEllipseArcCoord(int x,int y,int
                        xradius,int yradius,int startAngle,int
                        endAngle);

            Prototype   mgraph.h
            in

            Parameters  x,y - Centre of the elliptical arc.
                        xradius - X radius for the elliptical arc
                        yradius - Y radius for the elliptical arc
                        startAngle - Starting angle for arc (in
                        degrees)
                        endAngle - Ending angle for arc (in degrees).










            Chapter 6 - Console Library                               29






            Remarks     MGL_fillEllipseArcCoord() fills an elliptical
                        arc forming a wedge, given the centre, radii
                        and starting and endling angles. StartAngle
                        specifies where the arc begins and is treated
                        MOD 360. EndAngle specifies where the arc
                        ends and is treated MOD 360 also. The angles
                        are given in positive or negative degrees.
                        Zero degrees is at 3 o'clock, 90 is at 12
                        o'clock high, 180 is at 9 o'clock and 270 is
                        at 6 o'clock. Other angles are measured
                        relative to the enclosing rectangle. Thus an
                        angle of 45 degrees always defines a line
                        from the centre of the rectangle through it's
                        top right corner, even if the rectangle isn't
                        square.

                        The elliptical arc is filled in the current
                        pen color and style.

                        Note: This routine can only work with integer
                        semi-major and semi-minor axes, but can
                        sometimes be easier to work with (and it
                        provided for compatabilty with other graphics
                        packages).

            Return      True if the ellipse arc was scan converted,
            value       false if an error occurred (MGL_buf too
                        small).

            See also    MGL_ellipseArc(), MGL_ellipseArcCoord(),
                        MGL_fillEllipseArc().


            MGL_fillEllipseCoord

            Function    Fills an ellipse defined by a bounding
                        rectangle.

            Syntax      bool MGL_fillEllipseCoord(int x,int y,int
                        xradius,int yradius);

            Prototype   mgraph.h
            in

            Parameters  x,y - Centre of the ellipse
                        xradius - X radius for the ellipse
                        yradius - Y radius for the ellipse

            Remarks     MGL_fillEllipseCoord() fills an ellipse given
                        the centre and radii for the ellipse. The
                        ellipse is filled in the current pen color
                        and style.

                        Note: This routine can only work with integer
                        semi-major and semi-minor axes, but can
                        sometimes be easier to work with (and it
                        provided for compatability with other
                        graphics packages).


            30                      MegaGraph Graphics Library Reference







            Return      True if ellipse was scan converted, false if
            value       an error occured (MGL_buf too small)..

            See also    MGL_ellipse(), MGL_ellipseCoord(),
                        MGL_fillEllipse()


            MGL_fillGouraudPolygon

            Function    Fills a convex polygon with smooth shading.

            Syntax      bool MGL_fillGouraudPolygon(int count,point
                        *vArray,color_t *cArray,int xOffset,int
                        yOffset);

            Prototype   mgraph.h
            in

            Parameters  count - Number of vertices in polygon
                        vArray - Array of vertices in polygon
                        cArray - Array of vertex colors
                        xOffset - X coordinate offset value
                        yOffset - Y coordinate offset value

            Remarks     MGL_fillGouraudPolygon() scan converts a
                        filled        polygon, while smoothly
                               convex
                        interpolating the color values between the
                        vertices in the polygon. A convex polygon is
                        defined as a polygon such that every
                        horizontal line drawn through the polygon
                        would cross exactly two active edges (neither
                        horizontal lines nor zero-length edges count
                        as active edges; both are acceptable anywhere
                        in the polygon). Right & left edges may cross
                        (polygons may be nonsimple). Attempting to
                        scan convert a polygon that does not fit this
                        description will produce unpredictable
                        results.

                        In order to ensure correct scan conversion of
                        polygons with shared vertices, the right and
                        bottom edges of the polygons are not scan
                        converted. All vertices are offset by
                        (xOffset,yOffset).

                        Note: You must call MGL_beginGouraud() before
                        calling this routine, and you      call
                                                      must 
                        MGL_endGouraud() after drawing a set of one
                        or more shaded polygons. You cannot draw
                        anything else at the same time.

            Return      True if the polygon was scan converted, false
            value       if an error occurred.

            See also    MGL_fillPolygon(), MGL_fillPolygonFast(),
                        MGL_beginGouraud(), MGL_endGouraud().



            Chapter 6 - Console Library                               31






            MGL_fillPolygon

            Function    Fills an arbitrary polygon.

            Syntax      bool MGL_fillPolygon(int count,point
                        *vArray,int xOffset,int yOffset);

            Prototype   mgraph.h
            in

            Parameters  count - Number of vertices in polygon
                        vArray - Array of vertices in polygon
                        xOffset - X coordinate offset value
                        yOffset - Y coordinate offset value

            Remarks     MGL_fillPolygon() scan converts a filled
                        arbitrary polygon in the current color and
                        style. By default the routine will determine
                        the type of the polygon being scan converted,
                        and will scan convert convex polygons using a
                        faster scan conversion routine, otherwise a
                        general polygon scan conversion routine will
                        be used. Thus you can scan convert any type
                        of polygon that you desire.

                          convex
                        A        polygon is defined as a polygon such
                        that every horizontal line drawn through the
                        polygon would cross exactly two active edges
                        (neither horizontal lines nor zero-length
                        edges count as active edges; both are
                        acceptable anywhere in the polygon). Right &
                        left edges may cross (polygons may be
                        nonsimple). Attempting to scan convert a
                        polygon that does not fit this description
                        will produce unpredictable results.

                        Non simple or self intersecting polygons will
                        be scan converted using the standard in/out
                        rule, where points are defined as being
                        inside after crossing the first edge in the
                        polygon, and then alternate between defined
                        as inside then outside after crossing each
                        active edge in the polygon.

                        In order to ensure correct scan conversion of
                        polygons with shared vertices, the right and
                        bottom edges of the polygons are not scan
                        converted. All vertices are offset by
                        (xOffset,yOffset).

                        You may also use the MGL_setPolygonType()
                        routine to specify the type of polygons being
                        scan converted. This may be AUTO_POLYGON,
                        CONVEX_POLYGON or COMPLEX_POLYGON. Explicitly
                        setting the polygon type will speed the
                        drawing process.




            32                      MegaGraph Graphics Library Reference






            Return      True if the polygon was scan converted, false
            value       if an error occurred.

            See also    MGL_fillPolygonFast(),
                        MGL_fillGouraudPolygon, MGL_setPolygonType()


            MGL_fillPolygonFast

            Function    Fills a convex polygon quickly.

            Syntax      bool MGL_fillPolygonFast(int count,point
                        *vArray,int xOffset,int yOffset);

            Prototype   mgraph.h
            in

            Parameters  count - Number of vertices in polygon
                        vArray - Array of vertices in polygon
                        xOffset - X coordinate offset value
                        yOffset - Y coordinate offset value

            Remarks     MGL_fillPolygonFast() scan converts a filled
                        convex polygon in the current color and
                        style. A        polygon is defined as a
                                 convex
                        polygon such that every horizontal line drawn
                        through the polygon would cross exactly two
                        active edges (neither horizontal lines nor
                        zero-length edges count as active edges; both
                        are acceptable anywhere in the polygon).
                        Right & left edges may cross (polygons may be
                        nonsimple). Attempting to scan convert a
                        polygon that does not fit this description
                        will produce unpredictable results.

                        This is the fastest method to render
                        polygonal shapes such as triangles and
                        quadrilaterals.

                        In order to ensure correct scan conversion of
                        polygons with shared vertices, the right and
                        bottom edges of the polygons are not scan
                        converted. All vertices are offset by
                        (xOffset,yOffset).

                        Note: You      call MGL_beginDrawing() before
                                  must
                        calling this routine, and you must call
                        MGL_endDrawing() after scan converting one or
                        more convex polygons. You may call other MGL
                        routines at the same time however.

            Return      True if the polygon was scan converted, false
            value       if an error occurred.

            See also    MGL_fillPolygon(), MGL_fillGouraudPolygon(),
                        MGL_beginDrawing(), MGL_endDrawing().




            Chapter 6 - Console Library                               33






            MGL_fillRect

            Function    Draws a filled rectangle.

            Syntax      void MGL_fillRect(rect r);

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle to fill

            Remarks     MGL_fillRect() fills a rectangle in the
                        current current drawing attributes. The
                        mathematical definition of a rectangle does
                        not include the right and bottom endpoints,
                        so effectively the right and bottom endpoints
                        are not scan converted (solving problems with
                        shared vertices).

            See also    MGL_fillRectCoord(), MGL_fillRectPt().


            MGL_fillRectCoord

            Function    Draws a filled rectangle.

            Syntax      void MGL_fillRectCoord(int left,int top,int
                        right,int bottom);

            Prototype   mgraph.h
            in

            Parameters  left - Left edge of rectangle
                        top - Top egde of rectangle
                        right - Right edge of rectangle
                        bottom - Bottom edge of rectangle

            Remarks     MGL_fillRectCoord() fills a rectangle defined
                        by the coordinates of its edges in the
                        current current drawing attributes. The
                        mathematical definition of a rectangle does
                        not include the right and bottom endpoints,
                        so effectively the right and bottom endpoints
                        are not scan converted (solving problems with
                        shared vertices).

            See also    MGL_fillRect(), MGL_fillRectPt().













            34                      MegaGraph Graphics Library Reference






            MGL_fillRectPt

            Function    Draws a filled rectangle defined by two
                        points.

            Syntax      void MGL_fillRectPt(point lt,point rb);

            Prototype   mgraph.h
            in

            Parameters  lt - Point defining the left, top corner of
                        the rectangle
                        rb - Point defining the right, bottom corner
                        of rectangle.

            Remarks     MGL_fillRectPt() fills a rectangle defined by
                        two points in the current current drawing
                        attributes. The mathematical definition of a
                        rectangle does not include the right and
                        bottom endpoints, so effectively the right
                        and bottom endpoints are not scan converted
                        (solving problems with shared vertices).

            See also    MGL_fillRect(), MGL_fillRectCoord().


            MGL_getActivePage

            Function    Returns the currently active hardware page.

            Syntax      void MGL_getActivePage(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getActivePage() returns the currently
                        active hardware video page number. The first
                        hardware video page is number 0, the second
                        is 1 and so on. The number of available
                        hardware video pages depends on the type of
                        underlying hardware, the video mode
                        resolution and amount of video memory
                        installed. Thus not all video modes support
                        multiple hardware video pages,

            Return      Currently active hardware page.
            value

            See also    MGL_setActivePage(), MGL_getVisualPage(),
                        MGL_setVisualPage().










            Chapter 6 - Console Library                               35






            MGL_getArcCoords

            Function    Returns the starting and ending arc
                        coordinates.

            Syntax      void MGL_getArcCoords(arc_coords *coords);

            Prototype   mgraph.h
            in

            Parameters  coords - Pointer to structure to store
                        coordinates

            Remarks     MGL_getArcCoords() returns the centre
                        coordinate, and starting and ending points on
                        the ellipse that define the last elliptical
                        arc to be rendered. You can then use these
                        coordinate values to draw a line from the
                        centre of the ellipse to the starting and
                        ending points to complete the outline of the
                        elliptical wedge.

                        The coordinates are returned in the
                        arc_coords structure which is defined as:

                        typedef struct {
                            int     x,y;
                            int     startX,startY;
                            int     endX,endY;
                            } arc_coords;

                        where (x,y) defines the centre of the
                        ellipse, and (startX,startY) defines the
                        starting point on the ellipse and (endX,endY)
                        defines the ending point on the ellipse.

                        Note: This routine must be called immediately
                        after calling the MGL_ellipseArc() routines.


            MGL_getAspectRatio

            Function    Returns the current video mode aspect ratio.

            Syntax      int MGL_getAspectRatio(void);

            Prototype   mgraph.h
            in












            36                      MegaGraph Graphics Library Reference






            Remarks     MGL_getAspectRatio() returns the aspect ratio
                        of the currently active output device's
                        physical pixels. This ratio is equal to:

                                  pixel x size
                                          x 
                                          1000
                                  pixel y size

                        The device aspect ratio can be used to
                        display circles and squares on the display
                        device by approximating them with ellipses
                        and rectangles of the appropriate dimensions.
                        Thus in order to determine the number of
                        pixels in the y direction for a square with
                        100 pixels in the x direction, we can simply
                        use the formula:

                        y_pixels = ((long)x_pixels * 1000) /
                        aspectratio

                        Note the cast to a long to avoid arithmetic
                        overflow, as the apsect ratio is returned as
                        an integer value with 1000 being a 1:1 aspect
                        ratio.

            Return      Current video mode aspect ratio * 1000.
            value

            See also    MGL_setAspectRatio()


            MGL_getAttributes

            Function    Returns a copy of the current attribute list

            Syntax      void MGL_getAttributes(attributes *attr);

            Prototype   mgraph.h
            in

            Parameters  attr - Pointer to structure to store
                        attribute values in



















            Chapter 6 - Console Library                               37






            Remarks     MGL_getAttributes() returns a copy of the
                        currently active attribute lists. You can use
                        this routine to save the state of the MGL and
                        later restore this state with the
                        MGL_restoreAttributes() routine. The
                        attribute values are returned in a structure
                        define as:

                        typedef struct {
                            color_t         color;
                            color_t         backColor;
                            int             markerSize;
                            marker_style    markerStyle;
                            color_t         markerColor;
                            color_t         bdr_bright;
                            color_t         bdr_dark;
                            point           CP;
                            write_mode      writeMode;
                            fill_style      penStyle;
                            int             penHeight;
                            int             penWidth;
                            pattern         penPat;
                            pixpattern      penPixPat;
                            rect            viewport;
                            rect            clipRect;
                            bool            clip;
                            int             poly_type;
                            text_settings   tsettings;
                            } attributes;

                        Note: This routine does not return any values
                        to do with the current viewport stack. This
                        will need to be maintained separately.

            See also    MGL_restoreAttributes()


            MGL_getBackColor

            Function    Returns the current background color value.

            Syntax      color_t MGL_getBackColor(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getBackColor() returns the current
                        background color value. The background color
                        value is used to clear the display and
                        viewport with the MGL_clearDevice() and
                        MGL_clearViewport() routines, and is also
                        used for filling solid primitives in the
                        BITMAP_PATTERN_OPAQUE fill mode.

            Return      Current background color value.
            value




            38                      MegaGraph Graphics Library Reference






            See also    MGL_setBackColor(), MGL_getColor(),
                        MGL_setColor()


            MGL_getBorderColors

            Function    Returns the current border color values.

            Syntax      void MGL_getBorderColors(color_t
                        *bright,color_t *dark);

            Prototype   mgraph.h
            in

            Parameters  bright - Place to store bright color value
                        dark - Place to store dark color value

            Remarks     MGL_getBorderColors() returns the currently
                        active border colors values. There are two
                        border color defined by the MGL, the bright
                        border color value and the      border color
                                                   dark
                        value. These values are used by the
                        MGL_drawBorder(), MGL_drawHDivider() and
                        MGL_drawVDivider() routines to determine the
                        colors to draw the psuedo 3D borders in.
                        These values will be set automatically for
                        you by default when the MGL is initialised,
                        but you will need to change these values if
                        you modify the palette.

            See also    MGL_setBorderColors(), MGL_drawBorder(),
                        MGL_drawHDivider(), MGL_drawVDivider()


            MGL_getCharMetrics

            Function    Computes the metrics for a specific
                        character.

            Syntax      void MGL_getCharMetrics(char ch,metrics
                        *metrics);

            Prototype   mgraph.h
            in

            Parameters  metrics - Place to store the resulting
                        metrics.













            Chapter 6 - Console Library                               39






            Remarks     MGL_getCharMetrics() computes the character
                        metrics for a specific character. The
                        character metrics define specific characters
                        width, height, asecent, descent and other
                        values. These values can then be used to
                        correctly position the character with pixel
                        precise positioning. The metrics are computed
                        and returned in the metrics structure defined
                        as:

                        typedef struct {
                            int             width;
                            int             fontWidth;
                            int             fontHeight;
                            int             ascent;
                            int             descent;
                            int             leading;
                            int             kern;
                            } metrics;

                        where width defines the actual width in
                        pixels for the character, fontWidth defines
                        the width of the character including any
                        extra padding between it and the next
                        character and kern defines the actual kern
                        value for the specific character. All the
                        other values will be the same as those for
                        the entire font file.

                        All values are defined in pixels and will be
                        as accurate as possible given the current
                        fonts scaling factor (currently only vector
                        fonts can be scaled).

            See also    MGL_getFontMetrics()


            MGL_getClipMode

            Function    Returns the current clipping mode.

            Syntax      bool MGL_getClipMode(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getClipMode() returns the current
                        clipping mode. You can selectively turn
                        clipping on and off for the MGL, in order to
                        speed up some operations. Clipping is turned
                        on by default, and generally you will want to
                        leave clipping enabled.

            Return      True if clipping is on, false if not.
            value

            See also    MGL_setClipMode(), MGL_getClipRect(),
                        MGL_setClipRect()


            40                      MegaGraph Graphics Library Reference








            MGL_getClipRect

            Function    Returns the current clipping rectangle.

            Syntax      void MGL_getClipRect(rect *clip);

            Prototype   mgraph.h
            in

            Parameters  clip - Place to store the current clipping
                        rectangle

            Remarks     MGL_getClipRect() returns the current
                        clipping rectangle coordinates. The current
                        clipping rectangle is used to clip all
                        output, and is always defined as being
                        relative to the currently active viewport The
                        clipping rectangle can be no larger than the
                        currently active viewport.

            See also    MGL_setClipRect, MGL_getClipMode(),
                        MGL_getClipMode().


            MGL_getColor

            Function    Returns the current foreground color.

            Syntax      color_t MGL_getColor(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getColor() returns the current foreground
                        color values. The foreground color value is
                        used to draw all primitives.

            Return      Current foreground color.
            value

            See also    MGL_setColor(), MGL_getBackColor(),
                        MGL_setBackColor()


            MGL_getCP

            Function    Returns the current position value.

            Syntax      void MGL_getCP(point* CP);

            Prototype   mgraph.h
            in

            Parameters  CP - place to store the current position




            Chapter 6 - Console Library                               41






            Remarks     MGL_getCP() returns the current position
                        (CP). The CP is the current graphics cursor
                        position, and is used by a number of routines
                        to determine where to being drawing output.
                        You can use the MGL_moveTo() routine to
                        directly move the CP to a new position.

            See also    MGL_moveTo(), MGL_moveRel(), MGL_lineTo(),
                        MGL_lineRel(), MGL_drawStr().


            MGL_getCursorColor

            Function    Returns the current mouse cursor color.

            Syntax      color_t MGL_getCursorColor(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getCursorColor() returns the currently
                        active mouse cursor color. The mouse cursor
                        color is used to determine what foreground
                        color is used to draw the mouse cursor in.

            Return      Current mouse cursor color value.
            value

            See also    MGL_setCursorColor()


            MGL_getDefaultPalette

            Function    Returns the default palette for video mode.

            Syntax      void MGL_getDefaultPalette(palette *pal);

            Prototype   mgraph.h
            in

            Parameters  pal - Place to store the default palette
                        values.


















            42                      MegaGraph Graphics Library Reference






            Remarks     MGL_getDefaultPalette() returns a copy of the
                        default palette for the current video mode.
                        This can be used to reset the palette to the
                        original default values that the palette is
                        programmed with when the MGL is initialised.

                        The palette values are manipulated as arrays
                        of the         structure, defined as:
                               palette

                        typedef struct {
                            uchar   red;
                            uchar   green;
                            uchar   blue;
                            } palette;

                        where red, green and blue define the color
                        components for that entry. Each color
                        component is defined as an 8 bit value with a
                        range of 0-255.

            See also    MGL_setPalette(), MGL_getPalette()


            MGL_getDivot

            Function    Saves a divot of video memory in system RAM

            Syntax      void MGL_getDivot(rect r,void *divot)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the divot to save
                        divot - Pointer to area to store video memory
                        in

            Remarks     MGL_getDivot() copies a block of video memory
                        from the current video page into system RAM.
                          divot
                        A       is defined as being a rectangular
                        area of video memory that you wish to save.
                        However when the divot is saved, it may also
                        save other data slightly outside of the
                        specified area in order to increase the speed
                        at which the divot can be saved and restored.
                        Thus the divot routines save and restore the
                        video memory in the fastest possible manner.
                        This can be used to store the video memory
                        behind pull down menus etc.

                        You must pre-allocate enough space to hold
                        the entire divot in system RAM. Use the
                        MGL_divotSize() routine to determine the size
                        of the memory block required to store the
                        divot.

            See also    MGL_putDivot(), MGL_divotSize()




            Chapter 6 - Console Library                               43






            MGL_getDivotCoord

            Function    Saves a divot of video memory into system RAM

            Syntax      void MGL_getDivotCoord(int left,int top,int
                        right,int bottom,void *divot);

            Prototype   mgraph.h
            in

            Parameters  left - Left edge of area to save
                        top - Top egde of area to save
                        right - Right edge of area to save
                        bottom - Bottom edge of area to save
                        divot - Pointer to area to store the video
                        memory in

            Remarks     MGL_getDivotCoord() copies a block of video
                        memory from the current video page into
                        system RAM. A divot is defined as being a
                        rectangular area of video memory that you
                        wish to save. However when the divot is
                        saved, it may also save other data slightly
                        outside of the specified area in order to
                        increase the speed at which the divot can be
                        saved and restored. Thus the divot routines
                        save and restore the video memory in the
                        fastest possible manner. This can be used to
                        store the video memory behind pull down menus
                        etc.

                        You must pre-allocate enough space to hold
                        the entire divot in system RAM. Use the
                        MGL_divotSize() routine to determine the size
                        of the memory block required to store the
                        divot.

            See also    MGL_getDivot(), MGL_putDivot(),
                        MGL_divotSize()


            MGL_getDriver

            Function    Returns the current video device driver id

            Syntax      int MGL_getDriver(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getDriver() returns the numerical id of
                        the currently active video device driver.
                        This value can be converted in a printable
                        representation with the MGL_driverName()
                        routine.

            Return      Current video device driver id.
            value


            44                      MegaGraph Graphics Library Reference







            See also    MGL_driverName(), MGL_getMode()


            MGL_getFont

            Function    Returns the currently active font.

            Syntax      font *MGL_getFont(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getFont() returns a pointer to the
                        currently active font. The currently active
                        font is used to perform all text output by
                        the MGL.

            Return      Pointer to currently active font.
            value

            See also    MGL_useFont(), MGL_loadFont(),
                        MGL_unloadFont()


            MGL_getFontMetrics

            Function    Returns the currently active font metrics.

            Syntax      void MGL_getFontMetrics(metrics *metrics);

            Prototype   mgraph.h
            in

            Parameters  metrics - Place to store the font metrics.

























            Chapter 6 - Console Library                               45






            Remarks     MGL_getFontMetrics() computes the font
                        metrics for the current font. The metrics are
                        computed and returned in the metrics
                        structure defined as:

                        typedef struct {
                            int             width;
                            int             fontWidth;
                            int             fontHeight;
                            int             ascent;
                            int             descent;
                            int             leading;
                            int             kern;
                            } metrics;

                        where width defines the maximum physical
                        width of all characters in the font,
                        fontWidth defines the maximum width of all
                        the characters in the font including any
                        extra padding between each character. The
                        fontWidth value of each character is used to
                        advance the CP to the start of the next
                        character, and can be larger than the actual
                        character width (in order to put space
                        between the characters). The ascent and
                        descent values define the values from the
                        baseline of the font to the highest and
                        lowest points of all characters. The leading
                        value defines the number of pixels between
                        each line of text, and the kern value defines
                        the maximum kerning value for the font (how
                        far certain characters can extend behind the
                        character start position).

                        All values are defined in pixels and will be
                        as accurate as possible given the current
                        fonts scaling factor (currently only vector
                        fonts can be scaled).

            See also    MGL_getCharMetrics().


            MGL_getImage

            Function    Copies of block of video memory to system
                        RAM.

            Syntax      void MGL_getImage(rect r,void *image)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the image to save
                        image - Place to store the image data.






            46                      MegaGraph Graphics Library Reference






            Remarks     MGL_getImage() copies of block of video
                        memory into a system RAM buffer. The image
                        can then be modified in system RAM, and
                        restored to video RAM in another location.
                        MGL_getImage() is pixel exact so it only
                        copies the pixels that you specify, so it may
                        be slower than the MGL_getDivot() routine.

                        You must pre-allocate enough space to hold
                        the entire image in system RAM. Use the
                        MGL_imageSize() routine to determine the size
                        of the memory block required to store the
                        image.

            See also    MGL_getImageCoord(), MGL_putImage(),
                        MGL_putImageCoord(), MGL_imageSize().


            MGL_getImageCoord

            Function    Copies a block of video memory to system RAM.

            Syntax      void MGL_getImageCoord(int left,int top,int
                        right,int bottom,void *image);

            Prototype   mgraph.h
            in

            Parameters  left - Left edge of area to save
                        top - Top egde of area to save
                        right - Right edge of area to save
                        bottom - Bottom edge of area to save
                        image - Pointer to area to store the video
                        memory in

            Remarks     MGL_getImageCoord copies of block of video
                        memory into a system RAM buffer. The image
                        can then be modified in system RAM, and
                        restored to system RAM in another location.
                        MGL_getImageCoord is pixel exact so it only
                        copies the pixels that you specify, so it may
                        be slower than the MGL_getDivot() routine.

                        You must pre-allocate enough space to hold
                        the entire image in system RAM. Use the
                        MGL_imageSize() routine to determine the size
                        of the memory block required to store the
                        image.

            See also    MGL_getImage(), MGL_putImage(),
                        MGL_putImageCoord(), MGL_imageSize()









            Chapter 6 - Console Library                               47






            MGL_getMarkerColor

            Function    Returns the current marker color value.

            Syntax      color_t MGL_getMarkerColor(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getMarkerColor returns the current marker
                        color value. The marker color is used when
                        drawing markers with the MGL_marker()
                        routine.

            Return      Current marker color value.
            value

            See also    MGL_setMarkerColor(), MGL_marker(),
                        MGL_polyMarker()


            MGL_getMarkerSize

            Function    Returns the current marker size value

            Syntax      int MGL_getMarkerSize(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getMarkerSize() returns the current
                        marker size. The marker size is used to
                        determine how big to draw the markers that
                        are drawn with the MGL_marker() routine. The
                        size is defined as the dimension from the
                        middle of the marker to the edges, so the
                        actual dimensions of the marker will be twice
                        the maker size plus 1. If marker size of 1
                        will define a marker that is contained within
                        a rectangle 3 pixels wide.

            Return      Current marker size
            value

            See also    MGL_setMarkerSize(), MGL_setMarkerStyle(),
                        MGL_getMarkerStyle(), MGL_marker(),
                        MGL_polyMarker()


            MGL_getMarkerStyle

            Function    Returns the current marker style.

            Syntax      int MGL_getMarkerStyle(void);

            Prototype   mgraph.h
            in



            48                      MegaGraph Graphics Library Reference






            Remarks     MGL_getMarkerStyle() returns the current
                        marker style value. The marker style defines
                        the type of marker to be rendered. Currently
                        the MGL defines the following markers:

                        MARKER_SQUARE - A solid square
                        MARKER_CIRCLE - A solid circle
                        MARKER_X      - A cross made of two lines

            Return      Current marker style value.
            value

            See also    MGL_setMarkerSize(), MGL_getMarkerSize(),
                        MGL_setMarkerStyle(), MGL_marker(),
                        MGL_polyMarker()


            MGL_getMode

            Function    Returns the current video mode number.

            Syntax      int MGL_getMode(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getMode() returns the currently active
                        video mode number. This number can be
                        converted to a printable form using the
                        MGL_modeName() routine.

            Return      Current video mode number.
            value

            See also    MGL_init(), MGL_modeName()


            MGL_getPalette

            Function    Obtains the currently active palette values.

            Syntax      void MGL_getPalette(palette *pal,int
                        numColors,int startIndex);

            Prototype   mgraph.h
            in

            Parameters  pal - Place to store the retrieved values
                        numColors - Number of color values to
                        retrieve
                        startIndex - Starting palette index value to
                        retrieve








            Chapter 6 - Console Library                               49






            Remarks     MGL_getPalette() obtains part or all of the
                        currently active palette values and stores it
                        in the array pal. You can specify only a
                        subset of the palette values to be obtained
                        with the startIndex and numColors arguments.

                        Thus to save the entire palette in a 256
                        color video mode, you would use (assuming
                        enough space for the palette has been
                        allocated):

                            MGL_getPalette(pal,255,0);

                        or to get the top half of the palette you
                        would use:

                            MGL_getPalette(pal,128,128);

                        You should ensure that you have allocated
                        enough memory to hold all of the palette
                        values that you wish to read. You can use
                        MGL_getPaletteSize() to determine the size
                        required to save the entire palette.

            See also    MGL_getPaletteEntry(), MGL_setPalette(),
                        MGL_getDefaultPalette()


            MGL_getPaletteEntry

            Function    Returns the value of a single palette entry

            Syntax      void MGL_getPaletteEntry(int entry,uchar
                        *red,uchar *green,uchar *blue);

            Prototype   mgraph.h
            in

            Parameters  entry - Palette index to read
                        red - Place to store the red component
                        green - Place to store the green component
                        blue - Place to store the green component

            Remarks     MGL_getPaletteEntry() obtains the color
                        values of a single palette entry. If you wish
                        to obtain more than a single palette index
                        you should use the MGL_getPalette() routine
                        which is faster for multiple entries.

            See also    MGL_setPaletteEntry(), MGL_getPalette(),
                        MGL_setPalette()









            50                      MegaGraph Graphics Library Reference






            MGL_getPaletteSize

            Function    Returns the number of entries in the entire
                        palette

            Syntax      int MGL_getPaletteSize(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getPaletteSize() returns the number of
                        entries in the entire palette. You should use
                        this routine to determine the size of the
                        entire palette, as the palette is still
                        active even in HiColor and TrueColor video
                        modes (it is implemented in software rather
                        than hardware in these modes).

            Return      Number of entries in entire palette.
            value

            See also    MGL_getPalette()


            MGL_getPaletteSnowLevel

            Function    Returns the current palette snow level

            Syntax      int MGL_getPaletteSnowLevel(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getPaletteSnowLevel() returns the number
                        of palette entries that can be programmed
                        during a single vertical retrace before the
                        onset of snow. The MGL uses a reasonable
                        default of 100 entries per retrace, but you
                        may want to modify this on faster or slower
                        machines (this should be a user option).

            Return      Current palette snow level.
            value

            See also    MGL_setPaletteSnowLevel()


            MGL_getPenBitmapPattern

            Function    Returns the currently active bitmap pattern

            Syntax      void MGL_getPenBitmapPattern(pattern *pat);

            Prototype   mgraph.h
            in

            Parameters  pat - Place to store the bitmap pattern



            Chapter 6 - Console Library                               51






            Remarks     MGL_getPenBitmapPattern() returns a copy of
                        the currently active bitmap pattern used when
                        rendering patterned primitive in the
                        BITMAP_PATTERN_TRANSPARENT and
                        BITMAP_PATTERN_OPQAUE pen styles. A bitmap
                        pattern is defined as an 8 x 8 pixel bitmap
                        pattern stored as an array of 8 bytes.

                        When filling in the
                        BITMAP_PATTERN_TRANSPARENT mode, the
                        foreground color is used to fill in all
                        pixels in the bitmap pattern that are a 1.
                        Where the pixels in the bitmap pattern are a
                        0, the original background color is retained.
                        In the BITMAP_PATTERN_OPAQUE mode, the
                        background color is used to fill in the
                        pixels in the bitmap that are set to a 0.

            See also    MGL_setPenBitmapPattern(), MGL_setPenStyle(),
                        MGL_getPenStyle()


            MGL_getPenSize

            Function    Returns the current pen size.

            Syntax      void MGL_getPenSize(int *height,int *width);

            Prototype   mgraph.h
            in

            Parameters  height - Place to store the current pen
                        height
                        width - Place to store the current pen width

            Remarks     MGL_getPenSize() return the size of the
                        current pen in pixels. The default pen is 1
                        pixel by 1 pixel in dimensions, however you
                        can change this to whatever value you like.
                        When primitive are rendered with a pen other
                        than the default, the pixels in the pen
                        always lie to the right and below the current
                        pen position.

            See also    MGL_setPenSize()


            MGL_getPenStyle

            Function    Returns the current pen style.

            Syntax      int MGL_getPenStyle(void);

            Prototype   mgraph.h
            in





            52                      MegaGraph Graphics Library Reference






            Remarks     MGL_getPenStyle() returns the currently
                        active pen style. The MGL supports the
                        following pen styles:

                        SOLID_PATTERN              - Fill with solid
                        color
                        BITMAP_PATTERN_OPAQUE      - Pattern fill
                        BITMAP_PATTERN_TRANSPARENT - Transparent
                        pattern fill

                        When filling in the
                        BITMAP_PATTERN_TRANSPARENT mode, the
                        foreground color is used to fill in all
                        pixels in the bitmap pattern that are a 1.
                        Where the pixels in the bitmap pattern are a
                        0, the original background color is retained.
                        In the BITMAP_PATTERN_OPAQUE mode, the
                        background color is used to fill in the
                        pixels in the bitmap that are set to a 0.

            Return      Current pen style.
            value

            See also    MGL_setPenStyle(), MGL_setPenBitmapPattern()


            MGL_getPixel

            Function    Returns the color of a specified pixel

            Syntax      color_t MGL_getPixel(point p)

            Prototype   mgraph.h
            in

            Parameters  p - Point defining the pixel to read

            Remarks     MGL_getPixel() returns the color of the pixel
                        at the coordinates defined by the point  .
                                                                p

                        Note: You must ensure that you call the
                        routine MGL_beginPixel() before reading any
                        pixel values and the routine MGL_endPixel()
                        after reading a bunch of pixels.

            Return      Color of the specified pixel.
            value

            See also    MGL_pixel(), MGL_getPixelCoord(),
                        MGL_beginPixel(), MGL_endPixel()










            Chapter 6 - Console Library                               53






            MGL_getPixelCoord

            Function    Returns the color of a specified pixel

            Syntax      color_t MGL_getPixelCoord(int x,int y);

            Prototype   mgraph.h
            in

            Parameters  x,y - Coordinates of the pixel to read.

            Remarks     MGL_getPixelCoord() returns the color of the
                        pixel at the coordinates defined by the point
                             .
                        (x,y)

                        Note: You      ensure that you call the
                                  must
                        routine MGL_beginPixel() before reading any
                        pixel values and the routine MGL_endPixel()
                        after reading a bunch of pixels.

            Return      Color of the specified pixel.
            value

            See also    MGL_pixel(), MGL_getPixel(),
                        MGL_beginPixel(), MGL_endPixel()


            MGL_getPixelFormat

            Function    Returns the current packed pixel format
                        information.

            Syntax      void MGL_getPixelFormat(pixel_format
                        *format);

            Prototype   mgraph.h
            in

            Parameters  format - Place to store the pixel format
                        information.




















            54                      MegaGraph Graphics Library Reference






            Remarks     MGL_getPixelFormat() returns the current
                        pixel format information for the currently
                        active video mode. This information is used
                        by the MGL to encode the packed pixel
                        information, and can be used by your
                        application to work out how to pack values
                        correctly for the direct color video modes.
                        This routine should also be used to correctly
                        interpret the format of the pixel information
                        returned by the MGL_getImage() routine. The
                        pixel format structure is defined as follows:

                        typedef struct {
                            char    redMask,blueMask;
                            char    greenMask,rsvdMask;
                            int     redPos,redAdjust;
                            int     greenPos,greenAdjust;
                            int     bluePos,blueAdjust;
                            int     rsvdPos,rsvdAdjust;
                            } pixel_format;

                        The Mask values are logical AND masks that
                        can be used to represent the correct number
                        of usable bits in each color value. The Pos
                        values describe where in the packed pixel
                        format each value resides, and the Adjust
                        values descibe the bit shift required to
                        adjust to 8 bit component values. The
                        following code illustrates how these values
                        can be used to unpack values to and from 8
                        bit RGB tuples:

                        R = (((color) >> redPos) & redMask) <<
                        redAdjust;
                        G = (((color) >> greenPos) & greenMask) <<
                        greenAdjust;
                        B = (((color) >> bluePos) & blueMask) <<
                        blueAdjust;

                        and to pack values:

                        color = ((color_t)((R >> redAdjust) &
                        redMask) << redPos)
                         | ((color_t)((G >> greenAdjust) & greenMask)
                        << greenPos)
                         | ((color_t)((B >> blueAdjust) & blueMask)
                        << bluePos);

            See also    MGL_packColor(), MGL_unpackColor()











            Chapter 6 - Console Library                               55






            MGL_getPolygonType

            Function    Returns the current polygon type.

            Syntax      int MGL_getPolygonType(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getPolygonType() returns the current
                        polygon type. You can change this value with
                        the MGL_setPolygonType() to force the MGL to
                        work with a specific polygon type (and to
                        avoid the default automatic polygon type
                        checking). The MGL supports the following
                        polygon types:

                        AUTO_POLYGON    - MGL automatically
                        determines type
                        CONVEX_POLYGON  - All polygons rendered as
                        convex
                        COMPLEX_POLYGON - All polygons rendered as
                        complex

                        If you expect to be drawing lots of complex
                        or convex polygons, setting the polygon type
                        can result in faster polygon rendering.

            Return      Current polygon type code.
            value

            See also    MGL_setPolygonType(), MGL_fillPolygon()


            MGL_getSpaceExtra

            Function    Returns the current space extra value.

            Syntax      int MGL_getSpaceExtra(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getSpaceExtra() returns the current space
                        extra value used when drawing text in the
                        current font. The space extra value is
                        normally zero, but can be a positive or
                        negative value. This value can be used to
                        insert extra space between the characters in
                        a font (making this value a large negative
                        value will make the characters run on top of
                        each other).

            Return      Current space extra value.
            value

            See also    MGL_setSpaceExtra(), MGL_drawStr()



            56                      MegaGraph Graphics Library Reference






            MGL_getTextDirection

            Function    Returns the current text direction

            Syntax      int MGL_getTextDirection(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getTextDirection() returns the current
                        text direction. The MGL supports the
                        following text directions:

                        LEFT_DIR  - Text runs to the left (right to
                        left)
                        UP_DIR    - Text runs in the up direction
                        RIGHT_DIR - Text runs to the right (left to
                        right)
                        DOWN_DIR  - Text runs in the down direction

                        Currently the MGL only supports directional
                        text with the default 8x8 bitmap font and
                        vector fonts. Bitmap fonts can only be drawn
                        in the RIGHT_DIR direction.

            Return      Current text direction.
            value

            See also    MGL_setTextDirection(), MGL_drawStr()


            MGL_getTextJustify

            Function    Returns the current text justification.

            Syntax      void MGL_getTextJustify(int *horiz,int
                        *vert);

            Prototype   mgraph.h
            in

            Parameters  horiz - Place to store horizontal
                        justification
                        vert - Place to store vertical justification
















            Chapter 6 - Console Library                               57






            Remarks     MGL_getTextJustify() returns the current text
                        justification values. The MGL support the
                        following horizontal justification types:

                        LEFT_TEXT     - Text is left justified
                        CENTER_TEXT   - Text is centered left to
                        right
                        RIGHT_TEXT    - Text is right justified

                        and the following vertical justification
                        types:

                        TOP_TEXT      - Text is top justified
                        CENTER_TEXT   - Text is centered top to
                        bottom
                        BASELINE_TEXT - Text is justified to the
                        baseline
                        BOTTOM_TEXT   - Text is bottom justified

            See also    MGL_setTextJustify()


            MGL_getTextSettings

            Function    Returns the current text settings.

            Syntax      void MGL_getTextSettings(text_settings
                        *settings);

            Prototype   mgraph.h
            in

            Parameters  settings - Place to store the current text
                        settings


























            58                      MegaGraph Graphics Library Reference






            Remarks     MGL_getTextSettings() returns the currently
                        active text settings. This routine provides a
                        way to save and restore all the values
                        relating to the rendering of text in the MGL
                        with a single function call. The text
                        settings values are stored in the following
                        structure:

                        typedef struct {
                            int             horiz_just;
                            int             vert_just;
                            int             dir;
                            int             sz_numerx;
                            int             sz_numery;
                            int             sz_denomx;
                            int             sz_denomy;
                            int             space_extra;
                            font            *fnt;

                        where horiz_just     vert_just
                                         and           define the
                        horizontal and vertical justification values,
                            defines the current text direction,
                        dir
                        space_extra defines the current space extra
                        value and fnt define the currently active
                        font (stored in system memory). The
                        sz_numerx, sz_numery, sz_demonx and sz_denomy
                        specify the current text scaling factors.

            See also    MGL_setTextSettings


            MGL_getTextSize

            Function    Returns the current text scaling factors

            Syntax      void MGL_getTextSize(int *numerx,int
                        *denomx,int *numery,int *denomy);

            Prototype   mgraph.h
            in

            Parameters  numerx - Place to store the x numerator value
                        denomx - Place to store the x denominator
                        value
                        numery - Place to store the y numerator value
                        denomy - Place to store the y denominator
                        value













            Chapter 6 - Console Library                               59






            Remarks     MGL_getTextSize() returns the current text
                        scaling factors used by the MGL. The text
                        size values define an integer scaling factor
                        to be used, where the actual values will be
                        computed using the following formula:

                                  scaled
                                       unscaled
                                             numer
                                          denom

                        Note: Currently the MGL can only scale
                        vectors fonts.

            See also    MGL_setTextSize()


            MGL_getViewport

            Function    Returns the currently active viewport

            Syntax      void MGL_getViewport(rect *view);

            Prototype   mgraph.h
            in

            Parameters  view - Place to store the current viewport

            Remarks     MGL_getViewport() returns the dimensions of
                        the currently active viewport. These
                        dimensions are global to the entire display
                        area used by the currently active video
                        device driver.

                        All output in the MGL is relative to the
                        current viewport, so by changing the viewport
                        to a new value you can make all output appear
                        in a different rectangular portion of the
                        video display.

            See also    MGL_setViewport(), MGL_setRelViewport(),
                        MGL_clearViewport(), MGL_setClipRect()


            MGL_getVisualPage

            Function    Returns the currently visible hardware video
                        page.

            Syntax      int MGL_getVisualPage(void);

            Prototype   mgraph.h
            in









            60                      MegaGraph Graphics Library Reference






            Remarks     MGL_getVisualPage() returns the currently
                        visible hardware video page number. The first
                        hardware video page is number 0, the second
                        is 1 and so on. The number of available
                        hardware video pages depends on the type of
                        underlying hardware, the video mode
                        resolution and amount of video memory
                        installed. Thus not all video modes support
                        multiple hardware video pages.

            Return      Currently visible hardware video page.
            value

            See also    MGL_setVisualPage(), MGL_getActivePage(),
                        MGL_setActivePage().


            MGL_getWriteMode

            Function    Returns the current write mode operation

            Syntax      int MGL_getWriteMode(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getWriteMode() returns the currently
                        active write mode. The MGL supports the
                        following write mode operations for all
                        output primitives:

                        REPLACE_MODE - Replace the original pixels
                        AND_MODE     - Logical AND with original
                        pixels
                        OR_MODE      - Logical OR with original
                        pixels
                        XOR_MODE     - Logical XOR with original
                        pixels

            Return      Current write mode operation.
            value

            See also    MGL_setWriteMode()


            MGL_getX

            Function    Returns the X coordinate of the current
                        position.

            Syntax      int MGL_getX(void);

            Prototype   mgraph.h
            in






            Chapter 6 - Console Library                               61






            Remarks     MGL_getX() returns the X coordinate of the
                        current position (CP) value. The CP is the
                        current graphics cursor position, and is used
                        by a number of output routines to determine
                        where to being drawing.

            Return      X coordinate of current position
            value

            See also    MGL_getY(), MGL_getCP(), MGL_moveTo()


            MGL_getY

            Function    Returns the Y coordinate of the current
                        position.

            Syntax      int MGL_getY(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_getY() returns the Y coordinate of the
                        current position (CP) value. The CP is the
                        current graphics cursor position, and is used
                        by a number of output routines to determine
                        where to being drawing.

            Return      Y coordinate of current position
            value

            See also    MGL_getX(), MGL_getCP(), MGL_moveTo()


            MGL_globalToLocal

            Function    Converts a point from global coordinates to
                        local coordinates

            Syntax      void MGL_globalToLocal(point *p);

            Prototype   mgraph.h
            in

            Parameters  p - Pointer to point to be converted

            Remarks     MGL_globalToLocal() converts a coordinate
                        from global coordinates to local coordinates.
                        Global coordinates are defined relative to
                        the entire output devices display, while
                        local coordinates are relative to the
                        currently active viewport.

                        This routine is usually used to convert mouse
                        coordinate values from global screen
                        coordinates to the local coordinate system of
                        the currently active viewport.



            62                      MegaGraph Graphics Library Reference






            See also    MGL_localToGlobal()


            MGL_gouraudScanLine

            Function    Draws a smooth shaded scanline.

            Syntax      void MGL_gouraudScanLine(int y,int x1,int
                        x2,color_t c1,color_t c2);

            Prototype   mgraph.h
            in

            Parameters  y - Y coordinate of scanline
                        x1 - Starting X coordinate of scanline
                        x2 - Ending X coordinate of scanline
                        c1 - Starting color value
                        c2 - Ending color value

            Remarks     MGL_gouraudScanLine() draws a smooth shaded
                        scanline between the point        and the
                                                   (x1,y)
                        point       . The color values are smoothly
                              (x2,y)
                        interpolated across the scanline starting
                             c1
                        with    and ending with c2.

                        Note: You      call MGL_beginGouraud() before
                                  must
                        calling this routine to ensure that the
                        hardware is in the correct state to draws
                        shaded scanlines. You must also ensure that
                        you call MGL_endGouraud() after rendering a
                        set of shaded scanlines. You may not call any
                        other MGL routines while you are rendering
                        shaded scanlines.

            See also    MGL_fillGouraudPolygon(). MGL_beginGouraud(),
                        MGL_endGouraud()


            MGL_imageSize

            Function    Returns the number of bytes required to store
                        an image.

            Syntax      long MGL_imageSize(rect r);

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle defining the size of the image

            Remarks     MGL_imageSize() returns the number of bytes
                        required to store an offscreen video memory
                        image. You must use this routine to allocate
                        enough memory to store the image before you
                        call the MGL_getImage() routine to read an
                        image
                        from display memory.



            Chapter 6 - Console Library                               63






            Return      Number of bytes required to store the image.
            value

            See also    MGL_imageSizeCoord(), MGL_getImage(),
                        MGL_getImageCoord(), MGL_putImage(),
                        MGL_putImageCoord().

            See also    MGL_fillGouraudPolygon(). MGL_beginGouraud(),
                        MGL_endGouraud()


            MGL_imageSizeCoord

            Function    Returns the number of bytes required to store
                        an image.

            Syntax      long MGL_imageSizeCoord(int left,int top,int
                        right,int bottom);

            Prototype   mgraph.h
            in

            Parameters  left - Left edge of area to save
                        top - Top egde of area to save
                        right - Right edge of area to save
                        bottom - Bottom edge of area to save

            Remarks     MGL_imageSize() returns the number of bytes
                        required to store an offscreen video memory
                        image. You must use this routine to allocate
                        enough memory to store the image before you
                        call the MGL_getImage() routine to read an
                        image
                        from display memory.

            Return      Number of bytes required to store the image.
            value

            See also    MGL_imageSize(), MGL_getImage(),
                        MGL_getImageCoord(), MGL_putImage(),
                        MGL_putImageCoord().



















            64                      MegaGraph Graphics Library Reference






            MGL_init

            Function    Initialises the MGL.

            Syntax      void MGL_init(int *graphdriver,int
                        *graphmode,const char *pathtodriver);

            Prototype   mgraph.h
            in

            Parameters  graphdriver - Place to store detected
                        graphics device driver id
                        graphmode - Place to store suggested graphics
                        mode id
                        pathtodriver - Path to MGL driver files

            Remarks     MGL_init() initialises the MGL, sets the
                        specified video mode and clears the display
                        device ready to accept output. If you pass
                        the value grDETECT in the graphdriver
                        parameter, MGL_init() will automatically call
                        the MGL_detectGraph() routine to detect the
                        installed video device driver, and initialise
                        itself accordingly. The video mode used in
                        this case will be the one suggested by the
                        installed video device driver, and will be
                        returned in the           parameter. If a
                                        graphmode
                        suitable device is not found for use by the
                        MGL, it will return an error via the
                        MGL_result() routine and pass back the value
                        grNONE in the graphdriver parameter.

                        If you wish to start a video mode other than
                        the default one suggested by the video device
                        driver, you should call the MGL_detectGraph()
                        routine yourself, and pass the value returned
                            graphdriver
                        for             and your selected video mode
                           graphmode
                        in           to initialise the mode.

                        The video device drivers currently supported
                        by the MGL are (this is subject to change -
                        please consult the MGRAPH.H header file for
                        the latest information):

                        grDETECT  - Auto detect the graphics
                        subsystem
                        grNONE    - No graphics hardware detected
                        grEGA     - Standard EGA with 256k RAM
                        grVGA     - Standard VGA
                        grSVGA    - VESA VBE compliant Super VGA
                        grSVGA_S3 - S3 accelerated SuperVGA

                        The MGL supports a number of different video
                        mode resolutions, ranging from 320x200 up to
                        1280x1024 with color ranges from 16 colors up
                        to 16.7 million colors. The name for each
                        video mode can be constructed from the pixel
                        and color resolutions, so the video mode id
                        for 320x200 16 color EGA graphics mode is
                        grEGA_320x200x16, and the 1280x1024 16.7
            Chapter 6 - Console Library
                        million color mode is grSVGA_1280x1024x16m.   65
                        Please consult the MGRAPH.H header file for a
                        full list of defined video modes (subject to
                        change over time).







            See also    MGL_detectGraph(), MGL_setGraphMode(),
                        MGL_restoreCRTMode(), MGL_result()


            MGL_insetRect

            Function    Inset a rectangle by specified values.

            Syntax      void MGL_insetRect(rect r,int dx,int dy)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle to inset
                        dx - Value to inset the X coordinates by
                        dy - Value to inset the Y coordinates by

            Remarks     MGL_insetRect() insets the coordinates of a
                        rectangle by the specified amount in each
                        coordinate direction. The value of dx is
                        added to the left coordinate and subtracted
                        from the right coordinate, while the value of
                           is added to the top coordinate and
                        dy
                        subtracted from the bottom coordinate. You
                        may use negative values for        dy
                                                       and 
                                                    dx        in
                        order to increase the size of a rectangle
                        rather than descrease it's size.

            See also    MGL_offsetRect(), MGL_disjoingRect(),
                        MGL_ptInRect()


            MGL_line

            Function    Draws a line.

            Syntax      void MGL_line(point p1,point p2);

            Prototype   mgraph.h
            in

            Parameters  p1 - Starting point for the line
                        p2 - Ending point for the line

            Remarks     MGL_line() draws a line starting at the point
                        p1 and ending at the point p2 in the current
                        pen style, color and dimensions. The CP is
                        not updated, and the line is clipped to the
                        current clipping rectangle if clipping in on.

            See also    MGL_lineCoord(), MGL_lineFast(),
                        MGL_lineCoordFast(), MGL_lineTo(),
                        MGL_lineToCoord(), MGL_lineRel(),
                        MGL_lineRelCoord().





            66                      MegaGraph Graphics Library Reference






            MGL_lineCoord

            Function    Draws a line.

            Syntax      void MGL_lineCoord(int x1,int y1,int x2,int
                        y2);

            Prototype   mgraph.h
            in

            Parameters  x1,y1 - Starting point for the line
                        x2,y2 - Ending point for the line

            Remarks     MGL_lineCoord() draws a line starting at the
                        point         and ending at the point 
                              (x1,y1)                         (x2,y2)
                        in the current pen style, color and
                        dimensions. The CP is not updated, and the
                        line is clipped to the current clipping
                        rectangle if clipping in on.

            See also    MGL_lineCoord(), MGL_lineFast(),
                        MGL_lineCoordFast(), MGL_lineTo(),
                        MGL_lineToCoord(), MGL_lineRel(),
                        MGL_lineRelCoord().


            MGL_lineCoordFast

            Function    Draws a line as fast as possible.

            Syntax      void MGL_lineCoordFast(int x1,int y1,int
                        x2,int y2);

            Prototype   mgraph.h
            in

            Parameters  x1,y1 - Starting point for the line
                        x2,y2 - Ending point for the line

            Remarks     MGL_lineCoordFast() draws a line starting at
                        the point (x1,y1) and ending at the point
                        (x2,y2) in the current pen style, color and
                        dimensions. The CP is not updated, and the
                        line is clipped to the current clipping
                        rectangle if clipping in on.

                        Note: You must call the routine
                        MGL_beginDrawing() before calling the
                        MGL_lineCoordFast() routine to put the
                        hardware into the correct state fo for high
                        speed line drawing. The routines MGL_line()
                        and MGL_lineCoord() do this once for every
                        line to be drawn, so you can save time by
                        calling MGL_beginDrawing() once before
                        drawing a whole set of lines.





            Chapter 6 - Console Library                               67






            See also    MGL_lineCoord(), MGL_lineFast(),
                        MGL_lineCoordFast(), MGL_lineTo(),
                        MGL_lineToCoord(), MGL_lineRel(),
                        MGL_lineRelCoord(), MGL_beginDrawing(),
                        MGL_endDrawing().


            MGL_lineEngine

            Function    Generates the set of points on a line.

            Syntax      void MGL_lineEngine(int x1,int y1,int x2,int
                        y2,void (*plotPoint)(int x,int y));

            Prototype   mgraph.h
            in

            Parameters  x1,y1 - Starting point for the line
                        x2,y2 - Ending point for the line
                        plotPoint - User supplied pixel plotting
                        routine.

            Remarks     MGL_lineEngine() generates the set of points
                        on a line, and calls a user supplied
                        plotPoint routine for every point generated.
                        This is the same routine used for rendering
                        lines internally in the MGL.

                        The use supplied plotPoint routine will be
                        called once for every point on the line. The
                        set of points generated will always be in the
                        same order for any two endpoints, no matter
                        which order the endpoints are given.

            See also    MGL_ellipseEngine().


            MGL_lineFast

            Function    Draws a line as fast as possible.

            Syntax      void MGL_lineFast(point p1,point p2);

            Prototype   mgraph.h
            in

            Parameters  p1 - Starting point for the line
                        p2 - Ending point for the line












            68                      MegaGraph Graphics Library Reference






            Remarks     MGL_lineFast() draws a line starting at the
                        point    and ending at the point 
                              p1                            in the
                                                         p2
                        current pen style, color and dimensions. The
                        CP is not updated, and the line is clipped to
                        the current clipping rectangle if clipping in
                        on.

                        Note: You      call the routine
                                  must
                        MGL_beginDrawing()        calling the
                                           before
                        MGL_lineFast() routine to put the hardware
                        into the correct state fo for high speed line
                        drawing. The routines MGL_line() and
                        MGL_lineCoord() do this once for every line
                        to be drawn, so you can save time by calling
                        MGL_beginDrawing() once before drawing a
                        whole set of lines.

            See also    MGL_lineCoord(), MGL_lineFast(),
                        MGL_lineCoordFast(), MGL_lineTo(),
                        MGL_lineToCoord(), MGL_lineRel(),
                        MGL_lineRelCoord(), MGL_beginDrawing(),
                        MGL_endDrawing().


            MGL_lineRel

            Function    Draws a relative line from the CP.

            Syntax      void MGL_lineRel(point p)

            Prototype   mgraph.h
            in

            Parameters  p - Relative point to draw line to.

            Remarks     MGL_lineRel() draws a line from the current
                        position (CP) to the relative location that
                        is a distance of   away from the CP. Thus the
                                         p
                        location of the next point on the line is
                        (CP.x + p.x, CP.y + p.y). The CP is updated
                        to this value.

            See also    MGL_moveTo(), MGL_moveRel(), MGL_lineTo(),
                        MGL_lineRel().


            MGL_lineRelCoord

            Function    Draws a relative line.

            Syntax      void MGL_lineRelCoord(int dx,int dy);

            Prototype   mgraph.h
            in

            Parameters  dx,dy - Relative point to draw line to.




            Chapter 6 - Console Library                               69






            Remarks     MGL_lineRelCoord() draws a line from the
                        current position (CP) to the relative
                        location that is a distance of (dx,dy) away
                        from the CP. Thus the location of the next
                        point on the line is (CP.x + dx, CP.y + dy).
                        The CP is updated to this value.

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().


            MGL_lineTo

            Function    Draws a line from the CP to the specified
                        point.

            Syntax      void MGL_lineTo(point p);

            Prototype   mgraph.h
            in

            Parameters  p - Point to draw the line to.

            Remarks     MGL_lineTo() draws a line from the current
                        position (CP) to the new point p. The CP is
                        set to the point   on return from this
                                         p
                        routine.

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().


            MGL_lineToCoord

            Function    Draws a line from the CP to the specified
                        point.

            Syntax      void MGL_lineToCoord(int x,int y);

            Prototype   mgraph.h
            in

            Parameters  x,y - Point to draw the line to.

            Remarks     MGL_lineToCoord() draws a line from the
                        current position (CP) to the new point (x,y).
                        The CP is set to the point       on return
                                                   (x,y)
                        from this routine.

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().



            70                      MegaGraph Graphics Library Reference






            MGL_loadFont

            Function    Loads an MGL font file for use.

            Syntax      font *MGL_loadFont(const char *fontname);

            Prototype   mgraph.h
            in

            Parameters  fontname - Name of the font file to load

            Remarks     MGL_loadFont() attempts to locate and read in
                        the font specified by fontname. The parameter
                        fontname is the name of the actual MGL font
                        file on disk, and may include a relative
                        pathname component. MGL_loadFont() first
                        looks for the font file relative to the
                        directory where it found the MGL driver files
                        at initialisation time, and will then look
                        for the font file relative to the current
                        directory if the fontfile was not found.

                        If the font file was not found, or was not
                        successfully loaded, MGL_loadFont returns
                        NULL, and sets the MGL_result() error code.

            Return      Pointer to the loaded font file (NULL if an
            value       error occurred).

            See also    MGL_unloadFont(), MGL_useFont(),
                        MGL_availableFont().


            MGL_localToGlobal

            Function    Converts a point from local coordinates to
                        global coordinates

            Syntax      void MGL_localToGlobal(point *p);

            Prototype   mgraph.h
            in

            Parameters  p - Pointer to point to be converted

            Remarks     MGL_localToGlobal() converts a coordinate
                        from local coordinates to global coordinates.
                        Global coordinates are defined relative to
                        the entire output devices display, while
                        local coordinates are relative to the
                        currently active viewport.

            See also    MGL_globalToLocal()







            Chapter 6 - Console Library                               71






            MGL_marker

            Function    Draws a marker at the specified coordinate.

            Syntax      void MGL_marker(point p);

            Prototype   mgraph.h
            in

            Parameters  p - Coordinate to draw the marker at

            Remarks     MGL_marker() draws a marker in the current
                        marker color, style and size at the specified
                        location. Markers can be used to label the
                        vertices in graphs. Refer to the
                        MGL_setMarkerStyle() routine for a list of
                        the typs of markers supported.

            See also    MGL_setMarkerSize(), MGL_getMarkerSize(),
                        MGL_setMarkerStyle(), MGL_getMarkerStyle(),
                        MGL_polyMarker()


            MGL_maxCharWidth

            Function    Returns the maximum character width for
                        current font.

            Syntax      int MGL_maxCharWidth(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_maxCharWidth() returns the maximum
                        character width for the currently active
                        font. You can use this routine to quickly
                        determine if a character will possibly
                        overlap something else on the display screen.

            Return      Maximum character width for current font.
            value

            See also    MGL_getCharMetrics(), MGL_getFontMetrics(),
                        MGL_textHeight(), MGL_textWidth(),
                        MGL_charWidth()


            MGL_maxColor

            Function    Returns the maximum available color value.

            Syntax      color_t MGL_maxColor(void);

            Prototype   mgraph.h
            in





            72                      MegaGraph Graphics Library Reference






            Remarks     MGL_maxColor() retutns the values of the
                        largest available color values for the
                        current video modes. This value will always
                        be one less than the number of available
                        colors in that particular video mode.

            Return      Maximum color value for current video mode.
            value


            MGL_maxPage

            Function    Returns the maximum available hardware video
                        page.

            Syntax      int MGL_maxPage(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_maxPage() returns the index of the
                        highest hardware video page that is
                        available. This value will always be one less
                        than the number of hardware video pages
                        available. Some video modes only have one
                        hardware video page available, so this value
                        will be 0.

            Return      Index of maximum available hardware video
            value       page.


            MGL_maxx

            Function    Returns the current maximum X coordinate

            Syntax      int MGL_maxx(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_maxx() returns the maximum X coordinate
                        available in the currently active viewport.
                        This value will change if you change the
                        dimensions of the current viewport.

                        Use the MGL_sizex() routine to determine the
                        dimensions of the physical display area
                        available to the program.

            Return      Maximum X coordinate in current viewport.
            value

            See also    MGL_maxy(), MGL_sizex(), MGL_sizey()






            Chapter 6 - Console Library                               73






            MGL_maxy

            Function    Returns the current maximum Y coordinate

            Syntax      int MGL_maxy(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_maxy() returns the maximum Y coordinate
                        available in the currently active viewport.
                        This value will change if you change the
                        dimensions of the current viewport.

                        Use the MGL_sizey() routine to determine the
                        dimensions of the physical display area
                        available to the program.

            Return      Maximum Y coordinate in current viewport.
            value

            See also    MGL_maxx(), MGL_sizex(), MGL_sizey()


            MGL_modeName

            Function    Returns textual representation of the
                        specified video mode.

            Syntax      char *MGL_modeName(int mode);

            Prototype   mgraph.h
            in

            Parameters  mode - Video mode number to get name for.

            Remarks     MGL_modeName() returns a string representing
                        the specified video mode number.

            Return      Pointer to a string representing the name of
            value       the mode.

            See also    MGL_driverName().


            MGL_moveRel

            Function    Moves the CP to a new relative location.

            Syntax      void MGL_moveRel(point p)

            Prototype   mgraph.h
            in

            Parameters  p - Relative point to move the CP to.





            74                      MegaGraph Graphics Library Reference






            Remarks     MGL_moveRel() moves the current position (CP)
                        to the relative location that is a distance
                             away from the CP. Thus the location of
                           p
                        of 
                        the CP moves to is (CP.x + p.x, CP.y + p.y).

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRelCoord(), MGL_lineTo(),
                        MGL_lineToCoord(), MGL_lineRel(),
                        MGL_lineRelCoord().


            MGL_moveRelCoord

            Function    Moves the CP to a new relative location

            Syntax      void MGL_moveRelCoord(int dx,int dy);

            Prototype   mgraph.h
            in

            Parameters  dx,dy - Relative point to move the CP to.

            Remarks     MGL_moveRelCoord() moves the current position
                        (CP) to the relative location that is a
                        distance of (dx,dy) away from the CP. Thus
                        the location the CP is moved to is (CP.x +
                        dx, CP.y + dy).

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().


            MGL_moveTo

            Function    Moves the CP to a new location.

            Syntax      void MGL_moveTo(point p);

            Prototype   mgraph.h
            in

            Parameters  p - Point to move the CP to.

            Remarks     MGL_moveTo() moves the current position (CP)
                        to the new point p.

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().








            Chapter 6 - Console Library                               75






            MGL_moveToCoord

            Function    Moves the CP to a new location.

            Syntax      void MGL_moveToCoord(int x,int y);

            Prototype   mgraph.h
            in

            Parameters  x,y - Point to move the CP to.

            Remarks     MGL_moveToCoord() moves the current position
                        (CP) to the new point (x,y).

            See also    MGL_moveTo(), MGL_moveToCoord(),
                        MGL_moveRel(), MGL_moveRelCoord(),
                        MGL_lineTo(), MGL_lineToCoord(),
                        MGL_lineRel(), MGL_lineRelCoord().


            MGL_offsetRect

            Function    Offsets a rectangle by a specified amount

            Syntax      void MGL_offsetRect(rect r,int dx,int dy)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle to offset
                        dx - Value to offset the X coordinates by
                        dy - Value to offset the Y coordinates by

            Remarks     MGL_offsetRect() moves the start of a
                        rectangle to a new location, by adding the
                        specified offset values to the X and Y
                        coordinate values. The size of the rectangle
                        is not changes, just it's location.

            See also    MGL_insetRect(), MGL_disjoingRect(),
                        MGL_ptInRect()


            MGL_packColor

            Function    Packs an RGB color value.

            Syntax      color_t MGL_packColor(uchar R,uchar G,uchar
                        B);

            Prototype   mgraph.h
            in

            Parameters  R - Red color component (0-255)
                        G - Green color component (0-255)
                        B - Blue color component (0-255)




            76                      MegaGraph Graphics Library Reference






            Remarks     MGL_packColor() takes 8 bit color component
                        values and packs them into a packed color
                        value that is appropriate for the current
                        video mode. This function only works properly
                        in the HiColor and TrueColor modes, as you
                        cannot specifiy RGB values in the color
                        mapped modes.

            Return      MGL packed color value appropriate for the
            value       current video mode.

            See also    MGL_unpackColor().


            MGL_pixel

            Function    Draws a pixel at the specified location

            Syntax      void MGL_pixel(point p)

            Prototype   mgraph.h
            in

            Parameters  p - Point to plot the point at it.

            Remarks     MGL_pixel() plots a single pixel at the
                        specified location in the current foregrond
                        color.

                        Note: You      call the routine
                                  must
                        MGL_beginPixel() routine before calling the
                        MGL_pixel(), and you must call the
                        MGL_endPixel() routine after you have
                        finished plotting pixels.

            See also    MGL_pixelCoord(), MGL_beginPixel(),
                        MGL_endPixel().


            MGL_pixelCoord

            Function    Draws a pixel at the specified location

            Syntax      void MGL_pixelCoord(int x,int y);

            Prototype   mgraph.h
            in

            Parameters  x,y - Point to plot the point at it.











            Chapter 6 - Console Library                               77






            Remarks     MGL_pixelCoord() plots a single pixel at the
                        specified location in the current foregrond
                        color.

                        Note: You      call the routine
                                  must
                        MGL_beginPixel() routine before calling the
                        MGL_pixel(), and you      call the
                                             must
                        MGL_endPixel() routine after you have
                        finished plotting pixels.

            See also    MGL_pixelCoord(), MGL_beginPixel(),
                        MGL_endPixel().


            MGL_polyLine

            Function    Draws a set of connected lines.

            Syntax      void MGL_polyLine(int count,point *vArray);

            Prototype   mgraph.h
            in

            Parameters  count - Number of vertices in polyline
                        vArray - Array of vertices in the polyline

            Remarks     MGL_polyLine() draws a set of connected line
                        (a polyline). The coordinates of the polyline
                        are specified by       , and the lines are
                                         vArray
                        drawn in the current drawing attributes.

                        Note: The polyline is not closed by default,
                        so if you wish to draw the outline of a
                        polygon, you will need to add the starting
                        point to the end of the vertex array.

            See also    MGL_polyMarker(), MGL_polyPoint().


            MGL_polyMarker

            Function    Draws a set of markers.

            Syntax      void MGL_polyMarker(int count,point *vArray);

            Prototype   mgraph.h
            in

            Parameters  count - Number of markers to draw
                        vArray - Array of coordinates to draw the
                        markers at

            Remarks     MGL_polyMarker() draws a set of markers in
                        the current marker color, style and size at
                        the locations passed in the        parameter.
                                                    vArray

            See also    MGL_polyLine(), MGL_polyPoint()



            78                      MegaGraph Graphics Library Reference






            MGL_polyPoint

            Function    Draws a set of pixels.

            Syntax      void MGL_polyPoint(int count,point *vArray);

            Prototype   mgraph.h
            in

            Parameters  count - Number of pixels to draw
                        vArray - Array of coordinates to draw the
                        pixels at

            Remarks     MGL_polyPoint() draws a set of pixels in the
                        current color at the locations passed in the
                        vArray parameter.

            See also    MGL_polyLine(), MGL_polyPoint()


            MGL_popViewport

            Function    Pops the current viewport off the stack.

            Syntax      void MGL_popViewport(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_popViewport() pops the viewport off the
                        top of the viewport stack and makes it the
                        new active viewport.

                        The MGL maintains a viewport stack that you
                        may use to temporarily push viewport settings
                        onto for later retrival.

            See also    MGL_pushViewport(), MGL_setViewport(),
                        MGL_getViewport()


            MGL_ptInRect

            Function    Determines if a point is in a rectangle.

            Syntax      bool MGL_ptInRect(point p,rect r);

            Prototype   mgraph.h
            in

            Parameters  p - Point to test
                        r - Rectangle to test point against

            Remarks     MGL_ptInRect() determines if a specified
                        point is contained within a particular
                        rectangle.




            Chapter 6 - Console Library                               79






            Return      True if the point is contained in the
            value       rectangle, false if not.

            See also    MGL_ptInRectCoord().


            MGL_ptInRectCoord

            Function    Determines if a point is in a rectangle.

            Syntax      bool MGL_ptInRectCoord(int x,int y,rect r)

            Prototype   mgraph.h
            in

            Parameters  x,y - Point to test
                        r - Rectangle to test point against

            Remarks     MGL_ptInRectCoord() determines if a specified
                        point is contained within a particular
                        rectangle.

            Return      True if the point is contained in the
            value       rectangle, false if not.

            See also    MGL_ptInRect()


            MGL_pushViewport

            Function    Pushes the current viewport onto the stack.

            Syntax      void MGL_pushViewport(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_pushViewport() pushs the current viewport
                        values onto the viewport stack, to be
                        retrieved at a later date.

            See also    MGL_popViewport(), MGL_setViewport(),
                        MGL_getViewport()


            MGL_putDivot

            Function    Replaces a divot of video memory.

            Syntax      void MGL_putDivot(void *divot);

            Prototype   mgraph.h
            in

            Parameters  divot - Pointer to the divot to replace





            80                      MegaGraph Graphics Library Reference






            Remarks     MGL_putDivot() replaces a region of video
                        memory that was saved previously with an
                        MGL_getDivot() routine. The divot is replaced
                        at the same location that is was taken from
                        on the current display page.

            See also    MGL_getDivot(), MGL_divotSize(),
                        MGL_getImage(), MGL_putImage()


            MGL_putIcon

            Function    Draws an icon at the specified location.

            Syntax      void MGL_putIcon(int x,int y,icon_header
                        *icon);

            Prototype   mgraph.h
            in

            Parameters  x,y - Coordinates to draw the icon at
                        icon - Pointer to the icon data to draw

            Remarks     MGL_putIcon() draws an icon at the specified
                        location. The icon      be in the correct
                                           must
                        format for the current video mode. The icon
                        is drawn by punching a black hole in the
                        background with the icon mask, and then
                        OR'ing in the the image data for the icon.


            MGL_putImage

            Function    Draws a video memory image on the display

            Syntax      void MGL_putImage(rect r,void *image,int op)

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle to draw the image at
                        image - Pointer to the image to draw
                        op - Write mode operation to use.

















            Chapter 6 - Console Library                               81






            Remarks     MGL_putImage() blasts the specified video
                        memory image to the display memory at the
                        specified location. If the image is larger
                        than the destination rectangle, it will be
                        clipped to the current destination rectangle
                        extents. You may specify any of the following
                        write mode operations to be used when moving
                        the image to video memory:

                        REPLACE_MODE - Replace the original pixels
                        AND_MODE     - Logical AND with original
                        pixels
                        OR_MODE      - Logical OR with original
                        pixels
                        XOR_MODE     - Logical XOR with original
                        pixels

            See also    MGL_putImageCoord(), MGL_getImage(),
                        MGL_getImageCoord(), MGL_imageSize().


            MGL_putImageCoord

            Function    Draws a video memory image on the display

            Syntax      void MGL_putImageCoord(int left,int top,int
                        right,int bottom,void *image,int op);

            Prototype   mgraph.h
            in

            Parameters  left - Left coordinate to draw image at
                        top - Top coordinate to draw image at
                        right - Right coordinate to draw image at
                        bottom - Bottom coordinate to draw image at
                        image - Pointer to the image to draw
                        op - Write mode operation to use.

            Remarks     MGL_putImageCoord() blasts the specified
                        video memory image to the display memory at
                        the specified location. If the image is
                        larger than the destination rectangle, it
                        will be clipped to the current destination
                        rectangle extents. You may specify any of the
                        following write mode operations to be used
                        when moving the image to video memory:

                        REPLACE_MODE
                        AND_MODE
                        OR_MODE
                        XOR_MODE

            See also    MGL_putImage(), MGL_getImage(),
                        MGL_getImageCoord(), MGL_imageSize().






            82                      MegaGraph Graphics Library Reference






            MGL_putMonoImage

            Function    Plots a monochromatic image.

            Syntax      void MGL_putMonoImage(int x,int y,int
                        byteWidth,int height,void *image);

            Prototype   mgraph.h
            in

            Parameters  x,y - Coordinate to plot the image at
                        byteWidth - Width of the image in bytes
                        height - Height of the image in scanlines
                        image - Pointer to the buffer holding the
                        image

            Remarks     MGL_putMonoImage() displays a single color
                        image in the current foreground color. Where
                        a bit is a 1 in the image definition, a pixel
                        is plotted in the foreground color, where a
                        bit is a 0 the original pixels are left
                        alone.

            See also    MGL_getImage(), MGL_putImage().


            MGL_realColor

            Function    Returns the real color value for a color
                        mapped index.

            Syntax      color_t MGL_realColor(int color);

            Prototype   mgraph.h
            in

            Parameters  color -

            Remarks     MGL_realColor() returns a color value
                        appropriate for the current video mode, given
                        a color mapped index. This routine works in
                        all video modes, including the HiColor and
                        TrueColor video modes. In the color mapped
                        modes, the value is simply returned
                        unchanged. However in the HiColor and
                        TrueColor modes, the appropriate color is
                        looked up in the currently active palette.
                        Thus you can still write code for the HiColor
                        and TrueColor modes that works with color
                        mapped indexes (although you cannot do things
                        like hardware palette fades and rotates as
                        the palette is implemented in software).

            Return      Real color value for the color mapped index.
            value

            See also    MGL_setPalette(), MGL_getPalette().



            Chapter 6 - Console Library                               83






            MGL_rect

            Function    Draws a rectangle.

            Syntax      void MGL_rect(rect r);

            Prototype   mgraph.h
            in

            Parameters  r - Rectangle to draw

            Remarks     MGL_rect() draws a rectangle in the current
                        drawing attributes at the specified location.
                        The rectangle is drawn within the
                        mathematical boundary of the rectangle, so
                        effectively the right and bottom edges of the
                        rectangle are not drawn (solving problems
                        with shared edges). Degenerate rectangles are
                        not drawn.

            See also    MGL_rectCoord(), MGL_rectPt().


            MGL_rectCoord

            Function    Draws a rectangle.

            Syntax      void MGL_rectCoord(int left,int top,int
                        right,int bottom);

            Prototype   mgraph.h
            in

            Parameters  left - Left coordinate of the rectangle
                        top - Top coordinate of the rectangle
                        right - Right coordinate of the rectangle
                        bottom - Bottom coordinate of the rectangle

            Remarks     MGL_rectCoord() draws a rectangle in the
                        current drawing attributes at the specified
                        location. The rectangle is drawn within the
                        mathematical boundary of the rectangle, so
                        effectively the right and bottom edges of the
                        rectangle are not drawn (solving problems
                        with shared edges). Degenerate rectangles are
                        not drawn.

            See also    MGL_rect(), MGL_rectPt().












            84                      MegaGraph Graphics Library Reference






            MGL_rectPt

            Function    Draws a rectangle.

            Syntax      void MGL_rectPt(point lt,point rb);

            Prototype   mgraph.h
            in

            Parameters  lt - Left top coordinate of the rectangle
                        rb - Right bottom coordinate of the rectangle

            Remarks     MGL_rectPt() draws a rectangle in the current
                        drawing attributes at the specified location.
                        The rectangle is drawn within the
                        mathematical boundary of the rectangle, so
                        effectively the right and bottom edges of the
                        rectangle are not drawn (solving problems
                        with shared edges). Degenerate rectangles are
                        not drawn.

            See also    MGL_rect(), MGL_rectCoord().


            MGL_registerDriver

            Function    Registers a user loaded or linked device
                        driver

            Syntax      int MGL_registerDriver(const char *name,void
                        *driver);

            Prototype   mgraph.h
            in

            Parameters  name - Name of driver to register
                        driver - Pointer to the start of the driver
                        in memory

            Remarks     MGL_registerDriver() registers a linked in or
                        user loaded graphics driver with the graphics
                        system. The driver must be one of the
                        standard graphics device drivers supported by
                        the library. The loaded driver is checked to
                        ensure that it actually is a valid MGL device
                        driver.

                        This routine is usually used to inform the
                        MGL that the user has linked the device
                        driver code directly with the application (or
                        has loaded it onto the heap) so should not be
                        dynamically loaded from disk at runtime.

            Return      grOK on success, grBadDriver if driver passed
            value       was invalid

            See also    MGL_init()



            Chapter 6 - Console Library                               85






            MGL_restoreAttributes

            Function    Restores a previously saved attribute list

            Syntax      void MGL_restoreAttributes(attributes *attr);

            Prototype   mgraph.h
            in

            Parameters  attr - Pointer to the attribute list to
                        restore

            Remarks     MGL_restoreAttributes() restores a set of
                        attributes that were saved with the
                        MGL_getAttributes() routine. The attributes
                        list represents the current state of the MGL.
                        The value of the color palette is not changed
                        by this routine.

            See also    MGL_getAttributes


            MGL_restoreCRTMode

            Function    Resets the system back into text mode

            Syntax      void MGL_restoreCRTMode(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_restoreCRTMode() resets the system back
                        into the original text mode that was present
                        before the MGL was started. If the system was
                        in the EGA/VGA 43/50 line modes, this mode
                        will be reset to its original state. The MGL
                        can be re-started with the MGL_setGraphMode()
                        routine.

            See also    MGL_init(), MGL_setGraphMode()


            MGL_result

            Function    Returns result code of the last graphics
                        operation

            Syntax      int MGL_result(void);

            Prototype   mgraph.h
            in









            86                      MegaGraph Graphics Library Reference






            Remarks     MGL_result() returns the result code of the
                        last graphics operation. The internal result
                        code is reset back to grOK on return from
                        this routine, so you should only call the
                        routine once after the graphics operation.
                        The following result codes are returned by
                        MGL_result:

                        grOK             No error
                        grNoInit         Graphics driver has not been
                        installed
                        grNotDetected    Graphics hardware was not
                        detected
                        grDriverNotFound Graphics driver file was not
                        found
                        grBadDriver      File loaded was not a
                        graphics driver
                        grLoadMem        Not enough memory to load
                        graphics driver
                        grInvalidMode    Invalid graphics mode for
                        selected driver
                        grInvalidDriver  Driver number is invalid
                        grError          General graphics error
                        grInvalidName    Invalid driver name
                        grNoMem          Not enough memory to perform
                        operation
                        grNoModeSupport  Select video mode not
                        supported by hardware
                        grInvalidFont    Invalid font data
                        grBadFontFile    File loaded was not a font
                        file
                        grFontNotFound   Font file was not found

            Return      Result code of the last graphics operation
            value

            See also    MGL_setResult()


            MGL_rotatePalette

            Function    Rotates the values in a palette structure

            Syntax      void MGL_rotatePalette(palette *pal,int
                        numColors,int direction);

            Prototype   mgraph.h
            in

            Parameters  pal - Pointer to the palette array to rotate
                        numColors - Number of colors entries in the
                        palette array
                        direction - Direction to rotate the palette
                        entries






            Chapter 6 - Console Library                               87






            Remarks     MGL_rotatePalette() rotates the values in the
                        passed palette array in the specified
                        direction. The palette may be any arbitrary
                        size, so you can rotate just a subset of the
                        values in the current physical palette. Note
                        that this routine has not effect on the
                        currently active palette. In order to make
                        the new rotated palette active you will need
                        to call the MGL_setPalette() routine.

                        The direction of rotation should be one of
                        the following:

                        PAL_ROTATE_UP   - Rotate palette entries up
                        in memory
                        PAL_ROTATE_DOWN - Rotate palette entries down
                        in memory

                        When the direction specified is
                        PAL_ROTATE_UP, the first entry in the palette
                        is moved to the last position in the palette,
                        and all the remaining entries are move one
                        position down in the array. The the direction
                        specified is PAL_ROTATE_DOWN, the last entry
                        is moved into the first entry of the palette,
                        and the remaining entries are all moved on
                        position up in the array.

            See also    MGL_setPalette(), MGL_getPalette()


            MGL_scanLeftForColor

            Function    Scans left in video memory for a specified
                        color

            Syntax      int MGL_scanLeftForColor(int x,int y,color_t
                        color);

            Prototype   mgraph.h
            in

            Parameters  x,y - Location to begin scanline search
                        color - Color value to search for
















            88                      MegaGraph Graphics Library Reference






            Remarks     MGL_scanLeftForColor() begins scanning in
                        video memory at the specified location for
                        the specified color. The search begins at the
                        location (x,y) and searches left along the
                        scanline from this point and returns the x
                        coordinate of the pixel if one is found, or -
                        1 if the search went beyond the left edge of
                        the display screen.

                        No clipping or viewport mapping is performed
                        by this routine, but can be performed after
                        calling this routine. This routine can be
                        used as the basis of a high performance
                        floodfill operation. Have a look in the file
                        FFILL.C in the EXAMPLES directory which uses
                        this routine to implement a fast floodfill
                        operation.

            Return      X coordinate of pixel if found, or -1 if
            value       search hit left edge of display

            See also    MGL_scanRightForColor(),
                        MGL_scanLeftWhileColor(),
                        MGL_scanRightWhileColor()


            MGL_scanLeftWhileColor

            Function    Scans left in video memory for any color but
                        the specified color

            Syntax      int MGL_scanLeftWhileColor(int x,int
                        y,color_t color);

            Prototype   mgraph.h
            in

            Parameters  x,y - Location to begin scanline search
                        color - Color value to search on





















            Chapter 6 - Console Library                               89






            Remarks     MGL_scanLeftWhileColor() begins scanning in
                        video memory at the specified location and
                        continues to scan while the pixels are the
                        same as the specified seed color. The search
                        begins at the location (x,y) and searches
                        left along the scanline from this point and
                        returns the x coordinate of the first pixel
                        found that is not of the specified color, or
                        -1 if the search went beyond the left edge of
                        the display screen.

                        No clipping or viewport mapping is performed
                        by this routine, but can be performed after
                        calling this routine. This routine can be
                        used as the basis of a high performance
                        floodfill operation. Have a look in the file
                        FFILL.C in the EXAMPLES directory which uses
                        this routine to implement a fast floodfill
                        operation.

            Return      X coordinate of pixel if found, -1 if search
            value       hit left edge of display

            See also    MGL_scanLeftForColor(),
                        MGL_scanRightForColor(),
                        MGL_scanRightWhileColor()


            MGL_scanLine

            Function    Fills a specified scanline

            Syntax      void MGL_scanLine(int y,int x1,int x2);

            Prototype   mgraph.h
            in

            Parameters  y - Y coordinate of scanline to fill
                        x1 - Starting X coordinate of scanline to
                        fill
                        x2 - Ending X coordinate of scanline to fill

            Remarks     MGL_scanLine() fills the specified portion of
                        a scanline in the current attributes and fill
                        pattern. This can be used to implement higher
                        level complex fills, such as region fills,
                        floodfills etc.

            See also    MGL_penStyle(), MGL_setPenBitmapPattern(),
                        MGL_setPenPixmapPattern()










            90                      MegaGraph Graphics Library Reference






            MGL_scanRightForColor

            Function    Scans right in video memory for a specified
                        color

            Syntax      int MGL_scanRightForColor(int x,int y,color_t
                        color);

            Prototype   mgraph.h
            in

            Parameters  x,y - Location to begin scanline search
                        color - Color value to search for

            Remarks     MGL_scanRightForColor() begins scanning in
                        video memory at the specified location for
                        the specified color. The search begins at the
                        location (x,y) and searches right along the
                        scanline from this point and returns the x
                        coordinate of the pixel if one is found, or
                        one more than the maximum X coordinate if the
                        search went beyond the right edge of the
                        display screen.

                        No clipping or viewport mapping is performed
                        by this routine, but can be performed after
                        calling this routine. This routine can be
                        used as the basis of a high performance
                        floodfill operation. Have a look in the file
                        FFILL.C in the EXAMPLES directory which uses
                        this routine to implement a fast floodfill
                        operation.

            Return      X coordinate of pixel if found, or maxx+1 if
            value       search hit right edge of display

            See also    MGL_scanLeftForColor(),
                        MGL_scanLeftWhileColor(),
                        MGL_scanRightWhileColor()


            MGL_scanRightWhileColor

            Function    Scans right in video memory for any color but
                        the specified color

            Syntax      int MGL_scanRightWhileColor(int x,int
                        y,color_t color);

            Prototype   mgraph.h
            in

            Parameters  x,y - Location to begin scanline search
                        color - Color value to search on






            Chapter 6 - Console Library                               91






            Remarks     MGL_scanRightWhileColor() begins scanning in
                        video memory at the specified location and
                        continues to scan while the pixels are the
                        same as the specified seed color. The search
                        begins at the location (x,y) and searches
                        right along the scanline from this point and
                        returns the x coordinate of the first pixel
                        found that is not of the specified color, or
                        one more than the maximum X coordinate if the
                        search went beyond the right edge of the
                        display screen.

                        No clipping or viewport mapping is performed
                        by this routine, but can be performed after
                        calling this routine. This routine can be
                        used as the basis of a high performance
                        floodfill operation. Have a look in the file
                        FFILL.C in the EXAMPLES directory which uses
                        this routine to implement a fast floodfill
                        operation.

            Return      X coordinate of pixel if found, maxx+1 if
            value       search hit right edge of display

            See also    MGL_scanLeftForColor(),
                        MGL_scanRightForColor(),
                        MGL_scanLeftWhileColor()


            MGL_setActivePage

            Function    Sets the currently active hardware display
                        page.

            Syntax      void MGL_setActivePage(int page);

            Prototype   mgraph.h
            in

            Parameters  page - Number of active hardware display page
                        to use

            Remarks     MGL_setActivePage() sets the currently active
                        hardware video page number to which all
                        output from the MGL is sent to. The first
                        hardware video page is number 0, the second
                        is 1 and so on. The number of available
                        hardware video pages depends on the type of
                        underlying hardware, the video mode
                        resolution and amount of video memory
                        installed. Thus not all video modes support
                        multiple hardware video pages,

            See also    MGL_getActivePage(), MGL_setVisualPage(),
                        MGL_getVisualPage()





            92                      MegaGraph Graphics Library Reference






            MGL_setAspectRatio

            Function    Sets the current video modes aspect ratio

            Syntax      void MGL_setAspectRatio(int aspectRatio);

            Prototype   mgraph.h
            in

            Parameters  aspectRatio - New value for the aspect ratio

            Remarks     MGL_setAspectRatio() sets the aspect ratio of
                        the currently active output device's physical
                        pixels. This ratio is equal to:

                                  pixel x size
                                          1000
                                          x 
                                  pixel y size

                        The device aspect ratio can be used to
                        display circles and squares on the display
                        device by approximating them with ellipses
                        and rectangles of the appropriate dimensions.
                        Thus in order to determine the number of
                        pixels in the y direction for a square with
                        100 pixels in the x direction, we can simply
                        use the formula:

                        y_pixels = ((long)x_pixels * 1000) /
                        aspectratio

                        Note the cast to a long to avoid arithmetic
                        overflow, as the apsect ratio is returned as
                        an integer value with 1000 being a 1:1 aspect
                        ratio.

                        Normally you should not need to change the
                        aspect ratio, as the MGL will automatically
                        determine the correct aspect ratio for the
                        current display mode.

            See also    MGL_getAspectRatio()


            MGL_setBackColor

            Function    Sets the currently active background color

            Syntax      void MGL_setBackColor(color_t color);

            Prototype   mgraph.h
            in

            Parameters  color - New background color value







            Chapter 6 - Console Library                               93






            Remarks     MGL_setBackColor() sets the current
                        background color value. The background color
                        value is used to clear the display and
                        viewport with the MGL_clearDevice() and
                        MGL_clearViewport() routines, and is also
                        used for filling solid primitives in the
                        BITMAP_PATTERN_OPAQUE fill mode.

                        Note: The value passed to this routine is
                        either a color index or a color value in the
                        correct packed pixel format for the current
                        video mode. Use the MGL_packColor() routine
                        to pack 24 bit RGB values for direct color
                        video modes.

            See also    MGL_getBackColor(), MGL_setColor(),
                        MGL_getColor(), MGL_packColor()


            MGL_setBorderColors

            Function    Sets the current border color values.

            Syntax      void MGL_setBorderColors(color_t
                        bright,color_t dark);

            Prototype   mgraph.h
            in

            Parameters  bright - New value for border bright color
                        dark - New value for border dark color

            Remarks     MGL_setBorderColors() sets the currently
                        active border colors values. There are two
                        border color defined by the MGL, the bright
                        border color value and the      border color
                                                   dark
                        value. These values are used by the
                        MGL_drawBorder(), MGL_drawHDivider() and
                        MGL_drawVDivider() routines to determine the
                        colors to draw the psuedo 3D borders in.
                        These values will be set automatically for
                        you by default when the MGL is initisalised,
                        but you will need to change these values if
                        you modify the palette.

                        Note: The value passed to this routine is
                        either a color index or a color value in the
                        correct packed pixel format for the current
                        video mode. Use the MGL_packColor() routine
                        to pack 24 bit RGB values for direct color
                        video modes.

            See also    MGL_getBorderColors(), MGL_packColor()







            94                      MegaGraph Graphics Library Reference






            MGL_setBufSize

            Function    Sets the size of the internal MGL buffer.

            Syntax      void MGL_setBufSize(unsigned size);

            Prototype   mgraph.h
            in

            Parameters  size - New size of the internal MGL buffer

            Remarks     MGL_setBufSize() sets the size of the
                        internal MGL buffer. When the MGL is
                        rendering primitives, it needs a buffer of
                        local scratch space that it can uses for
                        temporary results while rendering the
                        primitives.

                        The default size of this buffer is 4096 bytes
                        and is adequate for most needs. If however
                        you attempt to render some primitives and the
                        MGL runs out of local storage space you would
                        need to increase the size of this internal
                        buffer.

                        This routine must be called        the MGL is
                                                    before
                        initialised for the first time.

            See also    MGL_init()


            MGL_setClipMode

            Function    Sets the clipping mode for the MGL

            Syntax      void MGL_setClipMode(bool mode);

            Prototype   mgraph.h
            in

            Parameters  mode - True for clipping to be turned on,
                        false for no clipping.

            Remarks     MGL_setClipMode() sets the current clipping
                        mode. You can selectively turn clipping on
                        and off for the MGL, in order to speed up
                        some operations. Clipping is turned on by
                        default, and generally you will want to leave
                        clipping enabled, however if you are doing
                        your own rendering and perform your own
                        clipping you may want to turn this off for
                        extra performance from the MGL.

            See also    MGL_getClipMode()






            Chapter 6 - Console Library                               95






            MGL_setClipRect

            Function    Sets the current clipping rectangle

            Syntax      void MGL_setClipRect(rect clip);

            Prototype   mgraph.h
            in

            Parameters  clip - New clipping rectangle to be used.

            Remarks     MGL_setClipRect() sets the current clipping
                        rectangle coordinates. The current clipping
                        rectangle is used to clip all output, and is
                        always defined as being relative to the
                        currently active viewport The clipping
                        rectangle can be no larger than the currently
                        active viewport, and will be truncated if an
                        attempt it made to allow clipping outside of
                        the active viewport.

            See also    MGL_getClipRect, MGL_setViewport(),
                        MGL_getViewport()


            MGL_setColor

            Function    Sets the current foreground color

            Syntax      void MGL_setColor(color_t color);

            Prototype   mgraph.h
            in

            Parameters  color - New foreground color value

            Remarks     MGL_setColor() sets the current foreground
                        color values. The foreground color value is
                        used to draw all primitives.

                        Note: The value passed to this routine is
                        either a color index or a color value in the
                        correct packed pixel format for the current
                        video mode. Use the MGL_packColor() routine
                        to pack 24 bit RGB values for direct color
                        video modes.

            See also    MGL_getColor(), MGL_setBackColor(),
                        MGL_getBackColor(), MGL_packColor()











            96                      MegaGraph Graphics Library Reference






            MGL_setCursorColor

            Function    Sets the current mouse cursor color.

            Syntax      void MGL_setCursorColor(color_t color);

            Prototype   mgraph.h
            in

            Parameters  color - New mouse cursor color value

            Remarks     MGL_setCursorColor() sets the currently
                        active mouse cursor color. The mouse cursor
                        color is used to determine what foreground
                        color is used to draw the mouse cursor in.

                        Note: The value passed to this routine is
                        either a color index or a color value in the
                        correct packed pixel format for the current
                        video mode. Use the MGL_packColor() routine
                        to pack 24 bit RGB values for direct color
                        video modes.

            See also    MGL_getCursorColor(), MGL_packColor()


            MGL_setDefaultPalette

            Function    Resets the palette to the MGL defaut values.

            Syntax      void MGL_setDefaultPalette(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_setDefaultPalette() sets the palette to
                        the current MGL default values for the
                        current video mode. This can be used to reset
                        the palette to the original default values
                        that the palette is programmed with when the
                        MGL is initialised.

            See also    MGL_getDefaultPalette(), MGL_setPalette(),
                        MGL_getPalette()


            MGL_setGraphMode

            Function    Restarts graphics mode operation.

            Syntax      void MGL_setGraphMode(void);

            Prototype   mgraph.h
            in






            Chapter 6 - Console Library                               97






            Remarks     MGL_setGraphMode() restarts the graphics mode
                        operation of the MGL after MGL_restoreCRTMode
                        has been called to put the system back into
                        the original text mode. To start the graphics
                        mode initialially, you call the MGL_int()
                        routine.

            See also    MGL_restoreCRTMode(), MGL_init()


            MGL_setMarkerColor

            Function    Sets the current marker color value.

            Syntax      void MGL_setMarkerColor(color_t color);

            Prototype   mgraph.h
            in

            Parameters  color - New marker color to set

            Remarks     MGL_setMarkerColor() sets the current marker
                        color value. The marker color is used when
                        drawing markers with the MGL_marker()
                        routine.

                        Note: The value passed to this routine is
                        either a color index or a color value in the
                        correct packed pixel format for the current
                        video mode. Use the MGL_packColor() routine
                        to pack 24 bit RGB values for direct color
                        video modes.

            See also    MGL_getMarkerColor(), MGL_marker(),
                        MGL_polyMarker(), MGL_packColor()


            MGL_setMarkerSize

            Function    Sets the current marker size value.

            Syntax      void MGL_setMarkerSize(int size);

            Prototype   mgraph.h
            in

            Parameters  size - New marker size

            Remarks     MGL_setMarkerSize() sets the current marker
                        size. The marker size is used to determine
                        how big to draw the markers that are drawn
                        with the MGL_marker() routine. The size is
                        defined as dimension from the middle of the
                        marker to the edges, so the actual dimensions
                        of the marker will be approximately twice the
                        maker size. If marker size of 1 will define a
                        marker that is contained within a rectangle 3
                        pixels wide.


            98                      MegaGraph Graphics Library Reference







            See also    MGL_getMarkerSize(), MGL_marker(),
                        MGL_polyMarker()


            MGL_setMarkerStyle

            Function    Sets the current marker style.

            Syntax      void MGL_setMarkerStyle(int style);

            Prototype   mgraph.h
            in

            Parameters  style - New marker style value.

            Remarks     MGL_setMarkerStyle() sets the current marker
                        style value. The marker style defines the
                        type of marker to be rendered. Currently the
                        MGL defines the following markers:

                        MARKER_SQUARE - A solid square
                        MARKER_CIRCLE - A solid circle
                        MARKER_X      - A cross made of two lines

            See also    MGL_getMarkerStyle(), MGL_marker(),
                        MGL_polyMarker()


            MGL_setPalette

            Function    Sets the currently active palette values.

            Syntax      void MGL_setPalette(palette *pal,int
                        numColors,int startIndex);

            Prototype   mgraph.h
            in

            Parameters  pal - Pointer to array of palette values to
                        program
                        numColors - Number of colors to program from
                        the array
                        startIndex - Starting index to program from
                        in the array















            Chapter 6 - Console Library                               99






            Remarks     MGL_setPalette() sets part or all of the
                        currently active palette given the values
                        passed in the array    . You can specify only
                                            pal
                        a subset of the palette values to be modified
                        with the startIndex and numColors arguments.

                        Thus to set the entire palette in a 256 color
                        video mode, you would use:

                            MGL_setPalette(pal,255,0);

                        or to set the top half of the palette you
                        would use:

                            MGL_setPalette(pal,128,128);

                        Note that the MGL will ensure that the
                        palette is programmed without snow depending
                        on the value of the current snow level
                        defined by calling the
                        MGL_setPaletteSnowLevel() routine, and will
                        wait for the start of a vertical retrace
                        before the first entry is programmed.

            See also    MGL_getPalette(), MGL_setPaletteEntry(),
                        MGL_setPaletteSnowLevel(),
                        MGL_getPaletteSnowLevel()



            MGL_setPaletteEntry

            Function

            Syntax      void MGL_setPaletteEntry(int entry,uchar
                        red,uchar green,uchar blue);

            Prototype   mgraph.h
            in

            Parameters  entry - Palette index to program
                        red - Red component for palette entry
                        green - Green component for palette entry
                        blue - Blue component for palette entry

            Remarks     MGL_setPaletteEntry() sets the color values
                        of a single palette entry. If you wish to set
                        more than a single palette index you should
                        use the MGL_setPalette() routine which is
                        faster for multiple entries. The main reason
                        for this is that this routine will wait for a
                        vertical retrace before the palette entry is
                        programmed to ensure that snow does not
                        occur.

            See also    MGL_getPaletteEntry(), MGL_setPalette(),
                        MGL_getPalette()



            100                     MegaGraph Graphics Library Reference






            MGL_setPaletteSnowLevel

            Function    Sets the current palette snow level

            Syntax      void MGL_setPaletteSnowLevel(int level);

            Prototype   mgraph.h
            in

            Parameters  level - New snow level

            Remarks     MGL_setPaletteSnowLevel() sets the number of
                        palette entries that can be programmed during
                        a single vertical retrace before the onset of
                        snow. The MGL uses a reasonable default of
                        100 entries per retrace, but you may want to
                        modify this on faster or slower machines
                        (this should be a user option). In the future
                        the MGL will automatically determine the
                        optimum value for this at initialisation
                        time.

            See also    MGL_getPaletteSnowLevel(), MGL_setPalette()


            MGL_setPenBitmapPattern

            Function    Sets the currently active bitmap pattern.

            Syntax      void MGL_setPenBitmapPattern(pattern *pat);

            Prototype   mgraph.h
            in

            Parameters  pat - New bitmap pattern to use.

            Remarks     MGL_setPenBitmapPattern() sets the currently
                        active bitmap pattern used when rendering
                        patterned primitive in the
                        BITMAP_PATTERN_TRANSPARENT and
                        BITMAP_PATTERN_OPQAUE pen styles. A bitmap
                        pattern is defined as an 8 x 8 pixel bitmap
                        pattern stored as an array of 8 bytes. The
                        pattern value is copied from the passed
                        structure.

                        When filling in the
                        BITMAP_PATTERN_TRANSPARENT mode, the
                        foreground color is used to fill in all
                        pixels in the bitmap pattern that are a 1.
                        Where the pixels in the bitmap pattern are a
                        0, the original background color is retained.
                        In the BITMAP_PATTERN_OPAQUE mode, the
                        background color is used to fill in the
                        pixels in the bitmap that are set to a 0.

            See also    MGL_getPenBitmapPattern(), MGL_setPenStyle(),
                        MGL_getPenStyle()


            Chapter 6 - Console Library                              101








            MGL_setPenSize

            Function    Sets the current pen size

            Syntax      void MGL_setPenSize(int height,int width);

            Prototype   mgraph.h
            in

            Parameters  height - Height of the pen in pixels
                        width - Width of the pen in pixels

            Remarks     MGL_setPenSize() sets the size of the current
                        pen in pixels. The default pen is 1 pixel by
                        1 pixel in dimensions, however you can change
                        this to whatever value you like. When
                        primitive are rendered with a pen other than
                        the default, the pixels in the pen always lie
                        to the right and below the current pen
                        position.

            See also    MGL_getPenSize()


            MGL_setPenStyle

            Function    Sets the current pen style

            Syntax      void MGL_setPenStyle(int style);

            Prototype   mgraph.h
            in

            Parameters  style - New pen style to use.

            Remarks     MGL_getPenStyle() returns the currently
                        active pen style. The MGL supports the
                        following pen styles:

                        SOLID_PATTERN              - Fill with solid
                        color
                        BITMAP_PATTERN_OPAQUE      - Pattern fill
                        BITMAP_PATTERN_TRANSPARENT - Transparent
                        pattern fill

                        When filling in the
                        BITMAP_PATTERN_TRANSPARENT mode, the
                        foreground color is used to fill in all
                        pixels in the bitmap pattern that are a 1.
                        Where the pixels in the bitmap pattern are a
                        0, the original background color is retained.
                        In the BITMAP_PATTERN_OPAQUE mode, the
                        background color is used to fill in the
                        pixels in the bitmap that are set to a 0.

            See also    MGL_getPenStyle(), MGL_setPenBitmapPattern()


            102                     MegaGraph Graphics Library Reference








            MGL_setPolygonType

            Function    Sets the current polygon type

            Syntax      void MGL_setPolygonType(int type);

            Prototype   mgraph.h
            in

            Parameters  type - New polygon type

            Remarks     MGL_setPolygonType() sets the current polygon
                        type. You can change this value to force the
                        MGL to work with a specific polygon type (and
                        to avoid the default automatic polygon type
                        checking). The MGL supports the following
                        polygon types:

                        AUTO_POLYGON    - MGL automatically
                        determines type
                        CONVEX_POLYGON  - All polygons rendered as
                        convex
                        COMPLEX_POLYGON - All polygons rendered as
                        complex

                        If you expect to be drawing lots of complex
                        or convex polygons, setting the polygon type
                        can result in faster polygon rendering.

            See also    MGL_getPolygonType(), MGL_fillPolygon()


            MGL_setRelViewport

            Function    Sets a viewport relative to the current one

            Syntax      void MGL_setRelViewport(rect view);

            Prototype   mgraph.h
            in

            Parameters  view - Bounding rectangle for the new
                        viewport.

            Remarks     MGL_setRelViewport() sets the current
                        viewport to the viewport specified by view,
                        where view is relative to the currently
                        active viewport. The new viewport is
                        restricted to fall within the bounds of the
                        currently active viewport.

                        All output in the MGL is relative to the
                        current viewport, so by changing the viewport
                        to a new value you can make all output appear
                        in a different rectangular portion of the
                        video display.


            Chapter 6 - Console Library                              103







            See also    MGL_getViewport(), MGL_setViewport(),
                        MGL_clearViewport(), MGL_setClipRect()


            MGL_setResult

            Function    Sets the internal MGL result flag.

            Syntax      void MGL_setResult(int result)

            Prototype   mgraph.h
            in

            Parameters  result - New internal result flag

            Remarks     MGL_setResult() sets the internal MGL result
                        flag to the specified value. This routine is
                        primarily for extension libraries, but you
                        can use it to add your own extension
                        functions to the MGL that will return result
                        codes in the same manner as the MGL.

            See also    MGL_getResult()


            MGL_setSpaceExtra

            Function    Sets the current space extra value.

            Syntax      void MGL_setSpaceExtra(int extra);

            Prototype   mgraph.h
            in

            Parameters  extra - New space extra value.

            Remarks     MGL_setSpaceExtra() sets the current space
                        extra value used when drawing text in the
                        current font. The space extra vaue is
                        normally zero, but can be a positive or
                        negative value. This value can be used to
                        insert extra space between the characters in
                        a font (making this value a large negative
                        value will make the characters run on top of
                        each other).

            See also    MGL_getSpaceExtra(), MGL_drawStr()












            104                     MegaGraph Graphics Library Reference






            MGL_setTextDirection

            Function    Sets the current text direction

            Syntax      void MGL_setTextDirection(int direction);

            Prototype   mgraph.h
            in

            Parameters  direction - New text direction value

            Remarks     MGL_setTextDirection() sets the current text
                        direction. The MGL supports the following
                        text directions:

                        LEFT_DIR  - Text runs to the left (right to
                        left)
                        UP_DIR    - Text runs in the up direction
                        RIGHT_DIR - Text runs to the right (left to
                        right)
                        DOWN_DIR  - Text runs in the down direction

                        Currently the MGL only supports directional
                        text with the default 8x8 bitmap font and
                        vector fonts. Bitmap fonts can only be drawn
                        in the RIGHT_DIR direction.

            See also    MGL_getTextDirection(), MGL_drawStr()


            MGL_setTextJustify

            Function    Sets the current text horizontal and vertical
                        justification

            Syntax      void MGL_setTextJustify(int horiz,int vert);

            Prototype   mgraph.h
            in

            Parameters  horiz - New horiztonal text justification
                        value
                        vert - New vertical text justification value

















            Chapter 6 - Console Library                              105






            Remarks     MGL_setTextJustify() sets the current text
                        justification values. The MGL supports the
                        following horizontal justification types:

                        LEFT_TEXT     - Text is left justified
                        CENTER_TEXT   - Text is centered left to
                        right
                        RIGHT_TEXT    - Text is right justified

                        and the following vertical justification
                        types:

                        TOP_TEXT      - Text is top justified
                        CENTER_TEXT   - Text is centered top to
                        bottom
                        BASELINE_TEXT - Text is justified to the
                        baseline
                        BOTTOM_TEXT   - Text is bottom justified

            See also    MGL_getTextJustify()


            MGL_setTextSettings

            Function    Restores the current text settings.

            Syntax      void MGL_setTextSettings(text_settings
                        *settings);

            Prototype   mgraph.h
            in

            Parameters  settings - Text settings to restore



























            106                     MegaGraph Graphics Library Reference






            Remarks     MGL_setTextSettings() restores a set of
                        previously saved text settings. This routine
                        is provides a way to save and restore all the
                        values relating to the rendering of text in
                        the MGL with a single function call. The text
                        settings values are stored in the following
                        structure:

                        typedef struct {
                            int             horiz_just;
                            int             vert_just;
                            int             dir;
                            int             sz_numerx;
                            int             sz_numery;
                            int             sz_denomx;
                            int             sz_denomy;
                            int             space_extra;
                            font            *fnt;

                        where horiz_just     vert_just
                                         and           define the
                        horizontal and vertical justification values,
                            defines the current text direction,
                        dir
                        space_extra defines the current space extra
                        value and     define the currently active
                                  fnt
                        font (stored in system memory). The
                        sz_numerx, sz_numery, sz_demonx and sz_denomy
                        specify the current text scaling factors.

            See also    MGL_getTextSettings()


            MGL_setTextSize

            Function    Sets the current text scaling factors

            Syntax      void MGL_setTextSize(int numerx,int
                        denomx,int numery,int denomy);

            Prototype   mgraph.h
            in

            Parameters  numerx - X scaling numerator value
                        denomx - X scaling denominator value
                        numery - Y scaling numerator value
                        denomy - Y scaling denominator value

            Remarks     MGL_setTextSize() sets the current text
                        scaling factors used by the MGL. The text
                        size values define an integer scaling factor
                        to be used, where the actual values will be
                        computed using the following formula:

                                  scaled
                                       unscaled
                                             numer
                                          denom

                        Note: Currently the MGL can only scale
                        vectors fonts.



            Chapter 6 - Console Library                              107






            See also    MGL_getTextSize()


            MGL_setViewport

            Function    Sets the currently active viewport

            Syntax      void MGL_setViewport(rect view);

            Prototype   mgraph.h
            in

            Parameters  view - New global viewport bounding rectangle

            Remarks     MGL_setViewport() sets the dimensions of the
                        currently active viewport. These dimensions
                        are global to the entire display area used by
                        the currently active video device driver.

                        All output in the MGL is relative to the
                        current viewport, so by changing the viewport
                        to a new value you can make all output appear
                        in a different rectangular portion of the
                        video display.

            See also    MGL_getViewport(), MGL_setRelViewport(),
                        MGL_clearViewport(), MGL_setClipRect()


            MGL_setVisualPage

            Function    Sets the currently visible hardware video
                        page.

            Syntax      int MGL_setVisualPage(int page);

            Prototype   mgraph.h
            in

            Parameters  page - New visible hardware page number

            Remarks     MGL_setVisualPage() sets the currently
                        visible hardware video page number. The first
                        hardware video page is number 0, the second
                        is 1 and so on. The number of available
                        hardware video pages depends on the type of
                        underlying hardware, the video mode
                        resolution and amount of video memory
                        installed. Thus not all video modes support
                        multiple hardware video pages.

            See also    MGL_getVisualPage(), MGL_getActivePage(),
                        MGL_setActivePage().







            108                     MegaGraph Graphics Library Reference






            MGL_setWriteMode

            Function    Sets the current write mode operation

            Syntax      int MGL_setWriteMode(int mode);

            Prototype   mgraph.h
            in

            Parameters  mode - New write mode operation to use

            Remarks     MGL_setWriteMode() sets the currently active
                        write mode. The MGL supports the following
                        write mode operations for all output
                        primitives:

                        REPLACE_MODE - Replace the original pixels
                        AND_MODE     - Logical AND with original
                        pixels
                        OR_MODE      - Logical OR with original
                        pixels
                        XOR_MODE     - Logical XOR with original
                        pixels

            See also    MGL_getWriteMode()


            MGL_singleBuffer

            Function    Returns the system back to single buffered
                        mode.

            Syntax      void MGL_singleBuffer(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_singleBuffer   puts the system back into
                                        ()
                        single buffer mode. The active display page
                        is made to be the same as the current visual
                        display page for hardware double buffering.
                        This may or may not be the first hardware
                        video page.

            See also    MGL_doubleBuffer(), MGL_swapBuffers()


            MGL_sizex

            Function    Returns the total device x coordinate
                        dimensions

            Syntax      int MGL_sizex(void);

            Prototype   mgraph.h
            in




            Chapter 6 - Console Library                              109






            Remarks     MGL_sixex() returns the total number of
                        pixels available along the X coordinate axis
                        for the currently active output device. This
                        is different to the MGL_maxx() routine which
                        returns the dimensions of the currently
                        active viewport.

            Return      Number of pixels in X direction for entire
            value       device - 1

            See also    MGL_sizey(), MGL_maxx(), MGL_maxy()


            MGL_sizey

            Function    Returns the total device y coordinate
                        dimensions

            Syntax      int MGL_sizey(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_sixey() returns the total number of
                        pixels available along the Y coordinate axis
                        for the currently active output device. This
                        is different to the MGL_maxy() routine which
                        returns the dimensions of the currently
                        active viewport.

            Return      Number of pixels in Y direction for entire
            value       device - 1

            See also    MGL_sizex(), MGL_maxx(), MGL_maxy()


            MGL_swapBuffers

            Function    Swaps the currently active front and back
                        buffers

            Syntax      void MGL_swapBuffers(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_swapBuffers() swaps the currently active
                        front and back buffers. This routine should
                        only be called after the MGL_doubleBuffer()
                        routine has been called to initialise the
                        double buffering. Once double buffering has
                        been set up, all output from the MGL will go
                        to the current offscreen buffer, and the
                        output can be made visible with the
                        MGL_swapBuffers() routine. This routine is
                        normally used to achieve smooth animation for
                        complex scenes.



            110                     MegaGraph Graphics Library Reference






            See also    MGL_doubleBuffer(), MGL_singleBuffer()


            MGL_textHeight

            Function    Returns the height of the current font in
                        pixels

            Syntax      int MGL_textHeight(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_textHeight() returns the height of the
                        currently active font in pixels. This
                        includes any scaling transformations that are
                        applied to the font and will be as accurate
                        as possible at the resolution of the display
                        device.

            Return      Height of the current font in pixels
            value

            See also    MGL_textWidth(), MGL_drawStr(),
                        MGL_getCharMetrics(), MGL_getFontMetrics()


            MGL_textWidth

            Function    Returns the width of the charcter string in
                        pixels

            Syntax      int MGL_textWidth(const char *str);

            Prototype   mgraph.h
            in

            Parameters  str - Character string to measure

            Remarks     MGL_textWidth() returns the width of the
                        specified character string using the
                        dimensions of the currently active font in
                        pixels. This includes any scaling
                        transformations that are applied to the font
                        and will be as accurate as possible at the
                        resolution of the display device.

            Return      Width of the character string in pixels
            value

            See also    MGL_textHeight(), MGL_drawStr(),
                        MGL_getCharMetrics(), MGL_getFontMetrics()








            Chapter 6 - Console Library                              111






            MGL_underScoreLocation

            Function    Returns the location to begin drawing an
                        underscore for the font.

            Syntax      void MGL_underScoreLocation(int *x, int *y,
                        const char *str)

            Prototype   mgraph.h
            in

            Parameters  x - X coordinate to be passed to
                        MGL_drawStrXY()
                        y - Y coordinate to be passed to
                        MGL_drawStrXY()
                        str - String to measure

            Remarks     MGL_underScoreLocation() takes an (x,y)
                        location that would normally be be used to
                        draw a string with MGL_drawStrXY(), and
                        adjusts the coordinates to begin at the under
                        score location for the current font, in the
                        current drawing attributes. Thus the entire
                        character string can be underlined by drawing
                        a line starting at the computed underscore
                        location and extending for MGL_textWidth()
                        pixels in length.

            See also    MGL_drawStrXY(), MGL_textWidth()


            MGL_unloadFont

            Function    Unloads the specified font from memory.

            Syntax      void MGL_unloadFont(font *font);

            Prototype   mgraph.h
            in

            Parameters  font - Pointer to loaded font file to unload.

            Remarks     MGL_unloadFont() attempts to unload the
                        specified font if the font is a valid font
                        that was loaded with the MGL_loadFont()
                        routine. The memory occupied by the font will
                        be released to the global heap.

            Return      True if font was unloaded, false if font was
            value       invalid.

            See also    MGL_loadFont()








            112                     MegaGraph Graphics Library Reference






            MGL_unpackColor

            Function    Unpacks a packed 24 bit color value into RGB
                        components.

            Syntax      void MGL_unpackColor(color_t color,uchar
                        *R,uchar *G,uchar *B);

            Prototype   mgraph.h
            in

            Parameters  color - Color value to unpack.
                        R - Place to store the red component
                        G - Place to store the green component
                        B - Place to store the blue component

            Remarks     MGL_unpackColor() takes a packed color value
                        in the correct format for the current color
                        mode, and extracts the red, green and blue
                        components. Note that the color values may
                        not be the same as when you packed them with
                        MGL_packColor() if the color mode is a 15 or
                        16 bit mode because of loss of precision. The
                        values are scaled back into the normal 24 bit
                        RGB space.

            See also    MGL_packColor(), MGL_getPixelFormat()


            MGL_packColor

            Function    Packs an RGB triple into the correct format
                        for current mode.

            Syntax      color_t MGL_packColor(uchar R, uchar G, uchar
                        B)

            Prototype   mgraph.h
            in

            Parameters  R - Red component of color
                        G - Green component of color
                        B - Blue component of color

            Remarks     MGL_packColor() takes a 24 bit RGB triple and
                        converts it to the correct pack pixel format
                        required by the current video mode. This
                        packed pixel color value can then be passed
                        to routines that require an MGL color_t color
                        value such as MGL_setColor() etc.

            Return      MGL pack pixel color value representing the
            value       specified color.

            See also    MGL_unpackColor(), MGL_getPixelFormat(),
                        MGL_setColor()




            Chapter 6 - Console Library                              113






            MGL_useFont

            Function    Sets the currently active font.

            Syntax      bool MGL_useFont(font *font)

            Prototype   mgraph.h
            in

            Parameters  font - New font to use.

            Remarks     MGL_useFont() selects the specified font as
                        the currently active font for use by the MGL.
                        If the font data is invalid, the MGL result
                        flag is set and the routine will return
                        false.

                        Note: Do not unload a font file if it is
                        currently in use by the MGL!

            Return      True if the font was valid and selected,
            value       false if not.

            See also    MGL_drawStr()


            MGL_vecFontEngine

            Function    Generates the commands to draw vector font.

            Syntax      bool MGL_vecFontEngine(int x, int y, const
                        char *str, void (*move)(int x,int y), void
                        (*draw)(int x,int y));

            Prototype   mgraph.h
            in

            Parameters  x,y - Coordinate to start drawing text at
                        str - Character string to draw
                        move - Routine to call to perform a move
                        operation
                        draw - Routine to call to perform a draw
                        operation

















            114                     MegaGraph Graphics Library Reference






            Remarks     MGL_vecFontEngine() calls a set of user
                        supplied routines to render the characters in
                        a vector font. This allows the vector fonts
                        to be drawn in 2D or 3D floating point
                        coordinate systems by transforming each of
                        the operations needed to draw each character,
                        or in any coordinate system that the users
                        desires.

                            move
                        The      routine is called to move the cursor
                        to a new location, and the      routine is
                                                   draw
                        used to perform a draw operation from the
                        current location to the specified location.
                        Each character in the vector font is started
                        with a move operation.

                        Note that the coordinates passed to the move
                        and draw routines will be offset from the
                        point (x,y), where the point (x,y) is the
                        origin of the first character (ie: it lies on
                        its baseline). Note also that the coordinates
                        will be relative to the origin with the
                        origin at the lower left corner of each
                        character (ie: inverse of normal device
                        coordinate yaxis values).

                        This routine does not honor the standard
                        scaling factors, but simply draws the
                        characters at character size of (1,1,1,1)
                        (because scaling will be done by the user
                        supplied move and draw routines).

                        If the passed font is NOT a valid vector
                        font, this routine returns false.

            Return      True if string correctly rendered, false if
            value       font is not a vector font.

            See also    MGL_drawStr(), MGL_useFont()


            MGL_vSync

            Function    Waits for a vertical refresh signal.

            Syntax      void MGL_vSync(void);

            Prototype   mgraph.h
            in

            Remarks     MGL_vSync() waits for a vertical refresh
                        signal from the video display before
                        returning. This can be used to sync your
                        graphics output to the vertical sync pulse to
                        produce flicker free animation or to produce
                        animation that runs at a constant speed.




            Chapter 6 - Console Library                              115






            MS_obscure

            Function    Hides the mouse cursor from view during
                        graphics output.

            Syntax      void MS_obscure(void);

            Prototype   mgraph.h
            in

            Remarks     MS_obscure   hides the mouse cursor from view
                                  ()
                        in order to perform graphics output using the
                        MGL. If the graphics device driver supports a
                        hardware cursor, this is handled by the
                        hardware, otherwise it is removed from the
                        display. You should call this routine rather
                        than MS_hide() in order to temporarily hide
                        the cursor during graphics output as the
                        MS_hide() routine can produce incorrect
                        results if call in quick succession for
                        systems that support a hardware mouse cursor.

            See also    MS_unobscure()


            MS_unobscure

            Function    Restores the mouse cursor to view after
                        graphics output.

            Syntax      void MS_unobscure(void);

            Prototype   mgraph.h
            in

            Remarks     MS_unobscure() redisplays the cursor again
                        after screen output has finished.

            See also    MS_obscure()





















            116                     MegaGraph Graphics Library Reference









                                                C  O  N  T  E  N  T  S



            Chapter 1 - Introduction
            Chapter 1 - Introduction
            Chapter 1 - Introduction ................................
                                     ................................
                                     ................................1
                                                                     1
                                                                     1

            Chapter 2 - Library reference
            Chapter 2 - Library reference
            Chapter 2 - Library reference ...........................
                                          ...........................
                                          ...........................3
                                                                     3
                                                                     3
                 How to use reference entries .......................4
                 MGL_availableFont ..................................5
                 MGL_availableModes .................................5
                 MGL_availablePages .................................6
                 MGL_beginDrawing ...................................6
                 MGL_beginGouraud ...................................7
                 MGL_beginPixel .....................................8
                 MGL_charWidth ......................................8
                 MGL_clearDevice ....................................8
                 MGL_clearViewport ..................................9
                 MGL_clipLine .......................................9
                 MGL_copyImage .....................................10
                 MGL_copyImageCoord ................................10
                 MGL_defaultAttributes .............................11
                 MGL_defaultColor ..................................11
                 MGL_detectGraph ...................................12
                 MGL_disjointRect ..................................13
                 MGL_divotSize .....................................13
                 MGL_divotSizeCoord ................................14
                 MGL_doubleBuffer ..................................14
                 MGL_drawBorder ....................................15
                 MGL_drawBorderCoord ...............................16
                 MGL_drawHDivider ..................................17
                 MGL_drawStr .......................................17
                 MGL_drawStrXY .....................................18
                 MGL_drawVDivider ..................................18
                 MGL_driverName ....................................19
                 MGL_ellipse .......................................19
                 MGL_ellipseArc ....................................20
                 MGL_ellipseArcCoord ...............................21
                 MGL_ellipseCoord ..................................22
                 MGL_ellipseEngine .................................22
                 MGL_emptyRect .....................................23
                 MGL_endDrawing ....................................24
                 MGL_endGouraud ....................................24
                 MGL_endPixel ......................................25
                 MGL_equalPoint ....................................25
                 MGL_equalRect .....................................25
                 MGL_errorMsg ......................................26
                 MGL_exit ..........................................26
                 MGL_fadePalette ...................................27
                 MGL_fillEllipse ...................................28
                 MGL_fillEllipseArc ................................28
                 MGL_fillEllipseArcCoord ...........................29
                 MGL_fillEllipseCoord ..............................30
                 MGL_fillGouraudPolygon ............................31
                 MGL_fillPolygon ...................................32
                 MGL_fillPolygonFast ...............................33


            Contents                                                   i






                 MGL_fillRect ......................................34
                 MGL_fillRectCoord .................................34
                 MGL_fillRectPt ....................................35
                 MGL_getActivePage .................................35
                 MGL_getArcCoords ..................................36
                 MGL_getAspectRatio ................................36
                 MGL_getAttributes .................................37
                 MGL_getBackColor ..................................38
                 MGL_getBorderColors ...............................39
                 MGL_getCharMetrics ................................39
                 MGL_getClipMode ...................................40
                 MGL_getClipRect ...................................41
                 MGL_getColor ......................................41
                 MGL_getCP .........................................41
                 MGL_getCursorColor ................................42
                 MGL_getDefaultPalette .............................42
                 MGL_getDivot ......................................43
                 MGL_getDivotCoord .................................44
                 MGL_getDriver .....................................44
                 MGL_getFont .......................................45
                 MGL_getFontMetrics ................................45
                 MGL_getImage ......................................46
                 MGL_getImageCoord .................................47
                 MGL_getMarkerColor ................................48
                 MGL_getMarkerSize .................................48
                 MGL_getMarkerStyle ................................48
                 MGL_getMode .......................................49
                 MGL_getPalette ....................................49
                 MGL_getPaletteEntry ...............................50
                 MGL_getPaletteSize ................................51
                 MGL_getPaletteSnowLevel ...........................51
                 MGL_getPenBitmapPattern ...........................51
                 MGL_getPenSize ....................................52
                 MGL_getPenStyle ...................................52
                 MGL_getPixel ......................................53
                 MGL_getPixelCoord .................................54
                 MGL_getPixelFormat ................................54
                 MGL_getPolygonType ................................56
                 MGL_getSpaceExtra .................................56
                 MGL_getTextDirection ..............................57
                 MGL_getTextJustify ................................57
                 MGL_getTextSettings ...............................58
                 MGL_getTextSize ...................................59
                 MGL_getViewport ...................................60
                 MGL_getVisualPage .................................60
                 MGL_getWriteMode ..................................61
                 MGL_getX ..........................................61
                 MGL_getY ..........................................62
                 MGL_globalToLocal .................................62
                 MGL_gouraudScanLine ...............................63
                 MGL_imageSize .....................................63
                 MGL_imageSizeCoord ................................64
                 MGL_init ..........................................65
                 MGL_insetRect .....................................66
                 MGL_line ..........................................66
                 MGL_lineCoord .....................................67
                 MGL_lineCoordFast .................................67
                 MGL_lineEngine ....................................68


            ii                                                  Contents






                 MGL_lineFast ......................................68
                 MGL_lineRel .......................................69
                 MGL_lineRelCoord ..................................69
                 MGL_lineTo ........................................70
                 MGL_lineToCoord ...................................70
                 MGL_loadFont ......................................71
                 MGL_localToGlobal .................................71
                 MGL_marker ........................................72
                 MGL_maxCharWidth ..................................72
                 MGL_maxColor ......................................72
                 MGL_maxPage .......................................73
                 MGL_maxx ..........................................73
                 MGL_maxy ..........................................74
                 MGL_modeName ......................................74
                 MGL_moveRel .......................................74
                 MGL_moveRelCoord ..................................75
                 MGL_moveTo ........................................75
                 MGL_moveToCoord ...................................76
                 MGL_offsetRect ....................................76
                 MGL_packColor .....................................76
                 MGL_pixel .........................................77
                 MGL_pixelCoord ....................................77
                 MGL_polyLine ......................................78
                 MGL_polyMarker ....................................78
                 MGL_polyPoint .....................................79
                 MGL_popViewport ...................................79
                 MGL_ptInRect ......................................79
                 MGL_ptInRectCoord .................................80
                 MGL_pushViewport ..................................80
                 MGL_putDivot ......................................80
                 MGL_putIcon .......................................81
                 MGL_putImage ......................................81
                 MGL_putImageCoord .................................82
                 MGL_putMonoImage ..................................83
                 MGL_realColor .....................................83
                 MGL_rect ..........................................84
                 MGL_rectCoord .....................................84
                 MGL_rectPt ........................................85
                 MGL_registerDriver ................................85
                 MGL_restoreAttributes .............................86
                 MGL_restoreCRTMode ................................86
                 MGL_result ........................................86
                 MGL_rotatePalette .................................87
                 MGL_scanLeftForColor ..............................88
                 MGL_scanLeftWhileColor ............................89
                 MGL_scanLine ......................................90
                 MGL_scanRightForColor .............................91
                 MGL_scanRightWhileColor ...........................91
                 MGL_setActivePage .................................92
                 MGL_setAspectRatio ................................93
                 MGL_setBackColor ..................................93
                 MGL_setBorderColors ...............................94
                 MGL_setBufSize ....................................95
                 MGL_setClipMode ...................................95
                 MGL_setClipRect ...................................96
                 MGL_setColor ......................................96
                 MGL_setCursorColor ................................97
                 MGL_setDefaultPalette .............................97


            Contents                                                 iii






                 MGL_setGraphMode ..................................97
                 MGL_setMarkerColor ................................98
                 MGL_setMarkerSize .................................98
                 MGL_setMarkerStyle ................................99
                 MGL_setPalette ....................................99
                 MGL_setPaletteEntry ..............................100
                 MGL_setPaletteSnowLevel ..........................101
                 MGL_setPenBitmapPattern ..........................101
                 MGL_setPenSize ...................................102
                 MGL_setPenStyle ..................................102
                 MGL_setPolygonType ...............................103
                 MGL_setRelViewport ...............................103
                 MGL_setResult ....................................104
                 MGL_setSpaceExtra ................................104
                 MGL_setTextDirection .............................105
                 MGL_setTextJustify ...............................105
                 MGL_setTextSettings ..............................106
                 MGL_setTextSize ..................................107
                 MGL_setViewport ..................................108
                 MGL_setVisualPage ................................108
                 MGL_setWriteMode .................................109
                 MGL_singleBuffer .................................109
                 MGL_sizex ........................................109
                 MGL_sizey ........................................110
                 MGL_swapBuffers ..................................110
                 MGL_textHeight ...................................111
                 MGL_textWidth ....................................111
                 MGL_underScoreLocation ...........................112
                 MGL_unloadFont ...................................112
                 MGL_unpackColor ..................................113
                 MGL_packColor ....................................113
                 MGL_useFont ......................................114
                 MGL_vecFontEngine ................................114
                 MGL_vSync ........................................115
                 MS_obscure .......................................116
                 MS_unobscure .....................................116
























            iv                                                  Contents




























                            MegaGraph Graphics Library
                             Library Reference Manual




                       Copyright (C) 1993 SciTech Software.
                               All Rights Reserved.


                                   Version 1.0
                                December 30, 1993
