VgaMem		VGA rest memory use and fast bitmap routines for copying
ver 1.53	screen regions and drawing icons and images.
		Copyright (c) 1993 by Matthias Kppe.

-----------------------------------------------------------------------------

1  General Information
----------------------

The Turbo Pascal VgaMem unit is part of the MyMouse software package. With
VgaMem, you can use the VGA rest memory (a large and important resource,
which is completely unused else) for screen buffers in graphics mode.
The unit provides highly-optimized screen copying routines with clipping and
shifting facilities. Further, it provides icon drawing routines and
replaces BGI's image routines.

VgaMem is based on the following unit:

- Gr        This unit is the commonly used graphic interface. The graphics
	    mode must be set by SetGrMode first. Please read Gr's
  documentation for more information.

2  Procedures and Functions
---------------------------

procedure InitVgaMan;

  Initializes the VGA manager, which provides a dynamical rest memory
  management. Buffer memory can be allocated and freed.
  A small portion of heap memory is used for storing this information.

  InitVgaMan does not require a graphics mode initialized. VgaMem will
  wait for messages sent by Gr.InitGraphics and activate itself.

procedure DoneVgaMan;

  De-initializes the VGA manager. You should call DoneVgaMan before leaving
  the program.

  You need not call DoneVgaMan before leaving the graphics mode. VgaMem
  waits for messages sent by Gr.CloseGraphics and deactivate itself.

function GetVgaMem(Size: Word): Word;

  This function allocates VGA rest memory. The requested size is given in
  paragraphs (i.e 16 bytes). The function returns a pseudo-address, which is
  a segment selector distance to the screen.

procedure FreeVgaMem(P, Size: Word);

  This procedure frees allocated VGA rest memory of the given size at the
  pseudo-address P.

function GetSize(x1, y1, x2, y2: Integer): Word;

  This function returns the memory size (in paragraphs) that is needed for
  storing the given rectangular region in VGA rest memory.
  NOTE: The rectangle is in Turbo Vision notation, i.e. the coordinates
	x2, y2 specify points that are outside the region to be stored.

function GetBPL(x1, x2: Integer): Word;

  This function returns the memory size (in bytes) that is needed for storing
  a given screen row in VGA rest memory.
  NOTE: Turbo Vision notation is used, i.e. the x2 coordinate specifies
	the column which is outside the region to be stored.

procedure SaveScreen(x1, y1, x2, y2: Integer; Addr: Word);

  This procedure stores the given rectangular region in VGA rest memory at
  the pseudo-address Addr.
  NOTE: The rectangle is in Turbo Vision notation.

procedure RestoreScreen(x1, y1, x2, y2, x3, y3: Integer; Addr: Word);

  This procedure restores a rectangular region from VGA rest memory.
  * x1, y1, x2, y2 are the coordinates of the stored rectangular region
    given to SaveScreen.
  * x3, y3 are the target coordinates.
  * Addr is the pseudo-address.

  This procedure supports clipping. The data structure Gr.ClipRect
  specifies the rectangular clipping region. (Have a look at the Gr.doc file.)

  Uses DestPage.

procedure CopyScreen(x1, y1, x2, y2, x3, y3: Integer);

  This procedure copies a rectangular region directly to another screen
  position. Overlappings are handled correctly.
  * x1, y1, x2, y2 are the coordinates of the source rectangle.
    NOTE: Turbo Vision notation is used.
  * x3, y3 are the target coordinates.

  This procedure provides clipping, too.

  Works with SourcePage and DestPage.

procedure CopyMem16(Source, Dest, Count: Word);

  This procedure copies a memory block within the VGA adaptor.
  * Source is the offset value of the source block.
  * Dest is the offset value of the destination address.
  * Count is the number of bytes to be copied.

  This procedure does neither provide clipping, nor shifting. Overlappings
  are not handled. CopyMem16 is only used for fast copies of large
  memory blocks.


Following routines draw icons on the screen.

