/* History:165,56 */ This is file libgr.doc Contents: * General information * C functions * C++ objects * Mouse functions All libgr.a functions are prototyped in and 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 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 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).