Bitmap objects

All routines from this chapter have been introduced.

Once you have selected a graphics mode, you can draw things onto the display via the `screen' bitmap. Screen bitmap can be accessed by passing nil. All the LuAllegro graphics routines draw onto AL_BITMAP userdata structures, which are areas of memory containing rectangular images, stored as packed byte arrays (in 8-bit modes one byte per pixel, in 15- and 16-bit modes two bytes per pixel, in 24-bit modes 3 bytes per pixel and in 32-bit modes 4 bytes per pixel). You can create and manipulate bitmaps in system RAM, or you can write to the special `screen' bitmap (which is nil) which represents the video memory in your graphics card.

Read chapter "Direct access to video memory" for information on how to get direct access to the image memory in a bitmap.

Allegro supports several different types of bitmaps:

extern BITMAP *screen;

Lua: nil


Global pointer to a bitmap, sized VIRTUAL_W x VIRTUAL_H. This is created by set_gfx_mode(), and represents the hardware video memory. Only a part of this bitmap will actually be visible, sized SCREEN_W x SCREEN_H. Normally this is the top left corner of the larger virtual screen, so you can ignore the extra invisible virtual size of the bitmap if you aren't interested in hardware scrolling or page flipping. To move the visible window to other parts of the screen bitmap, call scroll_screen(). Initially the clipping rectangle will be limited to the physical screen size, so if you want to draw onto a larger virtual screen space outside this rectangle, you will need to adjust the clipping.

For example, to draw a pixel onto the screen you would write:

      putpixel(screen, x, y, color);
      putpixel(nil, x, y, color);
or just:
      putpixel(x, y, color);
allegro.SCREEN_W( )

allegro.SCREEN_H( ) 

Functions that indicate the width and height of the screen, or zero if the screen has not been initialised yet. 


allegro.VIRTUAL_W( )

allegro.VIRTUAL_H( )

Functions that return the width and height of the virtual screen, or zero if the screen has not been initialised yet. 


width,height,bool cliping,x1,y1,x2,y2 = allegro.get_bitmap_info(AL_BITMAP bmp)

You will not find get_bitmap_info( ) in the Allegro library. I have introduced this function because there were no way to read width and height of an Allegro bitmap in Lua. In C you just write bitmap->w or bitmap->h and you just access these values, because bitmap is a struct under C.

Passing nil as bmp you ask about screen info.


userdata AL_BITMAP allegro.create_bitmap(width,height)

Creates a memory bitmap sized width by height. The bitmap will have clipping turned on, and the clipping rectangle set to the full size of the bitmap. The image memory will not be cleared, so it will probably contain garbage: you should clear the bitmap before using it. This routine always uses the global pixel format, as specified by calling allegro.set_color_depth(). The minimum height of the BITMAP must be 1 and width can't be negative. Example:
      --Create a 10 pixel tall bitmap, as wide as the screen.
      bmp = create_bitmap(SCREEN_W, 10);
      if not bmp then
         abort_on_error("Couldn't create bitmap!");
      -- Please notice that you don't call destroy_bitmap,
      --because garbage collection routine does it for you

Return value: Returns the created bitmap userdata, or nil if the bitmap could not be created. You don't have to remember to free this bitmap, because allegro garbage collection routine does it for you.


userdata AL_BITMAP allegro.create_bitmap_ex( color_depth , width , height )

Creates a bitmap in a specific color depth (8, 15, 16, 24 or 32 bits per pixel). 

Return value: Returns the created bitmap userdata, or nil if the bitmap could not be created. You don't have to remember to free this bitmap, because allegro garbage collection routine does it for you.


AL_BITMAP allegro.create_sub_bitmap(AL_BITMAP parent, x, y, width, height)

Creates a sub-bitmap, ie. a bitmap sharing drawing memory with a pre-existing bitmap, but possibly with a different size and clipping settings. When creating a sub-bitmap of the mode-X screen, the x position must be a multiple of four. The sub-bitmap width and height can extend beyond the right and bottom edges of the parent (they will be clipped), but the origin point must lie within the parent region.

Return value: Returns a pointer to the created sub bitmap, or NULL if the sub bitmap could not be created. Remember to free the sub bitmap before freeing the parent bitmap to avoid memory leaks and potential crashes accessing memory which has been freed.


AL_BITMAP allegro.create_video_bitmap( width , height )

