ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/DJGPP/DJDOC106.ZIP/DOCS/LIBGR.DOC

Text File | 1991-04-18 | 11.3 KB | 283 lines

/* History:165,56 */
This is file libgr.doc

Contents:

* General information
* C functions
* C++ objects
* Mouse functions

All libgr.a functions are prototyped in <graphics.h> and <mouse.h>





General Information:

The DOS extender understands the paging methods used by Super VGA's, and
liks that into the general paging mechanism it uses to provide virtual
memory.  Most Super VGA's can present 64K of video memory at one time
through the AT channel when in 256 color mode.  The extender uses the
page table entries of the 386 to trap on accesses to pages that aren't
mapped, while allowing accesses to memory corresponding to mapped memory.
When an access is made to unmapped memory, the extender traps it, selects
another graphics range to map, changes the present bits in the page
table, and retries the instruction.  This makes the graphics memory
appear to be a linear range of up to 1Mb of memory at 0xD0000000.
Because swapping pages takes more time than not swapping (but not much;
that swapping is done in protected mode without a mode switch), it follows
that drawing horizontal lines is faster then vertical, and updating regions
should be donw by rows, not columns, to minimize the number of swaps
required.

Only 256 color modes are supported, 16 color modes are not.  All r,g,b
values are in the range 0..255 (they wrap, so 256 == 0).  All color
indexes are also in the range 0..255, but if bit 8 is set ("GrXOR"),
then the color is XOR'd against the pixel already there.  All graphics
operations support the XOR feature.  XORing the color zero is, in effect,
a no-operation, as zero XOR anything is the same as before.

Some Super VGA's allow one range of memory to be mapped for reading and a
different one for writing.  The extender uses this mode for quickly moving
memory around on the screen by mapping the range 0xD0100000 to 0xD01FFFFF
to be the "read-only" video memory, and 0xD0200000 to 0xD02FFFFF to be the
"write-only" video memory, switching back to the primary range for normal
read-write operation.  This mode is designed specifically for the Blit
function (C++).  If a card does not support this mode, blit performance
may suffer slightly.  It is recommended that a memory GrRegion (see below)
be used for storage of images that are to be blitted around on the screen;
they are much faster than screen-to-screen blits.

The following practices are recommended to maximize performance:

* Use screen-to-screen blits when the image will be blitted once, or when
  the images are small.
* Store images in memory GrRegions if they will be copied more than once.
* Use memory GrRegions to create complex images, then blit them onto the
  screen when needed. (see the C++ section for information about GrRegions).
* Copy blits are faster than XOR blits, by a large margin.






C Functions:

GrSetMode(m, w, h) puts the screen into a text or graphics mode.  See the
  <graphics.h> file for a list of supported mode types.  Whenever you switch
  to a graphics mode, the palette is configured according to allocated
  colors.  When switching to a text mode, the palette is not initialized.
  It is strongly recommended that you use the GR_default_graphics and
  GR_default_text modes to switch to graphics and text.  This allows the
  user to select a favorite resolution.  It is important that you do NOT
  assume that you will get the mode you ask for!  You may ask for a mode
  that the card does not support, and will be given a lower resolution mode.

GrSetColor(n, r, g, b) - Set the red, green, blue values of a specific
  color index

GrAllocColor(r, g, b) - Allocate a color cell read-only.  Other calls to
  this function with the same r,g,b will return the same pixel value.

GrAllocCell() - allocate a cell for read-write (write via GrSetColor()).

GrQueryColor(n, &r, &g, &b) - Query the r,g,b values of a given color cell.

GrFreeColor(n) - free a cell from a previous AllocColor or AllocCell call.
  If the cell is allocated twice, two frees are required to free it.

GrBlack() - the value of a "black" pixel (set to 0 by libgr.a).
GrWhite() - the value of a "white" pixel (set to 1 by libgr.a).

NOTE: The functions GrXxxx() below (C linkage) operate only on the
graphics screen, with (0,0) at the upper left, and clip only at the edge.

GrPlot(x,y,c) - plot point (x,y) in color 'c' on the screen
GrPixel(x,y) - return the pixel value at (x,y)
GrMaxX() - maximum valid X value
GrMaxY() - maximum valid Y value
GrSizeX() - number of pixels across
GrSizeY() - number of pixels up/down.
GrLine(x1,y1,x2,y2,c) - draw a line.
GrText(x,y,str,fg,bg) - draw text (8x16 font), upper left of text at (x,y)






C++ functions:

The GrRegion class provides a much more robust interface to the screen by
the use of screen and memory regions that the drawing primitives operate
on.  Thus, you can create a memory region (new GrRegion(width,height)),
draw an image on it, and blit it to the physical screen when needed.
As far as the methods are concerned, there is no difference between a
memory region and a visible region (except speed and visibility).
GrRegions provide automatic coordinate translation and clipping and
store constant information about the region to enhance performance.

Creating and destroying GrRegions are very quick operations, and the
information they store makes programming very simple, so the use
of GrRegions (versus doing clipping/translating yourself) is recommended.
Even memory GrRegions are inexpensive.

GrScreenRegion() is a special function that returns a GrRegion encompassing
the entire visible graphics screen.  Subregions off this GrRegion provide
viewports onto the graphics screen.  You must call this function again if
you use GrSetMode() to change the screen mode (all GrRegions are useless if
you change screen modes).

