VgaMem		Nutzung des VGA-Restspeichers und schnelle Bitmap-Routinen
ver 1.53	zum Kopieren von Bildschirmbereichen und zur Darstellung
		von Icons und Images.
		Copyright (c) 1993 by Matthias Kppe.

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

1. Allgemeines
--------------

VGAMem ist eine Turbo-Pascal-Unit, die der Nutzung des VGA-Restspeichers
(einer mchtigen, doch sonst ungenutzten Ressource) und dem schnellen Kopieren
von Bildschirmbereichen dient. Ferner stellt es Routinen zur Darstellung von
Icons bereit und ersetzt die Image-Routinen des BGI.

Die unit VGAMem ist Teil des MyMouse-Pakets. Es baut auf folgende unit auf:

- Gr	    Diese unit ist das gemeinsam genutzte Graphikinterface. Der
	    Graphikmodus mu mittels SetGrMode gesetzt werden. Lesen Sie
  dazu die Dokumentation von Gr.

VGAMem untersttzt die MetaGraph-Spezifikation vollstndig.

2. Prozeduren und Funktionen
----------------------------

Folgende Routinen dienen der Verwaltung des Restspeichers.

procedure InitVGAMan;

  Initialisiert die dynamische Restspeicherverwaltung. Wird bentigt, wenn
  mittels GetVGAMem Restspeicher alloziert werden soll.
  Verwendet einen kleinen Speicherbereich auf dem Heap.

  InitVgaMan erfordert nicht einen initialisierten Graphikmodus. VgaMem
  reagiert auf Nachrichten von Gr.InitGraphics und aktiviert sich selbst.

procedure DoneVGAMan;

  Beendet die dynamische Restspeicherverwaltung. DoneVgaMan sollte
  aufgerufen werden, bevor das Programm verlassen wird.

  Es ist nicht erforderlich, DoneVgaMan aufzurufen, bevor der Graphikmodus
  verlassen wird. VgaMem reagiert auf Nachrichten von Gr.CloseGraphics und
  deaktiviert sich selbst.

function GetVGAMem(Size: Word): Word;

  Alloziert Restspeicher der Gre Size (angegeben in Paragraphen, d.h. 16
  Byte). Das Funktionsergebnis ist eine Pseudo-Adresse. Sie gibt die
  Distanz des allozierten Speicherbereichs zum Bildspeicheranfang in
  Paragraphen an.

procedure FreeVGAMem(P, Size: Word);

  Gibt Restspeicher der Gre Size ab der Pseudo-Adresse P frei. Die
  Angabe erfolgt in Paragraphen.


Folgende Routinen sind fr den modusunabhngigen Einsatz vorgesehen. Sie
ersetzen die Routinen mit dem Suffix "16", die aber aus Kompatibilitts-
grnden noch vorhanden sind.

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

  Ermittelt den Restspeicherbedarf des angegebenen Bildausschnitts (in
  Paragraphen). Man beachte die Turbo-Vision-Notation des Rechtecks, d.h.
  die Koordinaten x2, y2 geben die Zeilen/Spalten an, die gerade nicht
  mehr gespeichert werden sollen.

  Diese Routine ersetzt GetSize16 aus frheren Versionen.

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

  Ermittelt den Restspeicherbedarf einer Bildschirmzeile. Man beachte die
  Turbo-Vision-Notation, d.h. die Koordinate x2 gibt die Spalte an, die
  gerade nicht mehr gespeichert werden soll.

  Diese Routine ersetzt GetBPL16 aus frheren Versionen.

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

  Speichert den angegebenen Bildausschnitt (Turbo-Vision-Notation!) ab der
  Pseudo-Adresse Addr.

  Arbeitet mit SourcePage.

  Diese Routine ersetzt SaveScreen16 aus frheren Versionen.

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

  Stellt einen Bildausschnitt aus dem Restspeicher wieder her.
  * x1, y1, x2, y2 sind die Koordinaten, die bei SaveScreen bergeben wurden.
  * x3, y3 sind die Zielkoordinaten.
  * Addr ist die Pseudo-Adresse, an der der Bildausschnitt gespeichert ist.

  Die Prozedur beachtet Gr.ClipRect und schneidet den wiederhergestellten
  Bildausschnitt an dessen Grenzen ab. Lesen Sie dazu die Dokumentation
  von Gr.

  Arbeitet mit DestPage.

  Diese Routine ersetzt RestoreScreen16 aus frheren Versionen.

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

  Kopiert einen Bildausschnitt direkt. Dabei werden beliebige berlappungen
  korrekt behandelt.
  * x1, y1, x2, y2 sind die Koordinaten des zu kopierenden Rechtecks in
    Turbo-Vision-Notation.
  * x3, y3 sind die Zielkoordinaten.

  Die Prozedur beachtet Gr.ClipRect.

  Arbeitet mit SourcePage und DestPage.

  Diese Routine ersetzt CopyScreen16 aus frheren Versionen.


Die folgende Routine ist modusabhngig.

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

  Kopiert einen Speicherbereich auf der VGA-Karte.
  * Source ist das Offset der Quelle zum Speicheranfang und wird in Bytes
    angegeben.
  * Dest ist das Offset des Ziels.
  * Count ist die Anzahl der zu kopierenden Bytes.

  Es werden alle vier Farbebenen kopiert. berschneidungen werden nicht
  richtig behandelt. CopyMem16 dient ausschlielich dem schnellen Kopieren
  groer zusammenhngender Speicherbereiche.


