VRg SuperVGA Pascal Programmer's library
Translucency effects and Bitmap manipulations
==============================================================================
Revision 4
------------------------------------------------------------------------------

This document covers TRANS256 and BMFX units.

TRANS256 unit provides procedure for drawing translucent graphic primitives
and translucent overlapped images. It is intended for use simultaneously
with LFB256 unit.

BMFX unit contains miscellaneous bitmap manipulation procedures (like scaling,
rotation, smoothing etc.) This unit may be used together with LFB256 or
separately as well.


        [1.] Translucency

        [1.1] The basic idea behind translucency

When you drawing solid images on the screen, background color is replaced by
foreground (image) color for each image pixel. To draw translucent image,
we have to replace background color with color intermediate between background
and foreground one. To do so, we need to calculate Red, Green and Blue
components for that intermediate color. Furthermore, because we are talking
about 256 colors (packed pixel videomodes), we need to search through palette
to find existing RGB triplet closest to that calculated one. Of course this
technique is too slow to perform it in realtime. So, we are using translucency
lookup tables. Lookup table is a square matrix of 256x256 elements. Matrix
rows are background colors, while matrix columns are foreground colors.
Each matrix element [i,j] contains number of color closest to intermediate
between colors i and j. Then we use this matrix for fast determination of
required intermediate colors.

There is TTransTable type defined in TRANS256:

type TTransTable=array[0..255,0..255] of byte;
     PTransTable=^TTransTable;


Translucency lookup tables are precalculated with TRANSGEN utility, located
in \utils subdirectory of SuperVGA library distribution archive. Command
line syntax for TRANSGEN is:

TRANSGEN <palette file> [translucency table] [-t<opacity>] [-o]

Palette file may be either PCX file, or raw palette data (256 RGB triplets,
6 bit for each primary color component).
If translucency table file name is not specified, palette file name with .TT
extension will be used.
Opacity (translucency strength) may vary from 0 to 100. 0 is invisible image,
100 is solid image. Default value is 50.
-o switch forces TRANSGEN to overwrite output files without a prompt.

        [1.2] TRANS256 procedures and functions

 procedure transSetTable(TransTable:PTransTable);

This procedure is used to set up current translucency lookup table.
TransTable is a precalculated lookup table location in memory. This table
will be used for all subsequent drawing procedures calls, until new table is
set with transSetTable.

   (* Drawing routines *)
   (********************)

 procedure transPutPixel(x,y:word;Color:byte);
 procedure transPutTransparentPixel(x,y:word;Color:byte);
 procedure transLine(x1,y1,x2,y2:word;Color:byte);
 procedure transMaskedLine(x1,y1,x2,y2:word;Color:byte;Mask:word);
 procedure transHLine(x1,x2,y:word;Color:byte);
 procedure transVLine(x,y1,y2:word;Color:byte);
 procedure transRectangle(x1,y1,x2,y2:word;Color:byte);
 procedure transBar(x1,y1,x2,y2:word;Color:byte);
 procedure transEllipse(xc,yc,rx,ry:word;Color:byte);
 procedure transFilledEllipse(xc,yc,rx,ry:word;Color:byte);
 procedure transTriangle(x1,y1,x2,y2,x3,y3:word;Color:byte);
 procedure transFillTriangle(x1,y1,x2,y2,x3,y3:integer;Color:byte);
 procedure transFillPoly(var VertexArray;NumOfVertexes,Color:byte);

   (* The same with clipping *)
   (**************************)

 procedure _transPutPixel(x,y:integer;Color:byte);
 procedure _transPutTransparentPixel(x,y:integer;Color:byte);
 procedure _transLine(x1,y1,x2,y2:integer;Color:byte);
 procedure _transMaskedLine(x1,y1,x2,y2:integer;Color:byte;Mask:word);
 procedure _transHLine(x1,x2,y:integer;Color:byte);
 procedure _transVLine(x,y1,y2:integer;Color:byte);
 procedure _transRectangle(x1,y1,x2,y2:integer;Color:byte);
 procedure _transBar(x1,y1,x2,y2:integer;Color:byte);
 procedure _transEllipse(xc,yc:integer;rx,ry:word;Color:byte);
 procedure _transFilledEllipse(xc,yc:integer;rx,ry:word;Color:byte);
 procedure _transTriangle(x1,y1,x2,y2,x3,y3:integer;Color:byte);
 procedure _transFillTriangle(x1,y1,x2,y2,x3,y3:integer;Color:byte);
 procedure _transFillPoly(var VertexArray;NumOfVertexes,Color:byte);

   (* Getting/putting bitmaps *)
   (***************************)

 procedure transPutImage(x,y,Width,Height:word;Address:pointer);
 procedure transPutTransparentImage(x,y,Width,Height:word;Address:pointer);

   (* The same with clipping *)
   (**************************)

 procedure _transPutImage(x,y:integer;Width,Height:word;Address:pointer);
 procedure _transPutTransparentImage(x,y:integer;Width,Height:word;Address:pointer);

   (* Text writing *)
   (****************)

 procedure transWriteText(x,y:word;S:string;Color:byte);
 procedure _transWriteText(x,y:word;S:string;Color:byte);

Above procedures are identical to corresponding LFB256 procedures. See
LFB256.TXT for their input parameters and performed action description.


        [2.] Bitmap manipulations

        [2.1] Bitmap definition

Bitmap is a rectangular image in memory, each image element occupies one
byte. Bitmap type is defined in BMFX unit as follows:

        type TBitmap=record
         Width:word;
         Height:word;
         case byte of
          0:(Body:pointer);
          1:(_Body:dword);
        end;

