Simba/Doc/sphinx/scriptref/bitmaps.rst

.. _scriptref-bitmaps:

Bitmaps
=======

A bitmap in Simba is simply a two dimensional *field of colours*. These colours
can all be the same, or they can be of different colours. Simba features
functions to create, manipulate and search for bitmaps.

.. INSERT BITMAP EXAMPLE HERE (Picture, etc)

The bitmaps are - just as files - represented as integer in Simba (they point to
a list of bitmaps, and the value of the integer is the position in the list).
So typically, when referring to bitmaps in Simba, you simply represent them as
an integer:

.. code-block:: pascal

    var bmp, x, y: integer;
    bmp := CreateBitmap(10, 10); // Create a bitmap of size (10, 10)
    if FindBitmapIn(bmp, x, y, 0, 0, 300, 300) then
      writeln('Found it!');
    FreeBitmap(bmp); // Don't forget to free it when we are done.

Note that the previous example doesn't make a lot of sense as the bitmap has
only been created and not filled with any colours, they are as of yet,
undefined. You can also create bitmaps from screenshots and load them when your
script starts using the :ref:`scriptref-bitmapfromstring` function, or
simple store them as files and load them using the :ref:`scriptref-loadbitmap`
function.

Word of caution on bitmap creation
----------------------------------

Bitmaps in Simba are internally all instances of *TMufasBitmap*. Scripts should
generally access bitmaps using their *handle*: an integer. All functions
referenced here either require a bitmap *handle* or return one.

If you want to gain more access over a specific bitmap, see the
*GetMufasaBitmap* function. It is highly unrecommended to create bitmaps like
this, because Simba will not free them automatically for you. (There's no
problem doing it like this if you only want to perform operations on it and then
free it again)

.. code-block:: pascal

    var bmp: TMufasaBitmap;
    bmp := TMufasBitmap.Create;

Because there is no way to get a *handle* to this bitmap; as it will not be
managed by Simba internally. (All Bitmaps created by *CreateBitmap* are managed
by Simba, if you don't know what this means: you generally want Simba to manage
the bitmaps)

If you still want access to the TMufasaBitmap, use *GetMufasaBitmap*, described
below.

GetMufasaBitmap
---------------

.. code-block:: pascal

    function GetMufasaBitmap(bmp : integer) : TMufasaBitmap;

Returns the *TMufasaBitmap* for the given bitmap. They both reference the same
bitmap. TMufasaBitmap is a more advanced interface to bitmaps in Simba.
There is no way to get a *internal* (integer)
reference to a bitmap if you create it with TMufasaBitmap.Create; so the
recommended way is to use *CreateBitmap* to get the integer reference/handle and
then call this function to get the class reference.


.. code-block:: pascal

    var bmp: TMufasaBitmap;
        bmph: integer;
    bmph := CreateBitmap(100, 100);
    bmp := GetMufasaBitmap(bmph);

    bmp.SetSize(150,150); // also changes bmph, as they are the same bitmap.

.. _scriptref-createbitmapstring:

CreateBitmapString
------------------

.. code-block:: pascal

    function CreateBitmapString(bmp : integer) : string;

Creates a string for the given bitmap, you can use this to save a bitmap for
later us, for example loading it again using :ref:`scriptref-bitmapfromstring`.


.. _scriptref-createbitmap:

CreateBitmap
------------

.. code-block:: pascal

    function CreateBitmap(w,h :integer) : integer;

Create a bitmap with width *h* and height *h*.
Returns the reference to the created bitmap.

.. _scriptref-freebitmap:

FreeBitmap
----------

.. code-block:: pascal

    procedure FreeBitmap(Bmp : integer);

Free the bitmap. You should do this when you no longer need the bitmap.
Be careful when working with bitmaps: not freeing it when you no longer need it
leads to memory leaks, which will eventually make your script crash. (Unless you
stop it in time, in which case Simba will free the bitmaps for you)

.. _scriptref-savebitmap:

SaveBitmap
----------

.. code-block:: pascal

    procedure SaveBitmap(Bmp : integer; path : string);

Save the given bitmap to the specified path.

.. _scriptref-bitmapfromstring:

BitmapFromString
----------------

.. code-block:: pascal

    function BitmapFromString(Width,Height : integer; Data : string): integer;

Load a bitmap from the given string. This command is usually generated with the
Bitmap to String feature in Simba.

.. _scriptref-loadbitmap:

LoadBitmap
----------

.. code-block:: pascal

    function LoadBitmap(Path : string) : integer;

Load a bitmap from a path to a file. Formats known to work are BMP and PNG
images.

