Documentation: Add bitmaps references. (<3 vim)

Doc/sphinx/scriptref/bitmaps.rst

@@ -21,6 +21,7 @@ an 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,
@@ -79,6 +80,7 @@ then call this function to get the class reference.
 
     bmp.SetSize(150,150); // also changes bmph, as they are the same bitmap.
 
+.. _scriptref-createbitmapstring:
 
 CreateBitmapString
 ------------------
@@ -87,7 +89,11 @@ CreateBitmapString
 
     function CreateBitmapString(bmp : integer) : string;
 
-Creates a string for the given bitmap.
+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
 ------------
@@ -96,8 +102,10 @@ CreateBitmap
 
     function CreateBitmap(w,h :integer) : integer;
 
-Create a bitmap with width *h* and height *h*. Returns the bitmap reference.
+Create a bitmap with width *h* and height *h*.
+Returns the reference to the created bitmap.
 
+.. _scriptref-freebitmap:
 
 FreeBitmap
 ----------
@@ -111,6 +119,8 @@ 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
 ----------
 
@@ -120,7 +130,6 @@ SaveBitmap
 
 Save the given bitmap to the specified path.
 
-
 .. _scriptref-bitmapfromstring:
 
 BitmapFromString
@@ -133,7 +142,6 @@ BitmapFromString
 Load a bitmap from the given string. This command is usually generated with the
 Bitmap to String feature in Simba.
 
-
 .. _scriptref-loadbitmap:
 
 LoadBitmap
@@ -143,8 +151,10 @@ LoadBitmap
 
     function LoadBitmap(Path : string) : integer;
 
