Delphi SDK Reference: Class TVFBitmap

TVFBitmap is a wrapper class for the VFBitmap VC++ instance objects passed by Virtual Dub to external filters (for example, the src and dst fields in TFilterActivation). It encapsulates the behaviour of that instance objects providing run-time access to its virtual methods. You can also use TVFBitmap to create your own bitmaps and run Virtual Dub code on it.

Constructors

CreateWrapper
Declaration: constructor CreateWrapper(aCObj: PCObj_VFBitmap);
Description: Creates a wrapper around the VFBitmap instance object aCObj, giving access to the VirtualDub image processing functions.
Parameter(s): aCObj: a VFBitmap instance object to be wraped around
Result: An object of class TVFBitmap that wraps aCObj
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function runProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltDither(0,0,fa^.src,100,100,300,300);
  Bitmap.Destroy;
  ...
end;

CreateClone
Declaration: constructor CreateClone(aCObj: PCObj_VFBitmap);
Description: Creates a new VFBitmap instance object that is an exact copy of aCObj and a wrapper around it, giving access to the VirtualDub image processing functions.
Parameter(s): aCObj: the VFBitmap instance object to be copied
Result: An object of class TVFBitmap that wraps around the newly created VFBitmap instance object
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function runProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltDither(0,0,fa^.src,100,100,300,300);
  Bitmap.Destroy;
  ...
end;

CreateNew
Declaration: constructor CreateNew(w: TPixDim; h: TPixDim; depth: Integer);
Description: Creates a new empty VFBitmap instance object and a wrapper around it based on the width, hight and depth given. Memory for bitmap data is allocated.
Parameter(s): w: width of the VFBitmap instance object to be created
h: height of the VFBitmap instance object to be created
depth: depth of the VFBitmap instance object to be created
Result: An object of class TVFBitmap that wraps around the newly created VFBitmap instance object
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function runProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltDither(0,0,fa^.src,100,100,300,300);
  Bitmap.Destroy;
  ...
end;

CreateNew
Declaration: constructor CreateNew(bih: PBitmapInfoHeader);
Description: Creates a new empty VFBitmap instance object and a wrapper around it based on the given GDI bitmap structure. Memory for bitmap data is allocated.
Parameter(s): bih: pointer to GDI bitmap description of the VFBitmap instance object to be created
Result: An object of class TVFBitmap that wraps around the newly created VFBitmap instance object
Example: -

Destructors

Destroy
Declaration: destructor Destroy;
Description: Destroys the wrapper. If a new VFBitmap instance object was created with the CreateClone or CreateNew constructors then the memory allocated is freed up.
Parameter(s): -
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function runProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var
  SrcBitmap: TVFBitmap;
  DstBitmap: TVFBitmap;
begin
  ...
  SrcBitmap := TVFBitmap.CreateClone(fa^.src);
  DstBitmap := TVFBitmap.CreateWrapper(fa^.dst);
  DstBitmap.BitBltDither(0,0,SrcBitmap,100,100,300,300);
  DstBitmap.Destroy; //The wrapper is destroyed
  SrcBitmap.Destroy; //The wrapper is destroyed and the memory allocated free
  ...
end;

Methods

Address(), Address16() and Address32()
Declaration: function Address(x, y: TPixCoord): PPixel;
function Address16 (x, y: TPixCoord): PPixel;
function Address32 (x, y: TPixCoord): PPixel;
Description: Returns the address of a particular pixel in the bitmap, with normal y coordinates. Address() is general purpose for any depth. Address16() and Address32() are specific functions for 16 bits and 32 bits depths.
Parameter(s): x, y: coordinates of the desired pixel
Result: Address of the pixel at (x, y)
Example: -

Addressi(), Address16i() and Address32i()
Declaration: function Addressi(x, y: TPixCoord): PPixel;
function Address16i (x, y: TPixCoord): PPixel;
function Address32i (x, y: TPixCoord): PPixel;
Description: Returns the address of a particular pixel in the bitmap, with inverted y coordinates. Addressi() is general purpose for any depth. Address16i() and Address32i() are specific functions for 16 bits and 32 bits depths.
Parameter(s): x: x-coordinate of the desired pixel
y: inverted y-coordinate of the desired pixel
Result: Address of the pixel at (x, h-y-1)
Example: -