To create a visible GrRegion, you must start with a visible GrRegion
(hence the GrScreenRegion() function) and take a SubRegion() of it.

To create a memory GrRegion, simply instance a new GrRegion of the
appropriate width and height, or take a SubRegion() of another
memory GrRegion.

SubRegions are used to provide alternate clipping/translating sets for a
given region.  SubRegions share data with all other GrRegions derived
from the same top-level region.  The GrRegion methods DO NOT prevent
one region from writing into the data of another.

To move data around in a region, or from one region to another, use the
Blit functions.  They both take a source and destination GrRegion,
an offset from (0,0) in the destination GrRegion, and a Blit function to
perform.  Currently, the only BlitFuncs available are copy (BlitSrc),
no operation (BlitDest), or XOR (BlitXor).  One of the Blit functions
allows you to specify a subset of the source region as the actual source.
Internally, Blit creates two new GrRegions that are the actual source
and destination regions to perform the actual copy, then destroy them
when the copy is done.


GrRegion, the object:

NOTE: All methods work exactly the same, regardless of what type of
region the object represents.


flags - If set to 1, the destructor will free() the memory pointed to
  by data.  The contructor normally handles this.

color - the default foreground color to use if unspecified.  The default
  background color (for GrText()) is "transparent".

parent - NULL for new regions, else the region this was created from.
rel_x, rel_y - coordinates of (0,0) relative to immediate parent.
abs_x, abs_y - coordinates of (0,0) relative to topmost parent.

width - the width of the GrRegion.
height - the height of the GrRegion.
row_scale - the offset of the beginning of each row relative to the row
  above it.  This is used for subregions and indexing the data pointers.

data - pointer to the data of the region.  (0,0) is at data[0], (1,0) at
  data[1], (0,1) at data[row_scale].
rdata - pointer used for the read half of a bcopy().  Same as data for
  memory regions, but may be different for graphic regions.
wdata - pointer used for the write half of a bcopy().  Same as data for
  memory regions, but may be different for graphic regions.

GrRegion() - creates an "empty" region that can be attached to non-region
  data, such as from a file.
GrRegion(width, height) - returns a memory region.
~GrRegion() - destroys a region, freeing memory if needed.

SubRegion(x,y,width,height) - Creates a subregion of the given region.

MaxX() - maximum valid X coordinate before clipping happens.
MaxY() - maximum valid Y coordinate before clipping happens.
SizeX() - number of pixels across.
SizeY() - number of pixels up/down.

Plot(x, y [,c]) - plot the given point in the given color, or the default color
  if one is not given.
Line(x1, y1, x2, y2 [,c]) - draw a line from (x1,y1) to (x2,y2).
HLine(x1, x2, y [,c]) - optimized horizontal line.
VLine(x, y1, y2 [,c]) - optimized vertical line.
Rectangle(x1, y1, x2, y2 [,c]) - draw a retangle (unfilled).  Corners will
  be drawn only once each (for XORing colors).
Box(x, y, width, height [,c]) - filled box.
Text(x, y, string [,fg [,bg]]) - Text.  Font is 8x16, (x,y) represents the
  upper left corner.  if fg not given, color used.  If bg not given,
  transparent used.
Point(x,y) - return the pixel value at (x,y).






Mouse Functions:


MouseGetEvent(flags, event)
  int flags;
  MouseEvent *event;

The focal point of the mouse routines is the function MouseGetEvent().
It takes a set of desired events, specified by manifest constants from
<mouse.h> set in the "flags" parameter.  It returns a specific event in
the structure passed as the second parameter.  The available events are:


M_LEFT_DOWN    the left mouse button is pressed
M_LEFT_UP    the left mouse button is released
M_MIDDLE_DOWN    the middle mouse button is pressed
M_MIDDLE_UP    the middle mouse button is released
M_RIGHT_DOWN    the right mouse button is pressed
M_RIGHT_UP    the right mouse button is released
M_MOTION    the mouse moves
M_KEYPRESS    a key is pressed
M_BUTTON_DOWN    any button is pressed (the event says which)
M_BUTTON_UP    any button is released (the event says which)

M_NOPAINT    don't paint the mouse, just return the event.  Useful for
        developing an alternative mouse handler.
M_POLL        return current mouse information without waiting.


The "event" fields are:

  flags - specify the event that happened
  x,y - where the mouse was when the event happened, relative to the
    physical screen (no GrRegion support yet).
  buttons - the mouse buttons that are depressed when the event happened
      M_LEFT, M_MIDDLE, and M_RIGHT specify the bits in "buttons".
  key - the key that was pressed, if flags & M_KEYPRESS.  For Alt'd or
      function keys, returns 0x100 + scan code (bios INT 16h, AH ret).

Example:

draw()
{
  MouseEvent e;
  while (1)
  {
    MouseGetEvent(M_MOTION|M_RIGHT_DOWN|M_KEYPRESS, &e);
    if (e.flags & M_RIGHT_DOWN)
      return -1;
    if (e.flags & M_KEYPRESS)
      return e.key;
    GrPlot(e.x, e.y);
  }
}


MouseSetColors(fg, bg) - set the foreground and background colors for
  the mouse.  The current library does not allow the shape of the pointer
  to be changed without recompiling the library.

MouseWarp(x, y) - instantly move the mouse to position (x,y).




As a convenience, the libpc.a functions kbhit() and getkey() are included
in libgr.a as well (the mouse functions use them).