-Load a bitmap from a path to a file. Known formats are .bmp and .png. (Possibly
+Load a bitmap from a path to a file. Formats known to work are BMP and PNG
-others, don't know for sure)
+images.
+
+.. _scriptref-setbitmapsize:
 
 SetBitmapSize
 -------------
@@ -153,7 +163,12 @@ SetBitmapSize
 
     procedure SetBitmapSize(Bmp,NewW,NewH : integer);
 
-Change the size of the bitmap. Previous data will be preserved (if possible).
+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
 -------------
@@ -164,6 +179,8 @@ GetBitmapSize
 
 Returns the size of the bitmap in *BmpW*, *BmpH*.
 
+.. _scriptref-stretchbitmapresize:
+
 StretchBitmapResize
 -------------------
 
@@ -172,6 +189,8 @@ StretchBitmapResize
     procedure StretchBitmapResize(Bmp,NewW,NewH : integer);
 
 
+.. _scriptref-createmirroredbitmap:
+
 CreateMirroredBitmap
 --------------------
 
@@ -180,6 +199,8 @@ CreateMirroredBitmap
     function CreateMirroredBitmap(Bmp : integer) : integer;
 
 
+.. _scriptref-createmirroredbitmapex:
+
 CreateMirroredBitmapEx
 ----------------------
 
@@ -188,6 +209,8 @@ CreateMirroredBitmapEx
     function CreateMirroredBitmapEx(Bmp : integer; MirrorStyle : TBmpMirrorStyle) : integer;
 
 
+.. _scriptref-fastsetpixel:
+
 FastSetPixel
 ------------
 
@@ -197,6 +220,8 @@ FastSetPixel
 
 Set the pixel on the bitmap at position x, y to *color*.
 
+.. _scriptref-fastsetpixels:
+
 FastSetPixels
 -------------
 
@@ -206,6 +231,7 @@ FastSetPixels
 
 Set the pixels on the bitmap at position TPA[index] to Colors[index].
 
+.. _scriptref-fastgetpixel:
 
 FastGetPixel
 ------------
@@ -216,6 +242,8 @@ FastGetPixel
 
 Return the colour of pixel on the bitmap, position specified by x, y.
 
+.. _scriptref-fastgetpixels:
+
 FastGetPixels
 -------------
 
@@ -225,6 +253,7 @@ FastGetPixels
 
 Return an array of the colours on the bitmap; positions specified by *TPA*.
 
+.. _scriptref-getbitmapareacolors:
 
 GetBitmapAreaColors
 -------------------
@@ -236,6 +265,8 @@ GetBitmapAreaColors
 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
 -------------
 
@@ -245,6 +276,8 @@ FastDrawClear
 
 Draw *Color* on every pixel on the bitmap.
 
+.. _scriptref-fastdrawtransparent:
+
 FastDrawTransparent
 -------------------
 
@@ -253,6 +286,8 @@ FastDrawTransparent
     procedure FastDrawTransparent(x, y: Integer; SourceBitmap, TargetBitmap: Integer);
 
 
+.. _scriptref-setransparentcolor:
+
 SetTransparentColor
 -------------------
 
@@ -260,6 +295,7 @@ SetTransparentColor
 
     procedure SetTransparentColor(bmp : integer; Color : TColor);
 
+.. _scriptref-getransparentcolor:
 
 GetTransparentColor
 -------------------
@@ -268,6 +304,7 @@ GetTransparentColor
 
     function GetTransparentColor(bmp: integer) : TColor;
 
+.. _scriptref-fastreplacecolor:
 
 FastReplaceColor
 ----------------
@@ -276,6 +313,7 @@ FastReplaceColor
 
     procedure FastReplaceColor(Bmp : integer; OldColor,NewColor : TColor);
 
+.. _scriptref-copyclienttobitmap:
 
 CopyClientToBitmap
 ------------------
@@ -286,6 +324,8 @@ CopyClientToBitmap
 
 Copy client area *xs, ys, xe, ye* to specified bitmap.
 
+.. _scriptref-bitmapfromclient:
+
 BitmapFromClient
 ----------------
 
@@ -295,6 +335,8 @@ BitmapFromClient
 
 Create a bitmap from the client. Area specified by *xs, ye, xe, ye*.
 
+.. _scriptref-setbitmapname:
+
 SetBitmapName
 -------------
 
@@ -305,6 +347,20 @@ SetBitmapName
 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
 ----------
 
@@ -315,6 +371,8 @@ FindBitmap
 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
 ------------
 
@@ -327,6 +385,8 @@ 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
 ---------------------
 
@@ -340,6 +400,8 @@ Tolerance defines the tolerance per pixel when matching bitmaps. See
 Returns true if found. If found, *x, y* specifies the position where the bitmap
 was found.
 
+.. _scriptref-findbitmapspiral:
+
 FindBitmapSpiral
 ----------------
 
@@ -352,6 +414,8 @@ 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
 --------------------------
 
@@ -366,6 +430,8 @@ Tolerance defines the tolerance per pixel when matching bitmaps. See
 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
 -------------------------
 
@@ -380,6 +446,8 @@ 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
 ------------
 
@@ -388,6 +456,8 @@ RotateBitmap
     function RotateBitmap(bitmap: Integer; angle: Extended): Integer;
 
 
+.. _scriptref-desaturatebitmap:
+
 DesaturateBitmap
 ----------------
 
@@ -396,6 +466,8 @@ DesaturateBitmap
     function DesaturateBitmap(Bitmap : integer) : integer;
 
 
+.. _scriptref-invertbitmap:
+
 InvertBitmap
 ------------
 
@@ -404,6 +476,8 @@ InvertBitmap
     procedure InvertBitmap(Bitmap : integer);
 
 
+.. _scriptref-copybitmap:
+
 CopyBitmap
 ----------
 
@@ -413,6 +487,8 @@ CopyBitmap
 
 Creates a copy of the *Bitmap*. Returns the bitmap copy.
 
+.. _scriptref-greyscalebitmap:
+
 GreyScaleBitmap
 ---------------
 
@@ -422,6 +498,7 @@ GreyScaleBitmap
 
 Creates a copy of the bitmap, greyscaled.
 
+.. _scriptref-brightnessbitmap:
 
 BrightnessBitmap
 ----------------
@@ -436,6 +513,8 @@ 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
 --------------
 
@@ -446,6 +525,7 @@ ContrastBitmap
 Changes the constrast of a bitmap, returns a new bitmap with the contrast
 applied.
 
+.. _scriptref-posterizebitmap:
 
 PosterizeBitmap
 ---------------
@@ -477,6 +557,8 @@ Applying a filter on the current bitmap
         FreeBitmap(b);
     end.
 
+.. _scriptref-createmaskfrombitmap:
+
 CreateMaskFromBitmap
 --------------------
 
@@ -485,6 +567,8 @@ CreateMaskFromBitmap
     function CreateMaskFromBitmap(Bitmap : integer) : TMask;
 
 
+.. _scriptref-findmasktolerance:
+
 FindMaskTolerance
 -----------------
 
@@ -493,6 +577,8 @@ FindMaskTolerance
     function FindMaskTolerance(const mask: TMask; var x, y: Integer; xs,ys, xe, ye: Integer; Tolerance, ContourTolerance: Integer): Boolean;
 
 
+.. _scriptref-findbitmapmasktolerance:
+
 FindBitmapMaskTolerance
 -----------------------
 
@@ -501,6 +587,8 @@ FindBitmapMaskTolerance
     function FindBitmapMaskTolerance(mask: Integer; var x, y: Integer; xs, ys, xe, ye: Integer; Tolerance, ContourTolerance: Integer): Boolean;
 
 
+.. _scriptref-finddeformedbitmaptolerancein:
+
 FindDeformedBitmapToleranceIn
 -----------------------------
 
@@ -509,6 +597,8 @@ FindDeformedBitmapToleranceIn
     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
 -------------
 
@@ -520,6 +610,7 @@ DrawTPABitmap
 on the bitmap by setting the pixel on the bitmap (position defined by tpa point)
 to *color*.
 
+.. _scriptref-drawatpabitmap:
 
 DrawATPABitmap
 --------------
@@ -533,6 +624,8 @@ 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
 ----------------
 
@@ -545,6 +638,7 @@ 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
 ----------
@@ -555,6 +649,8 @@ DrawBitmap
 
 Draw the bitmap to a TCanvas.
 
+.. _scriptref-rectanglebitmap:
+
 RectangleBitmap
 ---------------
 
@@ -563,6 +659,8 @@ RectangleBitmap
     procedure RectangleBitmap(bitmap : integer; const box : TBox; Color : TColor);
 
 
+.. _scriptref-floodfillbitmap:
+
 FloodFillBitmap
 ---------------
 
@@ -571,6 +669,8 @@ FloodFillBitmap
     procedure FloodFillBitmap(bitmap : integer; const StartPoint : TPoint; const SearchCol,ReplaceCol : TColor);
 
 
+.. _scriptref-calculatepixelshift:
+
 CalculatePixelShift
 -------------------
 
@@ -579,6 +679,8 @@ CalculatePixelShift
     function CalculatePixelShift(Bmp1,Bmp2 : Integer; CompareBox : TBox) : integer;
 
 
+.. _scriptref-calculatepixeltolerance:
+
 CalculatePixelTolerance
 -----------------------
 
@@ -586,4 +688,3 @@ CalculatePixelTolerance
 
     function CalculatePixelTolerance(Bmp1,Bmp2 : Integer; CompareBox : TBox; CTS : integer) : extended;')
 
-