home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / grafik / mgl11 / doc / mgraph.txt
Encoding:
Text File  |  1993-12-30  |  259.8 KB  |  7,963 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                                                          C H A P T E R
  11.                                                                      1
  12.  
  13.                                                           Introduction
  14.  
  15.             The MegaGraph Graphics Library (MGL) is a full featured
  16.             graphics library for displaying high performance graphics
  17.             on personal computers. It provides fast, low level 2D
  18.             drawing primitives that can be used to implement video
  19.             games, user interface software and even real-time 3D
  20.             animation. It will work in any video mode that has 16 or
  21.             more colors, including the new HiColor and TrueColor
  22.             modes available on PC's.
  23.  
  24.             The MGL is aimed at the experienced programmer, so no
  25.             tutorial documentation or information on generally using
  26.             libraries to write and successfully compile programs is
  27.             given. For more information you will need to consult the
  28.             documentation that came with your compiler.
  29.  
  30.             This document does not provide any information on
  31.             graphics programming concepts, or general programming
  32.             information about the MGL. Consult the MGL Programmers
  33.             Guide for this information.
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.             Chapter 1 - Introduction                                   1
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.             2                       MegaGraph Graphics Library Reference
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.                                                          C H A P T E R
  143.                                                                      2
  144.  
  145.                                            About the Library Reference
  146.  
  147.             The following chapters provide a detailed reference to
  148.             the routines in the MGL. All of the routines in the MGL
  149.             are grouped in alphabetical order within this chapter.
  150.             There is an individual entry for every function in the
  151.             library. If you wanted to know what the MGL_lineCoord()
  152.             function does, you would look it up in the library
  153.             reference where you would find an entry that:
  154.  
  155.                  Summarises what MGL_lineCoord does
  156.  
  157.                  Gives the syntax for calling the MGL_lineCoord
  158.                  routine
  159.  
  160.                  Tells you which header file(s) contain the prototype
  161.                  for MGL_lineCoord
  162.  
  163.                  Gives a detailed description of how MGL_lineCoord
  164.                  is implemented and how it relates to other line
  165.                  drawing routines.
  166.  
  167.                  Makes a reference to other related library routines
  168.  
  169.             The following sample library entry explains how to find
  170.             out such details about the routines in the MGL.
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.             Chapter 6 - Console Library                                3
  200.  
  201.  
  202.  
  203.  
  204.  
  205.             How to use reference entries
  206.  
  207.             Function    Summary of what the function does
  208.  
  209.             Syntax      function(modifier parameter[, ... ]);
  210.  
  211.                         This gives you the declaration syntax for the
  212.                         function. The [, ... ] indicates that other
  213.                         parameters and modifiers may follow.
  214.  
  215.             Prototype   header.h
  216.             in
  217.                         This lists the header file(s) containing the
  218.                         prototype for the function. The prototype of
  219.                         a function may be contained in more than one
  220.                         header file, in which case all the files
  221.                         would be listed, so use whichever one is more
  222.                         appropriate.
  223.  
  224.             Parameters  Briefly describes each of the function
  225.                         parameters.
  226.  
  227.             Remarks     This section describes what the function
  228.                         does, the parameters it takes and any details
  229.                         that you might need to know in order to get
  230.                         full use out of the function.
  231.  
  232.             Return      This section describes the value returned by
  233.             value       the function (if any).
  234.  
  235.             See also    This sections gives a list of other related
  236.                         functions in the library that may be of
  237.                         interest.
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.             4                       MegaGraph Graphics Library Reference
  266.  
  267.  
  268.  
  269.  
  270.  
  271.             MGL_availableFont
  272.  
  273.             Function    Determines if a specific font file is
  274.                         available for use.
  275.  
  276.             Syntax      bool MGL_availableFont(const char *fontname);
  277.  
  278.             Prototype   mgraph.h
  279.             in
  280.  
  281.             Parameters  fontname - Relative filename of the required
  282.                         font file
  283.  
  284.             Remarks     MGL_availableFont() is used to determine if a
  285.                         particular font file exists and is available
  286.                         for use. It will check first in the directory
  287.                         where the MGL driver files were located, and
  288.                         then in the current directory. If the font
  289.                         file is found it will return true, otherwise
  290.                         it will return false.
  291.  
  292.             Return      True if font file is available, false if not.
  293.             value
  294.  
  295.             See also    MGL_loadFont()
  296.  
  297.  
  298.             MGL_availableModes
  299.  
  300.             Function    Returns a list of all available video modes.
  301.  
  302.             Syntax      int * MGL_availableModes(int driver);
  303.  
  304.             Prototype   mgraph.h
  305.             in
  306.  
  307.             Parameters  driver - Detected video device driver ID.
  308.  
  309.             Remarks     MGL_availableModes() will return a list of
  310.                         all the currently available video modes given
  311.                         a specific video device driver ID. The value
  312.                         for the video device driver ID should be
  313.                         obtained via the MGL_detectGraph or MGL_init
  314.                         routines prior to calling this function.
  315.  
  316.                         You may call this routine before MGL_init()
  317.                         is called to determine what video modes are
  318.                         available before actually initialising a
  319.                         particular video mode. You must ensure
  320.                         however that the MGL_detectGraph() routine is
  321.                         called before you call the
  322.                         MGL_availableModes() routine.
  323.  
  324.                         The list of available video modes is returned
  325.                         as a table of integer values. The table is
  326.                         terminate with a -1.
  327.  
  328.  
  329.  
  330.  
  331.             Chapter 6 - Console Library                                5
  332.  
  333.  
  334.  
  335.  
  336.  
  337.             Return      Pointer to list of available video modes
  338.             value
  339.  
  340.             See also    MGL_detectGraph(), MGL_init(),
  341.                         MGL_availablePages()
  342.  
  343.  
  344.             MGL_availablePages
  345.  
  346.             Function    Determine the number of available video pages
  347.                         for a specific video mode.
  348.  
  349.             Syntax      int MGL_availablePages(int driver,int mode);
  350.  
  351.             Prototype   mgraph.h
  352.             in
  353.  
  354.             Parameters  driver - Detected video device driver ID.
  355.                         mode - MGL mode number to query.
  356.  
  357.             Remarks     MGL_availablePages() will return the number
  358.                         of pages of pysical video memory available
  359.                         for a specific MGL video mode and video
  360.                         device driver. The value for the video device
  361.                         driver ID should be obtained via the
  362.                         MGL_detectGraph() or MGL_init() routines
  363.                         prior to calling this function.
  364.  
  365.                         You may call this routine before the MGL_init
  366.                         routine is used to intialise a particular
  367.                         video modes. Thus you can filter out support
  368.                         for modes that do not have the require number
  369.                         of hardware video pages available for use.
  370.  
  371.             Return      Number of available video pages for mode, -1
  372.             value       on error.
  373.  
  374.             See also    MGL_detectGraph(), MGL_init(),
  375.                         MGL_availableMode()
  376.  
  377.  
  378.             MGL_beginDrawing
  379.  
  380.             Function    Setup for high performance drawing operation.
  381.  
  382.             Syntax      void MGL_beginDrawing(void);
  383.  
  384.             Prototype   mgraph.h
  385.             in
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.             6                       MegaGraph Graphics Library Reference
  398.  
  399.  
  400.  
  401.  
  402.  
  403.             Remarks     MGL_beginDrawing() must be called before
  404.                         calling any of the special high performance
  405.                         drawing routines, such as the MGL_lineFast()
  406.                         and associated routines. MGL_beginDrawing
  407.                         will put the video hardware into a state that
  408.                         can be used to render the primitives much
  409.                         faster than otherwise possible.
  410.  
  411.                         All high performance drawing primitives end
  412.                         the word 'Fast', and must be bracketed
  413.                         between calls to MGL_beginDrawing() and
  414.                         MGL_endDrawing(). You may mix and match any
  415.                         of the fast drawing routines and normal
  416.                         library functions within an
  417.                         MGL_beginDrawing() and MG_endDrawing() block.
  418.                         You can also nest calls to MGL_beginDrawing()
  419.                         and MGL_endDrawing() (hence you can write
  420.                         your own functions that use the fast
  421.                         rendering routines but do not require the
  422.                         user to call MGL_beginDrawing() before
  423.                         calling your routine).
  424.  
  425.                             must                        You      ensure that you call the
  426.                         MGL_endDrawing() routine after drawing a set
  427.                         of high performance primitives.
  428.  
  429.             See also    MGL_endDrawing(), MGL_*fast()
  430.  
  431.  
  432.             MGL_beginGouraud
  433.  
  434.             Function    Setup for Gouraud Shaded drawing operation.
  435.  
  436.             Syntax      void MGL_beginGouraud(void);
  437.  
  438.             Prototype   mgraph.h
  439.             in
  440.  
  441.             Remarks     MGL_beginGouraud() must be called before any
  442.                         of the gouraud shading routines are called,
  443.                         such as the MGL_fillGouraudPolygon() routine.
  444.                         This will put the video hardware into a
  445.                         special mode for doing high peformance
  446.                         gouraud shaded rendering.
  447.  
  448.                         You should not call any other routines except
  449.                         the gouraud shading routines between calls to
  450.                         MGL_beginGouraud() and MGL_endGouraud(), and
  451.                         you should not nest calls to this routine.
  452.  
  453.             See also    MGL_endGouraud()
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.             Chapter 6 - Console Library                                7
  464.  
  465.  
  466.  
  467.  
  468.  
  469.             MGL_beginPixel
  470.  
  471.             Function    Setup for high speed pixel drawing.
  472.  
  473.             Syntax      void MGL_beginPixel(void);
  474.  
  475.             Prototype   mgraph.h
  476.             in
  477.  
  478.             Remarks     MGL_beginPixel() sets up the video hardware
  479.                         for plotting single pixels as fast a
  480.                         possible. You must call this routine before
  481.                         calling any of the MGL_*Pixel() routines to
  482.                         ensure correct operation, and you must call
  483.                         the MGL_endPixel() routine after you have
  484.                         finished.
  485.  
  486.                         This routine is intended primarily to ensure
  487.                         fast operation if you intend to plot more
  488.                         than a single pixel at a time, so it will be
  489.                         done as fast as possible.
  490.  
  491.             See also    MGL_endPixel()
  492.  
  493.  
  494.             MGL_charWidth
  495.  
  496.             Function    Returns the width of a character in pixels.
  497.  
  498.             Syntax      int MGL_charWidth(char ch);
  499.  
  500.             Prototype   mgraph.h
  501.             in
  502.  
  503.             Parameters  ch - Character to measure.
  504.  
  505.             Remarks     MGL_charWidth() will return the width of the
  506.                         specified character, given the currently
  507.                         active font and attribute settings.
  508.  
  509.             Return      Width of the character in pixels (will depend
  510.             value       on currently active font)
  511.  
  512.             See also    MGL_textWidth(), MGL_useFont()
  513.  
  514.  
  515.             MGL_clearDevice
  516.  
  517.             Function    Clears the currently active display page on
  518.                         the active device..
  519.  
  520.             Syntax      void MGL_clearDevice(void);
  521.  
  522.             Prototype   mgraph.h
  523.             in
  524.  
  525.  
  526.  
  527.  
  528.  
  529.             8                       MegaGraph Graphics Library Reference
  530.  
  531.  
  532.  
  533.  
  534.  
  535.             Remarks     MGL_clearDevice() will clear the entire
  536.                         currently active display page in the current
  537.                         background color. This is the fastest way to
  538.                         clear an entire display page, but if you wish
  539.                         to only clear a portion of the page, use the
  540.                         MGL_clearViewport() routine instead.
  541.  
  542.             See also    MGL_clearViewport()
  543.  
  544.  
  545.             MGL_clearViewport
  546.  
  547.             Function    Clears the currently active viewport.
  548.  
  549.             Syntax      void MGL_clearViewport(void);
  550.  
  551.             Prototype   mgraph.h
  552.             in
  553.  
  554.             Remarks     MGL_clearViewport() will clear the currently
  555.                         active display page viewport in the current
  556.                         background color. This is the fastest way to
  557.                         clear a rectangular viewport, but you may
  558.                         also wish to use the MGL_fillRect() routine
  559.                         to fill in an arbitrary pattern instead, as
  560.                         the MGL_clearViewport() always clears the
  561.                         viewport in a solid color.
  562.  
  563.             See also    MGL_clearDevice()
  564.  
  565.  
  566.             MGL_clipLine
  567.  
  568.             Function    Clips a line to a specified clipping
  569.                         rectangle.
  570.  
  571.             Syntax      bool MGL_clipLine(point *p1,point *p2,rect
  572.                         r);
  573.  
  574.             Prototype   mgraph.h
  575.             in
  576.  
  577.             Parameters  p1,p2 - Endpoints of line to clip.
  578.                         r - Rectangle to clip the line to
  579.  
  580.             Remarks     MGL_clipLine() will clip the line from point
  581.                         p1(x,y) to point p2(x.y) to the specified
  582.                         clipping rectangle. If the line is accepted
  583.                         (ie: it intersects with the clipping
  584.                         rectangle) then the routine will return true
  585.                         and the line enpoints will be updated to
  586.                         reflect the clipped lines new endpoints. If
  587.                         the line is completely outside of the
  588.                         clipping rectangle, the routine will return
  589.                         false.
  590.  
  591.             Return      True if line is visible, false if completely
  592.             value       outside rectangle.
  593.  
  594.  
  595.             Chapter 6 - Console Library                                9
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.             MGL_copyImage
  604.  
  605.             Function    Copies of block of video memory.
  606.  
  607.             Syntax      void MGL_copyImage(rect r,int dl,int dt,int
  608.                         sp,int dp)
  609.  
  610.             Prototype   mgraph.h
  611.             in
  612.  
  613.             Parameters  r - Rectangle specifying the region to copy
  614.                         dl - Left coordinate of destination location
  615.                         dt - Top coordinate of destination location
  616.                         sp - Source image page
  617.                         dp - Destination image page
  618.  
  619.             Remarks     MGL_copyImage() copies the data of a
  620.                         rectangular region of the specified display
  621.                         page to another location, either on the same
  622.                         page or on a different page. If the source
  623.                         and destination regions overlap, the image
  624.                         will be correctly copied.
  625.  
  626.                         NOTE: No clipping is done in this routine, so
  627.                         you can copy data outside of the
  628.                         current viewport.
  629.  
  630.             See also    MGL_copyImageCoord()
  631.  
  632.  
  633.             MGL_copyImageCoord
  634.  
  635.             Function    Copies of block of video memory.
  636.  
  637.             Syntax      void MGL_copyImageCoord(int left,int top,int
  638.                         right,int bottom,int dl,int dt,int sp,int dp)
  639.  
  640.             Prototype   mgraph.h
  641.             in
  642.  
  643.             Parameters  left - Left coordinate of source region
  644.                         top - Top coordinate of source region
  645.                         right - Right coordinate of source region
  646.                         bottom - Bottom coordinate of source region
  647.                         dl - Left coordinate of destination location
  648.                         dt - Top coordinate of destination location
  649.                         sp - Source image page
  650.                         dp - Destination image page
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.             10                      MegaGraph Graphics Library Reference
  662.  
  663.  
  664.  
  665.  
  666.  
  667.             Remarks     MGL_copyImageCoord() copies the data of a
  668.                         rectangular region of the specified display
  669.                         page to another location, either on the same
  670.                         page or on a different page. If the source
  671.                         and destination regions overlap, the image
  672.                         will be correctly copied.
  673.  
  674.                         NOTE: No clipping is done in this routine, so
  675.                         you can copy data outside of the
  676.                         current viewport.
  677.  
  678.             See also    MGL_copyImage()
  679.  
  680.  
  681.             MGL_defaultAttributes
  682.  
  683.             Function    Reset global attributes to their default
  684.                         values.
  685.  
  686.             Syntax      void MGL_defaultAttributes(void);
  687.  
  688.             Prototype   mgraph.h
  689.             in
  690.  
  691.             Remarks     MGL_defaultAttributes() resets all of the
  692.                         global attributes to their default values.
  693.                         MGL_defaultAttributes() does not reset the
  694.                         current palette.
  695.  
  696.             See also    MGL_getAttributes(), MGL_setAttributes(),
  697.                         MGL_getDefaultPalette()
  698.  
  699.  
  700.             MGL_defaultColor
  701.  
  702.             Function    Returns the default color value for the video
  703.                         mode.
  704.  
  705.             Syntax      color_t MGL_defaultColor(void);
  706.  
  707.             Prototype   mgraph.h
  708.             in
  709.  
  710.             Remarks     MGL_defaultColor() returns a default color
  711.                         values for the current video mode. This color
  712.                         value is white if the palette has not been
  713.                         changed, and will always be white in direct
  714.                         color modes.
  715.  
  716.             Return      Default color value for current video mode.
  717.             value
  718.  
  719.             See also    MGL_setColor(), MGL_getColor()
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.             Chapter 6 - Console Library                               11
  728.  
  729.  
  730.  
  731.  
  732.  
  733.             MGL_detectGraph
  734.  
  735.             Function    Detects the currently installed video
  736.                         hardware.
  737.  
  738.             Syntax      void MGL_detectGraph(int far *graphdriver,int
  739.                         far *graphmode);
  740.  
  741.             Prototype   mgraph.h
  742.             in
  743.  
  744.             Parameters  graphdriver - Pointer to graphics device
  745.                         driver id
  746.                         graphmode - Pointer to default video mode for
  747.                         device
  748.  
  749.             Remarks     MGL_detectGraph() autodetects the presence of
  750.                         all the standard graphics adapters supported
  751.                         by the MGL. If no suitable hardware is
  752.                         detected, it returns grNONE in the
  753.                         graphdriver parameter. If suitable hardware
  754.                         is detected, it will return an appropriate
  755.                         device driver id number in the graph driver
  756.                         parameter and a suggested default video mode
  757.                         in the graphmode parameter.
  758.  
  759.                         The video device drivers currently supported
  760.                         by the MGL are:
  761.  
  762.                         grDETECT  - Auto detect the graphics
  763.                         subsystem
  764.                         grNONE    - No graphics hardware detected
  765.                         grEGA     - Standard EGA with 256k RAM
  766.                         grVGA     - Standard VGA
  767.                         grSVGA    - VESA VBE compliant Super VGA
  768.                         grSVGA_S3 - S3 accelerated SuperVGA
  769.  
  770.                         The MGL supports a number of different video
  771.                         mode resolutions, ranging from 320x200 up to
  772.                         1280x1024 with color ranges from 16 colors up
  773.                         to 16.7 million colors. Thus the video mode
  774.                         id for 320x200 16 color EGA graphics mode is
  775.                         grEGA_320x200x16, and the 1280x1024 16.7
  776.                         million color mode is grSVGA_1280x1024x16m.
  777.                         Please consult the MGRAPH.H header file for a
  778.                         full list of defined video modes (to large to
  779.                         list here).
  780.  
  781.                         Once you have called MGL_detectGraph(), you
  782.                         can then call the MGL_availableModes and
  783.                         MGL_availablePages to determine all the
  784.                         available video modes for the currently
  785.                         installed driver and the number of available
  786.                         video pages for each video mode.
  787.  
  788.             See also    MGL_init()
  789.  
  790.  
  791.  
  792.  
  793.             12                      MegaGraph Graphics Library Reference
  794.  
  795.  
  796.  
  797.  
  798.  
  799.             MGL_disjointRect
  800.  
  801.             Function    Determines if two rectangles are disjoint.
  802.  
  803.             Syntax      bool MGL_disjointRect(recy r1,rect r2)
  804.  
  805.             Prototype   mgraph.h
  806.             in
  807.  
  808.             Parameters  r1 - First rectangle to test
  809.                         r2 - Second rectangle to test
  810.  
  811.             Remarks     MGL_disjointRect() will determine if two
  812.                         rectangles are non-overlapping (ie: the
  813.                         intersection between the rectangles is zero).
  814.                         If they are disjoint, it will return true,
  815.                         otherwise it will return false.
  816.  
  817.             Return      True if the rectangles are disjoint, false if
  818.             value       not.
  819.  
  820.             See also    MGL_emptyRect(), MGL_equalRect(),
  821.                         MGL_offsetRect(), MGL_insetRect(),
  822.                         MGL_ptInRect().
  823.  
  824.  
  825.             MGL_divotSize
  826.  
  827.             Function    Number of bytes required to store the divot.
  828.  
  829.             Syntax      long MGL_divotSize(rect r)
  830.  
  831.             Prototype   mgraph.h
  832.             in
  833.  
  834.             Parameters  r - Rectangle defining the divot area.
  835.  
  836.             Remarks     MGL_divotSize() determines the number of
  837.                         bytes required to store a particular video
  838.                         memory divot.
  839.  
  840.             Return      Size of the specified divot in bytes.
  841.             value
  842.  
  843.             See also    MGL_getDivot(), MGL_getDivotCoord(),
  844.                         MGL_putDivot()
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.             Chapter 6 - Console Library                               13
  860.  
  861.  
  862.  
  863.  
  864.  
  865.             MGL_divotSizeCoord
  866.  
  867.             Function    Number of bytes required to store the divot.
  868.  
  869.             Syntax      long MGL_divotSizeCoord(int left,int top,int
  870.                         right,int bottom)
  871.  
  872.             Prototype   mgraph.h
  873.             in
  874.  
  875.             Parameters  left - Left coordinate of divot area
  876.                         top - Top coordinate of divot area
  877.                         right - Right coordinate of divot area
  878.                         bottom - Bottom coordinate of divot area
  879.  
  880.             Remarks     MGL_divotSizeCoord() determines the number of
  881.                         bytes required to store a particular video
  882.                         memory divot.
  883.  
  884.             Return      Size of the specified divot in bytes.
  885.             value
  886.  
  887.             See also    MGL_getDivot(), MGL_getDivotCoord(),
  888.                         MGL_putDivot()
  889.  
  890.  
  891.             MGL_doubleBuffer
  892.  
  893.             Function    Sets up for double buffering if possible.
  894.  
  895.             Syntax      bool MGL_doubleBuffer(void);
  896.  
  897.             Prototype   mgraph.h
  898.             in
  899.  
  900.             Remarks     MGL_doubleBuffer() will attempt to enable
  901.                         double buffering for the current video mode.
  902.                         If double buffering is enabled, then the
  903.                         routine will return true, otherwise it will
  904.                         return false and single buffer mode will
  905.                         still be enabled.
  906.  
  907.                         MGL_doubleBuffer() will attempt to perform
  908.                         double buffering using an offscreen memory
  909.                         buffer if only one video memory page is
  910.                         supported by the hardware, so it is a
  911.                         transparent method of enabling simple double
  912.                         buffered animation.
  913.  
  914.                         NOTE: The current version of the MGL does not
  915.                         yet support off screen memory buffers (mostly
  916.                         because of memory requirements in real mode -
  917.                         the protected mode version of the library
  918.                         will, and limited support will be provided in
  919.                         real mode for the next version).
  920.  
  921.             Return      True if double buffering is now enabled.
  922.             value
  923.  
  924.  
  925.             14                      MegaGraph Graphics Library Reference
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.             See also    MGL_singleBuffer(), MGL_swapBuffers()
  933.  
  934.  
  935.             MGL_drawBorder
  936.  
  937.             Function    Draws a 3D border around the specified
  938.                         rectangle.
  939.  
  940.             Syntax      void MGL_drawBorder(rect r,int style,int
  941.                         thickness)
  942.  
  943.             Prototype   mgraph.h
  944.             in
  945.  
  946.             Parameters  r - Rectangle defining the region to draw the
  947.                         border around
  948.                         style - Type of border to draw
  949.                         thickness - Thickness of the border in pixels
  950.  
  951.             Remarks     MGL_drawBorder() draws a 3D style border
  952.                         around the specified rectangle in the
  953.                         specified border style and thickness. The
  954.                         different border styles are defined in the
  955.                         MGRAPH.H header file as:
  956.  
  957.                         BDR_INSET    - Interior is inset into display
  958.                         BDR_OUTSET   - Interior is outset from
  959.                         display
  960.                         BDR_OUTLINE  - Border is a 3D outline
  961.  
  962.                         Thus if you wish to create the effect of a 3D
  963.                         style push button, you would use the
  964.                         BDR_OUTSET style to make it appear to be
  965.                         protruding from the display screen. To make
  966.                         it look like it is depressed, use the
  967.                         BDR_INSET style to make it appear to be inset
  968.                         into the display. The BDR_OUTLINE style is
  969.                         used to create a 3D looking rectangle just
  970.                         inside the rectangle boundaries for grouping
  971.                         things together in a user interface dialog
  972.                         box.
  973.  
  974.                         The border is completely contained within the
  975.                         specified bounding rectangle.
  976.  
  977.                         The color of the border's highlights are
  978.                         determined by the currently active border
  979.                         color values.
  980.  
  981.             See also    MGL_drawBorderCoord(), MGL_drawHDivider(),
  982.                         MGL_drawVDivider(), MGL_setBorderColors()
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.             Chapter 6 - Console Library                               15
  992.  
  993.  
  994.  
  995.  
  996.  
  997.             MGL_drawBorderCoord
  998.  
  999.             Function    Draws a 3D border around the specified
  1000.                         rectangle.
  1001.  
  1002.             Syntax      MGL_drawBorderCoord(int left,int top,int
  1003.                         right,int bottom,int style,int thickness);
  1004.  
  1005.             Prototype   mgraph.h
  1006.             in
  1007.  
  1008.             Parameters  r - Rectangle defining the region to draw the
  1009.                         border around
  1010.                         style - Type of border to draw
  1011.                         thickness - Thickness of the border in pixels
  1012.  
  1013.             Remarks     MGL_drawBorderCoord() draws a 3D style border
  1014.                         around the specified rectangle in the
  1015.                         specified border style and thickness. The
  1016.                         different border styles are defined in the
  1017.                         MGRAPH.H header file as:
  1018.  
  1019.                         BDR_INSET    - Interior is inset into display
  1020.                         BDR_OUTSET   - Interior is outset from
  1021.                         display
  1022.                         BDR_OUTLINE  - Border is a 3D outline
  1023.  
  1024.                         Thus if you wish to create the effect of a 3D
  1025.                         style push button, you would use the
  1026.                         BDR_OUTSET style to make it appear to be
  1027.                         protruding from the display screen. To make
  1028.                         it look like it is depressed, use the
  1029.                         BDR_INSET style to make it appear to be inset
  1030.                         into the display. The BDR_OUTLINE style is
  1031.                         used to create a 3D looking rectangle just
  1032.                         inside the rectangle boundaries for grouping
  1033.                         things together in a user interface dialog
  1034.                         box.
  1035.  
  1036.                         The border is completely contained within the
  1037.                         specified bounding rectangle.
  1038.  
  1039.                         The color of the border's highlights are
  1040.                         determined by the currently active border
  1041.                         color values.
  1042.  
  1043.             See also    MGL_drawBorder(), MGL_drawHDivider(),
  1044.                         MGL_drawVDivider(), MGL_setBorderColors()
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.             16                      MegaGraph Graphics Library Reference
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.             MGL_drawHDivider
  1064.  
  1065.             Function    Draws a 3D looking horizontal dividing line
  1066.  
  1067.             Syntax      void MGL_drawHDivider(int y,int x1,int x2);
  1068.  
  1069.             Prototype   mgraph.h
  1070.             in
  1071.  
  1072.             Parameters  y - Y coordinate to draw the line at
  1073.                         x1 - Starting X coordinate
  1074.                         x2 - Ending X coordinate
  1075.  
  1076.             Remarks     MGL_drawHDivider() draws a 3D horizontal
  1077.                         dividing line beginning at the position
  1078.                         (x1,y) and ending at the position (x2,y).
  1079.  
  1080.                         The color of the dividing line is determine
  1081.                         by the currently active border colors values.
  1082.  
  1083.             See also    MGL_drawVDivider(), MGL_drawBorder(),
  1084.                         MGL_setBorderColors()
  1085.  
  1086.  
  1087.             MGL_drawStr
  1088.  
  1089.             Function    Draws a text string on the display.
  1090.  
  1091.             Syntax      void MGL_drawStr(const char *str);
  1092.  
  1093.             Prototype   mgraph.h
  1094.             in
  1095.  
  1096.             Parameters  str - String to display
  1097.  
  1098.             Remarks     MGL_drawStr() draws the specified string at
  1099.                         the current position (CP) in the current
  1100.                         drawing color, write mode, font, text
  1101.                         direction and justification. The CP is moved
  1102.                         so that drawing will begin directly after the
  1103.                         end of the string, only if the horizontal
  1104.                         justification is set to LEFT_TEXT, otherwise
  1105.                         the CP is not moved.
  1106.  
  1107.             See also    MGL_drawStrXY(), MGL_textHeight(),
  1108.                         MGL_textWidth(), MGL_useFont()
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.             Chapter 6 - Console Library                               17
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.             MGL_drawStrXY
  1130.  
  1131.             Function    Draws a text string on the display.
  1132.  
  1133.             Syntax      void MGL_drawStrXY(int x,int y,const char
  1134.                         *str);
  1135.  
  1136.             Prototype   mgraph.h
  1137.             in
  1138.  
  1139.             Parameters  x - X coordinate to begin rendering the
  1140.                         string at
  1141.                         y - Y coordinate to begin rendering the
  1142.                         string at
  1143.                         str - String to display
  1144.  
  1145.             Remarks     MGL_drawStrXY   draws the specified string at                                     ()
  1146.                         the specified (x,y) position in the current
  1147.                         drawing color, write mode, font, text
  1148.                         direction and justification.
  1149.  
  1150.             See also    MGL_drawStrXY(), MGL_textHeight(),
  1151.                         MGL_textWidth(), MGL_useFont()
  1152.  
  1153.  
  1154.             MGL_drawVDivider
  1155.  
  1156.             Function    Draws a 3D looking vertical dividing line
  1157.  
  1158.             Syntax      void MGL_drawVDivider(int x,int y1,int y2);
  1159.  
  1160.             Prototype   mgraph.h
  1161.             in
  1162.  
  1163.             Parameters  x - X coordinate to begin drawing divider
  1164.                         y1 - Starting Y coordinate
  1165.                         y2 - Ending Y coordinate
  1166.  
  1167.             Remarks     MGL_drawVDivider() draws a 3D vertical
  1168.                         dividing line beginning at the position
  1169.                         (x,y1) and ending at the position (x,y2).
  1170.  
  1171.                         The color of the dividing line is determine
  1172.                         by the currently active border colors values.
  1173.  
  1174.             See also    MGL_drawHDivider(), MGL_drawBorder(),
  1175.                         MGL_setBorderColors()
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.             18                      MegaGraph Graphics Library Reference
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.             MGL_driverName
  1196.  
  1197.             Function    Returns a string describing the name of the
  1198.                         device driver.
  1199.  
  1200.             Syntax      char *MGL_driverName(int driver);
  1201.  
  1202.             Prototype   mgraph.h
  1203.             in
  1204.  
  1205.             Parameters  driver - Device driver id number.
  1206.  
  1207.             Remarks     MGL_driverName() returns a string describing
  1208.                         the a device driver given a device driver
  1209.                         number.
  1210.  
  1211.             Return      Pointer to device driver name string.
  1212.             value
  1213.  
  1214.             See also    MGL_modeName()
  1215.  
  1216.  
  1217.             MGL_ellipse
  1218.  
  1219.             Function    Draws an ellipse outline defined by a
  1220.                         bounding rectangle.
  1221.  
  1222.             Syntax      bool MGL_ellipse(rect extentRect);
  1223.  
  1224.             Prototype   mgraph.h
  1225.             in
  1226.  
  1227.             Parameters  extentRect - Bounding rectangle defining the
  1228.                         ellipse.
  1229.  
  1230.             Remarks     MGL_ellipse() draws the outline of an ellipse
  1231.                         just inside the mathematical boundary of
  1232.                         extentRect. The ellipse outline is drawn in
  1233.                         the current pen color, style and size.
  1234.  
  1235.                         Note: This routine is more versatile than the
  1236.                         equivalent MGL_ellipseCoord() routine, as you
  1237.                         can have an ellipse with odd diameters
  1238.                         values, which you cannot get with the
  1239.                         MGL_ellipseCoord() routine.
  1240.  
  1241.             Return      True if ellipse was scan converted, false if
  1242.             value       an error occured (MGL_buf too small)..
  1243.  
  1244.             See also    MGL_ellipseCoord(), MGL_fillEllipse(),
  1245.                         MGL_fillEllipseCoord()
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.             Chapter 6 - Console Library                               19
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.             MGL_ellipseArc
  1262.  
  1263.             Function    Draws an elliptical arc outline defined by a
  1264.                         bounding rectangle.
  1265.  
  1266.             Syntax      bool MGL_ellipseArc(rect extentRect,int
  1267.                         startAngle,int endAngle);
  1268.  
  1269.             Prototype   mgraph.h
  1270.             in
  1271.  
  1272.             Parameters  extentRect - Bounding rectangle defining the
  1273.                         arc.
  1274.                         startAngle - Starting angle for arc (in
  1275.                         degrees)
  1276.                         endAngle - Ending angle for arc (in degrees).
  1277.  
  1278.             Remarks     MGL_ellipseArc() draw the outline of an
  1279.                         elliptical arc just inside the mathematical
  1280.                         boundary of extentRect. StartAngle specifies
  1281.                         where the arc begins and is treated MOD 360.
  1282.                         EndAngle specifies where the arc ends and is
  1283.                         treated MOD 360 also. The angles are given in
  1284.                         positive or negative degrees. Zero degrees is
  1285.                         at 3 o'clock, 90 is at 12 o'clock high, 180
  1286.                         is at 9 o'clock and 270 is at 6 o'clock.
  1287.                         Other angles are measured relative to the
  1288.                         enclosing rectangle. Thus an angle of 45
  1289.                         degrees always defines a line from the centre
  1290.                         of the rectangle through it's top right
  1291.                         corner, even if the rectangle isn't square.
  1292.  
  1293.                         The ellipse outline if drawn in the current
  1294.                         pen color, style and size (note that the
  1295.                         current version of the MGL only works with a
  1296.                         1x1 pen size with a solid pattern for
  1297.                         elliptical arcs).
  1298.  
  1299.                         Note: This routine is more versatile than the
  1300.                         equivalent MGL_ellipseArcCoord() routine, as
  1301.                         you can have an elliptical arc with odd
  1302.                         diameters values, which you cannot get with
  1303.                         the MGL_ellipseArcCoord() routine.
  1304.  
  1305.             Return      True if the ellipse arc was scan converted,
  1306.             value       false if an error occurred (MGL_buf too
  1307.                         small).
  1308.  
  1309.             See also    MGL_ellipseArcCoord(), MGL_fillEllipseArc(),
  1310.                         MGL_fillEllipseArcCoord()
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.             20                      MegaGraph Graphics Library Reference
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.             MGL_ellipseArcCoord
  1328.  
  1329.             Function    Draws an elliptical arc outline defined by a
  1330.                         centre and radii.
  1331.  
  1332.             Syntax      bool MGL_ellipseArcCoord(int x,int y,int
  1333.                         xradius,int yradius,int startAngle,int
  1334.                         endAngle);
  1335.  
  1336.             Prototype   mgraph.h
  1337.             in
  1338.  
  1339.             Parameters  x,y - Centre of the elliptical arc.
  1340.                         xradius - X radius for the elliptical arc
  1341.                         yradius - Y radius for the elliptical arc
  1342.                         startAngle - Starting angle for arc (in
  1343.                         degrees)
  1344.                         endAngle - Ending angle for arc (in degrees).
  1345.  
  1346.             Remarks     MGL_ellipseArcCoord() draws the outline of an
  1347.                         elliptical arc given the centre, radii and
  1348.                         starting and endling angles. StartAngle
  1349.                         specifies where the arc begins and is treated
  1350.                         MOD 360. EndAngle specifies where the arc
  1351.                         ends and is treated MOD 360 also. The angles
  1352.                         are given in positive or negative degrees.
  1353.                         Zero degrees is at 3 o'clock, 90 is at 12
  1354.                         o'clock high, 180 is at 9 o'clock and 270 is
  1355.                         at 6 o'clock. Other angles are measured
  1356.                         relative to the enclosing rectangle. Thus an
  1357.                         angle of 45 degrees always defines a line
  1358.                         from the centre of the rectangle through it's
  1359.                         top right corner, even if the rectangle isn't
  1360.                         square.
  1361.  
  1362.                         The ellipse outline if drawn in the current
  1363.                         pen color, style and size (note that the
  1364.                         current version of the MGL only works with a
  1365.                         1x1 pen size with a solid pattern).
  1366.  
  1367.                         Note: This routine can only work with integer
  1368.                         semi-major and semi-minor axes, but can
  1369.                         sometimes be easier to work with (and it
  1370.                         provided for compatabilty with other graphics
  1371.                         packages).
  1372.  
  1373.             Return      True if the ellipse arc was scan converted,
  1374.             value       false if an error occurred (MGL_buf too
  1375.                         small).
  1376.  
  1377.             See also    MGL_ellipseArc(), MGL_fillEllipseArc(),
  1378.                         MGL_fillEllipseArcCoord()
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.             Chapter 6 - Console Library                               21
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.             MGL_ellipseCoord
  1394.  
  1395.             Function    Draws an ellipse outline defined by a
  1396.                         bounding rectangle.
  1397.  
  1398.             Syntax      bool MGL_ellipseCoord(int x,int y,int
  1399.                         xradius,int yradius);
  1400.  
  1401.             Prototype   mgraph.h
  1402.             in
  1403.  
  1404.             Parameters  x,y - Centre of the ellipse
  1405.                         xradius - X radius for the ellipse
  1406.                         yradius - Y radius for the ellipse
  1407.  
  1408.             Remarks     MGL_ellipse() draws the outline of an ellipse
  1409.                         given the centre and radii for the ellipse.
  1410.                         The ellipse outline if drawn in the current
  1411.                         pen color, style and size.
  1412.  
  1413.                         Note: This routine can only work with integer
  1414.                         semi-major and semi-minor axes, but can
  1415.                         sometimes be easier to work with (and it
  1416.                         provided for compatability with other
  1417.                         graphics packages).
  1418.  
  1419.             Return      True if ellipse was scan converted, false if
  1420.             value       an error occured (MGL_buf too small)..
  1421.  
  1422.             See also    MGL_ellipse(), MGL_fillEllipse(),
  1423.                         MGL_fillEllipseCoord()
  1424.  
  1425.  
  1426.             MGL_ellipseEngine
  1427.  
  1428.             Function    Generates the set of points on an ellipse.
  1429.  
  1430.             Syntax      void MGL_ellipseEngine(rect extentRect,void
  1431.                         (*setup)(int topY,int botY,int left,int
  1432.                         right),void (*set4pixels)(bool inc_x,bool
  1433.                         inc_y,bool region1),void (*finished)(void));
  1434.  
  1435.             Prototype   mgraph.h
  1436.             in
  1437.  
  1438.             Parameters  extentRect - Bounding rectangle defining the
  1439.                         ellipse.
  1440.                         setup - Routine called to intialise pixel
  1441.                         plotting routines.
  1442.                         set4pixels - Routine called repeatedly for
  1443.                         each set of 4 pixels.
  1444.                         finished - Routine called to complete
  1445.                         plotting pixels.
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.             22                      MegaGraph Graphics Library Reference
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.             Remarks     MGL_ellipseEngine() is the same engine used
  1460.                         to generate all ellipse's and elliptical arc
  1461.                         in the MGL. You can call it to generate the
  1462.                         set of points on an ellipse, calling your own
  1463.                         user defined plotting routines.
  1464.  
  1465.                         The setup routine is called before any pixel
  1466.                         are plotted with the coordinates of the 4
  1467.                         seed points in the four ellipse quadrants.
  1468.  
  1469.                             set4pixels                        The            routine is called repeatedly
  1470.                         for each set of 4 pixels to be plotted, and
  1471.                         specified whether the coordinates in the x
  1472.                         and y directions should be incremented or
  1473.                         remain the same. This state of the 4 pixel
  1474.                         coordinates will need to be maintained by the
  1475.                         user supplied routines.
  1476.  
  1477.                             finished                        The          routine is called to clean up
  1478.                         after generating all the points on the
  1479.                         ellipse, such as releasing memory and
  1480.                         rendering the ellipse if the rendering was
  1481.                         deferred.
  1482.  
  1483.  
  1484.             MGL_emptyRect
  1485.  
  1486.             Function    Determines if a rectangle is empty.
  1487.  
  1488.             Syntax      bool MGL_emptyRect(rect r)
  1489.  
  1490.             Prototype   mgraph.h
  1491.             in
  1492.  
  1493.             Parameters  r - rectangle to test
  1494.  
  1495.             Remarks     MGL_emptyRect() determine if a rectangle is
  1496.                         empty. A rectangle is defined as being empty
  1497.                         if the right coordinate is less than or equal
  1498.                         to the left coordinate, or if the bottom
  1499.                         coordinate is less than or equal to the top
  1500.                         coordinate.
  1501.  
  1502.             Return      True if rectangle is empty, false if not.
  1503.             value
  1504.  
  1505.             See also    MGL_disjointRect(), MGL_equalRect(),
  1506.                         MGL_offsetRect(), MGL_insetRect(),
  1507.                         MGL_ptInRect().
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.             Chapter 6 - Console Library                               23
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.             MGL_endDrawing
  1526.  
  1527.             Function    Finish high performance drawing operation.
  1528.  
  1529.             Syntax      void MGL_endDrawing(void);
  1530.  
  1531.             Prototype   mgraph.h
  1532.             in
  1533.  
  1534.             Remarks     MGL_endDrawing() is called to end a set of
  1535.                         high performance drawing operations that we
  1536.                         started with the MGL_beginDrawing()
  1537.                         operation.
  1538.  
  1539.                         All high performance drawing primitives end
  1540.                         the word 'Fast', and must be bracketed
  1541.                         between calls to MGL_beginDrawing() and
  1542.                         MGL_endDrawing(). You may mix and match any
  1543.                         of the fast drawing routines and normal
  1544.                         library functions within an
  1545.                         MGL_beginDrawing() and MG_endDrawing() block.
  1546.                         You can also nest calls to MGL_beginDrawing()
  1547.                         and MGL_endDrawing() (hence you can write
  1548.                         your own functions that use the fast
  1549.                         rendering routines but do not require the
  1550.                         user to call MGL_beginDrawing() before
  1551.                         calling your routine).
  1552.  
  1553.                             must                        You      ensure that you call the
  1554.                         MGL_endDrawing routine after drawing a set of
  1555.                         high performance primitives.
  1556.  
  1557.             See also    MGL_beginDrawing(), MGL_*fast()
  1558.  
  1559.  
  1560.             MGL_endGouraud
  1561.  
  1562.             Function    Complete Gouraud Shaded drawing operation.
  1563.  
  1564.             Syntax      void MGL_endGouraud(void);
  1565.  
  1566.             Prototype   mgraph.h
  1567.             in
  1568.  
  1569.             Remarks     MGL_endGouraud() is called to end the
  1570.                         rendering of gouraud shaded primitives, such
  1571.                         as the MGL_fillGouraudPolygon() routine.
  1572.  
  1573.                         You should not call any other routines except
  1574.                         the gouraud shading routines between calls to
  1575.                         MGL_beginGouraud and MGL_endGouraud, and you
  1576.                         should not nest calls to this routine.
  1577.  
  1578.             See also    MGL_beginGouraud()
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.             24                      MegaGraph Graphics Library Reference
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.             MGL_endPixel
  1592.  
  1593.             Function    End high speed pixel drawing operation.
  1594.  
  1595.             Syntax      void MGL_endPixel(void);
  1596.  
  1597.             Prototype   mgraph.h
  1598.             in
  1599.  
  1600.             Remarks     MGL_endPixel() ends a set of high speed pixel
  1601.                         drawing operations.
  1602.  
  1603.                         This routine is intended primarily to ensure
  1604.                         fast operation if you intend to plot more
  1605.                         than a single pixel at a time, so it will be
  1606.                         done as fast as possible.
  1607.  
  1608.             See also    MGL_beginPixel()
  1609.  
  1610.  
  1611.             MGL_equalPoint
  1612.  
  1613.             Function    Determines if two points are equal.
  1614.  
  1615.             Syntax      bool MGL_equalPoint(point p1,point p2);
  1616.  
  1617.             Prototype   mgraph.h
  1618.             in
  1619.  
  1620.             Parameters  p1 - First point to compare
  1621.                         p2 - Second point to compare
  1622.  
  1623.             Remarks     MGL_equalPoint() determines if the value of
  1624.                         two coordinates are equal, returning true if
  1625.                         they are.
  1626.  
  1627.             Return      True if the points are equal, false if not.
  1628.             value
  1629.  
  1630.  
  1631.             MGL_equalRect
  1632.  
  1633.             Function    Determines if two rectangles are equal.
  1634.  
  1635.             Syntax      bool MGL_equalRect(rect r1,rect r2);
  1636.  
  1637.             Prototype   mgraph.h
  1638.             in
  1639.  
  1640.             Parameters  r1 - First rectangle to compare
  1641.                         r2 - Second rectangle to compare
  1642.  
  1643.             Remarks     MGL_equalRect() compares the values of two
  1644.                         rectangles and determines if they are equal,
  1645.                         returning true if they are.
  1646.  
  1647.             Return      True if the rectangles are equal.
  1648.             value
  1649.  
  1650.  
  1651.             Chapter 6 - Console Library                               25
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.             See also    MGL_disjointRect(), MGL_emptyRect(),
  1659.                         MGL_offsetRect(), MGL_insetRect(),
  1660.                         MGL_ptInRect().
  1661.  
  1662.  
  1663.             MGL_errorMsg
  1664.  
  1665.             Function    Returns a string describing an error
  1666.                         condition.
  1667.  
  1668.             Syntax      char *MGL_errorMsg(int err);
  1669.  
  1670.             Prototype   mgraph.h
  1671.             in
  1672.  
  1673.             Parameters  err - Error code to obtain string for.
  1674.  
  1675.             Remarks     MGL_errorMsg() returns a pointer to a string
  1676.                         describing a specified error condition. You
  1677.                         can use this to convert the error codes from
  1678.                         a numerical id return by MGL_result() to a
  1679.                         string which you can display for the users of
  1680.                         your programs.
  1681.  
  1682.             Return      Pointer to string describing the error
  1683.             value       condition.
  1684.  
  1685.             See also    MGL_result().
  1686.  
  1687.  
  1688.             MGL_exit
  1689.  
  1690.             Function    Closes down the graphics subsystem.
  1691.  
  1692.             Syntax      void MGL_exit(void);
  1693.  
  1694.             Prototype   mgraph.h
  1695.             in
  1696.  
  1697.             Remarks     MGL_exit() closes down the graphics
  1698.                         subsystem, deallocating any memory allocated
  1699.                         for use by the MGL, and restoring the system
  1700.                         back into the original text mode active
  1701.                         before the MGL was started.
  1702.  
  1703.             See also    MGL_init()
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.             26                      MegaGraph Graphics Library Reference
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.             MGL_fadePalette
  1724.  
  1725.             Function    Fades the values for programming the palette.
  1726.  
  1727.             Syntax      bool MGL_fadePalette(palette *dest,palette
  1728.                         *src,int numColors,uchar intensity);
  1729.  
  1730.             Prototype   mgraph.h
  1731.             in
  1732.  
  1733.             Parameters  dest - Pointer to destination palette
  1734.                         structure.
  1735.                         src - Pointer to source palette structure.
  1736.                         numColors - Number of colors in palette to
  1737.                         fade
  1738.                         intensity - Intensity value for the output
  1739.                         palette values.
  1740.  
  1741.             Remarks     MGL_fadePalette() will take the values from
  1742.                         one palette structure, fade the values and
  1743.                         store them into a second palette structure.
  1744.                         The actual hardware palette will not be
  1745.                         programmed, so you will then need to make a
  1746.                         call to MGL_setPalette() to make the changes
  1747.                         visiable.
  1748.  
  1749.                             intensity                        The           value is a number between 0 and
  1750.                         255 that defines the intensity of the output
  1751.                         values. An intensity of 255 will produce the
  1752.                         same output values as the input values. An
  1753.                         intensity of 128 will product values in the
  1754.                         output palette that are half the intensity of
  1755.                         the input palette.
  1756.  
  1757.                         The palette values are manipulated as arrays
  1758.                         of the         structure, defined as:                               palette
  1759.  
  1760.                         typedef struct {
  1761.                             uchar   red;
  1762.                             uchar   green;
  1763.                             uchar   blue;
  1764.                             } palette;
  1765.  
  1766.                         where red, green and blue define the color
  1767.                         components for that entry. Each color
  1768.                         component is defined as an 8 bit value with a
  1769.                         range of 0-255.
  1770.  
  1771.                         If the entire output palette is zero, then
  1772.                         the routine will return true, otherwise it
  1773.                         will return true.
  1774.  
  1775.             Return      True if the entire output palette is zero,
  1776.             value       false if not.
  1777.  
  1778.             See also    MGL_setPalette(), MGL_getPalette(),
  1779.                         MGL_rotatePalette()
  1780.  
  1781.  
  1782.  
  1783.             Chapter 6 - Console Library                               27
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.             MGL_fillEllipse
  1790.  
  1791.             Function    Fills an ellipse outline defined by a
  1792.                         bounding rectangle.
  1793.  
  1794.             Syntax      bool MGL_fillEllipse(rect extentRect);
  1795.  
  1796.             Prototype   mgraph.h
  1797.             in
  1798.  
  1799.             Parameters  extentRect - Bounding rectangle defining the
  1800.                         ellipse.
  1801.  
  1802.             Remarks     MGL_fillEllipse() fills an ellipse just
  1803.                         inside the mathematical boundary of
  1804.                         extentRect. The ellipse is filled in the
  1805.                         current pen color and style.
  1806.  
  1807.                         Note: This routine is more versatile than the
  1808.                         equivalent MGL_fillEllipseCoord() routine, as
  1809.                         you can have an ellipse with odd diameters
  1810.                         values, which you cannot get with the
  1811.                         MGL_fillEllipseCoord() routine.
  1812.  
  1813.             Return      True if ellipse was scan converted, false if
  1814.             value       an error occured (MGL_buf too small)..
  1815.  
  1816.             See also    MGL_ellipse(), MGL_ellipseCoord(),
  1817.                         MGL_fillEllipseCoord()
  1818.  
  1819.  
  1820.             MGL_fillEllipseArc
  1821.  
  1822.             Function    Fills an elliptical arc defined by a bounding
  1823.                         rectangle.
  1824.  
  1825.             Syntax      bool MGL_fillEllipseArc(rect extentRect,int
  1826.                         startAngle,int endAngle);
  1827.  
  1828.             Prototype   mgraph.h
  1829.             in
  1830.  
  1831.             Parameters  extentRect - Bounding rectangle defining the
  1832.                         arc.
  1833.                         startAngle - Starting angle for arc (in
  1834.                         degrees)
  1835.                         endAngle - Ending angle for arc (in degrees).
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.             28                      MegaGraph Graphics Library Reference
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.             Remarks     MGL_fillEllipseArc() fills an elliptical arc
  1856.                         forming a wedge, just inside the mathematical
  1857.                         boundary of extentRect. StartAngle specifies
  1858.                         where the arc begins and is treated MOD 360.
  1859.                         EndAngle specifies where the arc ends and is
  1860.                         treated MOD 360 also. The angles are given in
  1861.                         positive or negative degrees. Zero degrees is
  1862.                         at 3 o'clock, 90 is at 12 o'clock high, 180
  1863.                         is at 9 o'clock and 270 is at 6 o'clock.
  1864.                         Other angles are measured relative to the
  1865.                         enclosing rectangle. Thus an angle of 45
  1866.                         degrees always defines a line from the centre
  1867.                         of the rectangle through it's top right
  1868.                         corner, even if the rectangle isn't square.
  1869.  
  1870.                         The elliptical arc is filled in the current
  1871.                         pen color and style.
  1872.  
  1873.                         Note: This routine is more versatile than the
  1874.                         equivalent MGL_fillEllipseArcCoord() routine,
  1875.                         as you can have an elliptical arc with odd
  1876.                         diameter values, which you cannot get with
  1877.                         the MGL_fillEllipseArcCoord() routine.
  1878.  
  1879.             Return      True if the ellipse arc was scan converted,
  1880.             value       false if an error occurred (MGL_buf too
  1881.                         small).
  1882.  
  1883.             See also    MGL_fillEllipseArcCoord(), MGL_ellipseArc(),
  1884.                         MGL_ellipseArcCoord()
  1885.  
  1886.  
  1887.             MGL_fillEllipseArcCoord
  1888.  
  1889.             Function    Fills an elliptical arc defined by a centre
  1890.                         and radii.
  1891.  
  1892.             Syntax      bool MGL_fillEllipseArcCoord(int x,int y,int
  1893.                         xradius,int yradius,int startAngle,int
  1894.                         endAngle);
  1895.  
  1896.             Prototype   mgraph.h
  1897.             in
  1898.  
  1899.             Parameters  x,y - Centre of the elliptical arc.
  1900.                         xradius - X radius for the elliptical arc
  1901.                         yradius - Y radius for the elliptical arc
  1902.                         startAngle - Starting angle for arc (in
  1903.                         degrees)
  1904.                         endAngle - Ending angle for arc (in degrees).
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.             Chapter 6 - Console Library                               29
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.             Remarks     MGL_fillEllipseArcCoord() fills an elliptical
  1922.                         arc forming a wedge, given the centre, radii
  1923.                         and starting and endling angles. StartAngle
  1924.                         specifies where the arc begins and is treated
  1925.                         MOD 360. EndAngle specifies where the arc
  1926.                         ends and is treated MOD 360 also. The angles
  1927.                         are given in positive or negative degrees.
  1928.                         Zero degrees is at 3 o'clock, 90 is at 12
  1929.                         o'clock high, 180 is at 9 o'clock and 270 is
  1930.                         at 6 o'clock. Other angles are measured
  1931.                         relative to the enclosing rectangle. Thus an
  1932.                         angle of 45 degrees always defines a line
  1933.                         from the centre of the rectangle through it's
  1934.                         top right corner, even if the rectangle isn't
  1935.                         square.
  1936.  
  1937.                         The elliptical arc is filled in the current
  1938.                         pen color and style.
  1939.  
  1940.                         Note: This routine can only work with integer
  1941.                         semi-major and semi-minor axes, but can
  1942.                         sometimes be easier to work with (and it
  1943.                         provided for compatabilty with other graphics
  1944.                         packages).
  1945.  
  1946.             Return      True if the ellipse arc was scan converted,
  1947.             value       false if an error occurred (MGL_buf too
  1948.                         small).
  1949.  
  1950.             See also    MGL_ellipseArc(), MGL_ellipseArcCoord(),
  1951.                         MGL_fillEllipseArc().
  1952.  
  1953.  
  1954.             MGL_fillEllipseCoord
  1955.  
  1956.             Function    Fills an ellipse defined by a bounding
  1957.                         rectangle.
  1958.  
  1959.             Syntax      bool MGL_fillEllipseCoord(int x,int y,int
  1960.                         xradius,int yradius);
  1961.  
  1962.             Prototype   mgraph.h
  1963.             in
  1964.  
  1965.             Parameters  x,y - Centre of the ellipse
  1966.                         xradius - X radius for the ellipse
  1967.                         yradius - Y radius for the ellipse
  1968.  
  1969.             Remarks     MGL_fillEllipseCoord() fills an ellipse given
  1970.                         the centre and radii for the ellipse. The
  1971.                         ellipse is filled in the current pen color
  1972.                         and style.
  1973.  
  1974.                         Note: This routine can only work with integer
  1975.                         semi-major and semi-minor axes, but can
  1976.                         sometimes be easier to work with (and it
  1977.                         provided for compatability with other
  1978.                         graphics packages).
  1979.  
  1980.  
  1981.             30                      MegaGraph Graphics Library Reference
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.             Return      True if ellipse was scan converted, false if
  1989.             value       an error occured (MGL_buf too small)..
  1990.  
  1991.             See also    MGL_ellipse(), MGL_ellipseCoord(),
  1992.                         MGL_fillEllipse()
  1993.  
  1994.  
  1995.             MGL_fillGouraudPolygon
  1996.  
  1997.             Function    Fills a convex polygon with smooth shading.
  1998.  
  1999.             Syntax      bool MGL_fillGouraudPolygon(int count,point
  2000.                         *vArray,color_t *cArray,int xOffset,int
  2001.                         yOffset);
  2002.  
  2003.             Prototype   mgraph.h
  2004.             in
  2005.  
  2006.             Parameters  count - Number of vertices in polygon
  2007.                         vArray - Array of vertices in polygon
  2008.                         cArray - Array of vertex colors
  2009.                         xOffset - X coordinate offset value
  2010.                         yOffset - Y coordinate offset value
  2011.  
  2012.             Remarks     MGL_fillGouraudPolygon() scan converts a
  2013.                         filled        polygon, while smoothly                               convex
  2014.                         interpolating the color values between the
  2015.                         vertices in the polygon. A convex polygon is
  2016.                         defined as a polygon such that every
  2017.                         horizontal line drawn through the polygon
  2018.                         would cross exactly two active edges (neither
  2019.                         horizontal lines nor zero-length edges count
  2020.                         as active edges; both are acceptable anywhere
  2021.                         in the polygon). Right & left edges may cross
  2022.                         (polygons may be nonsimple). Attempting to
  2023.                         scan convert a polygon that does not fit this
  2024.                         description will produce unpredictable
  2025.                         results.
  2026.  
  2027.                         In order to ensure correct scan conversion of
  2028.                         polygons with shared vertices, the right and
  2029.                         bottom edges of the polygons are not scan
  2030.                         converted. All vertices are offset by
  2031.                         (xOffset,yOffset).
  2032.  
  2033.                         Note: You must call MGL_beginGouraud() before
  2034.                         calling this routine, and you      call                                                      must 
  2035.                         MGL_endGouraud() after drawing a set of one
  2036.                         or more shaded polygons. You cannot draw
  2037.                         anything else at the same time.
  2038.  
  2039.             Return      True if the polygon was scan converted, false
  2040.             value       if an error occurred.
  2041.  
  2042.             See also    MGL_fillPolygon(), MGL_fillPolygonFast(),
  2043.                         MGL_beginGouraud(), MGL_endGouraud().
  2044.  
  2045.  
  2046.  
  2047.             Chapter 6 - Console Library                               31
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.             MGL_fillPolygon
  2054.  
  2055.             Function    Fills an arbitrary polygon.
  2056.  
  2057.             Syntax      bool MGL_fillPolygon(int count,point
  2058.                         *vArray,int xOffset,int yOffset);
  2059.  
  2060.             Prototype   mgraph.h
  2061.             in
  2062.  
  2063.             Parameters  count - Number of vertices in polygon
  2064.                         vArray - Array of vertices in polygon
  2065.                         xOffset - X coordinate offset value
  2066.                         yOffset - Y coordinate offset value
  2067.  
  2068.             Remarks     MGL_fillPolygon() scan converts a filled
  2069.                         arbitrary polygon in the current color and
  2070.                         style. By default the routine will determine
  2071.                         the type of the polygon being scan converted,
  2072.                         and will scan convert convex polygons using a
  2073.                         faster scan conversion routine, otherwise a
  2074.                         general polygon scan conversion routine will
  2075.                         be used. Thus you can scan convert any type
  2076.                         of polygon that you desire.
  2077.  
  2078.                           convex                        A        polygon is defined as a polygon such
  2079.                         that every horizontal line drawn through the
  2080.                         polygon would cross exactly two active edges
  2081.                         (neither horizontal lines nor zero-length
  2082.                         edges count as active edges; both are
  2083.                         acceptable anywhere in the polygon). Right &
  2084.                         left edges may cross (polygons may be
  2085.                         nonsimple). Attempting to scan convert a
  2086.                         polygon that does not fit this description
  2087.                         will produce unpredictable results.
  2088.  
  2089.                         Non simple or self intersecting polygons will
  2090.                         be scan converted using the standard in/out
  2091.                         rule, where points are defined as being
  2092.                         inside after crossing the first edge in the
  2093.                         polygon, and then alternate between defined
  2094.                         as inside then outside after crossing each
  2095.                         active edge in the polygon.
  2096.  
  2097.                         In order to ensure correct scan conversion of
  2098.                         polygons with shared vertices, the right and
  2099.                         bottom edges of the polygons are not scan
  2100.                         converted. All vertices are offset by
  2101.                         (xOffset,yOffset).
  2102.  
  2103.                         You may also use the MGL_setPolygonType()
  2104.                         routine to specify the type of polygons being
  2105.                         scan converted. This may be AUTO_POLYGON,
  2106.                         CONVEX_POLYGON or COMPLEX_POLYGON. Explicitly
  2107.                         setting the polygon type will speed the
  2108.                         drawing process.
  2109.  
  2110.  
  2111.  
  2112.  
  2113.             32                      MegaGraph Graphics Library Reference
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.             Return      True if the polygon was scan converted, false
  2120.             value       if an error occurred.
  2121.  
  2122.             See also    MGL_fillPolygonFast(),
  2123.                         MGL_fillGouraudPolygon, MGL_setPolygonType()
  2124.  
  2125.  
  2126.             MGL_fillPolygonFast
  2127.  
  2128.             Function    Fills a convex polygon quickly.
  2129.  
  2130.             Syntax      bool MGL_fillPolygonFast(int count,point
  2131.                         *vArray,int xOffset,int yOffset);
  2132.  
  2133.             Prototype   mgraph.h
  2134.             in
  2135.  
  2136.             Parameters  count - Number of vertices in polygon
  2137.                         vArray - Array of vertices in polygon
  2138.                         xOffset - X coordinate offset value
  2139.                         yOffset - Y coordinate offset value
  2140.  
  2141.             Remarks     MGL_fillPolygonFast() scan converts a filled
  2142.                         convex polygon in the current color and
  2143.                         style. A        polygon is defined as a                                 convex
  2144.                         polygon such that every horizontal line drawn
  2145.                         through the polygon would cross exactly two
  2146.                         active edges (neither horizontal lines nor
  2147.                         zero-length edges count as active edges; both
  2148.                         are acceptable anywhere in the polygon).
  2149.                         Right & left edges may cross (polygons may be
  2150.                         nonsimple). Attempting to scan convert a
  2151.                         polygon that does not fit this description
  2152.                         will produce unpredictable results.
  2153.  
  2154.                         This is the fastest method to render
  2155.                         polygonal shapes such as triangles and
  2156.                         quadrilaterals.
  2157.  
  2158.                         In order to ensure correct scan conversion of
  2159.                         polygons with shared vertices, the right and
  2160.                         bottom edges of the polygons are not scan
  2161.                         converted. All vertices are offset by
  2162.                         (xOffset,yOffset).
  2163.  
  2164.                         Note: You      call MGL_beginDrawing() before                                  must
  2165.                         calling this routine, and you must call
  2166.                         MGL_endDrawing() after scan converting one or
  2167.                         more convex polygons. You may call other MGL
  2168.                         routines at the same time however.
  2169.  
  2170.             Return      True if the polygon was scan converted, false
  2171.             value       if an error occurred.
  2172.  
  2173.             See also    MGL_fillPolygon(), MGL_fillGouraudPolygon(),
  2174.                         MGL_beginDrawing(), MGL_endDrawing().
  2175.  
  2176.  
  2177.  
  2178.  
  2179.             Chapter 6 - Console Library                               33
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.             MGL_fillRect
  2186.  
  2187.             Function    Draws a filled rectangle.
  2188.  
  2189.             Syntax      void MGL_fillRect(rect r);
  2190.  
  2191.             Prototype   mgraph.h
  2192.             in
  2193.  
  2194.             Parameters  r - Rectangle to fill
  2195.  
  2196.             Remarks     MGL_fillRect() fills a rectangle in the
  2197.                         current current drawing attributes. The
  2198.                         mathematical definition of a rectangle does
  2199.                         not include the right and bottom endpoints,
  2200.                         so effectively the right and bottom endpoints
  2201.                         are not scan converted (solving problems with
  2202.                         shared vertices).
  2203.  
  2204.             See also    MGL_fillRectCoord(), MGL_fillRectPt().
  2205.  
  2206.  
  2207.             MGL_fillRectCoord
  2208.  
  2209.             Function    Draws a filled rectangle.
  2210.  
  2211.             Syntax      void MGL_fillRectCoord(int left,int top,int
  2212.                         right,int bottom);
  2213.  
  2214.             Prototype   mgraph.h
  2215.             in
  2216.  
  2217.             Parameters  left - Left edge of rectangle
  2218.                         top - Top egde of rectangle
  2219.                         right - Right edge of rectangle
  2220.                         bottom - Bottom edge of rectangle
  2221.  
  2222.             Remarks     MGL_fillRectCoord() fills a rectangle defined
  2223.                         by the coordinates of its edges in the
  2224.                         current current drawing attributes. The
  2225.                         mathematical definition of a rectangle does
  2226.                         not include the right and bottom endpoints,
  2227.                         so effectively the right and bottom endpoints
  2228.                         are not scan converted (solving problems with
  2229.                         shared vertices).
  2230.  
  2231.             See also    MGL_fillRect(), MGL_fillRectPt().
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.             34                      MegaGraph Graphics Library Reference
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.             MGL_fillRectPt
  2252.  
  2253.             Function    Draws a filled rectangle defined by two
  2254.                         points.
  2255.  
  2256.             Syntax      void MGL_fillRectPt(point lt,point rb);
  2257.  
  2258.             Prototype   mgraph.h
  2259.             in
  2260.  
  2261.             Parameters  lt - Point defining the left, top corner of
  2262.                         the rectangle
  2263.                         rb - Point defining the right, bottom corner
  2264.                         of rectangle.
  2265.  
  2266.             Remarks     MGL_fillRectPt() fills a rectangle defined by
  2267.                         two points in the current current drawing
  2268.                         attributes. The mathematical definition of a
  2269.                         rectangle does not include the right and
  2270.                         bottom endpoints, so effectively the right
  2271.                         and bottom endpoints are not scan converted
  2272.                         (solving problems with shared vertices).
  2273.  
  2274.             See also    MGL_fillRect(), MGL_fillRectCoord().
  2275.  
  2276.  
  2277.             MGL_getActivePage
  2278.  
  2279.             Function    Returns the currently active hardware page.
  2280.  
  2281.             Syntax      void MGL_getActivePage(void);
  2282.  
  2283.             Prototype   mgraph.h
  2284.             in
  2285.  
  2286.             Remarks     MGL_getActivePage() returns the currently
  2287.                         active hardware video page number. The first
  2288.                         hardware video page is number 0, the second
  2289.                         is 1 and so on. The number of available
  2290.                         hardware video pages depends on the type of
  2291.                         underlying hardware, the video mode
  2292.                         resolution and amount of video memory
  2293.                         installed. Thus not all video modes support
  2294.                         multiple hardware video pages,
  2295.  
  2296.             Return      Currently active hardware page.
  2297.             value
  2298.  
  2299.             See also    MGL_setActivePage(), MGL_getVisualPage(),
  2300.                         MGL_setVisualPage().
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.             Chapter 6 - Console Library                               35
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.             MGL_getArcCoords
  2318.  
  2319.             Function    Returns the starting and ending arc
  2320.                         coordinates.
  2321.  
  2322.             Syntax      void MGL_getArcCoords(arc_coords *coords);
  2323.  
  2324.             Prototype   mgraph.h
  2325.             in
  2326.  
  2327.             Parameters  coords - Pointer to structure to store
  2328.                         coordinates
  2329.  
  2330.             Remarks     MGL_getArcCoords() returns the centre
  2331.                         coordinate, and starting and ending points on
  2332.                         the ellipse that define the last elliptical
  2333.                         arc to be rendered. You can then use these
  2334.                         coordinate values to draw a line from the
  2335.                         centre of the ellipse to the starting and
  2336.                         ending points to complete the outline of the
  2337.                         elliptical wedge.
  2338.  
  2339.                         The coordinates are returned in the
  2340.                         arc_coords structure which is defined as:
  2341.  
  2342.                         typedef struct {
  2343.                             int     x,y;
  2344.                             int     startX,startY;
  2345.                             int     endX,endY;
  2346.                             } arc_coords;
  2347.  
  2348.                         where (x,y) defines the centre of the
  2349.                         ellipse, and (startX,startY) defines the
  2350.                         starting point on the ellipse and (endX,endY)
  2351.                         defines the ending point on the ellipse.
  2352.  
  2353.                         Note: This routine must be called immediately
  2354.                         after calling the MGL_ellipseArc() routines.
  2355.  
  2356.  
  2357.             MGL_getAspectRatio
  2358.  
  2359.             Function    Returns the current video mode aspect ratio.
  2360.  
  2361.             Syntax      int MGL_getAspectRatio(void);
  2362.  
  2363.             Prototype   mgraph.h
  2364.             in
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.             36                      MegaGraph Graphics Library Reference
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.             Remarks     MGL_getAspectRatio() returns the aspect ratio
  2384.                         of the currently active output device's
  2385.                         physical pixels. This ratio is equal to:
  2386.  
  2387.                                   pixel x size                                          x                                           1000
  2388.                                   pixel y size
  2389.  
  2390.                         The device aspect ratio can be used to
  2391.                         display circles and squares on the display
  2392.                         device by approximating them with ellipses
  2393.                         and rectangles of the appropriate dimensions.
  2394.                         Thus in order to determine the number of
  2395.                         pixels in the y direction for a square with
  2396.                         100 pixels in the x direction, we can simply
  2397.                         use the formula:
  2398.  
  2399.                         y_pixels = ((long)x_pixels * 1000) /
  2400.                         aspectratio
  2401.  
  2402.                         Note the cast to a long to avoid arithmetic
  2403.                         overflow, as the apsect ratio is returned as
  2404.                         an integer value with 1000 being a 1:1 aspect
  2405.                         ratio.
  2406.  
  2407.             Return      Current video mode aspect ratio * 1000.
  2408.             value
  2409.  
  2410.             See also    MGL_setAspectRatio()
  2411.  
  2412.  
  2413.             MGL_getAttributes
  2414.  
  2415.             Function    Returns a copy of the current attribute list
  2416.  
  2417.             Syntax      void MGL_getAttributes(attributes *attr);
  2418.  
  2419.             Prototype   mgraph.h
  2420.             in
  2421.  
  2422.             Parameters  attr - Pointer to structure to store
  2423.                         attribute values in
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.             Chapter 6 - Console Library                               37
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.             Remarks     MGL_getAttributes() returns a copy of the
  2450.                         currently active attribute lists. You can use
  2451.                         this routine to save the state of the MGL and
  2452.                         later restore this state with the
  2453.                         MGL_restoreAttributes() routine. The
  2454.                         attribute values are returned in a structure
  2455.                         define as:
  2456.  
  2457.                         typedef struct {
  2458.                             color_t         color;
  2459.                             color_t         backColor;
  2460.                             int             markerSize;
  2461.                             marker_style    markerStyle;
  2462.                             color_t         markerColor;
  2463.                             color_t         bdr_bright;
  2464.                             color_t         bdr_dark;
  2465.                             point           CP;
  2466.                             write_mode      writeMode;
  2467.                             fill_style      penStyle;
  2468.                             int             penHeight;
  2469.                             int             penWidth;
  2470.                             pattern         penPat;
  2471.                             pixpattern      penPixPat;
  2472.                             rect            viewport;
  2473.                             rect            clipRect;
  2474.                             bool            clip;
  2475.                             int             poly_type;
  2476.                             text_settings   tsettings;
  2477.                             } attributes;
  2478.  
  2479.                         Note: This routine does not return any values
  2480.                         to do with the current viewport stack. This
  2481.                         will need to be maintained separately.
  2482.  
  2483.             See also    MGL_restoreAttributes()
  2484.  
  2485.  
  2486.             MGL_getBackColor
  2487.  
  2488.             Function    Returns the current background color value.
  2489.  
  2490.             Syntax      color_t MGL_getBackColor(void);
  2491.  
  2492.             Prototype   mgraph.h
  2493.             in
  2494.  
  2495.             Remarks     MGL_getBackColor() returns the current
  2496.                         background color value. The background color
  2497.                         value is used to clear the display and
  2498.                         viewport with the MGL_clearDevice() and
  2499.                         MGL_clearViewport() routines, and is also
  2500.                         used for filling solid primitives in the
  2501.                         BITMAP_PATTERN_OPAQUE fill mode.
  2502.  
  2503.             Return      Current background color value.
  2504.             value
  2505.  
  2506.  
  2507.  
  2508.  
  2509.             38                      MegaGraph Graphics Library Reference
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.             See also    MGL_setBackColor(), MGL_getColor(),
  2516.                         MGL_setColor()
  2517.  
  2518.  
  2519.             MGL_getBorderColors
  2520.  
  2521.             Function    Returns the current border color values.
  2522.  
  2523.             Syntax      void MGL_getBorderColors(color_t
  2524.                         *bright,color_t *dark);
  2525.  
  2526.             Prototype   mgraph.h
  2527.             in
  2528.  
  2529.             Parameters  bright - Place to store bright color value
  2530.                         dark - Place to store dark color value
  2531.  
  2532.             Remarks     MGL_getBorderColors() returns the currently
  2533.                         active border colors values. There are two
  2534.                         border color defined by the MGL, the bright
  2535.                         border color value and the      border color                                                   dark
  2536.                         value. These values are used by the
  2537.                         MGL_drawBorder(), MGL_drawHDivider() and
  2538.                         MGL_drawVDivider() routines to determine the
  2539.                         colors to draw the psuedo 3D borders in.
  2540.                         These values will be set automatically for
  2541.                         you by default when the MGL is initialised,
  2542.                         but you will need to change these values if
  2543.                         you modify the palette.
  2544.  
  2545.             See also    MGL_setBorderColors(), MGL_drawBorder(),
  2546.                         MGL_drawHDivider(), MGL_drawVDivider()
  2547.  
  2548.  
  2549.             MGL_getCharMetrics
  2550.  
  2551.             Function    Computes the metrics for a specific
  2552.                         character.
  2553.  
  2554.             Syntax      void MGL_getCharMetrics(char ch,metrics
  2555.                         *metrics);
  2556.  
  2557.             Prototype   mgraph.h
  2558.             in
  2559.  
  2560.             Parameters  metrics - Place to store the resulting
  2561.                         metrics.
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.             Chapter 6 - Console Library                               39
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.             Remarks     MGL_getCharMetrics() computes the character
  2582.                         metrics for a specific character. The
  2583.                         character metrics define specific characters
  2584.                         width, height, asecent, descent and other
  2585.                         values. These values can then be used to
  2586.                         correctly position the character with pixel
  2587.                         precise positioning. The metrics are computed
  2588.                         and returned in the metrics structure defined
  2589.                         as:
  2590.  
  2591.                         typedef struct {
  2592.                             int             width;
  2593.                             int             fontWidth;
  2594.                             int             fontHeight;
  2595.                             int             ascent;
  2596.                             int             descent;
  2597.                             int             leading;
  2598.                             int             kern;
  2599.                             } metrics;
  2600.  
  2601.                         where width defines the actual width in
  2602.                         pixels for the character, fontWidth defines
  2603.                         the width of the character including any
  2604.                         extra padding between it and the next
  2605.                         character and kern defines the actual kern
  2606.                         value for the specific character. All the
  2607.                         other values will be the same as those for
  2608.                         the entire font file.
  2609.  
  2610.                         All values are defined in pixels and will be
  2611.                         as accurate as possible given the current
  2612.                         fonts scaling factor (currently only vector
  2613.                         fonts can be scaled).
  2614.  
  2615.             See also    MGL_getFontMetrics()
  2616.  
  2617.  
  2618.             MGL_getClipMode
  2619.  
  2620.             Function    Returns the current clipping mode.
  2621.  
  2622.             Syntax      bool MGL_getClipMode(void);
  2623.  
  2624.             Prototype   mgraph.h
  2625.             in
  2626.  
  2627.             Remarks     MGL_getClipMode() returns the current
  2628.                         clipping mode. You can selectively turn
  2629.                         clipping on and off for the MGL, in order to
  2630.                         speed up some operations. Clipping is turned
  2631.                         on by default, and generally you will want to
  2632.                         leave clipping enabled.
  2633.  
  2634.             Return      True if clipping is on, false if not.
  2635.             value
  2636.  
  2637.             See also    MGL_setClipMode(), MGL_getClipRect(),
  2638.                         MGL_setClipRect()
  2639.  
  2640.  
  2641.             40                      MegaGraph Graphics Library Reference
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.  
  2649.             MGL_getClipRect
  2650.  
  2651.             Function    Returns the current clipping rectangle.
  2652.  
  2653.             Syntax      void MGL_getClipRect(rect *clip);
  2654.  
  2655.             Prototype   mgraph.h
  2656.             in
  2657.  
  2658.             Parameters  clip - Place to store the current clipping
  2659.                         rectangle
  2660.  
  2661.             Remarks     MGL_getClipRect() returns the current
  2662.                         clipping rectangle coordinates. The current
  2663.                         clipping rectangle is used to clip all
  2664.                         output, and is always defined as being
  2665.                         relative to the currently active viewport The
  2666.                         clipping rectangle can be no larger than the
  2667.                         currently active viewport.
  2668.  
  2669.             See also    MGL_setClipRect, MGL_getClipMode(),
  2670.                         MGL_getClipMode().
  2671.  
  2672.  
  2673.             MGL_getColor
  2674.  
  2675.             Function    Returns the current foreground color.
  2676.  
  2677.             Syntax      color_t MGL_getColor(void);
  2678.  
  2679.             Prototype   mgraph.h
  2680.             in
  2681.  
  2682.             Remarks     MGL_getColor() returns the current foreground
  2683.                         color values. The foreground color value is
  2684.                         used to draw all primitives.
  2685.  
  2686.             Return      Current foreground color.
  2687.             value
  2688.  
  2689.             See also    MGL_setColor(), MGL_getBackColor(),
  2690.                         MGL_setBackColor()
  2691.  
  2692.  
  2693.             MGL_getCP
  2694.  
  2695.             Function    Returns the current position value.
  2696.  
  2697.             Syntax      void MGL_getCP(point* CP);
  2698.  
  2699.             Prototype   mgraph.h
  2700.             in
  2701.  
  2702.             Parameters  CP - place to store the current position
  2703.  
  2704.  
  2705.  
  2706.  
  2707.             Chapter 6 - Console Library                               41
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.             Remarks     MGL_getCP() returns the current position
  2714.                         (CP). The CP is the current graphics cursor
  2715.                         position, and is used by a number of routines
  2716.                         to determine where to being drawing output.
  2717.                         You can use the MGL_moveTo() routine to
  2718.                         directly move the CP to a new position.
  2719.  
  2720.             See also    MGL_moveTo(), MGL_moveRel(), MGL_lineTo(),
  2721.                         MGL_lineRel(), MGL_drawStr().
  2722.  
  2723.  
  2724.             MGL_getCursorColor
  2725.  
  2726.             Function    Returns the current mouse cursor color.
  2727.  
  2728.             Syntax      color_t MGL_getCursorColor(void);
  2729.  
  2730.             Prototype   mgraph.h
  2731.             in
  2732.  
  2733.             Remarks     MGL_getCursorColor() returns the currently
  2734.                         active mouse cursor color. The mouse cursor
  2735.                         color is used to determine what foreground
  2736.                         color is used to draw the mouse cursor in.
  2737.  
  2738.             Return      Current mouse cursor color value.
  2739.             value
  2740.  
  2741.             See also    MGL_setCursorColor()
  2742.  
  2743.  
  2744.             MGL_getDefaultPalette
  2745.  
  2746.             Function    Returns the default palette for video mode.
  2747.  
  2748.             Syntax      void MGL_getDefaultPalette(palette *pal);
  2749.  
  2750.             Prototype   mgraph.h
  2751.             in
  2752.  
  2753.             Parameters  pal - Place to store the default palette
  2754.                         values.
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.             42                      MegaGraph Graphics Library Reference
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.             Remarks     MGL_getDefaultPalette() returns a copy of the
  2780.                         default palette for the current video mode.
  2781.                         This can be used to reset the palette to the
  2782.                         original default values that the palette is
  2783.                         programmed with when the MGL is initialised.
  2784.  
  2785.                         The palette values are manipulated as arrays
  2786.                         of the         structure, defined as:                               palette
  2787.  
  2788.                         typedef struct {
  2789.                             uchar   red;
  2790.                             uchar   green;
  2791.                             uchar   blue;
  2792.                             } palette;
  2793.  
  2794.                         where red, green and blue define the color
  2795.                         components for that entry. Each color
  2796.                         component is defined as an 8 bit value with a
  2797.                         range of 0-255.
  2798.  
  2799.             See also    MGL_setPalette(), MGL_getPalette()
  2800.  
  2801.  
  2802.             MGL_getDivot
  2803.  
  2804.             Function    Saves a divot of video memory in system RAM
  2805.  
  2806.             Syntax      void MGL_getDivot(rect r,void *divot)
  2807.  
  2808.             Prototype   mgraph.h
  2809.             in
  2810.  
  2811.             Parameters  r - Rectangle defining the divot to save
  2812.                         divot - Pointer to area to store video memory
  2813.                         in
  2814.  
  2815.             Remarks     MGL_getDivot() copies a block of video memory
  2816.                         from the current video page into system RAM.
  2817.                           divot                        A       is defined as being a rectangular
  2818.                         area of video memory that you wish to save.
  2819.                         However when the divot is saved, it may also
  2820.                         save other data slightly outside of the
  2821.                         specified area in order to increase the speed
  2822.                         at which the divot can be saved and restored.
  2823.                         Thus the divot routines save and restore the
  2824.                         video memory in the fastest possible manner.
  2825.                         This can be used to store the video memory
  2826.                         behind pull down menus etc.
  2827.  
  2828.                         You must pre-allocate enough space to hold
  2829.                         the entire divot in system RAM. Use the
  2830.                         MGL_divotSize() routine to determine the size
  2831.                         of the memory block required to store the
  2832.                         divot.
  2833.  
  2834.             See also    MGL_putDivot(), MGL_divotSize()
  2835.  
  2836.  
  2837.  
  2838.  
  2839.             Chapter 6 - Console Library                               43
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.             MGL_getDivotCoord
  2846.  
  2847.             Function    Saves a divot of video memory into system RAM
  2848.  
  2849.             Syntax      void MGL_getDivotCoord(int left,int top,int
  2850.                         right,int bottom,void *divot);
  2851.  
  2852.             Prototype   mgraph.h
  2853.             in
  2854.  
  2855.             Parameters  left - Left edge of area to save
  2856.                         top - Top egde of area to save
  2857.                         right - Right edge of area to save
  2858.                         bottom - Bottom edge of area to save
  2859.                         divot - Pointer to area to store the video
  2860.                         memory in
  2861.  
  2862.             Remarks     MGL_getDivotCoord() copies a block of video
  2863.                         memory from the current video page into
  2864.                         system RAM. A divot is defined as being a
  2865.                         rectangular area of video memory that you
  2866.                         wish to save. However when the divot is
  2867.                         saved, it may also save other data slightly
  2868.                         outside of the specified area in order to
  2869.                         increase the speed at which the divot can be
  2870.                         saved and restored. Thus the divot routines
  2871.                         save and restore the video memory in the
  2872.                         fastest possible manner. This can be used to
  2873.                         store the video memory behind pull down menus
  2874.                         etc.
  2875.  
  2876.                         You must pre-allocate enough space to hold
  2877.                         the entire divot in system RAM. Use the
  2878.                         MGL_divotSize() routine to determine the size
  2879.                         of the memory block required to store the
  2880.                         divot.
  2881.  
  2882.             See also    MGL_getDivot(), MGL_putDivot(),
  2883.                         MGL_divotSize()
  2884.  
  2885.  
  2886.             MGL_getDriver
  2887.  
  2888.             Function    Returns the current video device driver id
  2889.  
  2890.             Syntax      int MGL_getDriver(void);
  2891.  
  2892.             Prototype   mgraph.h
  2893.             in
  2894.  
  2895.             Remarks     MGL_getDriver() returns the numerical id of
  2896.                         the currently active video device driver.
  2897.                         This value can be converted in a printable
  2898.                         representation with the MGL_driverName()
  2899.                         routine.
  2900.  
  2901.             Return      Current video device driver id.
  2902.             value
  2903.  
  2904.  
  2905.             44                      MegaGraph Graphics Library Reference
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.             See also    MGL_driverName(), MGL_getMode()
  2913.  
  2914.  
  2915.             MGL_getFont
  2916.  
  2917.             Function    Returns the currently active font.
  2918.  
  2919.             Syntax      font *MGL_getFont(void);
  2920.  
  2921.             Prototype   mgraph.h
  2922.             in
  2923.  
  2924.             Remarks     MGL_getFont() returns a pointer to the
  2925.                         currently active font. The currently active
  2926.                         font is used to perform all text output by
  2927.                         the MGL.
  2928.  
  2929.             Return      Pointer to currently active font.
  2930.             value
  2931.  
  2932.             See also    MGL_useFont(), MGL_loadFont(),
  2933.                         MGL_unloadFont()
  2934.  
  2935.  
  2936.             MGL_getFontMetrics
  2937.  
  2938.             Function    Returns the currently active font metrics.
  2939.  
  2940.             Syntax      void MGL_getFontMetrics(metrics *metrics);
  2941.  
  2942.             Prototype   mgraph.h
  2943.             in
  2944.  
  2945.             Parameters  metrics - Place to store the font metrics.
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.             Chapter 6 - Console Library                               45
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.             Remarks     MGL_getFontMetrics() computes the font
  2978.                         metrics for the current font. The metrics are
  2979.                         computed and returned in the metrics
  2980.                         structure defined as:
  2981.  
  2982.                         typedef struct {
  2983.                             int             width;
  2984.                             int             fontWidth;
  2985.                             int             fontHeight;
  2986.                             int             ascent;
  2987.                             int             descent;
  2988.                             int             leading;
  2989.                             int             kern;
  2990.                             } metrics;
  2991.  
  2992.                         where width defines the maximum physical
  2993.                         width of all characters in the font,
  2994.                         fontWidth defines the maximum width of all
  2995.                         the characters in the font including any
  2996.                         extra padding between each character. The
  2997.                         fontWidth value of each character is used to
  2998.                         advance the CP to the start of the next
  2999.                         character, and can be larger than the actual
  3000.                         character width (in order to put space
  3001.                         between the characters). The ascent and
  3002.                         descent values define the values from the
  3003.                         baseline of the font to the highest and
  3004.                         lowest points of all characters. The leading
  3005.                         value defines the number of pixels between
  3006.                         each line of text, and the kern value defines
  3007.                         the maximum kerning value for the font (how
  3008.                         far certain characters can extend behind the
  3009.                         character start position).
  3010.  
  3011.                         All values are defined in pixels and will be
  3012.                         as accurate as possible given the current
  3013.                         fonts scaling factor (currently only vector
  3014.                         fonts can be scaled).
  3015.  
  3016.             See also    MGL_getCharMetrics().
  3017.  
  3018.  
  3019.             MGL_getImage
  3020.  
  3021.             Function    Copies of block of video memory to system
  3022.                         RAM.
  3023.  
  3024.             Syntax      void MGL_getImage(rect r,void *image)
  3025.  
  3026.             Prototype   mgraph.h
  3027.             in
  3028.  
  3029.             Parameters  r - Rectangle defining the image to save
  3030.                         image - Place to store the image data.
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.             46                      MegaGraph Graphics Library Reference
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.             Remarks     MGL_getImage() copies of block of video
  3044.                         memory into a system RAM buffer. The image
  3045.                         can then be modified in system RAM, and
  3046.                         restored to video RAM in another location.
  3047.                         MGL_getImage() is pixel exact so it only
  3048.                         copies the pixels that you specify, so it may
  3049.                         be slower than the MGL_getDivot() routine.
  3050.  
  3051.                         You must pre-allocate enough space to hold
  3052.                         the entire image in system RAM. Use the
  3053.                         MGL_imageSize() routine to determine the size
  3054.                         of the memory block required to store the
  3055.                         image.
  3056.  
  3057.             See also    MGL_getImageCoord(), MGL_putImage(),
  3058.                         MGL_putImageCoord(), MGL_imageSize().
  3059.  
  3060.  
  3061.             MGL_getImageCoord
  3062.  
  3063.             Function    Copies a block of video memory to system RAM.
  3064.  
  3065.             Syntax      void MGL_getImageCoord(int left,int top,int
  3066.                         right,int bottom,void *image);
  3067.  
  3068.             Prototype   mgraph.h
  3069.             in
  3070.  
  3071.             Parameters  left - Left edge of area to save
  3072.                         top - Top egde of area to save
  3073.                         right - Right edge of area to save
  3074.                         bottom - Bottom edge of area to save
  3075.                         image - Pointer to area to store the video
  3076.                         memory in
  3077.  
  3078.             Remarks     MGL_getImageCoord copies of block of video
  3079.                         memory into a system RAM buffer. The image
  3080.                         can then be modified in system RAM, and
  3081.                         restored to system RAM in another location.
  3082.                         MGL_getImageCoord is pixel exact so it only
  3083.                         copies the pixels that you specify, so it may
  3084.                         be slower than the MGL_getDivot() routine.
  3085.  
  3086.                         You must pre-allocate enough space to hold
  3087.                         the entire image in system RAM. Use the
  3088.                         MGL_imageSize() routine to determine the size
  3089.                         of the memory block required to store the
  3090.                         image.
  3091.  
  3092.             See also    MGL_getImage(), MGL_putImage(),
  3093.                         MGL_putImageCoord(), MGL_imageSize()
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.             Chapter 6 - Console Library                               47
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.             MGL_getMarkerColor
  3110.  
  3111.             Function    Returns the current marker color value.
  3112.  
  3113.             Syntax      color_t MGL_getMarkerColor(void);
  3114.  
  3115.             Prototype   mgraph.h
  3116.             in
  3117.  
  3118.             Remarks     MGL_getMarkerColor returns the current marker
  3119.                         color value. The marker color is used when
  3120.                         drawing markers with the MGL_marker()
  3121.                         routine.
  3122.  
  3123.             Return      Current marker color value.
  3124.             value
  3125.  
  3126.             See also    MGL_setMarkerColor(), MGL_marker(),
  3127.                         MGL_polyMarker()
  3128.  
  3129.  
  3130.             MGL_getMarkerSize
  3131.  
  3132.             Function    Returns the current marker size value
  3133.  
  3134.             Syntax      int MGL_getMarkerSize(void);
  3135.  
  3136.             Prototype   mgraph.h
  3137.             in
  3138.  
  3139.             Remarks     MGL_getMarkerSize() returns the current
  3140.                         marker size. The marker size is used to
  3141.                         determine how big to draw the markers that
  3142.                         are drawn with the MGL_marker() routine. The
  3143.                         size is defined as the dimension from the
  3144.                         middle of the marker to the edges, so the
  3145.                         actual dimensions of the marker will be twice
  3146.                         the maker size plus 1. If marker size of 1
  3147.                         will define a marker that is contained within
  3148.                         a rectangle 3 pixels wide.
  3149.  
  3150.             Return      Current marker size
  3151.             value
  3152.  
  3153.             See also    MGL_setMarkerSize(), MGL_setMarkerStyle(),
  3154.                         MGL_getMarkerStyle(), MGL_marker(),
  3155.                         MGL_polyMarker()
  3156.  
  3157.  
  3158.             MGL_getMarkerStyle
  3159.  
  3160.             Function    Returns the current marker style.
  3161.  
  3162.             Syntax      int MGL_getMarkerStyle(void);
  3163.  
  3164.             Prototype   mgraph.h
  3165.             in
  3166.  
  3167.  
  3168.  
  3169.             48                      MegaGraph Graphics Library Reference
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.             Remarks     MGL_getMarkerStyle() returns the current
  3176.                         marker style value. The marker style defines
  3177.                         the type of marker to be rendered. Currently
  3178.                         the MGL defines the following markers:
  3179.  
  3180.                         MARKER_SQUARE - A solid square
  3181.                         MARKER_CIRCLE - A solid circle
  3182.                         MARKER_X      - A cross made of two lines
  3183.  
  3184.             Return      Current marker style value.
  3185.             value
  3186.  
  3187.             See also    MGL_setMarkerSize(), MGL_getMarkerSize(),
  3188.                         MGL_setMarkerStyle(), MGL_marker(),
  3189.                         MGL_polyMarker()
  3190.  
  3191.  
  3192.             MGL_getMode
  3193.  
  3194.             Function    Returns the current video mode number.
  3195.  
  3196.             Syntax      int MGL_getMode(void);
  3197.  
  3198.             Prototype   mgraph.h
  3199.             in
  3200.  
  3201.             Remarks     MGL_getMode() returns the currently active
  3202.                         video mode number. This number can be
  3203.                         converted to a printable form using the
  3204.                         MGL_modeName() routine.
  3205.  
  3206.             Return      Current video mode number.
  3207.             value
  3208.  
  3209.             See also    MGL_init(), MGL_modeName()
  3210.  
  3211.  
  3212.             MGL_getPalette
  3213.  
  3214.             Function    Obtains the currently active palette values.
  3215.  
  3216.             Syntax      void MGL_getPalette(palette *pal,int
  3217.                         numColors,int startIndex);
  3218.  
  3219.             Prototype   mgraph.h
  3220.             in
  3221.  
  3222.             Parameters  pal - Place to store the retrieved values
  3223.                         numColors - Number of color values to
  3224.                         retrieve
  3225.                         startIndex - Starting palette index value to
  3226.                         retrieve
  3227.  
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.             Chapter 6 - Console Library                               49
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.             Remarks     MGL_getPalette() obtains part or all of the
  3242.                         currently active palette values and stores it
  3243.                         in the array pal. You can specify only a
  3244.                         subset of the palette values to be obtained
  3245.                         with the startIndex and numColors arguments.
  3246.  
  3247.                         Thus to save the entire palette in a 256
  3248.                         color video mode, you would use (assuming
  3249.                         enough space for the palette has been
  3250.                         allocated):
  3251.  
  3252.                             MGL_getPalette(pal,255,0);
  3253.  
  3254.                         or to get the top half of the palette you
  3255.                         would use:
  3256.  
  3257.                             MGL_getPalette(pal,128,128);
  3258.  
  3259.                         You should ensure that you have allocated
  3260.                         enough memory to hold all of the palette
  3261.                         values that you wish to read. You can use
  3262.                         MGL_getPaletteSize() to determine the size
  3263.                         required to save the entire palette.
  3264.  
  3265.             See also    MGL_getPaletteEntry(), MGL_setPalette(),
  3266.                         MGL_getDefaultPalette()
  3267.  
  3268.  
  3269.             MGL_getPaletteEntry
  3270.  
  3271.             Function    Returns the value of a single palette entry
  3272.  
  3273.             Syntax      void MGL_getPaletteEntry(int entry,uchar
  3274.                         *red,uchar *green,uchar *blue);
  3275.  
  3276.             Prototype   mgraph.h
  3277.             in
  3278.  
  3279.             Parameters  entry - Palette index to read
  3280.                         red - Place to store the red component
  3281.                         green - Place to store the green component
  3282.                         blue - Place to store the green component
  3283.  
  3284.             Remarks     MGL_getPaletteEntry() obtains the color
  3285.                         values of a single palette entry. If you wish
  3286.                         to obtain more than a single palette index
  3287.                         you should use the MGL_getPalette() routine
  3288.                         which is faster for multiple entries.
  3289.  
  3290.             See also    MGL_setPaletteEntry(), MGL_getPalette(),
  3291.                         MGL_setPalette()
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.             50                      MegaGraph Graphics Library Reference
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.             MGL_getPaletteSize
  3308.  
  3309.             Function    Returns the number of entries in the entire
  3310.                         palette
  3311.  
  3312.             Syntax      int MGL_getPaletteSize(void);
  3313.  
  3314.             Prototype   mgraph.h
  3315.             in
  3316.  
  3317.             Remarks     MGL_getPaletteSize() returns the number of
  3318.                         entries in the entire palette. You should use
  3319.                         this routine to determine the size of the
  3320.                         entire palette, as the palette is still
  3321.                         active even in HiColor and TrueColor video
  3322.                         modes (it is implemented in software rather
  3323.                         than hardware in these modes).
  3324.  
  3325.             Return      Number of entries in entire palette.
  3326.             value
  3327.  
  3328.             See also    MGL_getPalette()
  3329.  
  3330.  
  3331.             MGL_getPaletteSnowLevel
  3332.  
  3333.             Function    Returns the current palette snow level
  3334.  
  3335.             Syntax      int MGL_getPaletteSnowLevel(void);
  3336.  
  3337.             Prototype   mgraph.h
  3338.             in
  3339.  
  3340.             Remarks     MGL_getPaletteSnowLevel() returns the number
  3341.                         of palette entries that can be programmed
  3342.                         during a single vertical retrace before the
  3343.                         onset of snow. The MGL uses a reasonable
  3344.                         default of 100 entries per retrace, but you
  3345.                         may want to modify this on faster or slower
  3346.                         machines (this should be a user option).
  3347.  
  3348.             Return      Current palette snow level.
  3349.             value
  3350.  
  3351.             See also    MGL_setPaletteSnowLevel()
  3352.  
  3353.  
  3354.             MGL_getPenBitmapPattern
  3355.  
  3356.             Function    Returns the currently active bitmap pattern
  3357.  
  3358.             Syntax      void MGL_getPenBitmapPattern(pattern *pat);
  3359.  
  3360.             Prototype   mgraph.h
  3361.             in
  3362.  
  3363.             Parameters  pat - Place to store the bitmap pattern
  3364.  
  3365.  
  3366.  
  3367.             Chapter 6 - Console Library                               51
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.             Remarks     MGL_getPenBitmapPattern() returns a copy of
  3374.                         the currently active bitmap pattern used when
  3375.                         rendering patterned primitive in the
  3376.                         BITMAP_PATTERN_TRANSPARENT and
  3377.                         BITMAP_PATTERN_OPQAUE pen styles. A bitmap
  3378.                         pattern is defined as an 8 x 8 pixel bitmap
  3379.                         pattern stored as an array of 8 bytes.
  3380.  
  3381.                         When filling in the
  3382.                         BITMAP_PATTERN_TRANSPARENT mode, the
  3383.                         foreground color is used to fill in all
  3384.                         pixels in the bitmap pattern that are a 1.
  3385.                         Where the pixels in the bitmap pattern are a
  3386.                         0, the original background color is retained.
  3387.                         In the BITMAP_PATTERN_OPAQUE mode, the
  3388.                         background color is used to fill in the
  3389.                         pixels in the bitmap that are set to a 0.
  3390.  
  3391.             See also    MGL_setPenBitmapPattern(), MGL_setPenStyle(),
  3392.                         MGL_getPenStyle()
  3393.  
  3394.  
  3395.             MGL_getPenSize
  3396.  
  3397.             Function    Returns the current pen size.
  3398.  
  3399.             Syntax      void MGL_getPenSize(int *height,int *width);
  3400.  
  3401.             Prototype   mgraph.h
  3402.             in
  3403.  
  3404.             Parameters  height - Place to store the current pen
  3405.                         height
  3406.                         width - Place to store the current pen width
  3407.  
  3408.             Remarks     MGL_getPenSize() return the size of the
  3409.                         current pen in pixels. The default pen is 1
  3410.                         pixel by 1 pixel in dimensions, however you
  3411.                         can change this to whatever value you like.
  3412.                         When primitive are rendered with a pen other
  3413.                         than the default, the pixels in the pen
  3414.                         always lie to the right and below the current
  3415.                         pen position.
  3416.  
  3417.             See also    MGL_setPenSize()
  3418.  
  3419.  
  3420.             MGL_getPenStyle
  3421.  
  3422.             Function    Returns the current pen style.
  3423.  
  3424.             Syntax      int MGL_getPenStyle(void);
  3425.  
  3426.             Prototype   mgraph.h
  3427.             in
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.             52                      MegaGraph Graphics Library Reference
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.             Remarks     MGL_getPenStyle() returns the currently
  3440.                         active pen style. The MGL supports the
  3441.                         following pen styles:
  3442.  
  3443.                         SOLID_PATTERN              - Fill with solid
  3444.                         color
  3445.                         BITMAP_PATTERN_OPAQUE      - Pattern fill
  3446.                         BITMAP_PATTERN_TRANSPARENT - Transparent
  3447.                         pattern fill
  3448.  
  3449.                         When filling in the
  3450.                         BITMAP_PATTERN_TRANSPARENT mode, the
  3451.                         foreground color is used to fill in all
  3452.                         pixels in the bitmap pattern that are a 1.
  3453.                         Where the pixels in the bitmap pattern are a
  3454.                         0, the original background color is retained.
  3455.                         In the BITMAP_PATTERN_OPAQUE mode, the
  3456.                         background color is used to fill in the
  3457.                         pixels in the bitmap that are set to a 0.
  3458.  
  3459.             Return      Current pen style.
  3460.             value
  3461.  
  3462.             See also    MGL_setPenStyle(), MGL_setPenBitmapPattern()
  3463.  
  3464.  
  3465.             MGL_getPixel
  3466.  
  3467.             Function    Returns the color of a specified pixel
  3468.  
  3469.             Syntax      color_t MGL_getPixel(point p)
  3470.  
  3471.             Prototype   mgraph.h
  3472.             in
  3473.  
  3474.             Parameters  p - Point defining the pixel to read
  3475.  
  3476.             Remarks     MGL_getPixel() returns the color of the pixel
  3477.                         at the coordinates defined by the point  .                                                                p
  3478.  
  3479.                         Note: You must ensure that you call the
  3480.                         routine MGL_beginPixel() before reading any
  3481.                         pixel values and the routine MGL_endPixel()
  3482.                         after reading a bunch of pixels.
  3483.  
  3484.             Return      Color of the specified pixel.
  3485.             value
  3486.  
  3487.             See also    MGL_pixel(), MGL_getPixelCoord(),
  3488.                         MGL_beginPixel(), MGL_endPixel()
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.             Chapter 6 - Console Library                               53
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.             MGL_getPixelCoord
  3506.  
  3507.             Function    Returns the color of a specified pixel
  3508.  
  3509.             Syntax      color_t MGL_getPixelCoord(int x,int y);
  3510.  
  3511.             Prototype   mgraph.h
  3512.             in
  3513.  
  3514.             Parameters  x,y - Coordinates of the pixel to read.
  3515.  
  3516.             Remarks     MGL_getPixelCoord() returns the color of the
  3517.                         pixel at the coordinates defined by the point
  3518.                              .                        (x,y)
  3519.  
  3520.                         Note: You      ensure that you call the                                  must
  3521.                         routine MGL_beginPixel() before reading any
  3522.                         pixel values and the routine MGL_endPixel()
  3523.                         after reading a bunch of pixels.
  3524.  
  3525.             Return      Color of the specified pixel.
  3526.             value
  3527.  
  3528.             See also    MGL_pixel(), MGL_getPixel(),
  3529.                         MGL_beginPixel(), MGL_endPixel()
  3530.  
  3531.  
  3532.             MGL_getPixelFormat
  3533.  
  3534.             Function    Returns the current packed pixel format
  3535.                         information.
  3536.  
  3537.             Syntax      void MGL_getPixelFormat(pixel_format
  3538.                         *format);
  3539.  
  3540.             Prototype   mgraph.h
  3541.             in
  3542.  
  3543.             Parameters  format - Place to store the pixel format
  3544.                         information.
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.             54                      MegaGraph Graphics Library Reference
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.             Remarks     MGL_getPixelFormat() returns the current
  3572.                         pixel format information for the currently
  3573.                         active video mode. This information is used
  3574.                         by the MGL to encode the packed pixel
  3575.                         information, and can be used by your
  3576.                         application to work out how to pack values
  3577.                         correctly for the direct color video modes.
  3578.                         This routine should also be used to correctly
  3579.                         interpret the format of the pixel information
  3580.                         returned by the MGL_getImage() routine. The
  3581.                         pixel format structure is defined as follows:
  3582.  
  3583.                         typedef struct {
  3584.                             char    redMask,blueMask;
  3585.                             char    greenMask,rsvdMask;
  3586.                             int     redPos,redAdjust;
  3587.                             int     greenPos,greenAdjust;
  3588.                             int     bluePos,blueAdjust;
  3589.                             int     rsvdPos,rsvdAdjust;
  3590.                             } pixel_format;
  3591.  
  3592.                         The Mask values are logical AND masks that
  3593.                         can be used to represent the correct number
  3594.                         of usable bits in each color value. The Pos
  3595.                         values describe where in the packed pixel
  3596.                         format each value resides, and the Adjust
  3597.                         values descibe the bit shift required to
  3598.                         adjust to 8 bit component values. The
  3599.                         following code illustrates how these values
  3600.                         can be used to unpack values to and from 8
  3601.                         bit RGB tuples:
  3602.  
  3603.                         R = (((color) >> redPos) & redMask) <<
  3604.                         redAdjust;
  3605.                         G = (((color) >> greenPos) & greenMask) <<
  3606.                         greenAdjust;
  3607.                         B = (((color) >> bluePos) & blueMask) <<
  3608.                         blueAdjust;
  3609.  
  3610.                         and to pack values:
  3611.  
  3612.                         color = ((color_t)((R >> redAdjust) &
  3613.                         redMask) << redPos)
  3614.                          | ((color_t)((G >> greenAdjust) & greenMask)
  3615.                         << greenPos)
  3616.                          | ((color_t)((B >> blueAdjust) & blueMask)
  3617.                         << bluePos);
  3618.  
  3619.             See also    MGL_packColor(), MGL_unpackColor()
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.             Chapter 6 - Console Library                               55
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.             MGL_getPolygonType
  3638.  
  3639.             Function    Returns the current polygon type.
  3640.  
  3641.             Syntax      int MGL_getPolygonType(void);
  3642.  
  3643.             Prototype   mgraph.h
  3644.             in
  3645.  
  3646.             Remarks     MGL_getPolygonType() returns the current
  3647.                         polygon type. You can change this value with
  3648.                         the MGL_setPolygonType() to force the MGL to
  3649.                         work with a specific polygon type (and to
  3650.                         avoid the default automatic polygon type
  3651.                         checking). The MGL supports the following
  3652.                         polygon types:
  3653.  
  3654.                         AUTO_POLYGON    - MGL automatically
  3655.                         determines type
  3656.                         CONVEX_POLYGON  - All polygons rendered as
  3657.                         convex
  3658.                         COMPLEX_POLYGON - All polygons rendered as
  3659.                         complex
  3660.  
  3661.                         If you expect to be drawing lots of complex
  3662.                         or convex polygons, setting the polygon type
  3663.                         can result in faster polygon rendering.
  3664.  
  3665.             Return      Current polygon type code.
  3666.             value
  3667.  
  3668.             See also    MGL_setPolygonType(), MGL_fillPolygon()
  3669.  
  3670.  
  3671.             MGL_getSpaceExtra
  3672.  
  3673.             Function    Returns the current space extra value.
  3674.  
  3675.             Syntax      int MGL_getSpaceExtra(void);
  3676.  
  3677.             Prototype   mgraph.h
  3678.             in
  3679.  
  3680.             Remarks     MGL_getSpaceExtra() returns the current space
  3681.                         extra value used when drawing text in the
  3682.                         current font. The space extra value is
  3683.                         normally zero, but can be a positive or
  3684.                         negative value. This value can be used to
  3685.                         insert extra space between the characters in
  3686.                         a font (making this value a large negative
  3687.                         value will make the characters run on top of
  3688.                         each other).
  3689.  
  3690.             Return      Current space extra value.
  3691.             value
  3692.  
  3693.             See also    MGL_setSpaceExtra(), MGL_drawStr()
  3694.  
  3695.  
  3696.  
  3697.             56                      MegaGraph Graphics Library Reference
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.             MGL_getTextDirection
  3704.  
  3705.             Function    Returns the current text direction
  3706.  
  3707.             Syntax      int MGL_getTextDirection(void);
  3708.  
  3709.             Prototype   mgraph.h
  3710.             in
  3711.  
  3712.             Remarks     MGL_getTextDirection() returns the current
  3713.                         text direction. The MGL supports the
  3714.                         following text directions:
  3715.  
  3716.                         LEFT_DIR  - Text runs to the left (right to
  3717.                         left)
  3718.                         UP_DIR    - Text runs in the up direction
  3719.                         RIGHT_DIR - Text runs to the right (left to
  3720.                         right)
  3721.                         DOWN_DIR  - Text runs in the down direction
  3722.  
  3723.                         Currently the MGL only supports directional
  3724.                         text with the default 8x8 bitmap font and
  3725.                         vector fonts. Bitmap fonts can only be drawn
  3726.                         in the RIGHT_DIR direction.
  3727.  
  3728.             Return      Current text direction.
  3729.             value
  3730.  
  3731.             See also    MGL_setTextDirection(), MGL_drawStr()
  3732.  
  3733.  
  3734.             MGL_getTextJustify
  3735.  
  3736.             Function    Returns the current text justification.
  3737.  
  3738.             Syntax      void MGL_getTextJustify(int *horiz,int
  3739.                         *vert);
  3740.  
  3741.             Prototype   mgraph.h
  3742.             in
  3743.  
  3744.             Parameters  horiz - Place to store horizontal
  3745.                         justification
  3746.                         vert - Place to store vertical justification
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.             Chapter 6 - Console Library                               57
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.             Remarks     MGL_getTextJustify() returns the current text
  3770.                         justification values. The MGL support the
  3771.                         following horizontal justification types:
  3772.  
  3773.                         LEFT_TEXT     - Text is left justified
  3774.                         CENTER_TEXT   - Text is centered left to
  3775.                         right
  3776.                         RIGHT_TEXT    - Text is right justified
  3777.  
  3778.                         and the following vertical justification
  3779.                         types:
  3780.  
  3781.                         TOP_TEXT      - Text is top justified
  3782.                         CENTER_TEXT   - Text is centered top to
  3783.                         bottom
  3784.                         BASELINE_TEXT - Text is justified to the
  3785.                         baseline
  3786.                         BOTTOM_TEXT   - Text is bottom justified
  3787.  
  3788.             See also    MGL_setTextJustify()
  3789.  
  3790.  
  3791.             MGL_getTextSettings
  3792.  
  3793.             Function    Returns the current text settings.
  3794.  
  3795.             Syntax      void MGL_getTextSettings(text_settings
  3796.                         *settings);
  3797.  
  3798.             Prototype   mgraph.h
  3799.             in
  3800.  
  3801.             Parameters  settings - Place to store the current text
  3802.                         settings
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.             58                      MegaGraph Graphics Library Reference
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.             Remarks     MGL_getTextSettings() returns the currently
  3836.                         active text settings. This routine provides a
  3837.                         way to save and restore all the values
  3838.                         relating to the rendering of text in the MGL
  3839.                         with a single function call. The text
  3840.                         settings values are stored in the following
  3841.                         structure:
  3842.  
  3843.                         typedef struct {
  3844.                             int             horiz_just;
  3845.                             int             vert_just;
  3846.                             int             dir;
  3847.                             int             sz_numerx;
  3848.                             int             sz_numery;
  3849.                             int             sz_denomx;
  3850.                             int             sz_denomy;
  3851.                             int             space_extra;
  3852.                             font            *fnt;
  3853.  
  3854.                         where horiz_just     vert_just                                         and           define the
  3855.                         horizontal and vertical justification values,
  3856.                             defines the current text direction,                        dir
  3857.                         space_extra defines the current space extra
  3858.                         value and fnt define the currently active
  3859.                         font (stored in system memory). The
  3860.                         sz_numerx, sz_numery, sz_demonx and sz_denomy
  3861.                         specify the current text scaling factors.
  3862.  
  3863.             See also    MGL_setTextSettings
  3864.  
  3865.  
  3866.             MGL_getTextSize
  3867.  
  3868.             Function    Returns the current text scaling factors
  3869.  
  3870.             Syntax      void MGL_getTextSize(int *numerx,int
  3871.                         *denomx,int *numery,int *denomy);
  3872.  
  3873.             Prototype   mgraph.h
  3874.             in
  3875.  
  3876.             Parameters  numerx - Place to store the x numerator value
  3877.                         denomx - Place to store the x denominator
  3878.                         value
  3879.                         numery - Place to store the y numerator value
  3880.                         denomy - Place to store the y denominator
  3881.                         value
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.             Chapter 6 - Console Library                               59
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.             Remarks     MGL_getTextSize() returns the current text
  3902.                         scaling factors used by the MGL. The text
  3903.                         size values define an integer scaling factor
  3904.                         to be used, where the actual values will be
  3905.                         computed using the following formula:
  3906.  
  3907.                                   scaled                                       unscaled                                             numer
  3908.                                           denom
  3909.  
  3910.                         Note: Currently the MGL can only scale
  3911.                         vectors fonts.
  3912.  
  3913.             See also    MGL_setTextSize()
  3914.  
  3915.  
  3916.             MGL_getViewport
  3917.  
  3918.             Function    Returns the currently active viewport
  3919.  
  3920.             Syntax      void MGL_getViewport(rect *view);
  3921.  
  3922.             Prototype   mgraph.h
  3923.             in
  3924.  
  3925.             Parameters  view - Place to store the current viewport
  3926.  
  3927.             Remarks     MGL_getViewport() returns the dimensions of
  3928.                         the currently active viewport. These
  3929.                         dimensions are global to the entire display
  3930.                         area used by the currently active video
  3931.                         device driver.
  3932.  
  3933.                         All output in the MGL is relative to the
  3934.                         current viewport, so by changing the viewport
  3935.                         to a new value you can make all output appear
  3936.                         in a different rectangular portion of the
  3937.                         video display.
  3938.  
  3939.             See also    MGL_setViewport(), MGL_setRelViewport(),
  3940.                         MGL_clearViewport(), MGL_setClipRect()
  3941.  
  3942.  
  3943.             MGL_getVisualPage
  3944.  
  3945.             Function    Returns the currently visible hardware video
  3946.                         page.
  3947.  
  3948.             Syntax      int MGL_getVisualPage(void);
  3949.  
  3950.             Prototype   mgraph.h
  3951.             in
  3952.  
  3953.  
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.             60                      MegaGraph Graphics Library Reference
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.             Remarks     MGL_getVisualPage() returns the currently
  3968.                         visible hardware video page number. The first
  3969.                         hardware video page is number 0, the second
  3970.                         is 1 and so on. The number of available
  3971.                         hardware video pages depends on the type of
  3972.                         underlying hardware, the video mode
  3973.                         resolution and amount of video memory
  3974.                         installed. Thus not all video modes support
  3975.                         multiple hardware video pages.
  3976.  
  3977.             Return      Currently visible hardware video page.
  3978.             value
  3979.  
  3980.             See also    MGL_setVisualPage(), MGL_getActivePage(),
  3981.                         MGL_setActivePage().
  3982.  
  3983.  
  3984.             MGL_getWriteMode
  3985.  
  3986.             Function    Returns the current write mode operation
  3987.  
  3988.             Syntax      int MGL_getWriteMode(void);
  3989.  
  3990.             Prototype   mgraph.h
  3991.             in
  3992.  
  3993.             Remarks     MGL_getWriteMode() returns the currently
  3994.                         active write mode. The MGL supports the
  3995.                         following write mode operations for all
  3996.                         output primitives:
  3997.  
  3998.                         REPLACE_MODE - Replace the original pixels
  3999.                         AND_MODE     - Logical AND with original
  4000.                         pixels
  4001.                         OR_MODE      - Logical OR with original
  4002.                         pixels
  4003.                         XOR_MODE     - Logical XOR with original
  4004.                         pixels
  4005.  
  4006.             Return      Current write mode operation.
  4007.             value
  4008.  
  4009.             See also    MGL_setWriteMode()
  4010.  
  4011.  
  4012.             MGL_getX
  4013.  
  4014.             Function    Returns the X coordinate of the current
  4015.                         position.
  4016.  
  4017.             Syntax      int MGL_getX(void);
  4018.  
  4019.             Prototype   mgraph.h
  4020.             in
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.             Chapter 6 - Console Library                               61
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.             Remarks     MGL_getX() returns the X coordinate of the
  4034.                         current position (CP) value. The CP is the
  4035.                         current graphics cursor position, and is used
  4036.                         by a number of output routines to determine
  4037.                         where to being drawing.
  4038.  
  4039.             Return      X coordinate of current position
  4040.             value
  4041.  
  4042.             See also    MGL_getY(), MGL_getCP(), MGL_moveTo()
  4043.  
  4044.  
  4045.             MGL_getY
  4046.  
  4047.             Function    Returns the Y coordinate of the current
  4048.                         position.
  4049.  
  4050.             Syntax      int MGL_getY(void);
  4051.  
  4052.             Prototype   mgraph.h
  4053.             in
  4054.  
  4055.             Remarks     MGL_getY() returns the Y coordinate of the
  4056.                         current position (CP) value. The CP is the
  4057.                         current graphics cursor position, and is used
  4058.                         by a number of output routines to determine
  4059.                         where to being drawing.
  4060.  
  4061.             Return      Y coordinate of current position
  4062.             value
  4063.  
  4064.             See also    MGL_getX(), MGL_getCP(), MGL_moveTo()
  4065.  
  4066.  
  4067.             MGL_globalToLocal
  4068.  
  4069.             Function    Converts a point from global coordinates to
  4070.                         local coordinates
  4071.  
  4072.             Syntax      void MGL_globalToLocal(point *p);
  4073.  
  4074.             Prototype   mgraph.h
  4075.             in
  4076.  
  4077.             Parameters  p - Pointer to point to be converted
  4078.  
  4079.             Remarks     MGL_globalToLocal() converts a coordinate
  4080.                         from global coordinates to local coordinates.
  4081.                         Global coordinates are defined relative to
  4082.                         the entire output devices display, while
  4083.                         local coordinates are relative to the
  4084.                         currently active viewport.
  4085.  
  4086.                         This routine is usually used to convert mouse
  4087.                         coordinate values from global screen
  4088.                         coordinates to the local coordinate system of
  4089.                         the currently active viewport.
  4090.  
  4091.  
  4092.  
  4093.             62                      MegaGraph Graphics Library Reference
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.             See also    MGL_localToGlobal()
  4100.  
  4101.  
  4102.             MGL_gouraudScanLine
  4103.  
  4104.             Function    Draws a smooth shaded scanline.
  4105.  
  4106.             Syntax      void MGL_gouraudScanLine(int y,int x1,int
  4107.                         x2,color_t c1,color_t c2);
  4108.  
  4109.             Prototype   mgraph.h
  4110.             in
  4111.  
  4112.             Parameters  y - Y coordinate of scanline
  4113.                         x1 - Starting X coordinate of scanline
  4114.                         x2 - Ending X coordinate of scanline
  4115.                         c1 - Starting color value
  4116.                         c2 - Ending color value
  4117.  
  4118.             Remarks     MGL_gouraudScanLine() draws a smooth shaded
  4119.                         scanline between the point        and the                                                   (x1,y)
  4120.                         point       . The color values are smoothly                              (x2,y)
  4121.                         interpolated across the scanline starting
  4122.                              c1                        with    and ending with c2.
  4123.  
  4124.                         Note: You      call MGL_beginGouraud() before                                  must
  4125.                         calling this routine to ensure that the
  4126.                         hardware is in the correct state to draws
  4127.                         shaded scanlines. You must also ensure that
  4128.                         you call MGL_endGouraud() after rendering a
  4129.                         set of shaded scanlines. You may not call any
  4130.                         other MGL routines while you are rendering
  4131.                         shaded scanlines.
  4132.  
  4133.             See also    MGL_fillGouraudPolygon(). MGL_beginGouraud(),
  4134.                         MGL_endGouraud()
  4135.  
  4136.  
  4137.             MGL_imageSize
  4138.  
  4139.             Function    Returns the number of bytes required to store
  4140.                         an image.
  4141.  
  4142.             Syntax      long MGL_imageSize(rect r);
  4143.  
  4144.             Prototype   mgraph.h
  4145.             in
  4146.  
  4147.             Parameters  r - Rectangle defining the size of the image
  4148.  
  4149.             Remarks     MGL_imageSize() returns the number of bytes
  4150.                         required to store an offscreen video memory
  4151.                         image. You must use this routine to allocate
  4152.                         enough memory to store the image before you
  4153.                         call the MGL_getImage() routine to read an
  4154.                         image
  4155.                         from display memory.
  4156.  
  4157.  
  4158.  
  4159.             Chapter 6 - Console Library                               63
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.             Return      Number of bytes required to store the image.
  4166.             value
  4167.  
  4168.             See also    MGL_imageSizeCoord(), MGL_getImage(),
  4169.                         MGL_getImageCoord(), MGL_putImage(),
  4170.                         MGL_putImageCoord().
  4171.  
  4172.             See also    MGL_fillGouraudPolygon(). MGL_beginGouraud(),
  4173.                         MGL_endGouraud()
  4174.  
  4175.  
  4176.             MGL_imageSizeCoord
  4177.  
  4178.             Function    Returns the number of bytes required to store
  4179.                         an image.
  4180.  
  4181.             Syntax      long MGL_imageSizeCoord(int left,int top,int
  4182.                         right,int bottom);
  4183.  
  4184.             Prototype   mgraph.h
  4185.             in
  4186.  
  4187.             Parameters  left - Left edge of area to save
  4188.                         top - Top egde of area to save
  4189.                         right - Right edge of area to save
  4190.                         bottom - Bottom edge of area to save
  4191.  
  4192.             Remarks     MGL_imageSize() returns the number of bytes
  4193.                         required to store an offscreen video memory
  4194.                         image. You must use this routine to allocate
  4195.                         enough memory to store the image before you
  4196.                         call the MGL_getImage() routine to read an
  4197.                         image
  4198.                         from display memory.
  4199.  
  4200.             Return      Number of bytes required to store the image.
  4201.             value
  4202.  
  4203.             See also    MGL_imageSize(), MGL_getImage(),
  4204.                         MGL_getImageCoord(), MGL_putImage(),
  4205.                         MGL_putImageCoord().
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219.  
  4220.  
  4221.  
  4222.  
  4223.  
  4224.  
  4225.             64                      MegaGraph Graphics Library Reference
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.             MGL_init
  4232.  
  4233.             Function    Initialises the MGL.
  4234.  
  4235.             Syntax      void MGL_init(int *graphdriver,int
  4236.                         *graphmode,const char *pathtodriver);
  4237.  
  4238.             Prototype   mgraph.h
  4239.             in
  4240.  
  4241.             Parameters  graphdriver - Place to store detected
  4242.                         graphics device driver id
  4243.                         graphmode - Place to store suggested graphics
  4244.                         mode id
  4245.                         pathtodriver - Path to MGL driver files
  4246.  
  4247.             Remarks     MGL_init() initialises the MGL, sets the
  4248.                         specified video mode and clears the display
  4249.                         device ready to accept output. If you pass
  4250.                         the value grDETECT in the graphdriver
  4251.                         parameter, MGL_init() will automatically call
  4252.                         the MGL_detectGraph() routine to detect the
  4253.                         installed video device driver, and initialise
  4254.                         itself accordingly. The video mode used in
  4255.                         this case will be the one suggested by the
  4256.                         installed video device driver, and will be
  4257.                         returned in the           parameter. If a                                        graphmode
  4258.                         suitable device is not found for use by the
  4259.                         MGL, it will return an error via the
  4260.                         MGL_result() routine and pass back the value
  4261.                         grNONE in the graphdriver parameter.
  4262.  
  4263.                         If you wish to start a video mode other than
  4264.                         the default one suggested by the video device
  4265.                         driver, you should call the MGL_detectGraph()
  4266.                         routine yourself, and pass the value returned
  4267.                             graphdriver                        for             and your selected video mode
  4268.                            graphmode                        in           to initialise the mode.
  4269.  
  4270.                         The video device drivers currently supported
  4271.                         by the MGL are (this is subject to change -
  4272.                         please consult the MGRAPH.H header file for
  4273.                         the latest information):
  4274.  
  4275.                         grDETECT  - Auto detect the graphics
  4276.                         subsystem
  4277.                         grNONE    - No graphics hardware detected
  4278.                         grEGA     - Standard EGA with 256k RAM
  4279.                         grVGA     - Standard VGA
  4280.                         grSVGA    - VESA VBE compliant Super VGA
  4281.                         grSVGA_S3 - S3 accelerated SuperVGA
  4282.  
  4283.                         The MGL supports a number of different video
  4284.                         mode resolutions, ranging from 320x200 up to
  4285.                         1280x1024 with color ranges from 16 colors up
  4286.                         to 16.7 million colors. The name for each
  4287.                         video mode can be constructed from the pixel
  4288.                         and color resolutions, so the video mode id
  4289.                         for 320x200 16 color EGA graphics mode is
  4290.                         grEGA_320x200x16, and the 1280x1024 16.7
  4291.             Chapter 6 - Console Library                        million color mode is grSVGA_1280x1024x16m.   65
  4292.                         Please consult the MGRAPH.H header file for a
  4293.                         full list of defined video modes (subject to
  4294.                         change over time).
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.  
  4301.             See also    MGL_detectGraph(), MGL_setGraphMode(),
  4302.                         MGL_restoreCRTMode(), MGL_result()
  4303.  
  4304.  
  4305.             MGL_insetRect
  4306.  
  4307.             Function    Inset a rectangle by specified values.
  4308.  
  4309.             Syntax      void MGL_insetRect(rect r,int dx,int dy)
  4310.  
  4311.             Prototype   mgraph.h
  4312.             in
  4313.  
  4314.             Parameters  r - Rectangle to inset
  4315.                         dx - Value to inset the X coordinates by
  4316.                         dy - Value to inset the Y coordinates by
  4317.  
  4318.             Remarks     MGL_insetRect() insets the coordinates of a
  4319.                         rectangle by the specified amount in each
  4320.                         coordinate direction. The value of dx is
  4321.                         added to the left coordinate and subtracted
  4322.                         from the right coordinate, while the value of
  4323.                            is added to the top coordinate and                        dy
  4324.                         subtracted from the bottom coordinate. You
  4325.                         may use negative values for        dy                                                       and                                                     dx        in
  4326.                         order to increase the size of a rectangle
  4327.                         rather than descrease it's size.
  4328.  
  4329.             See also    MGL_offsetRect(), MGL_disjoingRect(),
  4330.                         MGL_ptInRect()
  4331.  
  4332.  
  4333.             MGL_line
  4334.  
  4335.             Function    Draws a line.
  4336.  
  4337.             Syntax      void MGL_line(point p1,point p2);
  4338.  
  4339.             Prototype   mgraph.h
  4340.             in
  4341.  
  4342.             Parameters  p1 - Starting point for the line
  4343.                         p2 - Ending point for the line
  4344.  
  4345.             Remarks     MGL_line() draws a line starting at the point
  4346.                         p1 and ending at the point p2 in the current
  4347.                         pen style, color and dimensions. The CP is
  4348.                         not updated, and the line is clipped to the
  4349.                         current clipping rectangle if clipping in on.
  4350.  
  4351.             See also    MGL_lineCoord(), MGL_lineFast(),
  4352.                         MGL_lineCoordFast(), MGL_lineTo(),
  4353.                         MGL_lineToCoord(), MGL_lineRel(),
  4354.                         MGL_lineRelCoord().
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.             66                      MegaGraph Graphics Library Reference
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.             MGL_lineCoord
  4367.  
  4368.             Function    Draws a line.
  4369.  
  4370.             Syntax      void MGL_lineCoord(int x1,int y1,int x2,int
  4371.                         y2);
  4372.  
  4373.             Prototype   mgraph.h
  4374.             in
  4375.  
  4376.             Parameters  x1,y1 - Starting point for the line
  4377.                         x2,y2 - Ending point for the line
  4378.  
  4379.             Remarks     MGL_lineCoord() draws a line starting at the
  4380.                         point         and ending at the point                               (x1,y1)                         (x2,y2)
  4381.                         in the current pen style, color and
  4382.                         dimensions. The CP is not updated, and the
  4383.                         line is clipped to the current clipping
  4384.                         rectangle if clipping in on.
  4385.  
  4386.             See also    MGL_lineCoord(), MGL_lineFast(),
  4387.                         MGL_lineCoordFast(), MGL_lineTo(),
  4388.                         MGL_lineToCoord(), MGL_lineRel(),
  4389.                         MGL_lineRelCoord().
  4390.  
  4391.  
  4392.             MGL_lineCoordFast
  4393.  
  4394.             Function    Draws a line as fast as possible.
  4395.  
  4396.             Syntax      void MGL_lineCoordFast(int x1,int y1,int
  4397.                         x2,int y2);
  4398.  
  4399.             Prototype   mgraph.h
  4400.             in
  4401.  
  4402.             Parameters  x1,y1 - Starting point for the line
  4403.                         x2,y2 - Ending point for the line
  4404.  
  4405.             Remarks     MGL_lineCoordFast() draws a line starting at
  4406.                         the point (x1,y1) and ending at the point
  4407.                         (x2,y2) in the current pen style, color and
  4408.                         dimensions. The CP is not updated, and the
  4409.                         line is clipped to the current clipping
  4410.                         rectangle if clipping in on.
  4411.  
  4412.                         Note: You must call the routine
  4413.                         MGL_beginDrawing() before calling the
  4414.                         MGL_lineCoordFast() routine to put the
  4415.                         hardware into the correct state fo for high
  4416.                         speed line drawing. The routines MGL_line()
  4417.                         and MGL_lineCoord() do this once for every
  4418.                         line to be drawn, so you can save time by
  4419.                         calling MGL_beginDrawing() once before
  4420.                         drawing a whole set of lines.
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.             Chapter 6 - Console Library                               67
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.             See also    MGL_lineCoord(), MGL_lineFast(),
  4433.                         MGL_lineCoordFast(), MGL_lineTo(),
  4434.                         MGL_lineToCoord(), MGL_lineRel(),
  4435.                         MGL_lineRelCoord(), MGL_beginDrawing(),
  4436.                         MGL_endDrawing().
  4437.  
  4438.  
  4439.             MGL_lineEngine
  4440.  
  4441.             Function    Generates the set of points on a line.
  4442.  
  4443.             Syntax      void MGL_lineEngine(int x1,int y1,int x2,int
  4444.                         y2,void (*plotPoint)(int x,int y));
  4445.  
  4446.             Prototype   mgraph.h
  4447.             in
  4448.  
  4449.             Parameters  x1,y1 - Starting point for the line
  4450.                         x2,y2 - Ending point for the line
  4451.                         plotPoint - User supplied pixel plotting
  4452.                         routine.
  4453.  
  4454.             Remarks     MGL_lineEngine() generates the set of points
  4455.                         on a line, and calls a user supplied
  4456.                         plotPoint routine for every point generated.
  4457.                         This is the same routine used for rendering
  4458.                         lines internally in the MGL.
  4459.  
  4460.                         The use supplied plotPoint routine will be
  4461.                         called once for every point on the line. The
  4462.                         set of points generated will always be in the
  4463.                         same order for any two endpoints, no matter
  4464.                         which order the endpoints are given.
  4465.  
  4466.             See also    MGL_ellipseEngine().
  4467.  
  4468.  
  4469.             MGL_lineFast
  4470.  
  4471.             Function    Draws a line as fast as possible.
  4472.  
  4473.             Syntax      void MGL_lineFast(point p1,point p2);
  4474.  
  4475.             Prototype   mgraph.h
  4476.             in
  4477.  
  4478.             Parameters  p1 - Starting point for the line
  4479.                         p2 - Ending point for the line
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.             68                      MegaGraph Graphics Library Reference
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.             Remarks     MGL_lineFast() draws a line starting at the
  4499.                         point    and ending at the point                               p1                            in the                                                         p2
  4500.                         current pen style, color and dimensions. The
  4501.                         CP is not updated, and the line is clipped to
  4502.                         the current clipping rectangle if clipping in
  4503.                         on.
  4504.  
  4505.                         Note: You      call the routine                                  must
  4506.                         MGL_beginDrawing()        calling the                                           before
  4507.                         MGL_lineFast() routine to put the hardware
  4508.                         into the correct state fo for high speed line
  4509.                         drawing. The routines MGL_line() and
  4510.                         MGL_lineCoord() do this once for every line
  4511.                         to be drawn, so you can save time by calling
  4512.                         MGL_beginDrawing() once before drawing a
  4513.                         whole set of lines.
  4514.  
  4515.             See also    MGL_lineCoord(), MGL_lineFast(),
  4516.                         MGL_lineCoordFast(), MGL_lineTo(),
  4517.                         MGL_lineToCoord(), MGL_lineRel(),
  4518.                         MGL_lineRelCoord(), MGL_beginDrawing(),
  4519.                         MGL_endDrawing().
  4520.  
  4521.  
  4522.             MGL_lineRel
  4523.  
  4524.             Function    Draws a relative line from the CP.
  4525.  
  4526.             Syntax      void MGL_lineRel(point p)
  4527.  
  4528.             Prototype   mgraph.h
  4529.             in
  4530.  
  4531.             Parameters  p - Relative point to draw line to.
  4532.  
  4533.             Remarks     MGL_lineRel() draws a line from the current
  4534.                         position (CP) to the relative location that
  4535.                         is a distance of   away from the CP. Thus the                                         p
  4536.                         location of the next point on the line is
  4537.                         (CP.x + p.x, CP.y + p.y). The CP is updated
  4538.                         to this value.
  4539.  
  4540.             See also    MGL_moveTo(), MGL_moveRel(), MGL_lineTo(),
  4541.                         MGL_lineRel().
  4542.  
  4543.  
  4544.             MGL_lineRelCoord
  4545.  
  4546.             Function    Draws a relative line.
  4547.  
  4548.             Syntax      void MGL_lineRelCoord(int dx,int dy);
  4549.  
  4550.             Prototype   mgraph.h
  4551.             in
  4552.  
  4553.             Parameters  dx,dy - Relative point to draw line to.
  4554.  
  4555.  
  4556.  
  4557.  
  4558.             Chapter 6 - Console Library                               69
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.             Remarks     MGL_lineRelCoord() draws a line from the
  4565.                         current position (CP) to the relative
  4566.                         location that is a distance of (dx,dy) away
  4567.                         from the CP. Thus the location of the next
  4568.                         point on the line is (CP.x + dx, CP.y + dy).
  4569.                         The CP is updated to this value.
  4570.  
  4571.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4572.                         MGL_moveRel(), MGL_moveRelCoord(),
  4573.                         MGL_lineTo(), MGL_lineToCoord(),
  4574.                         MGL_lineRel(), MGL_lineRelCoord().
  4575.  
  4576.  
  4577.             MGL_lineTo
  4578.  
  4579.             Function    Draws a line from the CP to the specified
  4580.                         point.
  4581.  
  4582.             Syntax      void MGL_lineTo(point p);
  4583.  
  4584.             Prototype   mgraph.h
  4585.             in
  4586.  
  4587.             Parameters  p - Point to draw the line to.
  4588.  
  4589.             Remarks     MGL_lineTo() draws a line from the current
  4590.                         position (CP) to the new point p. The CP is
  4591.                         set to the point   on return from this                                         p
  4592.                         routine.
  4593.  
  4594.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4595.                         MGL_moveRel(), MGL_moveRelCoord(),
  4596.                         MGL_lineTo(), MGL_lineToCoord(),
  4597.                         MGL_lineRel(), MGL_lineRelCoord().
  4598.  
  4599.  
  4600.             MGL_lineToCoord
  4601.  
  4602.             Function    Draws a line from the CP to the specified
  4603.                         point.
  4604.  
  4605.             Syntax      void MGL_lineToCoord(int x,int y);
  4606.  
  4607.             Prototype   mgraph.h
  4608.             in
  4609.  
  4610.             Parameters  x,y - Point to draw the line to.
  4611.  
  4612.             Remarks     MGL_lineToCoord() draws a line from the
  4613.                         current position (CP) to the new point (x,y).
  4614.                         The CP is set to the point       on return                                                   (x,y)
  4615.                         from this routine.
  4616.  
  4617.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4618.                         MGL_moveRel(), MGL_moveRelCoord(),
  4619.                         MGL_lineTo(), MGL_lineToCoord(),
  4620.                         MGL_lineRel(), MGL_lineRelCoord().
  4621.  
  4622.  
  4623.  
  4624.             70                      MegaGraph Graphics Library Reference
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.             MGL_loadFont
  4631.  
  4632.             Function    Loads an MGL font file for use.
  4633.  
  4634.             Syntax      font *MGL_loadFont(const char *fontname);
  4635.  
  4636.             Prototype   mgraph.h
  4637.             in
  4638.  
  4639.             Parameters  fontname - Name of the font file to load
  4640.  
  4641.             Remarks     MGL_loadFont() attempts to locate and read in
  4642.                         the font specified by fontname. The parameter
  4643.                         fontname is the name of the actual MGL font
  4644.                         file on disk, and may include a relative
  4645.                         pathname component. MGL_loadFont() first
  4646.                         looks for the font file relative to the
  4647.                         directory where it found the MGL driver files
  4648.                         at initialisation time, and will then look
  4649.                         for the font file relative to the current
  4650.                         directory if the fontfile was not found.
  4651.  
  4652.                         If the font file was not found, or was not
  4653.                         successfully loaded, MGL_loadFont returns
  4654.                         NULL, and sets the MGL_result() error code.
  4655.  
  4656.             Return      Pointer to the loaded font file (NULL if an
  4657.             value       error occurred).
  4658.  
  4659.             See also    MGL_unloadFont(), MGL_useFont(),
  4660.                         MGL_availableFont().
  4661.  
  4662.  
  4663.             MGL_localToGlobal
  4664.  
  4665.             Function    Converts a point from local coordinates to
  4666.                         global coordinates
  4667.  
  4668.             Syntax      void MGL_localToGlobal(point *p);
  4669.  
  4670.             Prototype   mgraph.h
  4671.             in
  4672.  
  4673.             Parameters  p - Pointer to point to be converted
  4674.  
  4675.             Remarks     MGL_localToGlobal() converts a coordinate
  4676.                         from local coordinates to global coordinates.
  4677.                         Global coordinates are defined relative to
  4678.                         the entire output devices display, while
  4679.                         local coordinates are relative to the
  4680.                         currently active viewport.
  4681.  
  4682.             See also    MGL_globalToLocal()
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.             Chapter 6 - Console Library                               71
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.             MGL_marker
  4697.  
  4698.             Function    Draws a marker at the specified coordinate.
  4699.  
  4700.             Syntax      void MGL_marker(point p);
  4701.  
  4702.             Prototype   mgraph.h
  4703.             in
  4704.  
  4705.             Parameters  p - Coordinate to draw the marker at
  4706.  
  4707.             Remarks     MGL_marker() draws a marker in the current
  4708.                         marker color, style and size at the specified
  4709.                         location. Markers can be used to label the
  4710.                         vertices in graphs. Refer to the
  4711.                         MGL_setMarkerStyle() routine for a list of
  4712.                         the typs of markers supported.
  4713.  
  4714.             See also    MGL_setMarkerSize(), MGL_getMarkerSize(),
  4715.                         MGL_setMarkerStyle(), MGL_getMarkerStyle(),
  4716.                         MGL_polyMarker()
  4717.  
  4718.  
  4719.             MGL_maxCharWidth
  4720.  
  4721.             Function    Returns the maximum character width for
  4722.                         current font.
  4723.  
  4724.             Syntax      int MGL_maxCharWidth(void);
  4725.  
  4726.             Prototype   mgraph.h
  4727.             in
  4728.  
  4729.             Remarks     MGL_maxCharWidth() returns the maximum
  4730.                         character width for the currently active
  4731.                         font. You can use this routine to quickly
  4732.                         determine if a character will possibly
  4733.                         overlap something else on the display screen.
  4734.  
  4735.             Return      Maximum character width for current font.
  4736.             value
  4737.  
  4738.             See also    MGL_getCharMetrics(), MGL_getFontMetrics(),
  4739.                         MGL_textHeight(), MGL_textWidth(),
  4740.                         MGL_charWidth()
  4741.  
  4742.  
  4743.             MGL_maxColor
  4744.  
  4745.             Function    Returns the maximum available color value.
  4746.  
  4747.             Syntax      color_t MGL_maxColor(void);
  4748.  
  4749.             Prototype   mgraph.h
  4750.             in
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.             72                      MegaGraph Graphics Library Reference
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.             Remarks     MGL_maxColor() retutns the values of the
  4763.                         largest available color values for the
  4764.                         current video modes. This value will always
  4765.                         be one less than the number of available
  4766.                         colors in that particular video mode.
  4767.  
  4768.             Return      Maximum color value for current video mode.
  4769.             value
  4770.  
  4771.  
  4772.             MGL_maxPage
  4773.  
  4774.             Function    Returns the maximum available hardware video
  4775.                         page.
  4776.  
  4777.             Syntax      int MGL_maxPage(void);
  4778.  
  4779.             Prototype   mgraph.h
  4780.             in
  4781.  
  4782.             Remarks     MGL_maxPage() returns the index of the
  4783.                         highest hardware video page that is
  4784.                         available. This value will always be one less
  4785.                         than the number of hardware video pages
  4786.                         available. Some video modes only have one
  4787.                         hardware video page available, so this value
  4788.                         will be 0.
  4789.  
  4790.             Return      Index of maximum available hardware video
  4791.             value       page.
  4792.  
  4793.  
  4794.             MGL_maxx
  4795.  
  4796.             Function    Returns the current maximum X coordinate
  4797.  
  4798.             Syntax      int MGL_maxx(void);
  4799.  
  4800.             Prototype   mgraph.h
  4801.             in
  4802.  
  4803.             Remarks     MGL_maxx() returns the maximum X coordinate
  4804.                         available in the currently active viewport.
  4805.                         This value will change if you change the
  4806.                         dimensions of the current viewport.
  4807.  
  4808.                         Use the MGL_sizex() routine to determine the
  4809.                         dimensions of the physical display area
  4810.                         available to the program.
  4811.  
  4812.             Return      Maximum X coordinate in current viewport.
  4813.             value
  4814.  
  4815.             See also    MGL_maxy(), MGL_sizex(), MGL_sizey()
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.             Chapter 6 - Console Library                               73
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.             MGL_maxy
  4829.  
  4830.             Function    Returns the current maximum Y coordinate
  4831.  
  4832.             Syntax      int MGL_maxy(void);
  4833.  
  4834.             Prototype   mgraph.h
  4835.             in
  4836.  
  4837.             Remarks     MGL_maxy() returns the maximum Y coordinate
  4838.                         available in the currently active viewport.
  4839.                         This value will change if you change the
  4840.                         dimensions of the current viewport.
  4841.  
  4842.                         Use the MGL_sizey() routine to determine the
  4843.                         dimensions of the physical display area
  4844.                         available to the program.
  4845.  
  4846.             Return      Maximum Y coordinate in current viewport.
  4847.             value
  4848.  
  4849.             See also    MGL_maxx(), MGL_sizex(), MGL_sizey()
  4850.  
  4851.  
  4852.             MGL_modeName
  4853.  
  4854.             Function    Returns textual representation of the
  4855.                         specified video mode.
  4856.  
  4857.             Syntax      char *MGL_modeName(int mode);
  4858.  
  4859.             Prototype   mgraph.h
  4860.             in
  4861.  
  4862.             Parameters  mode - Video mode number to get name for.
  4863.  
  4864.             Remarks     MGL_modeName() returns a string representing
  4865.                         the specified video mode number.
  4866.  
  4867.             Return      Pointer to a string representing the name of
  4868.             value       the mode.
  4869.  
  4870.             See also    MGL_driverName().
  4871.  
  4872.  
  4873.             MGL_moveRel
  4874.  
  4875.             Function    Moves the CP to a new relative location.
  4876.  
  4877.             Syntax      void MGL_moveRel(point p)
  4878.  
  4879.             Prototype   mgraph.h
  4880.             in
  4881.  
  4882.             Parameters  p - Relative point to move the CP to.
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.             74                      MegaGraph Graphics Library Reference
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894.             Remarks     MGL_moveRel() moves the current position (CP)
  4895.                         to the relative location that is a distance
  4896.                              away from the CP. Thus the location of                           p                        of 
  4897.                         the CP moves to is (CP.x + p.x, CP.y + p.y).
  4898.  
  4899.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4900.                         MGL_moveRelCoord(), MGL_lineTo(),
  4901.                         MGL_lineToCoord(), MGL_lineRel(),
  4902.                         MGL_lineRelCoord().
  4903.  
  4904.  
  4905.             MGL_moveRelCoord
  4906.  
  4907.             Function    Moves the CP to a new relative location
  4908.  
  4909.             Syntax      void MGL_moveRelCoord(int dx,int dy);
  4910.  
  4911.             Prototype   mgraph.h
  4912.             in
  4913.  
  4914.             Parameters  dx,dy - Relative point to move the CP to.
  4915.  
  4916.             Remarks     MGL_moveRelCoord() moves the current position
  4917.                         (CP) to the relative location that is a
  4918.                         distance of (dx,dy) away from the CP. Thus
  4919.                         the location the CP is moved to is (CP.x +
  4920.                         dx, CP.y + dy).
  4921.  
  4922.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4923.                         MGL_moveRel(), MGL_moveRelCoord(),
  4924.                         MGL_lineTo(), MGL_lineToCoord(),
  4925.                         MGL_lineRel(), MGL_lineRelCoord().
  4926.  
  4927.  
  4928.             MGL_moveTo
  4929.  
  4930.             Function    Moves the CP to a new location.
  4931.  
  4932.             Syntax      void MGL_moveTo(point p);
  4933.  
  4934.             Prototype   mgraph.h
  4935.             in
  4936.  
  4937.             Parameters  p - Point to move the CP to.
  4938.  
  4939.             Remarks     MGL_moveTo() moves the current position (CP)
  4940.                         to the new point p.
  4941.  
  4942.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4943.                         MGL_moveRel(), MGL_moveRelCoord(),
  4944.                         MGL_lineTo(), MGL_lineToCoord(),
  4945.                         MGL_lineRel(), MGL_lineRelCoord().
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.             Chapter 6 - Console Library                               75
  4955.  
  4956.  
  4957.  
  4958.  
  4959.  
  4960.             MGL_moveToCoord
  4961.  
  4962.             Function    Moves the CP to a new location.
  4963.  
  4964.             Syntax      void MGL_moveToCoord(int x,int y);
  4965.  
  4966.             Prototype   mgraph.h
  4967.             in
  4968.  
  4969.             Parameters  x,y - Point to move the CP to.
  4970.  
  4971.             Remarks     MGL_moveToCoord() moves the current position
  4972.                         (CP) to the new point (x,y).
  4973.  
  4974.             See also    MGL_moveTo(), MGL_moveToCoord(),
  4975.                         MGL_moveRel(), MGL_moveRelCoord(),
  4976.                         MGL_lineTo(), MGL_lineToCoord(),
  4977.                         MGL_lineRel(), MGL_lineRelCoord().
  4978.  
  4979.  
  4980.             MGL_offsetRect
  4981.  
  4982.             Function    Offsets a rectangle by a specified amount
  4983.  
  4984.             Syntax      void MGL_offsetRect(rect r,int dx,int dy)
  4985.  
  4986.             Prototype   mgraph.h
  4987.             in
  4988.  
  4989.             Parameters  r - Rectangle to offset
  4990.                         dx - Value to offset the X coordinates by
  4991.                         dy - Value to offset the Y coordinates by
  4992.  
  4993.             Remarks     MGL_offsetRect() moves the start of a
  4994.                         rectangle to a new location, by adding the
  4995.                         specified offset values to the X and Y
  4996.                         coordinate values. The size of the rectangle
  4997.                         is not changes, just it's location.
  4998.  
  4999.             See also    MGL_insetRect(), MGL_disjoingRect(),
  5000.                         MGL_ptInRect()
  5001.  
  5002.  
  5003.             MGL_packColor
  5004.  
  5005.             Function    Packs an RGB color value.
  5006.  
  5007.             Syntax      color_t MGL_packColor(uchar R,uchar G,uchar
  5008.                         B);
  5009.  
  5010.             Prototype   mgraph.h
  5011.             in
  5012.  
  5013.             Parameters  R - Red color component (0-255)
  5014.                         G - Green color component (0-255)
  5015.                         B - Blue color component (0-255)
  5016.  
  5017.  
  5018.  
  5019.  
  5020.             76                      MegaGraph Graphics Library Reference
  5021.  
  5022.  
  5023.  
  5024.  
  5025.  
  5026.             Remarks     MGL_packColor() takes 8 bit color component
  5027.                         values and packs them into a packed color
  5028.                         value that is appropriate for the current
  5029.                         video mode. This function only works properly
  5030.                         in the HiColor and TrueColor modes, as you
  5031.                         cannot specifiy RGB values in the color
  5032.                         mapped modes.
  5033.  
  5034.             Return      MGL packed color value appropriate for the
  5035.             value       current video mode.
  5036.  
  5037.             See also    MGL_unpackColor().
  5038.  
  5039.  
  5040.             MGL_pixel
  5041.  
  5042.             Function    Draws a pixel at the specified location
  5043.  
  5044.             Syntax      void MGL_pixel(point p)
  5045.  
  5046.             Prototype   mgraph.h
  5047.             in
  5048.  
  5049.             Parameters  p - Point to plot the point at it.
  5050.  
  5051.             Remarks     MGL_pixel() plots a single pixel at the
  5052.                         specified location in the current foregrond
  5053.                         color.
  5054.  
  5055.                         Note: You      call the routine                                  must
  5056.                         MGL_beginPixel() routine before calling the
  5057.                         MGL_pixel(), and you must call the
  5058.                         MGL_endPixel() routine after you have
  5059.                         finished plotting pixels.
  5060.  
  5061.             See also    MGL_pixelCoord(), MGL_beginPixel(),
  5062.                         MGL_endPixel().
  5063.  
  5064.  
  5065.             MGL_pixelCoord
  5066.  
  5067.             Function    Draws a pixel at the specified location
  5068.  
  5069.             Syntax      void MGL_pixelCoord(int x,int y);
  5070.  
  5071.             Prototype   mgraph.h
  5072.             in
  5073.  
  5074.             Parameters  x,y - Point to plot the point at it.
  5075.  
  5076.  
  5077.  
  5078.  
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.             Chapter 6 - Console Library                               77
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.             Remarks     MGL_pixelCoord() plots a single pixel at the
  5093.                         specified location in the current foregrond
  5094.                         color.
  5095.  
  5096.                         Note: You      call the routine                                  must
  5097.                         MGL_beginPixel() routine before calling the
  5098.                         MGL_pixel(), and you      call the                                             must
  5099.                         MGL_endPixel() routine after you have
  5100.                         finished plotting pixels.
  5101.  
  5102.             See also    MGL_pixelCoord(), MGL_beginPixel(),
  5103.                         MGL_endPixel().
  5104.  
  5105.  
  5106.             MGL_polyLine
  5107.  
  5108.             Function    Draws a set of connected lines.
  5109.  
  5110.             Syntax      void MGL_polyLine(int count,point *vArray);
  5111.  
  5112.             Prototype   mgraph.h
  5113.             in
  5114.  
  5115.             Parameters  count - Number of vertices in polyline
  5116.                         vArray - Array of vertices in the polyline
  5117.  
  5118.             Remarks     MGL_polyLine() draws a set of connected line
  5119.                         (a polyline). The coordinates of the polyline
  5120.                         are specified by       , and the lines are                                         vArray
  5121.                         drawn in the current drawing attributes.
  5122.  
  5123.                         Note: The polyline is not closed by default,
  5124.                         so if you wish to draw the outline of a
  5125.                         polygon, you will need to add the starting
  5126.                         point to the end of the vertex array.
  5127.  
  5128.             See also    MGL_polyMarker(), MGL_polyPoint().
  5129.  
  5130.  
  5131.             MGL_polyMarker
  5132.  
  5133.             Function    Draws a set of markers.
  5134.  
  5135.             Syntax      void MGL_polyMarker(int count,point *vArray);
  5136.  
  5137.             Prototype   mgraph.h
  5138.             in
  5139.  
  5140.             Parameters  count - Number of markers to draw
  5141.                         vArray - Array of coordinates to draw the
  5142.                         markers at
  5143.  
  5144.             Remarks     MGL_polyMarker() draws a set of markers in
  5145.                         the current marker color, style and size at
  5146.                         the locations passed in the        parameter.                                                    vArray
  5147.  
  5148.             See also    MGL_polyLine(), MGL_polyPoint()
  5149.  
  5150.  
  5151.  
  5152.             78                      MegaGraph Graphics Library Reference
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.             MGL_polyPoint
  5159.  
  5160.             Function    Draws a set of pixels.
  5161.  
  5162.             Syntax      void MGL_polyPoint(int count,point *vArray);
  5163.  
  5164.             Prototype   mgraph.h
  5165.             in
  5166.  
  5167.             Parameters  count - Number of pixels to draw
  5168.                         vArray - Array of coordinates to draw the
  5169.                         pixels at
  5170.  
  5171.             Remarks     MGL_polyPoint() draws a set of pixels in the
  5172.                         current color at the locations passed in the
  5173.                         vArray parameter.
  5174.  
  5175.             See also    MGL_polyLine(), MGL_polyPoint()
  5176.  
  5177.  
  5178.             MGL_popViewport
  5179.  
  5180.             Function    Pops the current viewport off the stack.
  5181.  
  5182.             Syntax      void MGL_popViewport(void);
  5183.  
  5184.             Prototype   mgraph.h
  5185.             in
  5186.  
  5187.             Remarks     MGL_popViewport() pops the viewport off the
  5188.                         top of the viewport stack and makes it the
  5189.                         new active viewport.
  5190.  
  5191.                         The MGL maintains a viewport stack that you
  5192.                         may use to temporarily push viewport settings
  5193.                         onto for later retrival.
  5194.  
  5195.             See also    MGL_pushViewport(), MGL_setViewport(),
  5196.                         MGL_getViewport()
  5197.  
  5198.  
  5199.             MGL_ptInRect
  5200.  
  5201.             Function    Determines if a point is in a rectangle.
  5202.  
  5203.             Syntax      bool MGL_ptInRect(point p,rect r);
  5204.  
  5205.             Prototype   mgraph.h
  5206.             in
  5207.  
  5208.             Parameters  p - Point to test
  5209.                         r - Rectangle to test point against
  5210.  
  5211.             Remarks     MGL_ptInRect() determines if a specified
  5212.                         point is contained within a particular
  5213.                         rectangle.
  5214.  
  5215.  
  5216.  
  5217.  
  5218.             Chapter 6 - Console Library                               79
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.             Return      True if the point is contained in the
  5225.             value       rectangle, false if not.
  5226.  
  5227.             See also    MGL_ptInRectCoord().
  5228.  
  5229.  
  5230.             MGL_ptInRectCoord
  5231.  
  5232.             Function    Determines if a point is in a rectangle.
  5233.  
  5234.             Syntax      bool MGL_ptInRectCoord(int x,int y,rect r)
  5235.  
  5236.             Prototype   mgraph.h
  5237.             in
  5238.  
  5239.             Parameters  x,y - Point to test
  5240.                         r - Rectangle to test point against
  5241.  
  5242.             Remarks     MGL_ptInRectCoord() determines if a specified
  5243.                         point is contained within a particular
  5244.                         rectangle.
  5245.  
  5246.             Return      True if the point is contained in the
  5247.             value       rectangle, false if not.
  5248.  
  5249.             See also    MGL_ptInRect()
  5250.  
  5251.  
  5252.             MGL_pushViewport
  5253.  
  5254.             Function    Pushes the current viewport onto the stack.
  5255.  
  5256.             Syntax      void MGL_pushViewport(void);
  5257.  
  5258.             Prototype   mgraph.h
  5259.             in
  5260.  
  5261.             Remarks     MGL_pushViewport() pushs the current viewport
  5262.                         values onto the viewport stack, to be
  5263.                         retrieved at a later date.
  5264.  
  5265.             See also    MGL_popViewport(), MGL_setViewport(),
  5266.                         MGL_getViewport()
  5267.  
  5268.  
  5269.             MGL_putDivot
  5270.  
  5271.             Function    Replaces a divot of video memory.
  5272.  
  5273.             Syntax      void MGL_putDivot(void *divot);
  5274.  
  5275.             Prototype   mgraph.h
  5276.             in
  5277.  
  5278.             Parameters  divot - Pointer to the divot to replace
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.             80                      MegaGraph Graphics Library Reference
  5285.  
  5286.  
  5287.  
  5288.  
  5289.  
  5290.             Remarks     MGL_putDivot() replaces a region of video
  5291.                         memory that was saved previously with an
  5292.                         MGL_getDivot() routine. The divot is replaced
  5293.                         at the same location that is was taken from
  5294.                         on the current display page.
  5295.  
  5296.             See also    MGL_getDivot(), MGL_divotSize(),
  5297.                         MGL_getImage(), MGL_putImage()
  5298.  
  5299.  
  5300.             MGL_putIcon
  5301.  
  5302.             Function    Draws an icon at the specified location.
  5303.  
  5304.             Syntax      void MGL_putIcon(int x,int y,icon_header
  5305.                         *icon);
  5306.  
  5307.             Prototype   mgraph.h
  5308.             in
  5309.  
  5310.             Parameters  x,y - Coordinates to draw the icon at
  5311.                         icon - Pointer to the icon data to draw
  5312.  
  5313.             Remarks     MGL_putIcon() draws an icon at the specified
  5314.                         location. The icon      be in the correct                                           must
  5315.                         format for the current video mode. The icon
  5316.                         is drawn by punching a black hole in the
  5317.                         background with the icon mask, and then
  5318.                         OR'ing in the the image data for the icon.
  5319.  
  5320.  
  5321.             MGL_putImage
  5322.  
  5323.             Function    Draws a video memory image on the display
  5324.  
  5325.             Syntax      void MGL_putImage(rect r,void *image,int op)
  5326.  
  5327.             Prototype   mgraph.h
  5328.             in
  5329.  
  5330.             Parameters  r - Rectangle to draw the image at
  5331.                         image - Pointer to the image to draw
  5332.                         op - Write mode operation to use.
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.             Chapter 6 - Console Library                               81
  5351.  
  5352.  
  5353.  
  5354.  
  5355.  
  5356.             Remarks     MGL_putImage() blasts the specified video
  5357.                         memory image to the display memory at the
  5358.                         specified location. If the image is larger
  5359.                         than the destination rectangle, it will be
  5360.                         clipped to the current destination rectangle
  5361.                         extents. You may specify any of the following
  5362.                         write mode operations to be used when moving
  5363.                         the image to video memory:
  5364.  
  5365.                         REPLACE_MODE - Replace the original pixels
  5366.                         AND_MODE     - Logical AND with original
  5367.                         pixels
  5368.                         OR_MODE      - Logical OR with original
  5369.                         pixels
  5370.                         XOR_MODE     - Logical XOR with original
  5371.                         pixels
  5372.  
  5373.             See also    MGL_putImageCoord(), MGL_getImage(),
  5374.                         MGL_getImageCoord(), MGL_imageSize().
  5375.  
  5376.  
  5377.             MGL_putImageCoord
  5378.  
  5379.             Function    Draws a video memory image on the display
  5380.  
  5381.             Syntax      void MGL_putImageCoord(int left,int top,int
  5382.                         right,int bottom,void *image,int op);
  5383.  
  5384.             Prototype   mgraph.h
  5385.             in
  5386.  
  5387.             Parameters  left - Left coordinate to draw image at
  5388.                         top - Top coordinate to draw image at
  5389.                         right - Right coordinate to draw image at
  5390.                         bottom - Bottom coordinate to draw image at
  5391.                         image - Pointer to the image to draw
  5392.                         op - Write mode operation to use.
  5393.  
  5394.             Remarks     MGL_putImageCoord() blasts the specified
  5395.                         video memory image to the display memory at
  5396.                         the specified location. If the image is
  5397.                         larger than the destination rectangle, it
  5398.                         will be clipped to the current destination
  5399.                         rectangle extents. You may specify any of the
  5400.                         following write mode operations to be used
  5401.                         when moving the image to video memory:
  5402.  
  5403.                         REPLACE_MODE
  5404.                         AND_MODE
  5405.                         OR_MODE
  5406.                         XOR_MODE
  5407.  
  5408.             See also    MGL_putImage(), MGL_getImage(),
  5409.                         MGL_getImageCoord(), MGL_imageSize().
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.             82                      MegaGraph Graphics Library Reference
  5417.  
  5418.  
  5419.  
  5420.  
  5421.  
  5422.             MGL_putMonoImage
  5423.  
  5424.             Function    Plots a monochromatic image.
  5425.  
  5426.             Syntax      void MGL_putMonoImage(int x,int y,int
  5427.                         byteWidth,int height,void *image);
  5428.  
  5429.             Prototype   mgraph.h
  5430.             in
  5431.  
  5432.             Parameters  x,y - Coordinate to plot the image at
  5433.                         byteWidth - Width of the image in bytes
  5434.                         height - Height of the image in scanlines
  5435.                         image - Pointer to the buffer holding the
  5436.                         image
  5437.  
  5438.             Remarks     MGL_putMonoImage() displays a single color
  5439.                         image in the current foreground color. Where
  5440.                         a bit is a 1 in the image definition, a pixel
  5441.                         is plotted in the foreground color, where a
  5442.                         bit is a 0 the original pixels are left
  5443.                         alone.
  5444.  
  5445.             See also    MGL_getImage(), MGL_putImage().
  5446.  
  5447.  
  5448.             MGL_realColor
  5449.  
  5450.             Function    Returns the real color value for a color
  5451.                         mapped index.
  5452.  
  5453.             Syntax      color_t MGL_realColor(int color);
  5454.  
  5455.             Prototype   mgraph.h
  5456.             in
  5457.  
  5458.             Parameters  color -
  5459.  
  5460.             Remarks     MGL_realColor() returns a color value
  5461.                         appropriate for the current video mode, given
  5462.                         a color mapped index. This routine works in
  5463.                         all video modes, including the HiColor and
  5464.                         TrueColor video modes. In the color mapped
  5465.                         modes, the value is simply returned
  5466.                         unchanged. However in the HiColor and
  5467.                         TrueColor modes, the appropriate color is
  5468.                         looked up in the currently active palette.
  5469.                         Thus you can still write code for the HiColor
  5470.                         and TrueColor modes that works with color
  5471.                         mapped indexes (although you cannot do things
  5472.                         like hardware palette fades and rotates as
  5473.                         the palette is implemented in software).
  5474.  
  5475.             Return      Real color value for the color mapped index.
  5476.             value
  5477.  
  5478.             See also    MGL_setPalette(), MGL_getPalette().
  5479.  
  5480.  
  5481.  
  5482.             Chapter 6 - Console Library                               83
  5483.  
  5484.  
  5485.  
  5486.  
  5487.  
  5488.             MGL_rect
  5489.  
  5490.             Function    Draws a rectangle.
  5491.  
  5492.             Syntax      void MGL_rect(rect r);
  5493.  
  5494.             Prototype   mgraph.h
  5495.             in
  5496.  
  5497.             Parameters  r - Rectangle to draw
  5498.  
  5499.             Remarks     MGL_rect() draws a rectangle in the current
  5500.                         drawing attributes at the specified location.
  5501.                         The rectangle is drawn within the
  5502.                         mathematical boundary of the rectangle, so
  5503.                         effectively the right and bottom edges of the
  5504.                         rectangle are not drawn (solving problems
  5505.                         with shared edges). Degenerate rectangles are
  5506.                         not drawn.
  5507.  
  5508.             See also    MGL_rectCoord(), MGL_rectPt().
  5509.  
  5510.  
  5511.             MGL_rectCoord
  5512.  
  5513.             Function    Draws a rectangle.
  5514.  
  5515.             Syntax      void MGL_rectCoord(int left,int top,int
  5516.                         right,int bottom);
  5517.  
  5518.             Prototype   mgraph.h
  5519.             in
  5520.  
  5521.             Parameters  left - Left coordinate of the rectangle
  5522.                         top - Top coordinate of the rectangle
  5523.                         right - Right coordinate of the rectangle
  5524.                         bottom - Bottom coordinate of the rectangle
  5525.  
  5526.             Remarks     MGL_rectCoord() draws a rectangle in the
  5527.                         current drawing attributes at the specified
  5528.                         location. The rectangle is drawn within the
  5529.                         mathematical boundary of the rectangle, so
  5530.                         effectively the right and bottom edges of the
  5531.                         rectangle are not drawn (solving problems
  5532.                         with shared edges). Degenerate rectangles are
  5533.                         not drawn.
  5534.  
  5535.             See also    MGL_rect(), MGL_rectPt().
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.             84                      MegaGraph Graphics Library Reference
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.             MGL_rectPt
  5555.  
  5556.             Function    Draws a rectangle.
  5557.  
  5558.             Syntax      void MGL_rectPt(point lt,point rb);
  5559.  
  5560.             Prototype   mgraph.h
  5561.             in
  5562.  
  5563.             Parameters  lt - Left top coordinate of the rectangle
  5564.                         rb - Right bottom coordinate of the rectangle
  5565.  
  5566.             Remarks     MGL_rectPt() draws a rectangle in the current
  5567.                         drawing attributes at the specified location.
  5568.                         The rectangle is drawn within the
  5569.                         mathematical boundary of the rectangle, so
  5570.                         effectively the right and bottom edges of the
  5571.                         rectangle are not drawn (solving problems
  5572.                         with shared edges). Degenerate rectangles are
  5573.                         not drawn.
  5574.  
  5575.             See also    MGL_rect(), MGL_rectCoord().
  5576.  
  5577.  
  5578.             MGL_registerDriver
  5579.  
  5580.             Function    Registers a user loaded or linked device
  5581.                         driver
  5582.  
  5583.             Syntax      int MGL_registerDriver(const char *name,void
  5584.                         *driver);
  5585.  
  5586.             Prototype   mgraph.h
  5587.             in
  5588.  
  5589.             Parameters  name - Name of driver to register
  5590.                         driver - Pointer to the start of the driver
  5591.                         in memory
  5592.  
  5593.             Remarks     MGL_registerDriver() registers a linked in or
  5594.                         user loaded graphics driver with the graphics
  5595.                         system. The driver must be one of the
  5596.                         standard graphics device drivers supported by
  5597.                         the library. The loaded driver is checked to
  5598.                         ensure that it actually is a valid MGL device
  5599.                         driver.
  5600.  
  5601.                         This routine is usually used to inform the
  5602.                         MGL that the user has linked the device
  5603.                         driver code directly with the application (or
  5604.                         has loaded it onto the heap) so should not be
  5605.                         dynamically loaded from disk at runtime.
  5606.  
  5607.             Return      grOK on success, grBadDriver if driver passed
  5608.             value       was invalid
  5609.  
  5610.             See also    MGL_init()
  5611.  
  5612.  
  5613.  
  5614.             Chapter 6 - Console Library                               85
  5615.  
  5616.  
  5617.  
  5618.  
  5619.  
  5620.             MGL_restoreAttributes
  5621.  
  5622.             Function    Restores a previously saved attribute list
  5623.  
  5624.             Syntax      void MGL_restoreAttributes(attributes *attr);
  5625.  
  5626.             Prototype   mgraph.h
  5627.             in
  5628.  
  5629.             Parameters  attr - Pointer to the attribute list to
  5630.                         restore
  5631.  
  5632.             Remarks     MGL_restoreAttributes() restores a set of
  5633.                         attributes that were saved with the
  5634.                         MGL_getAttributes() routine. The attributes
  5635.                         list represents the current state of the MGL.
  5636.                         The value of the color palette is not changed
  5637.                         by this routine.
  5638.  
  5639.             See also    MGL_getAttributes
  5640.  
  5641.  
  5642.             MGL_restoreCRTMode
  5643.  
  5644.             Function    Resets the system back into text mode
  5645.  
  5646.             Syntax      void MGL_restoreCRTMode(void);
  5647.  
  5648.             Prototype   mgraph.h
  5649.             in
  5650.  
  5651.             Remarks     MGL_restoreCRTMode() resets the system back
  5652.                         into the original text mode that was present
  5653.                         before the MGL was started. If the system was
  5654.                         in the EGA/VGA 43/50 line modes, this mode
  5655.                         will be reset to its original state. The MGL
  5656.                         can be re-started with the MGL_setGraphMode()
  5657.                         routine.
  5658.  
  5659.             See also    MGL_init(), MGL_setGraphMode()
  5660.  
  5661.  
  5662.             MGL_result
  5663.  
  5664.             Function    Returns result code of the last graphics
  5665.                         operation
  5666.  
  5667.             Syntax      int MGL_result(void);
  5668.  
  5669.             Prototype   mgraph.h
  5670.             in
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.             86                      MegaGraph Graphics Library Reference
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.             Remarks     MGL_result() returns the result code of the
  5687.                         last graphics operation. The internal result
  5688.                         code is reset back to grOK on return from
  5689.                         this routine, so you should only call the
  5690.                         routine once after the graphics operation.
  5691.                         The following result codes are returned by
  5692.                         MGL_result:
  5693.  
  5694.                         grOK             No error
  5695.                         grNoInit         Graphics driver has not been
  5696.                         installed
  5697.                         grNotDetected    Graphics hardware was not
  5698.                         detected
  5699.                         grDriverNotFound Graphics driver file was not
  5700.                         found
  5701.                         grBadDriver      File loaded was not a
  5702.                         graphics driver
  5703.                         grLoadMem        Not enough memory to load
  5704.                         graphics driver
  5705.                         grInvalidMode    Invalid graphics mode for
  5706.                         selected driver
  5707.                         grInvalidDriver  Driver number is invalid
  5708.                         grError          General graphics error
  5709.                         grInvalidName    Invalid driver name
  5710.                         grNoMem          Not enough memory to perform
  5711.                         operation
  5712.                         grNoModeSupport  Select video mode not
  5713.                         supported by hardware
  5714.                         grInvalidFont    Invalid font data
  5715.                         grBadFontFile    File loaded was not a font
  5716.                         file
  5717.                         grFontNotFound   Font file was not found
  5718.  
  5719.             Return      Result code of the last graphics operation
  5720.             value
  5721.  
  5722.             See also    MGL_setResult()
  5723.  
  5724.  
  5725.             MGL_rotatePalette
  5726.  
  5727.             Function    Rotates the values in a palette structure
  5728.  
  5729.             Syntax      void MGL_rotatePalette(palette *pal,int
  5730.                         numColors,int direction);
  5731.  
  5732.             Prototype   mgraph.h
  5733.             in
  5734.  
  5735.             Parameters  pal - Pointer to the palette array to rotate
  5736.                         numColors - Number of colors entries in the
  5737.                         palette array
  5738.                         direction - Direction to rotate the palette
  5739.                         entries
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.             Chapter 6 - Console Library                               87
  5747.  
  5748.  
  5749.  
  5750.  
  5751.  
  5752.             Remarks     MGL_rotatePalette() rotates the values in the
  5753.                         passed palette array in the specified
  5754.                         direction. The palette may be any arbitrary
  5755.                         size, so you can rotate just a subset of the
  5756.                         values in the current physical palette. Note
  5757.                         that this routine has not effect on the
  5758.                         currently active palette. In order to make
  5759.                         the new rotated palette active you will need
  5760.                         to call the MGL_setPalette() routine.
  5761.  
  5762.                         The direction of rotation should be one of
  5763.                         the following:
  5764.  
  5765.                         PAL_ROTATE_UP   - Rotate palette entries up
  5766.                         in memory
  5767.                         PAL_ROTATE_DOWN - Rotate palette entries down
  5768.                         in memory
  5769.  
  5770.                         When the direction specified is
  5771.                         PAL_ROTATE_UP, the first entry in the palette
  5772.                         is moved to the last position in the palette,
  5773.                         and all the remaining entries are move one
  5774.                         position down in the array. The the direction
  5775.                         specified is PAL_ROTATE_DOWN, the last entry
  5776.                         is moved into the first entry of the palette,
  5777.                         and the remaining entries are all moved on
  5778.                         position up in the array.
  5779.  
  5780.             See also    MGL_setPalette(), MGL_getPalette()
  5781.  
  5782.  
  5783.             MGL_scanLeftForColor
  5784.  
  5785.             Function    Scans left in video memory for a specified
  5786.                         color
  5787.  
  5788.             Syntax      int MGL_scanLeftForColor(int x,int y,color_t
  5789.                         color);
  5790.  
  5791.             Prototype   mgraph.h
  5792.             in
  5793.  
  5794.             Parameters  x,y - Location to begin scanline search
  5795.                         color - Color value to search for
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.             88                      MegaGraph Graphics Library Reference
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.             Remarks     MGL_scanLeftForColor() begins scanning in
  5819.                         video memory at the specified location for
  5820.                         the specified color. The search begins at the
  5821.                         location (x,y) and searches left along the
  5822.                         scanline from this point and returns the x
  5823.                         coordinate of the pixel if one is found, or -
  5824.                         1 if the search went beyond the left edge of
  5825.                         the display screen.
  5826.  
  5827.                         No clipping or viewport mapping is performed
  5828.                         by this routine, but can be performed after
  5829.                         calling this routine. This routine can be
  5830.                         used as the basis of a high performance
  5831.                         floodfill operation. Have a look in the file
  5832.                         FFILL.C in the EXAMPLES directory which uses
  5833.                         this routine to implement a fast floodfill
  5834.                         operation.
  5835.  
  5836.             Return      X coordinate of pixel if found, or -1 if
  5837.             value       search hit left edge of display
  5838.  
  5839.             See also    MGL_scanRightForColor(),
  5840.                         MGL_scanLeftWhileColor(),
  5841.                         MGL_scanRightWhileColor()
  5842.  
  5843.  
  5844.             MGL_scanLeftWhileColor
  5845.  
  5846.             Function    Scans left in video memory for any color but
  5847.                         the specified color
  5848.  
  5849.             Syntax      int MGL_scanLeftWhileColor(int x,int
  5850.                         y,color_t color);
  5851.  
  5852.             Prototype   mgraph.h
  5853.             in
  5854.  
  5855.             Parameters  x,y - Location to begin scanline search
  5856.                         color - Color value to search on
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.  
  5867.  
  5868.  
  5869.  
  5870.  
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.             Chapter 6 - Console Library                               89
  5879.  
  5880.  
  5881.  
  5882.  
  5883.  
  5884.             Remarks     MGL_scanLeftWhileColor() begins scanning in
  5885.                         video memory at the specified location and
  5886.                         continues to scan while the pixels are the
  5887.                         same as the specified seed color. The search
  5888.                         begins at the location (x,y) and searches
  5889.                         left along the scanline from this point and
  5890.                         returns the x coordinate of the first pixel
  5891.                         found that is not of the specified color, or
  5892.                         -1 if the search went beyond the left edge of
  5893.                         the display screen.
  5894.  
  5895.                         No clipping or viewport mapping is performed
  5896.                         by this routine, but can be performed after
  5897.                         calling this routine. This routine can be
  5898.                         used as the basis of a high performance
  5899.                         floodfill operation. Have a look in the file
  5900.                         FFILL.C in the EXAMPLES directory which uses
  5901.                         this routine to implement a fast floodfill
  5902.                         operation.
  5903.  
  5904.             Return      X coordinate of pixel if found, -1 if search
  5905.             value       hit left edge of display
  5906.  
  5907.             See also    MGL_scanLeftForColor(),
  5908.                         MGL_scanRightForColor(),
  5909.                         MGL_scanRightWhileColor()
  5910.  
  5911.  
  5912.             MGL_scanLine
  5913.  
  5914.             Function    Fills a specified scanline
  5915.  
  5916.             Syntax      void MGL_scanLine(int y,int x1,int x2);
  5917.  
  5918.             Prototype   mgraph.h
  5919.             in
  5920.  
  5921.             Parameters  y - Y coordinate of scanline to fill
  5922.                         x1 - Starting X coordinate of scanline to
  5923.                         fill
  5924.                         x2 - Ending X coordinate of scanline to fill
  5925.  
  5926.             Remarks     MGL_scanLine() fills the specified portion of
  5927.                         a scanline in the current attributes and fill
  5928.                         pattern. This can be used to implement higher
  5929.                         level complex fills, such as region fills,
  5930.                         floodfills etc.
  5931.  
  5932.             See also    MGL_penStyle(), MGL_setPenBitmapPattern(),
  5933.                         MGL_setPenPixmapPattern()
  5934.  
  5935.  
  5936.  
  5937.  
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.             90                      MegaGraph Graphics Library Reference
  5945.  
  5946.  
  5947.  
  5948.  
  5949.  
  5950.             MGL_scanRightForColor
  5951.  
  5952.             Function    Scans right in video memory for a specified
  5953.                         color
  5954.  
  5955.             Syntax      int MGL_scanRightForColor(int x,int y,color_t
  5956.                         color);
  5957.  
  5958.             Prototype   mgraph.h
  5959.             in
  5960.  
  5961.             Parameters  x,y - Location to begin scanline search
  5962.                         color - Color value to search for
  5963.  
  5964.             Remarks     MGL_scanRightForColor() begins scanning in
  5965.                         video memory at the specified location for
  5966.                         the specified color. The search begins at the
  5967.                         location (x,y) and searches right along the
  5968.                         scanline from this point and returns the x
  5969.                         coordinate of the pixel if one is found, or
  5970.                         one more than the maximum X coordinate if the
  5971.                         search went beyond the right edge of the
  5972.                         display screen.
  5973.  
  5974.                         No clipping or viewport mapping is performed
  5975.                         by this routine, but can be performed after
  5976.                         calling this routine. This routine can be
  5977.                         used as the basis of a high performance
  5978.                         floodfill operation. Have a look in the file
  5979.                         FFILL.C in the EXAMPLES directory which uses
  5980.                         this routine to implement a fast floodfill
  5981.                         operation.
  5982.  
  5983.             Return      X coordinate of pixel if found, or maxx+1 if
  5984.             value       search hit right edge of display
  5985.  
  5986.             See also    MGL_scanLeftForColor(),
  5987.                         MGL_scanLeftWhileColor(),
  5988.                         MGL_scanRightWhileColor()
  5989.  
  5990.  
  5991.             MGL_scanRightWhileColor
  5992.  
  5993.             Function    Scans right in video memory for any color but
  5994.                         the specified color
  5995.  
  5996.             Syntax      int MGL_scanRightWhileColor(int x,int
  5997.                         y,color_t color);
  5998.  
  5999.             Prototype   mgraph.h
  6000.             in
  6001.  
  6002.             Parameters  x,y - Location to begin scanline search
  6003.                         color - Color value to search on
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.             Chapter 6 - Console Library                               91
  6011.  
  6012.  
  6013.  
  6014.  
  6015.  
  6016.             Remarks     MGL_scanRightWhileColor() begins scanning in
  6017.                         video memory at the specified location and
  6018.                         continues to scan while the pixels are the
  6019.                         same as the specified seed color. The search
  6020.                         begins at the location (x,y) and searches
  6021.                         right along the scanline from this point and
  6022.                         returns the x coordinate of the first pixel
  6023.                         found that is not of the specified color, or
  6024.                         one more than the maximum X coordinate if the
  6025.                         search went beyond the right edge of the
  6026.                         display screen.
  6027.  
  6028.                         No clipping or viewport mapping is performed
  6029.                         by this routine, but can be performed after
  6030.                         calling this routine. This routine can be
  6031.                         used as the basis of a high performance
  6032.                         floodfill operation. Have a look in the file
  6033.                         FFILL.C in the EXAMPLES directory which uses
  6034.                         this routine to implement a fast floodfill
  6035.                         operation.
  6036.  
  6037.             Return      X coordinate of pixel if found, maxx+1 if
  6038.             value       search hit right edge of display
  6039.  
  6040.             See also    MGL_scanLeftForColor(),
  6041.                         MGL_scanRightForColor(),
  6042.                         MGL_scanLeftWhileColor()
  6043.  
  6044.  
  6045.             MGL_setActivePage
  6046.  
  6047.             Function    Sets the currently active hardware display
  6048.                         page.
  6049.  
  6050.             Syntax      void MGL_setActivePage(int page);
  6051.  
  6052.             Prototype   mgraph.h
  6053.             in
  6054.  
  6055.             Parameters  page - Number of active hardware display page
  6056.                         to use
  6057.  
  6058.             Remarks     MGL_setActivePage() sets the currently active
  6059.                         hardware video page number to which all
  6060.                         output from the MGL is sent to. The first
  6061.                         hardware video page is number 0, the second
  6062.                         is 1 and so on. The number of available
  6063.                         hardware video pages depends on the type of
  6064.                         underlying hardware, the video mode
  6065.                         resolution and amount of video memory
  6066.                         installed. Thus not all video modes support
  6067.                         multiple hardware video pages,
  6068.  
  6069.             See also    MGL_getActivePage(), MGL_setVisualPage(),
  6070.                         MGL_getVisualPage()
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.             92                      MegaGraph Graphics Library Reference
  6077.  
  6078.  
  6079.  
  6080.  
  6081.  
  6082.             MGL_setAspectRatio
  6083.  
  6084.             Function    Sets the current video modes aspect ratio
  6085.  
  6086.             Syntax      void MGL_setAspectRatio(int aspectRatio);
  6087.  
  6088.             Prototype   mgraph.h
  6089.             in
  6090.  
  6091.             Parameters  aspectRatio - New value for the aspect ratio
  6092.  
  6093.             Remarks     MGL_setAspectRatio() sets the aspect ratio of
  6094.                         the currently active output device's physical
  6095.                         pixels. This ratio is equal to:
  6096.  
  6097.                                   pixel x size                                          1000                                          x 
  6098.                                   pixel y size
  6099.  
  6100.                         The device aspect ratio can be used to
  6101.                         display circles and squares on the display
  6102.                         device by approximating them with ellipses
  6103.                         and rectangles of the appropriate dimensions.
  6104.                         Thus in order to determine the number of
  6105.                         pixels in the y direction for a square with
  6106.                         100 pixels in the x direction, we can simply
  6107.                         use the formula:
  6108.  
  6109.                         y_pixels = ((long)x_pixels * 1000) /
  6110.                         aspectratio
  6111.  
  6112.                         Note the cast to a long to avoid arithmetic
  6113.                         overflow, as the apsect ratio is returned as
  6114.                         an integer value with 1000 being a 1:1 aspect
  6115.                         ratio.
  6116.  
  6117.                         Normally you should not need to change the
  6118.                         aspect ratio, as the MGL will automatically
  6119.                         determine the correct aspect ratio for the
  6120.                         current display mode.
  6121.  
  6122.             See also    MGL_getAspectRatio()
  6123.  
  6124.  
  6125.             MGL_setBackColor
  6126.  
  6127.             Function    Sets the currently active background color
  6128.  
  6129.             Syntax      void MGL_setBackColor(color_t color);
  6130.  
  6131.             Prototype   mgraph.h
  6132.             in
  6133.  
  6134.             Parameters  color - New background color value
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.             Chapter 6 - Console Library                               93
  6143.  
  6144.  
  6145.  
  6146.  
  6147.  
  6148.             Remarks     MGL_setBackColor() sets the current
  6149.                         background color value. The background color
  6150.                         value is used to clear the display and
  6151.                         viewport with the MGL_clearDevice() and
  6152.                         MGL_clearViewport() routines, and is also
  6153.                         used for filling solid primitives in the
  6154.                         BITMAP_PATTERN_OPAQUE fill mode.
  6155.  
  6156.                         Note: The value passed to this routine is
  6157.                         either a color index or a color value in the
  6158.                         correct packed pixel format for the current
  6159.                         video mode. Use the MGL_packColor() routine
  6160.                         to pack 24 bit RGB values for direct color
  6161.                         video modes.
  6162.  
  6163.             See also    MGL_getBackColor(), MGL_setColor(),
  6164.                         MGL_getColor(), MGL_packColor()
  6165.  
  6166.  
  6167.             MGL_setBorderColors
  6168.  
  6169.             Function    Sets the current border color values.
  6170.  
  6171.             Syntax      void MGL_setBorderColors(color_t
  6172.                         bright,color_t dark);
  6173.  
  6174.             Prototype   mgraph.h
  6175.             in
  6176.  
  6177.             Parameters  bright - New value for border bright color
  6178.                         dark - New value for border dark color
  6179.  
  6180.             Remarks     MGL_setBorderColors() sets the currently
  6181.                         active border colors values. There are two
  6182.                         border color defined by the MGL, the bright
  6183.                         border color value and the      border color                                                   dark
  6184.                         value. These values are used by the
  6185.                         MGL_drawBorder(), MGL_drawHDivider() and
  6186.                         MGL_drawVDivider() routines to determine the
  6187.                         colors to draw the psuedo 3D borders in.
  6188.                         These values will be set automatically for
  6189.                         you by default when the MGL is initisalised,
  6190.                         but you will need to change these values if
  6191.                         you modify the palette.
  6192.  
  6193.                         Note: The value passed to this routine is
  6194.                         either a color index or a color value in the
  6195.                         correct packed pixel format for the current
  6196.                         video mode. Use the MGL_packColor() routine
  6197.                         to pack 24 bit RGB values for direct color
  6198.                         video modes.
  6199.  
  6200.             See also    MGL_getBorderColors(), MGL_packColor()
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.             94                      MegaGraph Graphics Library Reference
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  
  6214.             MGL_setBufSize
  6215.  
  6216.             Function    Sets the size of the internal MGL buffer.
  6217.  
  6218.             Syntax      void MGL_setBufSize(unsigned size);
  6219.  
  6220.             Prototype   mgraph.h
  6221.             in
  6222.  
  6223.             Parameters  size - New size of the internal MGL buffer
  6224.  
  6225.             Remarks     MGL_setBufSize() sets the size of the
  6226.                         internal MGL buffer. When the MGL is
  6227.                         rendering primitives, it needs a buffer of
  6228.                         local scratch space that it can uses for
  6229.                         temporary results while rendering the
  6230.                         primitives.
  6231.  
  6232.                         The default size of this buffer is 4096 bytes
  6233.                         and is adequate for most needs. If however
  6234.                         you attempt to render some primitives and the
  6235.                         MGL runs out of local storage space you would
  6236.                         need to increase the size of this internal
  6237.                         buffer.
  6238.  
  6239.                         This routine must be called        the MGL is                                                    before
  6240.                         initialised for the first time.
  6241.  
  6242.             See also    MGL_init()
  6243.  
  6244.  
  6245.             MGL_setClipMode
  6246.  
  6247.             Function    Sets the clipping mode for the MGL
  6248.  
  6249.             Syntax      void MGL_setClipMode(bool mode);
  6250.  
  6251.             Prototype   mgraph.h
  6252.             in
  6253.  
  6254.             Parameters  mode - True for clipping to be turned on,
  6255.                         false for no clipping.
  6256.  
  6257.             Remarks     MGL_setClipMode() sets the current clipping
  6258.                         mode. You can selectively turn clipping on
  6259.                         and off for the MGL, in order to speed up
  6260.                         some operations. Clipping is turned on by
  6261.                         default, and generally you will want to leave
  6262.                         clipping enabled, however if you are doing
  6263.                         your own rendering and perform your own
  6264.                         clipping you may want to turn this off for
  6265.                         extra performance from the MGL.
  6266.  
  6267.             See also    MGL_getClipMode()
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.             Chapter 6 - Console Library                               95
  6275.  
  6276.  
  6277.  
  6278.  
  6279.  
  6280.             MGL_setClipRect
  6281.  
  6282.             Function    Sets the current clipping rectangle
  6283.  
  6284.             Syntax      void MGL_setClipRect(rect clip);
  6285.  
  6286.             Prototype   mgraph.h
  6287.             in
  6288.  
  6289.             Parameters  clip - New clipping rectangle to be used.
  6290.  
  6291.             Remarks     MGL_setClipRect() sets the current clipping
  6292.                         rectangle coordinates. The current clipping
  6293.                         rectangle is used to clip all output, and is
  6294.                         always defined as being relative to the
  6295.                         currently active viewport The clipping
  6296.                         rectangle can be no larger than the currently
  6297.                         active viewport, and will be truncated if an
  6298.                         attempt it made to allow clipping outside of
  6299.                         the active viewport.
  6300.  
  6301.             See also    MGL_getClipRect, MGL_setViewport(),
  6302.                         MGL_getViewport()
  6303.  
  6304.  
  6305.             MGL_setColor
  6306.  
  6307.             Function    Sets the current foreground color
  6308.  
  6309.             Syntax      void MGL_setColor(color_t color);
  6310.  
  6311.             Prototype   mgraph.h
  6312.             in
  6313.  
  6314.             Parameters  color - New foreground color value
  6315.  
  6316.             Remarks     MGL_setColor() sets the current foreground
  6317.                         color values. The foreground color value is
  6318.                         used to draw all primitives.
  6319.  
  6320.                         Note: The value passed to this routine is
  6321.                         either a color index or a color value in the
  6322.                         correct packed pixel format for the current
  6323.                         video mode. Use the MGL_packColor() routine
  6324.                         to pack 24 bit RGB values for direct color
  6325.                         video modes.
  6326.  
  6327.             See also    MGL_getColor(), MGL_setBackColor(),
  6328.                         MGL_getBackColor(), MGL_packColor()
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.             96                      MegaGraph Graphics Library Reference
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.             MGL_setCursorColor
  6347.  
  6348.             Function    Sets the current mouse cursor color.
  6349.  
  6350.             Syntax      void MGL_setCursorColor(color_t color);
  6351.  
  6352.             Prototype   mgraph.h
  6353.             in
  6354.  
  6355.             Parameters  color - New mouse cursor color value
  6356.  
  6357.             Remarks     MGL_setCursorColor() sets the currently
  6358.                         active mouse cursor color. The mouse cursor
  6359.                         color is used to determine what foreground
  6360.                         color is used to draw the mouse cursor in.
  6361.  
  6362.                         Note: The value passed to this routine is
  6363.                         either a color index or a color value in the
  6364.                         correct packed pixel format for the current
  6365.                         video mode. Use the MGL_packColor() routine
  6366.                         to pack 24 bit RGB values for direct color
  6367.                         video modes.
  6368.  
  6369.             See also    MGL_getCursorColor(), MGL_packColor()
  6370.  
  6371.  
  6372.             MGL_setDefaultPalette
  6373.  
  6374.             Function    Resets the palette to the MGL defaut values.
  6375.  
  6376.             Syntax      void MGL_setDefaultPalette(void);
  6377.  
  6378.             Prototype   mgraph.h
  6379.             in
  6380.  
  6381.             Remarks     MGL_setDefaultPalette() sets the palette to
  6382.                         the current MGL default values for the
  6383.                         current video mode. This can be used to reset
  6384.                         the palette to the original default values
  6385.                         that the palette is programmed with when the
  6386.                         MGL is initialised.
  6387.  
  6388.             See also    MGL_getDefaultPalette(), MGL_setPalette(),
  6389.                         MGL_getPalette()
  6390.  
  6391.  
  6392.             MGL_setGraphMode
  6393.  
  6394.             Function    Restarts graphics mode operation.
  6395.  
  6396.             Syntax      void MGL_setGraphMode(void);
  6397.  
  6398.             Prototype   mgraph.h
  6399.             in
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.             Chapter 6 - Console Library                               97
  6407.  
  6408.  
  6409.  
  6410.  
  6411.  
  6412.             Remarks     MGL_setGraphMode() restarts the graphics mode
  6413.                         operation of the MGL after MGL_restoreCRTMode
  6414.                         has been called to put the system back into
  6415.                         the original text mode. To start the graphics
  6416.                         mode initialially, you call the MGL_int()
  6417.                         routine.
  6418.  
  6419.             See also    MGL_restoreCRTMode(), MGL_init()
  6420.  
  6421.  
  6422.             MGL_setMarkerColor
  6423.  
  6424.             Function    Sets the current marker color value.
  6425.  
  6426.             Syntax      void MGL_setMarkerColor(color_t color);
  6427.  
  6428.             Prototype   mgraph.h
  6429.             in
  6430.  
  6431.             Parameters  color - New marker color to set
  6432.  
  6433.             Remarks     MGL_setMarkerColor() sets the current marker
  6434.                         color value. The marker color is used when
  6435.                         drawing markers with the MGL_marker()
  6436.                         routine.
  6437.  
  6438.                         Note: The value passed to this routine is
  6439.                         either a color index or a color value in the
  6440.                         correct packed pixel format for the current
  6441.                         video mode. Use the MGL_packColor() routine
  6442.                         to pack 24 bit RGB values for direct color
  6443.                         video modes.
  6444.  
  6445.             See also    MGL_getMarkerColor(), MGL_marker(),
  6446.                         MGL_polyMarker(), MGL_packColor()
  6447.  
  6448.  
  6449.             MGL_setMarkerSize
  6450.  
  6451.             Function    Sets the current marker size value.
  6452.  
  6453.             Syntax      void MGL_setMarkerSize(int size);
  6454.  
  6455.             Prototype   mgraph.h
  6456.             in
  6457.  
  6458.             Parameters  size - New marker size
  6459.  
  6460.             Remarks     MGL_setMarkerSize() sets the current marker
  6461.                         size. The marker size is used to determine
  6462.                         how big to draw the markers that are drawn
  6463.                         with the MGL_marker() routine. The size is
  6464.                         defined as dimension from the middle of the
  6465.                         marker to the edges, so the actual dimensions
  6466.                         of the marker will be approximately twice the
  6467.                         maker size. If marker size of 1 will define a
  6468.                         marker that is contained within a rectangle 3
  6469.                         pixels wide.
  6470.  
  6471.  
  6472.             98                      MegaGraph Graphics Library Reference
  6473.  
  6474.  
  6475.  
  6476.  
  6477.  
  6478.  
  6479.             See also    MGL_getMarkerSize(), MGL_marker(),
  6480.                         MGL_polyMarker()
  6481.  
  6482.  
  6483.             MGL_setMarkerStyle
  6484.  
  6485.             Function    Sets the current marker style.
  6486.  
  6487.             Syntax      void MGL_setMarkerStyle(int style);
  6488.  
  6489.             Prototype   mgraph.h
  6490.             in
  6491.  
  6492.             Parameters  style - New marker style value.
  6493.  
  6494.             Remarks     MGL_setMarkerStyle() sets the current marker
  6495.                         style value. The marker style defines the
  6496.                         type of marker to be rendered. Currently the
  6497.                         MGL defines the following markers:
  6498.  
  6499.                         MARKER_SQUARE - A solid square
  6500.                         MARKER_CIRCLE - A solid circle
  6501.                         MARKER_X      - A cross made of two lines
  6502.  
  6503.             See also    MGL_getMarkerStyle(), MGL_marker(),
  6504.                         MGL_polyMarker()
  6505.  
  6506.  
  6507.             MGL_setPalette
  6508.  
  6509.             Function    Sets the currently active palette values.
  6510.  
  6511.             Syntax      void MGL_setPalette(palette *pal,int
  6512.                         numColors,int startIndex);
  6513.  
  6514.             Prototype   mgraph.h
  6515.             in
  6516.  
  6517.             Parameters  pal - Pointer to array of palette values to
  6518.                         program
  6519.                         numColors - Number of colors to program from
  6520.                         the array
  6521.                         startIndex - Starting index to program from
  6522.                         in the array
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.  
  6529.  
  6530.  
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.             Chapter 6 - Console Library                               99
  6539.  
  6540.  
  6541.  
  6542.  
  6543.  
  6544.             Remarks     MGL_setPalette() sets part or all of the
  6545.                         currently active palette given the values
  6546.                         passed in the array    . You can specify only                                            pal
  6547.                         a subset of the palette values to be modified
  6548.                         with the startIndex and numColors arguments.
  6549.  
  6550.                         Thus to set the entire palette in a 256 color
  6551.                         video mode, you would use:
  6552.  
  6553.                             MGL_setPalette(pal,255,0);
  6554.  
  6555.                         or to set the top half of the palette you
  6556.                         would use:
  6557.  
  6558.                             MGL_setPalette(pal,128,128);
  6559.  
  6560.                         Note that the MGL will ensure that the
  6561.                         palette is programmed without snow depending
  6562.                         on the value of the current snow level
  6563.                         defined by calling the
  6564.                         MGL_setPaletteSnowLevel() routine, and will
  6565.                         wait for the start of a vertical retrace
  6566.                         before the first entry is programmed.
  6567.  
  6568.             See also    MGL_getPalette(), MGL_setPaletteEntry(),
  6569.                         MGL_setPaletteSnowLevel(),
  6570.                         MGL_getPaletteSnowLevel()
  6571.  
  6572.  
  6573.  
  6574.             MGL_setPaletteEntry
  6575.  
  6576.             Function
  6577.  
  6578.             Syntax      void MGL_setPaletteEntry(int entry,uchar
  6579.                         red,uchar green,uchar blue);
  6580.  
  6581.             Prototype   mgraph.h
  6582.             in
  6583.  
  6584.             Parameters  entry - Palette index to program
  6585.                         red - Red component for palette entry
  6586.                         green - Green component for palette entry
  6587.                         blue - Blue component for palette entry
  6588.  
  6589.             Remarks     MGL_setPaletteEntry() sets the color values
  6590.                         of a single palette entry. If you wish to set
  6591.                         more than a single palette index you should
  6592.                         use the MGL_setPalette() routine which is
  6593.                         faster for multiple entries. The main reason
  6594.                         for this is that this routine will wait for a
  6595.                         vertical retrace before the palette entry is
  6596.                         programmed to ensure that snow does not
  6597.                         occur.
  6598.  
  6599.             See also    MGL_getPaletteEntry(), MGL_setPalette(),
  6600.                         MGL_getPalette()
  6601.  
  6602.  
  6603.  
  6604.             100                     MegaGraph Graphics Library Reference
  6605.  
  6606.  
  6607.  
  6608.  
  6609.  
  6610.             MGL_setPaletteSnowLevel
  6611.  
  6612.             Function    Sets the current palette snow level
  6613.  
  6614.             Syntax      void MGL_setPaletteSnowLevel(int level);
  6615.  
  6616.             Prototype   mgraph.h
  6617.             in
  6618.  
  6619.             Parameters  level - New snow level
  6620.  
  6621.             Remarks     MGL_setPaletteSnowLevel() sets the number of
  6622.                         palette entries that can be programmed during
  6623.                         a single vertical retrace before the onset of
  6624.                         snow. The MGL uses a reasonable default of
  6625.                         100 entries per retrace, but you may want to
  6626.                         modify this on faster or slower machines
  6627.                         (this should be a user option). In the future
  6628.                         the MGL will automatically determine the
  6629.                         optimum value for this at initialisation
  6630.                         time.
  6631.  
  6632.             See also    MGL_getPaletteSnowLevel(), MGL_setPalette()
  6633.  
  6634.  
  6635.             MGL_setPenBitmapPattern
  6636.  
  6637.             Function    Sets the currently active bitmap pattern.
  6638.  
  6639.             Syntax      void MGL_setPenBitmapPattern(pattern *pat);
  6640.  
  6641.             Prototype   mgraph.h
  6642.             in
  6643.  
  6644.             Parameters  pat - New bitmap pattern to use.
  6645.  
  6646.             Remarks     MGL_setPenBitmapPattern() sets the currently
  6647.                         active bitmap pattern used when rendering
  6648.                         patterned primitive in the
  6649.                         BITMAP_PATTERN_TRANSPARENT and
  6650.                         BITMAP_PATTERN_OPQAUE pen styles. A bitmap
  6651.                         pattern is defined as an 8 x 8 pixel bitmap
  6652.                         pattern stored as an array of 8 bytes. The
  6653.                         pattern value is copied from the passed
  6654.                         structure.
  6655.  
  6656.                         When filling in the
  6657.                         BITMAP_PATTERN_TRANSPARENT mode, the
  6658.                         foreground color is used to fill in all
  6659.                         pixels in the bitmap pattern that are a 1.
  6660.                         Where the pixels in the bitmap pattern are a
  6661.                         0, the original background color is retained.
  6662.                         In the BITMAP_PATTERN_OPAQUE mode, the
  6663.                         background color is used to fill in the
  6664.                         pixels in the bitmap that are set to a 0.
  6665.  
  6666.             See also    MGL_getPenBitmapPattern(), MGL_setPenStyle(),
  6667.                         MGL_getPenStyle()
  6668.  
  6669.  
  6670.             Chapter 6 - Console Library                              101
  6671.  
  6672.  
  6673.  
  6674.  
  6675.  
  6676.  
  6677.  
  6678.             MGL_setPenSize
  6679.  
  6680.             Function    Sets the current pen size
  6681.  
  6682.             Syntax      void MGL_setPenSize(int height,int width);
  6683.  
  6684.             Prototype   mgraph.h
  6685.             in
  6686.  
  6687.             Parameters  height - Height of the pen in pixels
  6688.                         width - Width of the pen in pixels
  6689.  
  6690.             Remarks     MGL_setPenSize() sets the size of the current
  6691.                         pen in pixels. The default pen is 1 pixel by
  6692.                         1 pixel in dimensions, however you can change
  6693.                         this to whatever value you like. When
  6694.                         primitive are rendered with a pen other than
  6695.                         the default, the pixels in the pen always lie
  6696.                         to the right and below the current pen
  6697.                         position.
  6698.  
  6699.             See also    MGL_getPenSize()
  6700.  
  6701.  
  6702.             MGL_setPenStyle
  6703.  
  6704.             Function    Sets the current pen style
  6705.  
  6706.             Syntax      void MGL_setPenStyle(int style);
  6707.  
  6708.             Prototype   mgraph.h
  6709.             in
  6710.  
  6711.             Parameters  style - New pen style to use.
  6712.  
  6713.             Remarks     MGL_getPenStyle() returns the currently
  6714.                         active pen style. The MGL supports the
  6715.                         following pen styles:
  6716.  
  6717.                         SOLID_PATTERN              - Fill with solid
  6718.                         color
  6719.                         BITMAP_PATTERN_OPAQUE      - Pattern fill
  6720.                         BITMAP_PATTERN_TRANSPARENT - Transparent
  6721.                         pattern fill
  6722.  
  6723.                         When filling in the
  6724.                         BITMAP_PATTERN_TRANSPARENT mode, the
  6725.                         foreground color is used to fill in all
  6726.                         pixels in the bitmap pattern that are a 1.
  6727.                         Where the pixels in the bitmap pattern are a
  6728.                         0, the original background color is retained.
  6729.                         In the BITMAP_PATTERN_OPAQUE mode, the
  6730.                         background color is used to fill in the
  6731.                         pixels in the bitmap that are set to a 0.
  6732.  
  6733.             See also    MGL_getPenStyle(), MGL_setPenBitmapPattern()
  6734.  
  6735.  
  6736.             102                     MegaGraph Graphics Library Reference
  6737.  
  6738.  
  6739.  
  6740.  
  6741.  
  6742.  
  6743.  
  6744.             MGL_setPolygonType
  6745.  
  6746.             Function    Sets the current polygon type
  6747.  
  6748.             Syntax      void MGL_setPolygonType(int type);
  6749.  
  6750.             Prototype   mgraph.h
  6751.             in
  6752.  
  6753.             Parameters  type - New polygon type
  6754.  
  6755.             Remarks     MGL_setPolygonType() sets the current polygon
  6756.                         type. You can change this value to force the
  6757.                         MGL to work with a specific polygon type (and
  6758.                         to avoid the default automatic polygon type
  6759.                         checking). The MGL supports the following
  6760.                         polygon types:
  6761.  
  6762.                         AUTO_POLYGON    - MGL automatically
  6763.                         determines type
  6764.                         CONVEX_POLYGON  - All polygons rendered as
  6765.                         convex
  6766.                         COMPLEX_POLYGON - All polygons rendered as
  6767.                         complex
  6768.  
  6769.                         If you expect to be drawing lots of complex
  6770.                         or convex polygons, setting the polygon type
  6771.                         can result in faster polygon rendering.
  6772.  
  6773.             See also    MGL_getPolygonType(), MGL_fillPolygon()
  6774.  
  6775.  
  6776.             MGL_setRelViewport
  6777.  
  6778.             Function    Sets a viewport relative to the current one
  6779.  
  6780.             Syntax      void MGL_setRelViewport(rect view);
  6781.  
  6782.             Prototype   mgraph.h
  6783.             in
  6784.  
  6785.             Parameters  view - Bounding rectangle for the new
  6786.                         viewport.
  6787.  
  6788.             Remarks     MGL_setRelViewport() sets the current
  6789.                         viewport to the viewport specified by view,
  6790.                         where view is relative to the currently
  6791.                         active viewport. The new viewport is
  6792.                         restricted to fall within the bounds of the
  6793.                         currently active viewport.
  6794.  
  6795.                         All output in the MGL is relative to the
  6796.                         current viewport, so by changing the viewport
  6797.                         to a new value you can make all output appear
  6798.                         in a different rectangular portion of the
  6799.                         video display.
  6800.  
  6801.  
  6802.             Chapter 6 - Console Library                              103
  6803.  
  6804.  
  6805.  
  6806.  
  6807.  
  6808.  
  6809.             See also    MGL_getViewport(), MGL_setViewport(),
  6810.                         MGL_clearViewport(), MGL_setClipRect()
  6811.  
  6812.  
  6813.             MGL_setResult
  6814.  
  6815.             Function    Sets the internal MGL result flag.
  6816.  
  6817.             Syntax      void MGL_setResult(int result)
  6818.  
  6819.             Prototype   mgraph.h
  6820.             in
  6821.  
  6822.             Parameters  result - New internal result flag
  6823.  
  6824.             Remarks     MGL_setResult() sets the internal MGL result
  6825.                         flag to the specified value. This routine is
  6826.                         primarily for extension libraries, but you
  6827.                         can use it to add your own extension
  6828.                         functions to the MGL that will return result
  6829.                         codes in the same manner as the MGL.
  6830.  
  6831.             See also    MGL_getResult()
  6832.  
  6833.  
  6834.             MGL_setSpaceExtra
  6835.  
  6836.             Function    Sets the current space extra value.
  6837.  
  6838.             Syntax      void MGL_setSpaceExtra(int extra);
  6839.  
  6840.             Prototype   mgraph.h
  6841.             in
  6842.  
  6843.             Parameters  extra - New space extra value.
  6844.  
  6845.             Remarks     MGL_setSpaceExtra() sets the current space
  6846.                         extra value used when drawing text in the
  6847.                         current font. The space extra vaue is
  6848.                         normally zero, but can be a positive or
  6849.                         negative value. This value can be used to
  6850.                         insert extra space between the characters in
  6851.                         a font (making this value a large negative
  6852.                         value will make the characters run on top of
  6853.                         each other).
  6854.  
  6855.             See also    MGL_getSpaceExtra(), MGL_drawStr()
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.             104                     MegaGraph Graphics Library Reference
  6869.  
  6870.  
  6871.  
  6872.  
  6873.  
  6874.             MGL_setTextDirection
  6875.  
  6876.             Function    Sets the current text direction
  6877.  
  6878.             Syntax      void MGL_setTextDirection(int direction);
  6879.  
  6880.             Prototype   mgraph.h
  6881.             in
  6882.  
  6883.             Parameters  direction - New text direction value
  6884.  
  6885.             Remarks     MGL_setTextDirection() sets the current text
  6886.                         direction. The MGL supports the following
  6887.                         text directions:
  6888.  
  6889.                         LEFT_DIR  - Text runs to the left (right to
  6890.                         left)
  6891.                         UP_DIR    - Text runs in the up direction
  6892.                         RIGHT_DIR - Text runs to the right (left to
  6893.                         right)
  6894.                         DOWN_DIR  - Text runs in the down direction
  6895.  
  6896.                         Currently the MGL only supports directional
  6897.                         text with the default 8x8 bitmap font and
  6898.                         vector fonts. Bitmap fonts can only be drawn
  6899.                         in the RIGHT_DIR direction.
  6900.  
  6901.             See also    MGL_getTextDirection(), MGL_drawStr()
  6902.  
  6903.  
  6904.             MGL_setTextJustify
  6905.  
  6906.             Function    Sets the current text horizontal and vertical
  6907.                         justification
  6908.  
  6909.             Syntax      void MGL_setTextJustify(int horiz,int vert);
  6910.  
  6911.             Prototype   mgraph.h
  6912.             in
  6913.  
  6914.             Parameters  horiz - New horiztonal text justification
  6915.                         value
  6916.                         vert - New vertical text justification value
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922.  
  6923.  
  6924.  
  6925.  
  6926.  
  6927.  
  6928.  
  6929.  
  6930.  
  6931.  
  6932.  
  6933.  
  6934.             Chapter 6 - Console Library                              105
  6935.  
  6936.  
  6937.  
  6938.  
  6939.  
  6940.             Remarks     MGL_setTextJustify() sets the current text
  6941.                         justification values. The MGL supports the
  6942.                         following horizontal justification types:
  6943.  
  6944.                         LEFT_TEXT     - Text is left justified
  6945.                         CENTER_TEXT   - Text is centered left to
  6946.                         right
  6947.                         RIGHT_TEXT    - Text is right justified
  6948.  
  6949.                         and the following vertical justification
  6950.                         types:
  6951.  
  6952.                         TOP_TEXT      - Text is top justified
  6953.                         CENTER_TEXT   - Text is centered top to
  6954.                         bottom
  6955.                         BASELINE_TEXT - Text is justified to the
  6956.                         baseline
  6957.                         BOTTOM_TEXT   - Text is bottom justified
  6958.  
  6959.             See also    MGL_getTextJustify()
  6960.  
  6961.  
  6962.             MGL_setTextSettings
  6963.  
  6964.             Function    Restores the current text settings.
  6965.  
  6966.             Syntax      void MGL_setTextSettings(text_settings
  6967.                         *settings);
  6968.  
  6969.             Prototype   mgraph.h
  6970.             in
  6971.  
  6972.             Parameters  settings - Text settings to restore
  6973.  
  6974.  
  6975.  
  6976.  
  6977.  
  6978.  
  6979.  
  6980.  
  6981.  
  6982.  
  6983.  
  6984.  
  6985.  
  6986.  
  6987.  
  6988.  
  6989.  
  6990.  
  6991.  
  6992.  
  6993.  
  6994.  
  6995.  
  6996.  
  6997.  
  6998.  
  6999.  
  7000.             106                     MegaGraph Graphics Library Reference
  7001.  
  7002.  
  7003.  
  7004.  
  7005.  
  7006.             Remarks     MGL_setTextSettings() restores a set of
  7007.                         previously saved text settings. This routine
  7008.                         is provides a way to save and restore all the
  7009.                         values relating to the rendering of text in
  7010.                         the MGL with a single function call. The text
  7011.                         settings values are stored in the following
  7012.                         structure:
  7013.  
  7014.                         typedef struct {
  7015.                             int             horiz_just;
  7016.                             int             vert_just;
  7017.                             int             dir;
  7018.                             int             sz_numerx;
  7019.                             int             sz_numery;
  7020.                             int             sz_denomx;
  7021.                             int             sz_denomy;
  7022.                             int             space_extra;
  7023.                             font            *fnt;
  7024.  
  7025.                         where horiz_just     vert_just                                         and           define the
  7026.                         horizontal and vertical justification values,
  7027.                             defines the current text direction,                        dir
  7028.                         space_extra defines the current space extra
  7029.                         value and     define the currently active                                  fnt
  7030.                         font (stored in system memory). The
  7031.                         sz_numerx, sz_numery, sz_demonx and sz_denomy
  7032.                         specify the current text scaling factors.
  7033.  
  7034.             See also    MGL_getTextSettings()
  7035.  
  7036.  
  7037.             MGL_setTextSize
  7038.  
  7039.             Function    Sets the current text scaling factors
  7040.  
  7041.             Syntax      void MGL_setTextSize(int numerx,int
  7042.                         denomx,int numery,int denomy);
  7043.  
  7044.             Prototype   mgraph.h
  7045.             in
  7046.  
  7047.             Parameters  numerx - X scaling numerator value
  7048.                         denomx - X scaling denominator value
  7049.                         numery - Y scaling numerator value
  7050.                         denomy - Y scaling denominator value
  7051.  
  7052.             Remarks     MGL_setTextSize() sets the current text
  7053.                         scaling factors used by the MGL. The text
  7054.                         size values define an integer scaling factor
  7055.                         to be used, where the actual values will be
  7056.                         computed using the following formula:
  7057.  
  7058.                                   scaled                                       unscaled                                             numer
  7059.                                           denom
  7060.  
  7061.                         Note: Currently the MGL can only scale
  7062.                         vectors fonts.
  7063.  
  7064.  
  7065.  
  7066.             Chapter 6 - Console Library                              107
  7067.  
  7068.  
  7069.  
  7070.  
  7071.  
  7072.             See also    MGL_getTextSize()
  7073.  
  7074.  
  7075.             MGL_setViewport
  7076.  
  7077.             Function    Sets the currently active viewport
  7078.  
  7079.             Syntax      void MGL_setViewport(rect view);
  7080.  
  7081.             Prototype   mgraph.h
  7082.             in
  7083.  
  7084.             Parameters  view - New global viewport bounding rectangle
  7085.  
  7086.             Remarks     MGL_setViewport() sets the dimensions of the
  7087.                         currently active viewport. These dimensions
  7088.                         are global to the entire display area used by
  7089.                         the currently active video device driver.
  7090.  
  7091.                         All output in the MGL is relative to the
  7092.                         current viewport, so by changing the viewport
  7093.                         to a new value you can make all output appear
  7094.                         in a different rectangular portion of the
  7095.                         video display.
  7096.  
  7097.             See also    MGL_getViewport(), MGL_setRelViewport(),
  7098.                         MGL_clearViewport(), MGL_setClipRect()
  7099.  
  7100.  
  7101.             MGL_setVisualPage
  7102.  
  7103.             Function    Sets the currently visible hardware video
  7104.                         page.
  7105.  
  7106.             Syntax      int MGL_setVisualPage(int page);
  7107.  
  7108.             Prototype   mgraph.h
  7109.             in
  7110.  
  7111.             Parameters  page - New visible hardware page number
  7112.  
  7113.             Remarks     MGL_setVisualPage() sets the currently
  7114.                         visible hardware video page number. The first
  7115.                         hardware video page is number 0, the second
  7116.                         is 1 and so on. The number of available
  7117.                         hardware video pages depends on the type of
  7118.                         underlying hardware, the video mode
  7119.                         resolution and amount of video memory
  7120.                         installed. Thus not all video modes support
  7121.                         multiple hardware video pages.
  7122.  
  7123.             See also    MGL_getVisualPage(), MGL_getActivePage(),
  7124.                         MGL_setActivePage().
  7125.  
  7126.  
  7127.  
  7128.  
  7129.  
  7130.  
  7131.  
  7132.             108                     MegaGraph Graphics Library Reference
  7133.  
  7134.  
  7135.  
  7136.  
  7137.  
  7138.             MGL_setWriteMode
  7139.  
  7140.             Function    Sets the current write mode operation
  7141.  
  7142.             Syntax      int MGL_setWriteMode(int mode);
  7143.  
  7144.             Prototype   mgraph.h
  7145.             in
  7146.  
  7147.             Parameters  mode - New write mode operation to use
  7148.  
  7149.             Remarks     MGL_setWriteMode() sets the currently active
  7150.                         write mode. The MGL supports the following
  7151.                         write mode operations for all output
  7152.                         primitives:
  7153.  
  7154.                         REPLACE_MODE - Replace the original pixels
  7155.                         AND_MODE     - Logical AND with original
  7156.                         pixels
  7157.                         OR_MODE      - Logical OR with original
  7158.                         pixels
  7159.                         XOR_MODE     - Logical XOR with original
  7160.                         pixels
  7161.  
  7162.             See also    MGL_getWriteMode()
  7163.  
  7164.  
  7165.             MGL_singleBuffer
  7166.  
  7167.             Function    Returns the system back to single buffered
  7168.                         mode.
  7169.  
  7170.             Syntax      void MGL_singleBuffer(void);
  7171.  
  7172.             Prototype   mgraph.h
  7173.             in
  7174.  
  7175.             Remarks     MGL_singleBuffer   puts the system back into                                        ()
  7176.                         single buffer mode. The active display page
  7177.                         is made to be the same as the current visual
  7178.                         display page for hardware double buffering.
  7179.                         This may or may not be the first hardware
  7180.                         video page.
  7181.  
  7182.             See also    MGL_doubleBuffer(), MGL_swapBuffers()
  7183.  
  7184.  
  7185.             MGL_sizex
  7186.  
  7187.             Function    Returns the total device x coordinate
  7188.                         dimensions
  7189.  
  7190.             Syntax      int MGL_sizex(void);
  7191.  
  7192.             Prototype   mgraph.h
  7193.             in
  7194.  
  7195.  
  7196.  
  7197.  
  7198.             Chapter 6 - Console Library                              109
  7199.  
  7200.  
  7201.  
  7202.  
  7203.  
  7204.             Remarks     MGL_sixex() returns the total number of
  7205.                         pixels available along the X coordinate axis
  7206.                         for the currently active output device. This
  7207.                         is different to the MGL_maxx() routine which
  7208.                         returns the dimensions of the currently
  7209.                         active viewport.
  7210.  
  7211.             Return      Number of pixels in X direction for entire
  7212.             value       device - 1
  7213.  
  7214.             See also    MGL_sizey(), MGL_maxx(), MGL_maxy()
  7215.  
  7216.  
  7217.             MGL_sizey
  7218.  
  7219.             Function    Returns the total device y coordinate
  7220.                         dimensions
  7221.  
  7222.             Syntax      int MGL_sizey(void);
  7223.  
  7224.             Prototype   mgraph.h
  7225.             in
  7226.  
  7227.             Remarks     MGL_sixey() returns the total number of
  7228.                         pixels available along the Y coordinate axis
  7229.                         for the currently active output device. This
  7230.                         is different to the MGL_maxy() routine which
  7231.                         returns the dimensions of the currently
  7232.                         active viewport.
  7233.  
  7234.             Return      Number of pixels in Y direction for entire
  7235.             value       device - 1
  7236.  
  7237.             See also    MGL_sizex(), MGL_maxx(), MGL_maxy()
  7238.  
  7239.  
  7240.             MGL_swapBuffers
  7241.  
  7242.             Function    Swaps the currently active front and back
  7243.                         buffers
  7244.  
  7245.             Syntax      void MGL_swapBuffers(void);
  7246.  
  7247.             Prototype   mgraph.h
  7248.             in
  7249.  
  7250.             Remarks     MGL_swapBuffers() swaps the currently active
  7251.                         front and back buffers. This routine should
  7252.                         only be called after the MGL_doubleBuffer()
  7253.                         routine has been called to initialise the
  7254.                         double buffering. Once double buffering has
  7255.                         been set up, all output from the MGL will go
  7256.                         to the current offscreen buffer, and the
  7257.                         output can be made visible with the
  7258.                         MGL_swapBuffers() routine. This routine is
  7259.                         normally used to achieve smooth animation for
  7260.                         complex scenes.
  7261.  
  7262.  
  7263.  
  7264.             110                     MegaGraph Graphics Library Reference
  7265.  
  7266.  
  7267.  
  7268.  
  7269.  
  7270.             See also    MGL_doubleBuffer(), MGL_singleBuffer()
  7271.  
  7272.  
  7273.             MGL_textHeight
  7274.  
  7275.             Function    Returns the height of the current font in
  7276.                         pixels
  7277.  
  7278.             Syntax      int MGL_textHeight(void);
  7279.  
  7280.             Prototype   mgraph.h
  7281.             in
  7282.  
  7283.             Remarks     MGL_textHeight() returns the height of the
  7284.                         currently active font in pixels. This
  7285.                         includes any scaling transformations that are
  7286.                         applied to the font and will be as accurate
  7287.                         as possible at the resolution of the display
  7288.                         device.
  7289.  
  7290.             Return      Height of the current font in pixels
  7291.             value
  7292.  
  7293.             See also    MGL_textWidth(), MGL_drawStr(),
  7294.                         MGL_getCharMetrics(), MGL_getFontMetrics()
  7295.  
  7296.  
  7297.             MGL_textWidth
  7298.  
  7299.             Function    Returns the width of the charcter string in
  7300.                         pixels
  7301.  
  7302.             Syntax      int MGL_textWidth(const char *str);
  7303.  
  7304.             Prototype   mgraph.h
  7305.             in
  7306.  
  7307.             Parameters  str - Character string to measure
  7308.  
  7309.             Remarks     MGL_textWidth() returns the width of the
  7310.                         specified character string using the
  7311.                         dimensions of the currently active font in
  7312.                         pixels. This includes any scaling
  7313.                         transformations that are applied to the font
  7314.                         and will be as accurate as possible at the
  7315.                         resolution of the display device.
  7316.  
  7317.             Return      Width of the character string in pixels
  7318.             value
  7319.  
  7320.             See also    MGL_textHeight(), MGL_drawStr(),
  7321.                         MGL_getCharMetrics(), MGL_getFontMetrics()
  7322.  
  7323.  
  7324.  
  7325.  
  7326.  
  7327.  
  7328.  
  7329.  
  7330.             Chapter 6 - Console Library                              111
  7331.  
  7332.  
  7333.  
  7334.  
  7335.  
  7336.             MGL_underScoreLocation
  7337.  
  7338.             Function    Returns the location to begin drawing an
  7339.                         underscore for the font.
  7340.  
  7341.             Syntax      void MGL_underScoreLocation(int *x, int *y,
  7342.                         const char *str)
  7343.  
  7344.             Prototype   mgraph.h
  7345.             in
  7346.  
  7347.             Parameters  x - X coordinate to be passed to
  7348.                         MGL_drawStrXY()
  7349.                         y - Y coordinate to be passed to
  7350.                         MGL_drawStrXY()
  7351.                         str - String to measure
  7352.  
  7353.             Remarks     MGL_underScoreLocation() takes an (x,y)
  7354.                         location that would normally be be used to
  7355.                         draw a string with MGL_drawStrXY(), and
  7356.                         adjusts the coordinates to begin at the under
  7357.                         score location for the current font, in the
  7358.                         current drawing attributes. Thus the entire
  7359.                         character string can be underlined by drawing
  7360.                         a line starting at the computed underscore
  7361.                         location and extending for MGL_textWidth()
  7362.                         pixels in length.
  7363.  
  7364.             See also    MGL_drawStrXY(), MGL_textWidth()
  7365.  
  7366.  
  7367.             MGL_unloadFont
  7368.  
  7369.             Function    Unloads the specified font from memory.
  7370.  
  7371.             Syntax      void MGL_unloadFont(font *font);
  7372.  
  7373.             Prototype   mgraph.h
  7374.             in
  7375.  
  7376.             Parameters  font - Pointer to loaded font file to unload.
  7377.  
  7378.             Remarks     MGL_unloadFont() attempts to unload the
  7379.                         specified font if the font is a valid font
  7380.                         that was loaded with the MGL_loadFont()
  7381.                         routine. The memory occupied by the font will
  7382.                         be released to the global heap.
  7383.  
  7384.             Return      True if font was unloaded, false if font was
  7385.             value       invalid.
  7386.  
  7387.             See also    MGL_loadFont()
  7388.  
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.             112                     MegaGraph Graphics Library Reference
  7397.  
  7398.  
  7399.  
  7400.  
  7401.  
  7402.             MGL_unpackColor
  7403.  
  7404.             Function    Unpacks a packed 24 bit color value into RGB
  7405.                         components.
  7406.  
  7407.             Syntax      void MGL_unpackColor(color_t color,uchar
  7408.                         *R,uchar *G,uchar *B);
  7409.  
  7410.             Prototype   mgraph.h
  7411.             in
  7412.  
  7413.             Parameters  color - Color value to unpack.
  7414.                         R - Place to store the red component
  7415.                         G - Place to store the green component
  7416.                         B - Place to store the blue component
  7417.  
  7418.             Remarks     MGL_unpackColor() takes a packed color value
  7419.                         in the correct format for the current color
  7420.                         mode, and extracts the red, green and blue
  7421.                         components. Note that the color values may
  7422.                         not be the same as when you packed them with
  7423.                         MGL_packColor() if the color mode is a 15 or
  7424.                         16 bit mode because of loss of precision. The
  7425.                         values are scaled back into the normal 24 bit
  7426.                         RGB space.
  7427.  
  7428.             See also    MGL_packColor(), MGL_getPixelFormat()
  7429.  
  7430.  
  7431.             MGL_packColor
  7432.  
  7433.             Function    Packs an RGB triple into the correct format
  7434.                         for current mode.
  7435.  
  7436.             Syntax      color_t MGL_packColor(uchar R, uchar G, uchar
  7437.                         B)
  7438.  
  7439.             Prototype   mgraph.h
  7440.             in
  7441.  
  7442.             Parameters  R - Red component of color
  7443.                         G - Green component of color
  7444.                         B - Blue component of color
  7445.  
  7446.             Remarks     MGL_packColor() takes a 24 bit RGB triple and
  7447.                         converts it to the correct pack pixel format
  7448.                         required by the current video mode. This
  7449.                         packed pixel color value can then be passed
  7450.                         to routines that require an MGL color_t color
  7451.                         value such as MGL_setColor() etc.
  7452.  
  7453.             Return      MGL pack pixel color value representing the
  7454.             value       specified color.
  7455.  
  7456.             See also    MGL_unpackColor(), MGL_getPixelFormat(),
  7457.                         MGL_setColor()
  7458.  
  7459.  
  7460.  
  7461.  
  7462.             Chapter 6 - Console Library                              113
  7463.  
  7464.  
  7465.  
  7466.  
  7467.  
  7468.             MGL_useFont
  7469.  
  7470.             Function    Sets the currently active font.
  7471.  
  7472.             Syntax      bool MGL_useFont(font *font)
  7473.  
  7474.             Prototype   mgraph.h
  7475.             in
  7476.  
  7477.             Parameters  font - New font to use.
  7478.  
  7479.             Remarks     MGL_useFont() selects the specified font as
  7480.                         the currently active font for use by the MGL.
  7481.                         If the font data is invalid, the MGL result
  7482.                         flag is set and the routine will return
  7483.                         false.
  7484.  
  7485.                         Note: Do not unload a font file if it is
  7486.                         currently in use by the MGL!
  7487.  
  7488.             Return      True if the font was valid and selected,
  7489.             value       false if not.
  7490.  
  7491.             See also    MGL_drawStr()
  7492.  
  7493.  
  7494.             MGL_vecFontEngine
  7495.  
  7496.             Function    Generates the commands to draw vector font.
  7497.  
  7498.             Syntax      bool MGL_vecFontEngine(int x, int y, const
  7499.                         char *str, void (*move)(int x,int y), void
  7500.                         (*draw)(int x,int y));
  7501.  
  7502.             Prototype   mgraph.h
  7503.             in
  7504.  
  7505.             Parameters  x,y - Coordinate to start drawing text at
  7506.                         str - Character string to draw
  7507.                         move - Routine to call to perform a move
  7508.                         operation
  7509.                         draw - Routine to call to perform a draw
  7510.                         operation
  7511.  
  7512.  
  7513.  
  7514.  
  7515.  
  7516.  
  7517.  
  7518.  
  7519.  
  7520.  
  7521.  
  7522.  
  7523.  
  7524.  
  7525.  
  7526.  
  7527.  
  7528.             114                     MegaGraph Graphics Library Reference
  7529.  
  7530.  
  7531.  
  7532.  
  7533.  
  7534.             Remarks     MGL_vecFontEngine() calls a set of user
  7535.                         supplied routines to render the characters in
  7536.                         a vector font. This allows the vector fonts
  7537.                         to be drawn in 2D or 3D floating point
  7538.                         coordinate systems by transforming each of
  7539.                         the operations needed to draw each character,
  7540.                         or in any coordinate system that the users
  7541.                         desires.
  7542.  
  7543.                             move                        The      routine is called to move the cursor
  7544.                         to a new location, and the      routine is                                                   draw
  7545.                         used to perform a draw operation from the
  7546.                         current location to the specified location.
  7547.                         Each character in the vector font is started
  7548.                         with a move operation.
  7549.  
  7550.                         Note that the coordinates passed to the move
  7551.                         and draw routines will be offset from the
  7552.                         point (x,y), where the point (x,y) is the
  7553.                         origin of the first character (ie: it lies on
  7554.                         its baseline). Note also that the coordinates
  7555.                         will be relative to the origin with the
  7556.                         origin at the lower left corner of each
  7557.                         character (ie: inverse of normal device
  7558.                         coordinate yaxis values).
  7559.  
  7560.                         This routine does not honor the standard
  7561.                         scaling factors, but simply draws the
  7562.                         characters at character size of (1,1,1,1)
  7563.                         (because scaling will be done by the user
  7564.                         supplied move and draw routines).
  7565.  
  7566.                         If the passed font is NOT a valid vector
  7567.                         font, this routine returns false.
  7568.  
  7569.             Return      True if string correctly rendered, false if
  7570.             value       font is not a vector font.
  7571.  
  7572.             See also    MGL_drawStr(), MGL_useFont()
  7573.  
  7574.  
  7575.             MGL_vSync
  7576.  
  7577.             Function    Waits for a vertical refresh signal.
  7578.  
  7579.             Syntax      void MGL_vSync(void);
  7580.  
  7581.             Prototype   mgraph.h
  7582.             in
  7583.  
  7584.             Remarks     MGL_vSync() waits for a vertical refresh
  7585.                         signal from the video display before
  7586.                         returning. This can be used to sync your
  7587.                         graphics output to the vertical sync pulse to
  7588.                         produce flicker free animation or to produce
  7589.                         animation that runs at a constant speed.
  7590.  
  7591.  
  7592.  
  7593.  
  7594.             Chapter 6 - Console Library                              115
  7595.  
  7596.  
  7597.  
  7598.  
  7599.  
  7600.             MS_obscure
  7601.  
  7602.             Function    Hides the mouse cursor from view during
  7603.                         graphics output.
  7604.  
  7605.             Syntax      void MS_obscure(void);
  7606.  
  7607.             Prototype   mgraph.h
  7608.             in
  7609.  
  7610.             Remarks     MS_obscure   hides the mouse cursor from view                                  ()
  7611.                         in order to perform graphics output using the
  7612.                         MGL. If the graphics device driver supports a
  7613.                         hardware cursor, this is handled by the
  7614.                         hardware, otherwise it is removed from the
  7615.                         display. You should call this routine rather
  7616.                         than MS_hide() in order to temporarily hide
  7617.                         the cursor during graphics output as the
  7618.                         MS_hide() routine can produce incorrect
  7619.                         results if call in quick succession for
  7620.                         systems that support a hardware mouse cursor.
  7621.  
  7622.             See also    MS_unobscure()
  7623.  
  7624.  
  7625.             MS_unobscure
  7626.  
  7627.             Function    Restores the mouse cursor to view after
  7628.                         graphics output.
  7629.  
  7630.             Syntax      void MS_unobscure(void);
  7631.  
  7632.             Prototype   mgraph.h
  7633.             in
  7634.  
  7635.             Remarks     MS_unobscure() redisplays the cursor again
  7636.                         after screen output has finished.
  7637.  
  7638.             See also    MS_obscure()
  7639.  
  7640.  
  7641.  
  7642.  
  7643.  
  7644.  
  7645.  
  7646.  
  7647.  
  7648.  
  7649.  
  7650.  
  7651.  
  7652.  
  7653.  
  7654.  
  7655.  
  7656.  
  7657.  
  7658.  
  7659.  
  7660.             116                     MegaGraph Graphics Library Reference
  7661.  
  7662.  
  7663.  
  7664.  
  7665.  
  7666.  
  7667.  
  7668.  
  7669.                                                 C  O  N  T  E  N  T  S
  7670.  
  7671.  
  7672.  
  7673.             Chapter 1 - Introduction            Chapter 1 - Introduction            Chapter 1 - Introduction ................................                                     ................................                                     ................................1                                                                     1                                                                     1
  7674.  
  7675.             Chapter 2 - Library reference            Chapter 2 - Library reference            Chapter 2 - Library reference ...........................                                          ...........................                                          ...........................3                                                                     3                                                                     3
  7676.                  How to use reference entries .......................4
  7677.                  MGL_availableFont ..................................5
  7678.                  MGL_availableModes .................................5
  7679.                  MGL_availablePages .................................6
  7680.                  MGL_beginDrawing ...................................6
  7681.                  MGL_beginGouraud ...................................7
  7682.                  MGL_beginPixel .....................................8
  7683.                  MGL_charWidth ......................................8
  7684.                  MGL_clearDevice ....................................8
  7685.                  MGL_clearViewport ..................................9
  7686.                  MGL_clipLine .......................................9
  7687.                  MGL_copyImage .....................................10
  7688.                  MGL_copyImageCoord ................................10
  7689.                  MGL_defaultAttributes .............................11
  7690.                  MGL_defaultColor ..................................11
  7691.                  MGL_detectGraph ...................................12
  7692.                  MGL_disjointRect ..................................13
  7693.                  MGL_divotSize .....................................13
  7694.                  MGL_divotSizeCoord ................................14
  7695.                  MGL_doubleBuffer ..................................14
  7696.                  MGL_drawBorder ....................................15
  7697.                  MGL_drawBorderCoord ...............................16
  7698.                  MGL_drawHDivider ..................................17
  7699.                  MGL_drawStr .......................................17
  7700.                  MGL_drawStrXY .....................................18
  7701.                  MGL_drawVDivider ..................................18
  7702.                  MGL_driverName ....................................19
  7703.                  MGL_ellipse .......................................19
  7704.                  MGL_ellipseArc ....................................20
  7705.                  MGL_ellipseArcCoord ...............................21
  7706.                  MGL_ellipseCoord ..................................22
  7707.                  MGL_ellipseEngine .................................22
  7708.                  MGL_emptyRect .....................................23
  7709.                  MGL_endDrawing ....................................24
  7710.                  MGL_endGouraud ....................................24
  7711.                  MGL_endPixel ......................................25
  7712.                  MGL_equalPoint ....................................25
  7713.                  MGL_equalRect .....................................25
  7714.                  MGL_errorMsg ......................................26
  7715.                  MGL_exit ..........................................26
  7716.                  MGL_fadePalette ...................................27
  7717.                  MGL_fillEllipse ...................................28
  7718.                  MGL_fillEllipseArc ................................28
  7719.                  MGL_fillEllipseArcCoord ...........................29
  7720.                  MGL_fillEllipseCoord ..............................30
  7721.                  MGL_fillGouraudPolygon ............................31
  7722.                  MGL_fillPolygon ...................................32
  7723.                  MGL_fillPolygonFast ...............................33
  7724.  
  7725.  
  7726.             Contents                                                   i
  7727.  
  7728.  
  7729.  
  7730.  
  7731.  
  7732.                  MGL_fillRect ......................................34
  7733.                  MGL_fillRectCoord .................................34
  7734.                  MGL_fillRectPt ....................................35
  7735.                  MGL_getActivePage .................................35
  7736.                  MGL_getArcCoords ..................................36
  7737.                  MGL_getAspectRatio ................................36
  7738.                  MGL_getAttributes .................................37
  7739.                  MGL_getBackColor ..................................38
  7740.                  MGL_getBorderColors ...............................39
  7741.                  MGL_getCharMetrics ................................39
  7742.                  MGL_getClipMode ...................................40
  7743.                  MGL_getClipRect ...................................41
  7744.                  MGL_getColor ......................................41
  7745.                  MGL_getCP .........................................41
  7746.                  MGL_getCursorColor ................................42
  7747.                  MGL_getDefaultPalette .............................42
  7748.                  MGL_getDivot ......................................43
  7749.                  MGL_getDivotCoord .................................44
  7750.                  MGL_getDriver .....................................44
  7751.                  MGL_getFont .......................................45
  7752.                  MGL_getFontMetrics ................................45
  7753.                  MGL_getImage ......................................46
  7754.                  MGL_getImageCoord .................................47
  7755.                  MGL_getMarkerColor ................................48
  7756.                  MGL_getMarkerSize .................................48
  7757.                  MGL_getMarkerStyle ................................48
  7758.                  MGL_getMode .......................................49
  7759.                  MGL_getPalette ....................................49
  7760.                  MGL_getPaletteEntry ...............................50
  7761.                  MGL_getPaletteSize ................................51
  7762.                  MGL_getPaletteSnowLevel ...........................51
  7763.                  MGL_getPenBitmapPattern ...........................51
  7764.                  MGL_getPenSize ....................................52
  7765.                  MGL_getPenStyle ...................................52
  7766.                  MGL_getPixel ......................................53
  7767.                  MGL_getPixelCoord .................................54
  7768.                  MGL_getPixelFormat ................................54
  7769.                  MGL_getPolygonType ................................56
  7770.                  MGL_getSpaceExtra .................................56
  7771.                  MGL_getTextDirection ..............................57
  7772.                  MGL_getTextJustify ................................57
  7773.                  MGL_getTextSettings ...............................58
  7774.                  MGL_getTextSize ...................................59
  7775.                  MGL_getViewport ...................................60
  7776.                  MGL_getVisualPage .................................60
  7777.                  MGL_getWriteMode ..................................61
  7778.                  MGL_getX ..........................................61
  7779.                  MGL_getY ..........................................62
  7780.                  MGL_globalToLocal .................................62
  7781.                  MGL_gouraudScanLine ...............................63
  7782.                  MGL_imageSize .....................................63
  7783.                  MGL_imageSizeCoord ................................64
  7784.                  MGL_init ..........................................65
  7785.                  MGL_insetRect .....................................66
  7786.                  MGL_line ..........................................66
  7787.                  MGL_lineCoord .....................................67
  7788.                  MGL_lineCoordFast .................................67
  7789.                  MGL_lineEngine ....................................68
  7790.  
  7791.  
  7792.             ii                                                  Contents
  7793.  
  7794.  
  7795.  
  7796.  
  7797.  
  7798.                  MGL_lineFast ......................................68
  7799.                  MGL_lineRel .......................................69
  7800.                  MGL_lineRelCoord ..................................69
  7801.                  MGL_lineTo ........................................70
  7802.                  MGL_lineToCoord ...................................70
  7803.                  MGL_loadFont ......................................71
  7804.                  MGL_localToGlobal .................................71
  7805.                  MGL_marker ........................................72
  7806.                  MGL_maxCharWidth ..................................72
  7807.                  MGL_maxColor ......................................72
  7808.                  MGL_maxPage .......................................73
  7809.                  MGL_maxx ..........................................73
  7810.                  MGL_maxy ..........................................74
  7811.                  MGL_modeName ......................................74
  7812.                  MGL_moveRel .......................................74
  7813.                  MGL_moveRelCoord ..................................75
  7814.                  MGL_moveTo ........................................75
  7815.                  MGL_moveToCoord ...................................76
  7816.                  MGL_offsetRect ....................................76
  7817.                  MGL_packColor .....................................76
  7818.                  MGL_pixel .........................................77
  7819.                  MGL_pixelCoord ....................................77
  7820.                  MGL_polyLine ......................................78
  7821.                  MGL_polyMarker ....................................78
  7822.                  MGL_polyPoint .....................................79
  7823.                  MGL_popViewport ...................................79
  7824.                  MGL_ptInRect ......................................79
  7825.                  MGL_ptInRectCoord .................................80
  7826.                  MGL_pushViewport ..................................80
  7827.                  MGL_putDivot ......................................80
  7828.                  MGL_putIcon .......................................81
  7829.                  MGL_putImage ......................................81
  7830.                  MGL_putImageCoord .................................82
  7831.                  MGL_putMonoImage ..................................83
  7832.                  MGL_realColor .....................................83
  7833.                  MGL_rect ..........................................84
  7834.                  MGL_rectCoord .....................................84
  7835.                  MGL_rectPt ........................................85
  7836.                  MGL_registerDriver ................................85
  7837.                  MGL_restoreAttributes .............................86
  7838.                  MGL_restoreCRTMode ................................86
  7839.                  MGL_result ........................................86
  7840.                  MGL_rotatePalette .................................87
  7841.                  MGL_scanLeftForColor ..............................88
  7842.                  MGL_scanLeftWhileColor ............................89
  7843.                  MGL_scanLine ......................................90
  7844.                  MGL_scanRightForColor .............................91
  7845.                  MGL_scanRightWhileColor ...........................91
  7846.                  MGL_setActivePage .................................92
  7847.                  MGL_setAspectRatio ................................93
  7848.                  MGL_setBackColor ..................................93
  7849.                  MGL_setBorderColors ...............................94
  7850.                  MGL_setBufSize ....................................95
  7851.                  MGL_setClipMode ...................................95
  7852.                  MGL_setClipRect ...................................96
  7853.                  MGL_setColor ......................................96
  7854.                  MGL_setCursorColor ................................97
  7855.                  MGL_setDefaultPalette .............................97
  7856.  
  7857.  
  7858.             Contents                                                 iii
  7859.  
  7860.  
  7861.  
  7862.  
  7863.  
  7864.                  MGL_setGraphMode ..................................97
  7865.                  MGL_setMarkerColor ................................98
  7866.                  MGL_setMarkerSize .................................98
  7867.                  MGL_setMarkerStyle ................................99
  7868.                  MGL_setPalette ....................................99
  7869.                  MGL_setPaletteEntry ..............................100
  7870.                  MGL_setPaletteSnowLevel ..........................101
  7871.                  MGL_setPenBitmapPattern ..........................101
  7872.                  MGL_setPenSize ...................................102
  7873.                  MGL_setPenStyle ..................................102
  7874.                  MGL_setPolygonType ...............................103
  7875.                  MGL_setRelViewport ...............................103
  7876.                  MGL_setResult ....................................104
  7877.                  MGL_setSpaceExtra ................................104
  7878.                  MGL_setTextDirection .............................105
  7879.                  MGL_setTextJustify ...............................105
  7880.                  MGL_setTextSettings ..............................106
  7881.                  MGL_setTextSize ..................................107
  7882.                  MGL_setViewport ..................................108
  7883.                  MGL_setVisualPage ................................108
  7884.                  MGL_setWriteMode .................................109
  7885.                  MGL_singleBuffer .................................109
  7886.                  MGL_sizex ........................................109
  7887.                  MGL_sizey ........................................110
  7888.                  MGL_swapBuffers ..................................110
  7889.                  MGL_textHeight ...................................111
  7890.                  MGL_textWidth ....................................111
  7891.                  MGL_underScoreLocation ...........................112
  7892.                  MGL_unloadFont ...................................112
  7893.                  MGL_unpackColor ..................................113
  7894.                  MGL_packColor ....................................113
  7895.                  MGL_useFont ......................................114
  7896.                  MGL_vecFontEngine ................................114
  7897.                  MGL_vSync ........................................115
  7898.                  MS_obscure .......................................116
  7899.                  MS_unobscure .....................................116
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.  
  7915.  
  7916.  
  7917.  
  7918.  
  7919.  
  7920.  
  7921.  
  7922.  
  7923.  
  7924.             iv                                                  Contents
  7925.  
  7926.  
  7927.  
  7928.  
  7929.  
  7930.  
  7931.  
  7932.  
  7933.  
  7934.  
  7935.  
  7936.  
  7937.  
  7938.  
  7939.  
  7940.  
  7941.  
  7942.  
  7943.  
  7944.  
  7945.  
  7946.  
  7947.  
  7948.  
  7949.  
  7950.  
  7951.  
  7952.                             MegaGraph Graphics Library
  7953.                              Library Reference Manual
  7954.  
  7955.  
  7956.  
  7957.  
  7958.                        Copyright (C) 1993 SciTech Software.
  7959.                                All Rights Reserved.
  7960.  
  7961.  
  7962.                                    Version 1.0
  7963.                                 December 30, 1993