Tutorials

h1. Common bitmap manipulations in Scol

In the standard API, a bitmap is an Scol object with an opaque type *ObjBitmap*. You can not modify directly its structure.

These objects are rather heavy. Available functions are documented in this "section":http://www.scolring.org/files/doc_html/bitmap.html.

When we create or load a bitmap, it is loaded in memory until it is destroyed. Thus, destroy it when we no longer need it.

h2. Create and destroy

To create a bitmap object, you can load a graphic resource (jpeg, targa or bmp formats only) or create it ex nihilo.

All these functions return an bitmap object, except the destruction function.

h3. Load from a graphic resource

Supported formats are bmp, jpeg and targa only. For the png format, see [[Common AlphaBitmap manipulations in Scol]].

h4. BMP format :

*_LDbitmap* : @<channel> <reference_graphic_file>@

<pre>

tyepof bmp = ObjBitmap;;

...

set bmp = _LDbitmap _channel _checkpack "dir_1/dir_2/file.bmp";

</pre>

h4. JPEG format

*_LDjpeg* : @<channel> <reference_graphic_file>@

<pre>

tyepof jpeg = ObjBitmap;;

...

set jpeg = _LDjpeg _channel _checkpack "dir_1/dir_2/file.jpg";

</pre>

h4. TARGA format

*_LDtga* : @<channel> <reference_graphic_file>@

<pre>

tyepof tga = ObjBitmap;;

...

set tga = _LDtga _channel _checkpack "dir_1/dir_2/file.tga";

</pre>

h3. Create an ObjBitmap

Pratically, we initialize the object with the Scol function *_CRbitmap* : @_CRbitmap <channel> <width> <height>@

Next, but this is optional, we fill it with a color : *_FILLbitmap* : @_FILLbitmap <bitmap_object> <color_24bits>@

<pre>typeof bmp = ObjBitmap;;

...

set bmp = _FILLbitmap _CRbitmap _channel 320 240 0x777777;</pre>

h3. Destroy an ObjBitmap

*_DSbitmap* : @_DSbitmap <bitmap_object>@

If the bitmap object is a global variable, we should always set it to nil after the destruction. Indeed, the value can keep in the undefined state.

h3. Example

We load the Scol logo (line 1) in the current channel. Next, we get its width (line 2) and we write its value in the console.

Then, we destroy the bitmap (line 3) and we set the variable to nil (line 4). In the rest of code (lines N), it is very judicious to verify always if the object is at nil (or not) before perform any transformations/manipulations.

<pre>

typeof bitmap = ObjBitmap;;

fun main ()=

    _showconsole;

    set bitmap = _LDbitmap _channel "logo.bmp"; // line 1

    let _GETbitmapSize bitmap -> [width _] in   // line 2

    _fooId width;    // 64

    _DSbitmap bitmap;                           // line 3

    set bitmap = nil;                           // line 4

    // do anything                              // lines N

    0;;

</pre>

h2. Other examples

h3. Create, copy, draw and save a bitmap

This example shows some common bitmap's manipulations : creation, load, copy, draw, blur, etc ...

<pre>

fun transform (bmp)=

	// retrieve the size of the bitmap

	let _GETbitmapSize bmp -> [width height] in

	// load the Scol logo

	let _LDbitmap _channel _checkpack "logo.bmp" -> logo in

	// create a font-reference from Arial. With 1800, the string will displayed upside down

	let _CRfont _channel 24 1800 FF_WEIGHT "Arial" -> font in

	(

	// draw a blue rectangle inside our bitmap. The border has a width of 4 pixels

	_DRAWrectangle bmp 25 25 width-50 height-50 DRAW_SOLID 4 0xdd4444 DRAW_INVISIBLE 0;

	// copy the logo at the top left corner of the rectangle with a transparency color (here, white)

	_CPbitmap24 bmp 10 10 logo 0 0 64 64 0xFFFFFF;

	// draw a red circle at the center of the bitmap

	_DRAWcircle bmp width/2 height/2 200 DRAW_SOLID 2 0x4444dd DRAW_INVISIBLE 0;

	// draw a gradent inside a second rectangle

	_DRAWgradient bmp (width/2)-100 (height/2)-100 200 200 0x00FF00 0x006600 90;

	// Write a string at the center of the bitmap

	_DRAWtext bmp font width/2 height/2 TD_CENTER|TD_BASELINE 0xDddDdd "Hello wolrd !";

	// copy the logo at the bottom right corner of the rectangle without a transparency color

	_CPbitmap24 bmp width-74 height-74 logo 0 0 64 64 nil;

	// process a gaussian blur on a second logo

	_BLURbitmap bmp width-74 height-74 64 64 10 5;

	// destroy the font, no longer needed

	_DSfont font;

	0

	);;

fun main ()=

	_showconsole;

	// create an empty bitmap with a given size (500 x 500 pixels)

	let _CRbitmap _channel 500 500 -> bmp in

	(

	// paint the bitmap in white

	_FILLbitmap bmp 0xFFFFFF;

	// call the function to transform our bitmap

	transform bmp;

	// save the result in a jpg file

	_SAVEjpeg bmp _getmodifypack "examples/bitmap/transformation.jpg" 85;

	// end

	_DSbitmap bmp; // don't forget to destroy the bitmap at the end

	_fooS "Done !";

	0

	);;

</pre>

h3. Colorize a bitmap pixel by pixel

<pre>

typeof window = ObjWin;;

typeof bmp = ObjBitmap;;

/*

	Set the color for each pixel.

	If the pixel is in the lower left half, its color is black. Otherwise, its color is random.

	Prototype : fun [I I I I] I

*/

fun bypixel (x, y, width, height)=

    if x >= width then

    (

        set x = 0;

        set y = y+1

    )

    else

        0;

    if y >= height then

        0    // end !

    else

        let if x < y*2 then 0x000000 else (mod rand 512) * (mod rand 0xFFFFFF) -> color in

        (

        _PUTpixel24 bmp x y color;

        _PAINTwindow window;

        bypixel x+1 y width height

        );;

/*

	Paint the main window : the bitmap is displayed inside it

	Prototype : fun [ObjWin I] I

*/

fun CBpaint (win, user_parameter)=

    _BLTbitmap window bmp 0 0;

    0;;

fun CBend (win, user_parameter)=

    _DSbitmap bmp;  // we destroy the bitmap object

    _closemachine;; // we exit the program

fun main ()=

    _showconsole;

    srand (time); // initialize random

    // create and fill a bitmap

    set bmp = _FILLbitmap _CRbitmap _channel 200 100 0xFFFFFF;

    // create a window

    set window = _CRwindow _channel nil 0 0 200 130 WN_MENU "Bitmaps > Bypixels";

    _CBwinDestroy window @CBend 0;

    _CBwinPaint window @CBpaint 0;

    // call the function to set each pixel color

    bypixel 0 0 200 100;

    _fooS "Done !";

    0;;

</pre>