PitchAlign4()
Declaration: function PitchAlign4: TPixOffset;
Description: Computes a dword-aligned pitch value for the current width and bit depth.
Parameter(s): -
Result: Scanline pitch for current width and bit depth, rounded up to next 4 bytes
Example: -

PitchAlign8()
Declaration: function PitchAlign8: TPixOffset;
Description: Computes a qword-aligned pitch value for the current width and bit depth.
Parameter(s): -
Result: Scanline pitch for current width and bit depth, rounded up to next 8 bytes
Example: -

Modulo()
Declaration: function Modulo: TPixOffset;
Description: Computes the gap between scanlines from the current pitch, width, and bit depth.
Parameter(s): -
Result: Gap between scanlines, in bytes
Example: -

Size()
Declaration: function Size: TPixOffset;
Description: Computes the total number of bytes the bitmap occupies in memory.
Parameter(s): -
Result: Total number of bytes bitmap occupies
Example: -

MakeBitmapHeader(pBitmapInfoHeader)
Declaration: procedure MakeBitmapHeader(bih: PBitmapInfoHeader);
Description: Creates a Win32 bitmap description from a VFBitmap.
Parameter(s): pBitmapInfoHeader:    pointer to Win32 bitmap desc. to be filled in.
Result: -
Example: -

AlignTo4()
Declaration: procedure AlignTo4;
Description: Computes and sets the pitch, modulo, and size members of a VFBitmap for 4-byte alignment.
Parameter(s): -
Result: -
Example: -

AlignTo8()
Declaration: procedure AlignTo8;
Description: Computes and sets the pitch, modulo, and size members of a VFBitmap for 8-byte alignment.
Parameter(s): -
Result: -
Example: -

BitBlt()
Declaration: procedure BitBlt(x2, y2: TPixCoord; const src: PCObj_VFBitmap; x1, y1: TPixCoord; dx, dy: TPixDim);
procedure BitBlt(x2, y2: TPixCoord; const src: TVFBitmap; x1, y1: TPixCoord; dx, dy: TPixDim);
Description: Copies a rectangular region from one bitmap to another. BitBlt() can do format conversion between 16, 24, and 32 bit deep bitmaps. It will also convert 8-bit paletted bitmaps to 16-, 24-, and 32-bit bitmaps.
Parameter(s): x2, y2: top left corner of destination rectangle
x1, y1: top left corner of source rectangle
src:       source bitmap (can be the pointer to an original C++ object PCObj_VFBitmap or a Delphi wrapper object TVFBitmap)
dx, dy: dimensions of rectangle to be copied
            -1, -1 to copy largest possible rectangle
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBlt(0,0,fa^.src,100,100,300,300);
  Bitmap.Destroy;
  ...
end;

{ In the following example, wrappers are created for the VirtualDub bitmap objects fa^.src and fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the destination bitmap at (0,0). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var BitmapSrc: TVFBitmap;
    BitmapDst: TVFBitmap;
begin
  ...
  BitmapSrc := TVFBitmap.CreateWrapper(fa^.src);
  BitmapDst := TVFBitmap.CreateWrapper(fa^.dst);
  BitmapDst.BitBlt(0,0,BitmapSrc,100,100,300,300);
  BitmapDst.Destroy;
  BitmapSrc.Destroy;
  ...
end;

BitBltDither()
Declaration: procedure BitBltDither(x2, y2: TPixCoord; const src: PCObj_VFBitmap; x1, y1: TPixDim; dx, dy: TPixDim; to565: Boolean);
Description: Dithers a 32-bit deep bitmap down to 15- or 16-bit RGB. BitBltDither() uses a 4x4 ordered dither matrix. Images dithered using this routine may appear slightly darker than with BitBlt().
Parameter(s): x2, y2: top left corner of destination rectangle
x1, y1: top left corner of source rectangle
src:       source bitmap
dx, dy: dimensions of rectangle to be copied
            -1, -1 to copy largest possible rectangle
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltDither(0,0,fa^.src,100,100,300,300);
  Bitmap.Destroy;
  ...
end;

BitBltDither565()
Declaration: procedure BitBlt565(x2, y2: TPixCoord; const src: PCObj_VFBitmap; x1, y1: TPixDim; dx, dy: TPixDim);
Description: Copies a rectangular region from a 32-bit bitmap to a 16-bit 565 bitmap.
Parameter(s): x2, y2: top left corner of destination rectangle
x1, y1: top left corner of source rectangle
src:       source bitmap
dx, dy: dimensions of rectangle to be copied
            -1, -1 to copy largest possible rectangle
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x1,y1,dx,dy)=(100,100,300,300) from the source bitmap is copied into the first one at (0,0). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
 ...
 Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
 BitBltDither565(0,0,fa^.src,100,100,300,300);
 Bitmap.Destroy;
 ...