.. _scriptref-setbitmapsize:

SetBitmapSize
-------------

.. code-block:: pascal

    procedure SetBitmapSize(Bmp,NewW,NewH : integer);

Change the size of the bitmap.
Previous data will be preserved (if possible), so enlarging the bitmap won't
destroy the old data, but shrinking it will inevitably destroy some data.
(Everything that falls out of the new bounds)

.. _scriptref-getbitmapsize:

GetBitmapSize
-------------

.. code-block:: pascal

    procedure GetBitmapSize(Bmp : integer; var BmpW,BmpH : integer);

Returns the size of the bitmap in *BmpW*, *BmpH*.

.. _scriptref-stretchbitmapresize:

StretchBitmapResize
-------------------

.. code-block:: pascal

    procedure StretchBitmapResize(Bmp,NewW,NewH : integer);


.. _scriptref-createmirroredbitmap:

CreateMirroredBitmap
--------------------

.. code-block:: pascal

    function CreateMirroredBitmap(Bmp : integer) : integer;


.. _scriptref-createmirroredbitmapex:

CreateMirroredBitmapEx
----------------------

.. code-block:: pascal

    function CreateMirroredBitmapEx(Bmp : integer; MirrorStyle : TBmpMirrorStyle) : integer;


.. _scriptref-fastsetpixel:

FastSetPixel
------------

.. code-block:: pascal

    procedure FastSetPixel(bmp,x,y : integer; Color : TColor);

Set the pixel on the bitmap at position x, y to *color*.

.. _scriptref-fastsetpixels:

FastSetPixels
-------------

.. code-block:: pascal

    procedure FastSetPixels(bmp : integer; TPA : TPointArray; Colors : TIntegerArray);

Set the pixels on the bitmap at position TPA[index] to Colors[index].

.. _scriptref-fastgetpixel:

FastGetPixel
------------

.. code-block:: pascal

    function FastGetPixel(bmp, x,y : integer) : TColor;

Return the colour of pixel on the bitmap, position specified by x, y.

.. _scriptref-fastgetpixels:

FastGetPixels
-------------

.. code-block:: pascal

    function FastGetPixels(Bmp : integer; TPA : TPointArray) : TIntegerArray;

Return an array of the colours on the bitmap; positions specified by *TPA*.

.. _scriptref-getbitmapareacolors:

GetBitmapAreaColors
-------------------

.. code-block:: pascal

    function GetBitmapAreaColors(bmp,xs, ys, xe, ye: Integer): T2DIntegerArray;

Returns all the colours in the area defined by (*xs*, *xy*, *xe*, *ye*) on the
bitmap in a two dimensions integer array.

.. _scriptref-fastdrawclear:

FastDrawClear
-------------

.. code-block:: pascal

    procedure FastDrawClear(bmp : integer; Color : TColor);

Draw *Color* on every pixel on the bitmap.

.. _scriptref-fastdrawtransparent:

FastDrawTransparent
-------------------

.. code-block:: pascal

    procedure FastDrawTransparent(x, y: Integer; SourceBitmap, TargetBitmap: Integer);


.. _scriptref-setransparentcolor:

SetTransparentColor
-------------------

.. code-block:: pascal

    procedure SetTransparentColor(bmp : integer; Color : TColor);

.. _scriptref-getransparentcolor:

GetTransparentColor
-------------------

.. code-block:: pascal

    function GetTransparentColor(bmp: integer) : TColor;

.. _scriptref-fastreplacecolor:

FastReplaceColor
----------------

.. code-block:: pascal

    procedure FastReplaceColor(Bmp : integer; OldColor,NewColor : TColor);

.. _scriptref-copyclienttobitmap:

CopyClientToBitmap
------------------

.. code-block:: pascal

    procedure CopyClientToBitmap(bmp, xs, ys, xe, ye: Integer);

Copy client area *xs, ys, xe, ye* to specified bitmap.

.. _scriptref-bitmapfromclient:

BitmapFromClient
----------------

.. code-block:: pascal

    function BitmapFromClient(const xs, ys, xe, ye: Integer): Integer;

Create a bitmap from the client. Area specified by *xs, ye, xe, ye*.

.. _scriptref-setbitmapname:

SetBitmapName
-------------

.. code-block:: pascal

    procedure SetBitmapName(Bmp : integer; name : string);