Allocates a video memory bitmap of the specified size. This can be used to allocate offscreen video memory for storing source graphics ready for a hardware accelerated blitting operation, or to create multiple video memory pages which can then be displayed by calling allegro.show_video_bitmap(). 

Warning: video memory bitmaps are usually allocated from the same space as the screen bitmap, so they may overlap with it; it is therefore not a good idea to use the global screen at the same time as any surfaces returned by this function.

Return value: Returns the video bitmap userdata on success, or nil if you have run out of video ram. 

Remember to destroy this bitmap before any subsequent call to set_gfx_mode() - 

- that means remove any references to it and explicitly call collectgarbage().


AL_BITMAP allegro.create_system_bitmap(width,height)

Allocates a system memory bitmap of the specified size. Read the introduction of this chapter for a comparison with other types of bitmaps and other specific details.

Return value: Returns a pointer to the bitmap on success, NULL otherwise. Remember to destroy this bitmap before any subsequent call to set_gfx_mode( ).


destroy_bitmap(AL_BITMAP bitmap);

This routine is implemented as a part of LuAllegro garbage collection routine. Destroys a memory bitmap, sub-bitmap, video memory bitmap, or system bitmap when you are finished with it. You can't call this routine directly in LuAllegro. Garbage collection routine does this for you, when you don't have any references to the bitmap userdata.



allegro.lock_bitmap(AL_BITMAP bitmap)

Under DOS, locks all the memory used by a bitmap. You don't normally need to call this function unless you are doing very weird things in your program.

allegro.bitmap_color_depth(AL_BITMAP bmp)

