Simba/trunk/Doc/bitmap documentation

Bitmaps

For the bitmap implantation we can distinguish roughly two different objects. The bitmap manager and the bitmap itself. The bitmap manager is a class that manages multiple bitmaps, later more about this.

The bitmap
When using Lazarus you will run into some compatibility issues when working with the normal TBitmap class. Therefore we decided to make our bitmap class: TMufasaBitmap. The aim of this class is to be fast and be able to run on Linux&Windows. 
The image-data (32 bits) is stored in the FData property, an array of TRGB32. TRGB32 is a record with 4 members: B,G,R,A : byte. 32 Bits bitmaps have the advantage that their memory is better aligned (4-bytes), so easier accessible. As you can directly access the rawdata, bitmap functions will be fast and easy to use. Since the data is stored as an array you need to do convert your coordinate into a array-index using the following transformation: (x,y) -> y * w(width of the bitmap) + x.
For example we want to change pixel (5,20) to clWhite and our bitmaps width = 50:
Bitmap.FData[20 * 50 + 5].r := 255;
Bitmap.FData[20 * 50 + 5].g := 255;
Bitmap.FData[20 * 50 + 5].b := 255;
or 
With  Bitmap.FData[20 * 50 + 5] do
begin;
  r:= 255;g:= 255;b:= 255;
end;

Also you can name a bitmap by setting the BmpName property. This may come in handy when handling multiple bitmaps (later more about this). A brief explanation of certain functions and there behaviour:
LoadFromFile/SaveToFile
Does, as the title says, loads or saves a bitmap. It should be able to load/save most of the standard extensions (bmp,png,jpg)
Width/Height
These are read-only properties, they return the bitmap width/height
SetSize
Use this to change the width&height of the bitmap. It kind-of crops the old image (if there was any). So if you make your bitmap bigger, you would get the old bitmap with a black border. If you would make your bitmap smaller, you would get only a part of the original bitmap.
ValidatePoint
Checks whether the point(x,y) is on the bitmap, if not throws an exception
TransparentColor
When using FindBitmap, the TransparentColor is used. If it hasn't been set yet, clBlack is used instead. Transparent color means every pixel with that color isn't checked in finding procedures. Also if set, it's used in FastDraw functions
CreateTMask
It creates a TMask from the bitmap, it doesn't check whether the bitmap actually is a mask, so be sure when to use this. (It checks if the red = 255, and then assumes the pixel is a white pixel, otherwise it assumes its black).
TheRest
Most of these functions speak for themselves. If it has the parameter TargetBitmap, it assumes this bitmap is already created.

TMBitmaps
If you need to manage multiple bitmaps, like scripts do, you can make use of the bitmap manager TMBitmaps. It takes care of your bitmaps, returns a new one when you need it, lets you free the bitmaps, and makes sure there aren't any unfreed bitmaps left.

CreateBMP
Creates a new bitmap with size w,h. Then returns you the index of this bitmap in the manager, use this index to retrieve the bitmap later.

Bmp[Index]/GetBMP
Gets the TMufasaBitmap stored at the index, checks if the bitmap exists, throws an exception otherwise

CreateBMPFromString
Creates a bmp based on a string. The string would be made like this:
1) Make a string with the following format: RGBRGBRGB; Where every RGB represents a pixel of the bitmap
2) Compress it with zLib, store the width/height of the bitmap
3) Encode it with base64, so that it doesn't have unreadable characters and can be freely spread over the internet.

CreateMirroredBitmap
Creates a copy of the bitmap, but mirrored with one of the mirror styles:
MirrorWidth: Mirror in the Y-axis
MirrorHeight: Mirror in the X-axis
MirrorLine: Mirror in the line y=x

Destroy
If you destroy the bitmap manager, it goes through every bitmap to check whether its freed or not, if not it will mention the BitmapName (if not set the bitmap index).