Folgende Routinen dienen der Darstellung von Icons auf dem Bildschirm.

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

  Stellt das bergebene Icon (graphisches Symbol) an den Koordinaten x1, y1
  dar. Das Icon ist maximal 16 Pixel breit, beliebig lang und einfarbig. Es
  mu in folgendem Format vorliegen:
    - 1 Wort: Lnge des Icons in Pixelzeilen.
    - Fr jede Pixelzeile 1 Wort. Die Binrschreibweise dieses Worts
      wird "auf den Bildschirm projiziert" und stellt die modifizierten
      Punkte dar.
  Die Prozedur modifiziert die in MapMask angegebenen Farbebenen
  ($0F alle, $01 die blaue, $02 die grne, $04 die rote, $08 die Intensitt).
  Das Einerkomplement der Icon-Daten wird mit diesen Farbebenen AND-verknpft.
  D.h., wo in der Binrschreibweise eine 1 ist, wird in den angegebenen
  Farbebenen das entsprechende Pixel entfernt; wo eine 0 ist, passiert
  nichts.
  PutIconAnd beachtet Gr.ClipRect und die aktive Seite.

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

  Arbeitet wie PutIconAnd, doch verknpft die Icon-Daten mit den Farbebenen
  OR. D.h., wo eine 1 ist, wird in den angegebenen Farbebenen das ent-
  sprechende Pixel eingetragen.


Folgende Routinen dienen der Umleitung von Graphikausgaben in einen nicht
sichtbaren Bildschirmpuffer und dem schnellen Kopieren von Ausschnitten aus
diesem Puffer in den sichtbaren Bildschirm.

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

  Diese Routine bereitet das Umleiten von Graphikausgaben in einen
  Restspeicherpuffer vor.
  * R ist ein Rechteck in TV-Notation, das die Einhllende aller zu
    zeichnenden Regionen beschreibt. Die maximale Gre dieses Rechtecks ist
    durch den freien Restspeicher beschrnkt.
  * Action gibt an, wie der Restspeicherpuffer vorbereitet werden soll
    - pbNone:	Der Puffer wird nicht initialisiert.
    - pbCopy:	Das Reckteck R auf dem sichtbaren Bildschirm wird in den
		Restspeicher kopiert. Dadurch sind Vernderungen an dem
		dargestellten Bild mglich.
    - pbClear:	Der Puffer wird schwarz gefllt.
  * Buf ist eine Datenstruktur des Typs TVgaBuf, in der PrepBuf wichtige
    Informationen speichert.

  PrepBuf gibt true zurck, wenn der Puffer vorbereitet werden konnte,
  ansonsten false. Nach erfolgreichem Aufruf von PrepBuf verwenden alle
  Graphikroutinen, die auf der unit Gr aufbauen, den vorbereiteten Puffer
  als Ausgabebildschirm.

  PrepBuf verndert
  * den DrawOrigin derart, da die linke obere Ecke des angegebenen Rechtecks
    globalisiert Etwanull-Koordinaten erhlt,
  * das ClipRect derart, da es DrawOrigin-lokal wird,
  * den Parameter BytesPerLine und
  * das ActiveSeg
  und alloziert mittels GetVgaMem Restspeicher. Daher mu vor der Verwendung
  von PrepBuf der VGA-Manager initialisiert werden (InitVgaMan).

procedure EndBufDraw;

  Diese Routine beendet die Umleitung von Graphikausgaben in einen Puffer
  und stellt die normale Graphikausgabe wieder her.

procedure ReleaseBuf(var Buf: TVgaBuf);

  Diese Routine gibt allozierten Pufferspeicher wieder frei.

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

  Diese Routine kopiert einen Ausschnitt aus einem Restspeicherpuffer in
  den sichtbaren Bildschirm.
  * R ist der darzustellende Ausschnitt in globalen Koordinaten.
  * Buf ist die von PrepBuf gefllte TVgaBuf-Datenstruktur.


Folgende Routinen ersetzen die gleichnamigen Routinen der Unit Graph. Sie
untersttzen Gr-Clipping (die Graph-Routinen arbeiten nicht einmal mit
ihrem Viewport zusammen) und arbeiten mit den Graphik-Parametern von 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. Variablen
------------

BlockList: Pointer;

  Speichert den Zeiger auf einen dynamisch reservierten Speicherbereich, der
  die Reservierungsinformationen fr den Restspeicher enthlt. Sollte
  niemals modifiziert werden.

ListSize: Word;

  Gibt die Gre des Speicherbereichs an. Nicht modifizieren!

SourcePage: Word = 0 und
DestPage: Word = 0;

  Geben Quell- und Zielseite an. - Bei niedrigen Graphikmodi knnen die
  Bildschirmoperationen von VGAMem auch auf zwei Seiten geschehen.
  SourcePage gibt die Nummer der Seite an, auf der Leseoperationen ablaufen
  sollen; DestPage entsprechend die, auf der Schreiboperationen ablaufen.

  Haben Wirkung auf SaveScreen16, RestoreScreen16, CopyScreen16.

-----------------------------------------------------------------------------
				Neu in Version 1.5
-----------------------------------------------------------------------------

1. Die Kopierroutinen CopyScreen16 und RestoreScreen16 wurden wesentlich
   beschleunigt. Sie sind jetzt mehr als doppelt so schnell gegenber der
   Version 1.2.
2. Die Routinen PutIconXX knnen jetzt auch auf der zweiten Bildschirmseite
   angewendet werden.
3. VGAMem stellt jetzt Ersatzroutinen fr die BGI-Image-Routinen zur
   Verfgung, die mit den Graphikroutinen von Gr arbeiten und das Clipping
   richtig behandeln.
4. VGAMem stellt Routinen zur Umleitung von Graphikausgaben in den
   Restspeicher bereit.