Returns the color depth of the specified bitmap (8, 15, 16, 24, or 32). Example:
Convert example to Lua!!!:
      switch (bitmap_color_depth(screen)) {
         case 8:
            /* Access screen using optimized 8-bit code. */
            /* Use generic slow functions. */
allegro.bitmap_mask_color(AL_BITMAP bmp)

Returns the mask color for the specified bitmap (the value which is skipped when drawing sprites). For 256-color bitmaps this is zero, and for truecolor bitmaps it is bright pink (maximum red and blue, zero green). A frequent use of this function is to clear a bitmap with the mask color so you can later use this bitmap with masked_blit() or draw_sprite() after drawing other stuff on it. Example:
Convert example to Lua!!!:
      /* Replace mask color with another color. */
      for (y = 0; y < bmp->h; y++)
         for (x = 0; x < bmp->w; x++)
            if (getpixel(bmp, x, y) == bitmap_mask_color(bmp))
               putpixel(bmp, x, y, another_color);
See also: MASK_COLOR_8, set_color_depth, bitmap_color_depth.
bool allegro.is_same_bitmap(AL_BITMAP bmp1,AL_BITMAP bmp2)

Returns TRUE if the two bitmaps describe the same drawing surface, ie. the pointers are equal, one is a sub-bitmap of the other, or they are both sub-bitmaps of a common parent.
bool allegro.is_planar_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is a planar (mode-X or Xtended mode) screen bitmap.


bool allegro.is_linear_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is a linear bitmap, i.e. a bitmap that can be accessed linearly within each scanline (for example a memory bitmap, the DOS VGA or SVGA screen, Windows bitmaps, etc). Linear bitmaps can be used with the _putpixel(), _getpixel(), bmp_write_line(), and bmp_read_line() functions.

Historically there were only linear and planar bitmaps for Allegro, so is_linear_bitmap() is actually an alias for !is_planar_bitmap().

See also: is_planar_bitmap, is_memory_bitmap.
bool allegro.is_memory_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is a memory bitmap, ie. it was created by calling create_bitmap() or loaded from a grabber datafile or image file. Memory bitmaps can be accessed directly via the line pointers in the bitmap structure, eg. bmp->line[y][x] = color.
See also: is_linear_bitmap, is_planar_bitmap.
bool allegro.is_screen_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is the screen bitmap, or a sub-bitmap of the screen.
See also: screen, create_sub_bitmap.
bool allegro..is_video_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is the screen bitmap, a video memory bitmap, or a sub-bitmap of either.
See also: screen, create_video_bitmap, create_sub_bitmap.
bool allegro.is_system_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is a system bitmap object, or a sub-bitmap of one.
See also: create_system_bitmap, create_sub_bitmap.
bool is_sub_bitmap(AL_BITMAP bmp)

Returns TRUE if bmp is a sub-bitmap.
See also: create_sub_bitmap.
allegro.acquire_bitmap(AL_BITMAP bmp)

Locks the specified video memory bitmap prior to drawing onto it. This does not apply to memory bitmaps, and only affects some platforms (Windows needs it, DOS does not). These calls are not strictly required, because the drawing routines will automatically acquire the bitmap before accessing it, but locking a DirectDraw surface is very slow, so you will get much better performance if you acquire the screen just once at the start of your main redraw function, and only release it when the drawing is completely finished. Multiple acquire calls may be nested, and the bitmap will only be truly released when the lock count returns to zero. Be warned that DirectX programs activate a mutex lock whenever a surface is locked, which prevents them from getting any input messages, so you must be sure to release all your bitmaps before using any timer, keyboard, or other non-graphics routines!

Note that if you are using hardware accelerated VRAM->VRAM blits, you should not call acquire_bitmap().

See also: release_bitmap, acquire_screen, release_screen.
allegro.release_bitmap(AL_BITMAP bmp)

Releases a bitmap that was previously locked by calling acquire_bitmap(). If the bitmap was locked multiple times, you must release it the same number of times before it will truly be unlocked.
See also: acquire_bitmap, acquire_screen, release_screen.
allegro.acquire_screen( )

Shortcut version of acquire_bitmap(screen);
See also: acquire_bitmap, release_bitmap, release_screen.
allegro.release_screen( )

Shortcut version of release_bitmap(screen);
See also: acquire_bitmap, release_bitmap, acquire_screen.
allegro.set_clip_rect(AL_BITMAP bitmap, x1, y1, x2, y2)

Each bitmap has an associated clipping rectangle, which is the area of the image that it is ok to draw onto. Nothing will be drawn to positions outside this space. This function sets the clipping rectangle for the specified bitmap. Pass the coordinates of the top-left and bottom-right corners of the clipping rectangle in this order; these are both inclusive, i.e. set_clip_rect(bitmap, 16, 16, 32, 32) will allow drawing to (16, 16) and (32, 32), but not to (15, 15) and (33, 33).

Drawing operations will be performed (at least partially) on the bitmap as long as the first coordinates of its clipping rectangle are not greater than the second coordinates and its intersection with the actual image is non-empty. If either condition is not fulfilled, drawing will be turned off for the bitmap, e.g.

      set_clip_rect(bmp, 0, 0, -1, -1); /* disable drawing on bmp */

Note that passing "out-of-bitmap" coordinates is allowed, but they are likely to be altered (and so the coordinates returned by get_clip_rect() will be different). However, such modifications are guaranteed to preserve the external effect of the clipping rectangle, that is not to modify the actual area of the image that it is ok to draw onto.

See also: get_clip_rect, add_clip_rect, set_clip_state, get_clip_state.
x1,y1,x2,y2 = allegro.get_clip_rect(AL_BITMAP bitmap)

Returns the clipping rectangle for the specified bitmap.
See also: set_clip_rect, add_clip_rect, set_clip_state, get_clip_state.
allegro.add_clip_rect(AL_BITMAP bitmap, x1, y1, x2, y2)

Sets the clipping rectangle of the specified bitmap as the intersection of its current clipping rectangle and the rectangle described by the four coordinates.
See also: set_clip_rect, get_clip_rect, set_clip_state, get_clip_state.
allegro.set_clip_state(AL_BITMAP bitmap,bool state)

Turns on (if state is true) or off (if state is false) clipping for the specified bitmap. Turning clipping off may slightly speed up some drawing operations (usually a negligible difference, although every little helps) but will result in your program dying a horrible death if you try to draw beyond the edges of the bitmap.
See also: set_clip_rect, get_clip_rect, add_clip_rect, get_clip_state.
bool allegro.get_clip_state(AL_BITMAP bitmap)

Returns non-zero if clipping is turned on for the specified bitmap and zero otherwise.
See also: set_clip_rect, get_clip_rect, add_clip_rect, set_clip_state.
bool allegro.is_inside_bitmap(AL_BITMAP bmp, x, y, bool clip)

Returns non-zero if point (x, y) lies inside the bitmap. If `clip' is true, the function compares the coordinates with the clipping rectangle, that is it returns non-zero if the point lies inside the clipping rectangle or if clipping is disabled for the bitmap. If `clip' is false, the function compares the coordinates with the actual dimensions of the bitmap.
See also: set_clip_rect, set_clip_state, getpixel.

Go to main page