Width and Height are bitmap width and height respectively. Body is a pointer
to first bitmap element. _Body is a dword type alias for Body. Since version
3.0 TMT Pascal allows transparent dword<->pointer type conversion, so _Body
alias is actually needed only for versions 2.x of TMT Pascal compiler.

        [2.2] BMFX procedures and functions


 procedure bmRescaleX(OldBitmap,NewBitmap:TBitmap);

This procedure performs bitmap rescaling to different width.
Scale factor is defined by NewBitmap.Width. NewBitmap.Body must point to
previously allocated memory block, where rescaled bitmap will be placed.

 procedure bmRescaleY(OldBitmap,NewBitmap:TBitmap);

This procedure performs bitmap rescaling to different height.
Scale factor is defined by NewBitmap.Height. NewBitmap.Body must point to
previously allocated memory block, where rescaled bitmap will be placed.

 procedure bmRescaleXY(OldBitmap,NewBitmap:TBitmap);

This procedure performs bitmap rescaling to different width and height.
Scale factors are defined by NewBitmap.Width and NewBitmap.Height.
NewBitmap.Body must point to previously allocated memory block, where rescaled
bitmap will be placed.

 procedure bmShiftLine(Bitmap:TBitmap;Line,ShiftValue:word);

This procedure will rotate specified bitmap line left-to-right for
ShiftValue pixels.

 procedure bmShiftLineZ(Bitmap:TBitmap;Line,ShiftValue:word;FillColor:byte);

This procedure will shift specified bitmap line left-to-right for
ShiftValue pixels. Pixels at line start will be filled with FillColor.

 procedure bmShiftColumn(Bitmap:TBitmap;Column,ShiftValue:word);

This procedure will rotate specified bitmap column top-to-bottom for
ShiftValue pixels.

 procedure bmShiftColumnZ(Bitmap:TBitmap;Column,ShiftValue:word;FillColor:byte);

This procedure will shift specified bitmap column top-to-bottom for
ShiftValue pixels. Pixels at column top will be filled with FillColor.

 procedure bmRotate(OldBitmap,NewBitmap:TBitmap;cx,cy,Angle:word);

This procedure will rotate OldBitmap around (cx,cy) point for Angle degrees.
Rotated bitmap body will be put to NewBitmap.

 procedure bmRotateZ(OldBitmap,NewBitmap:TBitmap;cx,cy,Angle:word;FillColor:byte);

This procedure will rotate OldBitmap around (cx,cy) point for Angle degrees.
Rotated bitmap body will be put to NewBitmap. Rotated bitmap margins will be
filled with FillColor.

 procedure bmRotScale(OldBitmap,NewBitmap:TBitmap;cx,cy,Angle,ScaleFactor:word);

This procedure will rotate OldBitmap around (cx,cy) point for Angle degrees
and rescale resulting bitmap with specified scale factor. Rotated bitmap body
will be put to NewBitmap.

 procedure bmRotScaleZ(OldBitmap,NewBitmap:TBitmap;cx,cy,Angle,ScaleFactor:word;FillColor:byte);

This procedure will rotate OldBitmap around (cx,cy) point for Angle degrees
and rescale resulting bitmap with specified scale factor. Rotated bitmap body
will be put to NewBitmap. Rotated bitmap margins will be filled with
FillColor.

 procedure bmHalf(OldBitmap,NewBitmap:TBitmap);

Rescales bitmap to half its original size. This one is somewhat faster then
bmRescaleXY.

 procedure bmDouble(OldBitmap,NewBitmap:TBitmap);

Rescales bitmap to double its original size. This one is somewhat faster then
bmRescaleXY.

 procedure bmHalfSmooth(OldBitmap,NewBitmap:TBitmap;TransTable:pointer);

Rescales bitmap to half its original size, with smoothing. TransTable must
contain translucency lookup table for bitmap palette. For best filtering use
translucency strength about 40..50.

 procedure bmDoubleInterlace(OldBitmap,NewBitmap:TBitmap);

Rescales bitmap to double its original size, but skips all even lines.
This one is somewhat faster then bmDouble.

 procedure bmSmooth(Bitmap:TBitmap;TransTable:pointer);

Performs bitmap smoothing. TransTable must contain translucency lookup table
for bitmap palette. For best filtering use translucency strength about 20..30
(25 should do the best). This procedure is especially effective for previously
enlarged (rescaled) bitmaps.

 procedure bmAltSmooth(Bitmap:TBitmap;TransTable:pointer);

Performs bitmap smoothing with alternative algorithm. TransTable must contain
translucency lookup table for bitmap palette. For best filtering use
translucency strength 50. This procedure sometimes gives better result then
previous one.

 procedure bmFlipX(Bitmap:TBitmap);

Flips bitmap left-to-right.

 procedure bmFlipY(Bitmap:TBitmap);

Flips bitmap top-to-bottom.

 procedure bmAnd(Bitmap1,Bitmap2:TBitmap);

Bitwise ANDs two bitmaps.

 procedure bmAndN(Bitmap1,Bitmap2:TBitmap);

Bitwise ANDs two bitmaps and then bitwise NOTs result.

 procedure bmOr(Bitmap1,Bitmap2:TBitmap);

Bitwise ORs two bitmaps.

 procedure bmXor(Bitmap1,Bitmap2:TBitmap);

Bitwise XORs two bitmaps.

 procedure bmNot(Bitmap:TBitmap);

Bitwise NOTs given bitmap.

==============================================================================

                                Written by Asp //VRg
                                July 1999