procedure PutIconAnd(x1, y1: Integer; MapMask: Byte; Icon: pointer);

  This procedure draws an icon at the coordinates x1, y1 on the screen.
  The icon is maximal 16 pixels wide and monochrome. It may have any length.
  The format of the icon is the following:
    - 1 word for the length of the icon in pixel rows.
    - 1 word for each pixel row. The bits of the word are mapped to the
      screen as written in binary.
  The procedure modifies the color maps given in MapMask (e.g. $01 the blue
  map, $02 the green map, $04 the red map, $0F all maps). The 1-complement
  of the Icon data is "anded" with the maps. That means, a "1" in binary
  removes the corresponding pixel from the specified maps. A "0" in binary
  leaves the bits as they are.
  This procedure provides clipping by Gr.ClipRect.

procedure PutIconOr(x1, y1: Integer; MapMask: Byte; Icon: pointer);

  Works in the same way as PutIconOr but "ors" the bits of icon data with
  the specified maps. That means, a "1" in binary sets the corresponding
  pixel in the maps. A "0" in binary leaves the bits as they are.


Following routines are used for directing graphic output into an invisible
(rest memory) screen buffer and fast copying parts of it to the visible
screen.

function PrepBuf(var R: TRect; Action: Word; var Buf: TVgaBuf): Boolean;

  This function directs the following graphic operations into a rest memory
  buffer.
  * R is a rectangle in TV notation which gives the union of all regions to
    be drawn. The maximal size of this rectangle is limited by the free
    rest memory.
  * Action specifies how the buffer is to be prepared:
    - pbNone:	The buffer is not initialized.
    - pbCopy:	The R rectangle on the visible screen is copied into the
		buffer. So, changes on the shown image are possible.
    - pbClear:	The buffer is filled with black color.
  * Buf: TVgaBuf is a data structure PrepBuf stores some important information
    in.

  PrepBuf returns true if the buffer could successfully be prepared. After
  a successful PrepBuf call, all graphic operations that are based on the
  Gr unit use the prepared buffer as output screen.

  PrepBuf changes
  * DrawOrigin so that the left upper corner of the specified rectangle
    gets - if globalized - ApproxZero co-ordinates,
  * ClipRect so that it becomes DrawOrigin-local
  * BytesPerLine
  * ActiveSeg
  and allocates rest memory by GetVgaMem. Therefore, the VGA manager must
  have been initialized (InitVgaMan).

procedure EndBufDraw;

  This procedure ends the direction of graphic operations into a buffer and
  restores normal graphic output.

procedure ReleaseBuf(var Buf: TVgaBuf);

  This procedure releases allocated buffer memory.

procedure PasteRect(var R: TRect; var Buf: TVgaBuf);

  This procedure copies a rectangle from a rest memory buffer to the
  visible screen.
  * R is the rectangular region in global co-ordinates to be copied.
  * Buf is the data structure filled by PrepBuf.


Following routines replace the respective ones of the Graph unit. They
provide Gr clipping (Graph's routines do not even co-operate with their
ViewPort) and work with the graphic parameters of Gr.

function ImageSize(x1, y1, x2, y2: Integer): Word;
procedure GetImage(x1, y1, x2, y2: Integer; var BitMap);
procedure PutImage(X, Y: Integer; var BitMap; BitBlt: Word);


3  Variables
------------

BlockList: pointer;

  This variable stores a pointer to a memory block that contains the
  allocation information for the VGA rest memory. DO NOT MODIFY.

ListSize: Word;

  This variable stores the size of this memory block. DO NOT MODIFY.

SourcePage: Byte = 0
DestPage: Byte = 0

  Specify the source and destination screen page for SaveScreen16,
  RestoreScreen16, CopyScreen16.

-----------------------------------------------------------------------------
				New in Version 1.5
-----------------------------------------------------------------------------

1. The copying routines CopyScreen16 and RestoreScreen16 have been
   considerably accelerated. They are more than twice as fast as they were
   in version 1.2.
2. The PutIconXXX procedures now work on both screen pages.
3. VgaMem now provides routines replacing BGI's image routines, which work
   with clipping and Gr parameters.
4. VgaMem now provides routines for directing graphic operations into
   rest memory.
