Simba/Doc/sphinx/scriptref/bitmaps.rst

.. _scriptref-bitmaps:

Bitmaps
=======

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 with:

.. 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.


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

.. code-block:: pascal

    function CreateBitmapString(bmp : integer) : string;

Creates a string for the given bitmap.

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

.. code-block:: pascal

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

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


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)

SaveBitmap
----------

.. code-block:: pascal

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

Save the given bitmap to the specified path.

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.


LoadBitmap
----------

.. code-block:: pascal

    function LoadBitmap(Path : string) : integer;

Load a bitmap from a path to a file. Known formats are .bmp and .png. (Possibly
others, don't know for sure)

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

.. code-block:: pascal

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

Change the size of the bitmap. Previous data will be preserved (if possible).

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

.. code-block:: pascal

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

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

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

.. code-block:: pascal

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


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

.. code-block:: pascal

    function CreateMirroredBitmap(Bmp : integer) : integer;


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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

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

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].


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

.. code-block:: pascal

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

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

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

.. code-block:: pascal

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

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


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.

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

.. code-block:: pascal

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

Draw *Color* on every pixel on the bitmap.

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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

    function GetTransparentColor(bmp: integer) : TColor;


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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

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

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*.

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.)

FindBitmap
----------

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

    function DesaturateBitmap(Bitmap : integer) : integer;


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

.. code-block:: pascal

    procedure InvertBitmap(Bitmap : integer);


CopyBitmap
----------

.. code-block:: pascal

    function CopyBitmap(Bitmap:  integer) : integer)


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

.. code-block:: pascal

    function GreyScaleBitmap(bitmap : integer) : integer


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

    function CreateMaskFromBitmap(Bitmap : integer) : TMask;


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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;


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


DrawBitmap
----------

.. code-block:: pascal

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

Draw the bitmap to a TCanvas.


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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


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

.. code-block:: pascal

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