end;

BitBltXlat1()
Declaration: function BitBltXlat1(x2, y2: TPixCoord; const src: PCObj_VFBitmap; x1, y1: TPixCoord; dx, dy: TPixDim; const tbl: PPixelTable): Boolean;
Description: Translates a rectangular region from one 32-bit bitmap to another with a single lookup table for all channels. BitBltXlat1() takes each of the three RGB channels in each pixel and runs it through the given lookup table. This allows you to do simple monochromatic effects such as brightness, contrast, and gamma correction.
Parameter(s): x2, y2: top left corner of destination rectangle
x1, y1: top left corner of source rectangle
src:       source bitmap
dx, dy: dimensions of rectangle to be copied
            -1, -1 to copy largest possible rectangle
tbl:      256-byte lookup table used to translate pixels
Result: -
Example:

{ In the following example, a conversion table is created where the converted value of each Byte corresponds to its negation. Then, a wrapper is created for the VirtualDub bitmap object fa^.dst. Finally, the region (x1,y1,dx,dy)=(100,100,200,200) from the source bitmap is converted into the first one at (100,100). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var
  Bitmap: TVFBitmap;
  table: PPixel8Table;
begin
  ...
  new(table);
  for I := 0 to 255 do
    table^[I] := not I;
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltXlat1(100,100,fa^.src,100,100,200,200, table);
  Bitmap.Destroy;
  dispose(table);
  ...
end;

BitBltXlat3()
Declaration: function BitBltXlat3(x2, y2: TPixCoord; const src: PCObj_VFBitmap; x1, y1: TPixCoord; dx, dy: TPixDim; const tbl: PPixelTableRGB): Boolean;
Description: Translates a rectangular region from one 32-bit bitmap to another with a separate lookup table for all channels. BitBltXlat3() is similar to BitBltXlat1() except that each RGB channel has its own lookup table, allowing you to use separate colour ramps. The three tables are interleaved together in a 256 dword entry table in pixel format (0x00rrggbb).
Parameter(s): x2, y2: top left corner of destination rectangle
x1, y1: top left corner of source rectangle
src:       source bitmap
dx, dy: dimensions of rectangle to be copied
            -1, -1 to copy largest possible rectangle
tbl:      1k lookup table used to translate pixels
Result: -
Example:

{ In the following example, a conversion table is created where the converted value of each Byte corresponds to its negation. Then, a wrapper is created for the VirtualDub bitmap object fa^.dst. Finally, the region (x1,y1,dx,dy)=(100,100,200,200) from the source bitmap is converted into the first one at (100,100). }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var
  Bitmap: TVFBitmap;
  table: PPixelTableRGB;
begin
  ...
  new(table);
  for I := 0 to 255 do begin
    rgbRed := I div 2;
    rgbGreen := I div 3;
    rgbBlue := I;
    end;
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.BitBltXlat3(100,100,fa^.src,100,100,200,200, table);
  Bitmap.Destroy;
  dispose(table);
  ...
end;

StretchBltNearestFast()
Declaration: function StretchBltNearestFast(x1, y1: TPixCoord; dx1, dy1: TPixDim; const src: PCObj_VFBitmap; x2, y2, dx2, dy2: double): Boolean;
Description: Stretches a region from one 32-bit bitmap to another using nearest neighbour sampling. StretchBltNearestFast() will not clip either the source or destination regions and will return false if any of the regions exceed their bitmaps. You can flip the source region horizontally and vertically by making dx2 and/or dy2 negative. With horizontal flips, x2 becomes the right side of the rectangle, and with vertical flips, y2 is the bottom.
Parameter(s): x1, y1:     top left corner of destination rectangle
dx1, dy1: dimensions of the destination rectangle
x2, y2:     top left corner of source rectangle
dx2, dy2: dimensions of the source rectangle
src:          source bitmap
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x2,y2,dx2,dy2)=(100,100,100,200) from the source bitmap is stretched into it at (100,100) with the same height and double width. }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.StretchBltNearestFast(100,100,200,200,fa^.src,100,100,100,200);
  Bitmap.Destroy;
  ...