Assign a name to the bitmap. Mainly for debugging purposes. (It will write the
name of the bitmap if it hasn't been freed.)

.. code-block:: pascal

    program new;

    var bmp: integer;
    begin
      bmp := CreateBitmap(10, 10);
      SetBitmapName(bmp, 'We will not free this bitmap');
    end.
    // Simba will print what bitmap has not been freed (along with his long
    // name)

.. _scriptref-findbitmap:

FindBitmap
----------

.. code-block:: pascal

    function FindBitmap(bitmap: integer; var x, y: Integer): Boolean;

Searches for the Bitmap *bmp* on the entire client. Returns true if found.
If found, *x, y* specifies the position where the bitmap was found.

.. _scriptref-findbitmapin:

FindBitmapIn
------------

.. code-block:: pascal

    function FindBitmapIn(bitmap: integer; var x, y: Integer;  xs, ys, xe, ye: Integer): Boolean;


Searches for the Bitmap *bmp* on the client in the area defined by *xs,ys,xe,ye*.
Returns true if found. If found, *x, y* specifies the position where the bitmap
was found.

.. _scriptref-findbitmaptolerancein:

FindBitmapToleranceIn
---------------------

.. code-block:: pascal

    function FindBitmapToleranceIn(bitmap: integer; var x, y: Integer; xs, ys, xe, ye: Integer; tolerance: Integer): Boolean;

Searches for the Bitmap *bmp* on the client in the area defined by *xs,ys,xe,ye*.
Tolerance defines the tolerance per pixel when matching bitmaps. See
:ref:`scriptref-CTS` for more information on tolerance.
Returns true if found. If found, *x, y* specifies the position where the bitmap
was found.

.. _scriptref-findbitmapspiral:

FindBitmapSpiral
----------------

.. code-block:: pascal

    function FindBitmapSpiral(bitmap: Integer; var x, y: Integer; xs, ys, xe, ye: Integer): Boolean;

Searches for the Bitmap *bmp* on the client in the area defined by *xs,ys,xe,ye*.
Returns true if found. If found, *x, y* specifies the position where the bitmap
was found. Search starts from a point defined by *x, y*.


.. _scriptref-findbitmapsspiraltolerance:

FindBitmapsSpiralTolerance
--------------------------

.. code-block:: pascal

    function FindBitmapsSpiralTolerance(bitmap: integer; x, y: Integer; var Points : TPointArray; xs, ys, xe, ye,tolerance: Integer): Boolean;


Searches for the Bitmap *bmp* on the client in the area defined by *xs,ys,xe,ye*.
Tolerance defines the tolerance per pixel when matching bitmaps. See
:ref:`scriptref-CTS` for more information on tolerance.
Search starts from a point defined by *x, y*.
Returns true if found. If found, each point in *TPA* specifies a match.

.. _scriptref-findbitmapspiraltolerance:

FindBitmapSpiralTolerance
-------------------------

.. code-block:: pascal

    function FindBitmapSpiralTolerance(bitmap: integer; var x, y: Integer; xs, ys, xe, ye,tolerance : integer): Boolean;

Searches for the Bitmap *bmp* on the client in the area defined by *xs,ys,xe,ye*.
Tolerance defines the tolerance per pixel when matching bitmaps. See
:ref:`scriptref-CTS` for more information on tolerance.
Search starts from a point defined by *x, y*.
Returns true if found. If found, *x, y* specifies the position where the bitmap
was found.

.. _scriptref-rotatebitmap:

RotateBitmap
------------

.. code-block:: pascal

    function RotateBitmap(bitmap: Integer; angle: Extended): Integer;


.. _scriptref-desaturatebitmap:

DesaturateBitmap
----------------

.. code-block:: pascal

    function DesaturateBitmap(Bitmap : integer) : integer;


.. _scriptref-invertbitmap:

InvertBitmap
------------

.. code-block:: pascal

    procedure InvertBitmap(Bitmap : integer);


.. _scriptref-copybitmap:

CopyBitmap
----------

.. code-block:: pascal

    function CopyBitmap(Bitmap:  integer) : integer)

Creates a copy of the *Bitmap*. Returns the bitmap copy.

.. _scriptref-greyscalebitmap:

GreyScaleBitmap
---------------

.. code-block:: pascal

    function GreyScaleBitmap(bitmap : integer) : integer

Creates a copy of the bitmap, greyscaled.

.. _scriptref-brightnessbitmap:

BrightnessBitmap
----------------

.. code-block:: pascal

    function BrightnessBitmap(Bitmap,br : integer) : integer;

Changes the brightness of a bitmap, intensity defined by *br*.
Returns a new bitmap with the brightness applied.

If you instead want to apply brightness to the current bitmap, see
:ref:`filter_apply_bitmap`

.. _scriptref-contrastbitmap:

ContrastBitmap
--------------

.. code-block:: pascal

    function ContrastBitmap(bitmap : integer; co : extended) : integer;

Changes the constrast of a bitmap, returns a new bitmap with the contrast
applied.

.. _scriptref-posterizebitmap:

PosterizeBitmap
---------------

.. code-block:: pascal

    function PosterizeBitmap(Bitmap : integer; po : integer) : integer;

Posterizes a bitmap, intensity defined by *po*; returns a new bitmap with the
posterisation applied.


.. _filter_apply_bitmap:

Applying a filter on the current bitmap
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: pascal

    var b: integer;
    begin
        // Dummy bitmap. You'll want something that's not just a blank bitmap.
        B:=CreateBitmap(100,100);

        // Apply the filter (Posterize in this case) without making a copy.
        GetMufasaBitmap(b).Posterize(GetMufasaBitmap(b), 10);

        // Always free your bitmaps when you no longer use them. :) 
        FreeBitmap(b);
    end.

.. _scriptref-createmaskfrombitmap:

CreateMaskFromBitmap
--------------------

.. code-block:: pascal

    function CreateMaskFromBitmap(Bitmap : integer) : TMask;


.. _scriptref-findmasktolerance:

FindMaskTolerance
-----------------

.. code-block:: pascal

    function FindMaskTolerance(const mask: TMask; var x, y: Integer; xs,ys, xe, ye: Integer; Tolerance, ContourTolerance: Integer): Boolean;


.. _scriptref-findbitmapmasktolerance:

FindBitmapMaskTolerance
-----------------------

.. code-block:: pascal

    function FindBitmapMaskTolerance(mask: Integer; var x, y: Integer; xs, ys, xe, ye: Integer; Tolerance, ContourTolerance: Integer): Boolean;


.. _scriptref-finddeformedbitmaptolerancein:

FindDeformedBitmapToleranceIn
-----------------------------

.. code-block:: pascal

    function FindDeformedBitmapToleranceIn(bitmap: integer; var x,y: Integer; xs, ys, xe, ye: Integer; tolerance: Integer; Range: Integer; AllowPartialAccuracy: Boolean; var accuracy: Extended): Boolean;


.. _scriptref-drawtpabitmap:

DrawTPABitmap
-------------

.. code-block:: pascal

    procedure DrawTPABitmap(bitmap: integer; TPA: TPointArray; Color: integer);

*Draws* a TPointArray on a bitmap. Each point in the TPointArray is *painted*
on the bitmap by setting the pixel on the bitmap (position defined by tpa point)
to *color*.

.. _scriptref-drawatpabitmap:

DrawATPABitmap
--------------

.. code-block:: pascal

    procedure DrawATPABitmap(bitmap: integer; ATPA: T2DPointArray);

*Draws* a Array of TPointArray on a bitmap.
Each point in the TPointArray is *painted* on the bitmap by setting
the pixel on the bitmap (position defined by tpa point)
to a color. Colors differ per TPointArray (group).

.. _scriptref-drawatpabitmapex:

DrawATPABitmapEx
----------------

.. code-block:: pascal

    procedure DrawATPABitmapEx(bitmap: integer; ATPA: T2DPointArray; Colors: TIntegerArray);

*Draws* a Array of TPointArray on a bitmap.
Each point in the TPointArray is *painted* on the bitmap by setting
the pixel on the bitmap (position defined by tpa point)
to a color. Colors are defined by *Colors*.

.. _scriptref-drawbitmap:

DrawBitmap
----------

.. code-block:: pascal

    procedure DrawBitmap(Bmp: Integer; Dest: TCanvas; x, y: Integer);

Draw the bitmap to a TCanvas.

.. _scriptref-rectanglebitmap:

RectangleBitmap
---------------

.. code-block:: pascal

    procedure RectangleBitmap(bitmap : integer; const box : TBox; Color : TColor);


.. _scriptref-floodfillbitmap:

FloodFillBitmap
---------------

.. code-block:: pascal

    procedure FloodFillBitmap(bitmap : integer; const StartPoint : TPoint; const SearchCol,ReplaceCol : TColor);


.. _scriptref-calculatepixelshift:

CalculatePixelShift
-------------------

.. code-block:: pascal

    function CalculatePixelShift(Bmp1,Bmp2 : Integer; CompareBox : TBox) : integer;


.. _scriptref-calculatepixeltolerance:

CalculatePixelTolerance
-----------------------

.. code-block:: pascal

    function CalculatePixelTolerance(Bmp1,Bmp2 : Integer; CompareBox : TBox; CTS : integer) : extended;')