end;

StretchBltBilinearFast()
Declaration: function StretchBltBilinearFast(x1, y1: TPixCoord; dx1, dy1: TPixDim; const src: PCObj_VFBitmap; x2, y2, dx2, dy2: double): Boolean;
Description: Stretches a region from one 32-bit bitmap to another using bilinear sampling. StretchBltBilinearFast() will not clip either the source or destination regions and will return false if any of the regions exceed their bitmaps. You can flip the source region horizontally and vertically by making dx2 and/or dy2 negative. With horizontal flips, x2 becomes the right side of the rectangle, and with vertical flips, y2 is the bottom. StretchBltBilinearFast() always uses a 2x2 source pixel block and will give suboptimal results on shrink operations.
Parameter(s): x1, y1:     top left corner of destination rectangle
dx1, dy1: dimensions of the destination rectangle
x2, y2:     top left corner of source rectangle
dx2, dy2: dimensions of the source rectangle
src:          source bitmap
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then the region (x2,y2,dx2,dy2)=(100,100,100,200) from the source bitmap is stretched into it at (100,100) with the same height and double width. }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.StretchBltBilinearFast(100,100,200,200,fa^.src,100,100,100,200);
  Bitmap.Destroy;
  ...
end;

RectFill()
Declaration: function RectFill(x, y: TPixCoord; dx, dy: TPixDim; c: TPixel32): Boolean;
Description: Fills a rectangular region in a 32-bit bitmap with a solid colour.
Parameter(s): x, y:     top left corner of rectangle
dx, dy: dimensions of rectangle
-1, -1 to copy largest possible rectangle
c: colour to fill with
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst, and then a red rectangle (colour code 255) is drawn at (x,y)=(50,50) with width (dx) equal to 200 and height (dy) equal to 100. }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var Bitmap: TVFBitmap;
begin
  ...
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.RectFill(50,50,200,100,255);
  Bitmap.Destroy;
  ...
end;

Histogram()
Declaration: function Histogram(x, y: TPixCoord; dx, dy: TPixDim; pHisto: PHistoTable;
Description: Creates a histogram from pixels in a given source rectangle of a 16-, 24-, or 32-bit bitmap. Histogram() does not clear the histogram array, so you must reset it to all zero beforehand. You can also clear it once, and then call Histogram() multiple times to combine the results from several regions. In all cases except HISTO_GRAY, a value from 0-255 is added to pHisto[i] for each pixel. With HISTO_GRAY, because channel values range 0-255, values 0-765 can be added per pixel.
Parameter(s): x, y:              top left corner of rectangle
dx, dy:         dimensions of rectangle
                    -1, -1 to copy largest possible rectangle
pHisto:         pointer to 256-entry histogram array to be modified
iHistoType:  one of these values, to specify histogram type:
                     HISTO_LUMA luminance channel (21%/71%/7%)
                     HISTO_GRAY red, green, and blue
                     HISTO_RED red channel only
                     HISTO_GREEN green channel only
                     HISTO_BLUE blue channel only
Result: -
Example:

{ In the following example, a wrapper is created for the VirtualDub bitmap object fa^.dst. Next a dynamic variable for the histogram table is created and all the 256 entries are reset to zero. Finally the histogram is created for the pixels inside the region (x,y,dx,dy)=(100,100,300,300) considering only the Red channel. }

function tutorialRunProc(const fa: PFilterActivation; const ff: PFilterfunctions): Integer; cdecl;
var
  Bitmap: TVFBitmap;
  histo: PHistoTable;
  I: Byte;
begin
  ...
  new(histo);
  for I := 0 to 255 do histo^[I] := 0;
  Bitmap := TVFBitmap.CreateWrapper(fa^.dst);
  Bitmap.Histogram(100,100,300,300,histo,HISTO_RED);
  Bitmap.Destroy;
  dispose(histo);
  ...
end;
© 2005 Fernando Reis <>
Adapted from VirtualDub external filter SDK 1.05 documentation © 1999-2001 Avery Lee