Once you have selected a graphics mode, you can draw things onto the display via the `screen' bitmap. All the Allegro graphics routines draw onto BITMAP 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 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:
For example, to draw a pixel onto the screen you would write:
Or to implement a double-buffered system:putpixel(screen, x, y, color);
/* Make a bitmap in RAM. */ BITMAP *bmp = create_bitmap(320, 200); /* Clean the memory bitmap. */ clear_bitmap(bmp); /* Draw onto the memory bitmap. */ putpixel(bmp, x, y, color); /* Copy it to the screen. */ blit(bmp, screen, 0, 0, 0, 0, 320, 200);
Warning: be very careful when using this pointer at the same time as any bitmaps created by the create_video_bitmap() function (see the description of this function for more detailed information). And never try to destroy it with destroy_bitmap().
See also: set_gfx_mode, is_screen_bitmap, create_video_bitmap, scroll_screen.
Examples using this: Available Allegro examples.
char buf[100]; ... uszprintf(buf, sizeof(buf), "The screen size is %d x %d pixels", SCREEN_W, SCREEN_H);
See also: screen, set_gfx_mode, VIRTUAL_W, VIRTUAL_H.
Examples using this: Available Allegro examples.
char buf[100]; ... uszprintf(buf, sizeof(buf), "The virtual screen size is %d x %d pixels", SCREEN_W, SCREEN_H);
See also: screen, set_gfx_mode, SCREEN_W, SCREEN_H.
/* Create a 10 pixel tall bitmap, as wide as the screen. */ BITMAP *bmp = create_bitmap(SCREEN_W, 10); if (!bmp) abort_on_error("Couldn't create bitmap!"); /* Use the bitmap. */ ... /* Destroy it when we don't need it any more. */ destroy_bitmap(bmp);
Return value: Returns a pointer to the created bitmap, or NULL if the bitmap could not be created. Remember to free this bitmap later to avoid memory leaks.
See also: create_bitmap_ex, create_sub_bitmap, create_video_bitmap, create_system_bitmap, destroy_bitmap, set_color_depth, is_memory_bitmap, clear_bitmap, clear_to_color.
Examples using this: Available Allegro examples.
/* Create screen sized bitmap in 32 bits per pixel. */ BITMAP *bmp = create_bitmap_ex(32, SCREEN_W, SCREEN_H); if (!bmp) abort_on_error("Couldn't create bitmap!"); /* Use the bitmap. */ ... /* Destroy it when we don't need it any more. */ destroy_bitmap(bmp);
Return value: Returns a pointer to the created bitmap, or NULL if the bitmap could not be created. Remember to free this bitmap later to avoid memory leaks.
See also: create_bitmap, create_sub_bitmap, create_video_bitmap, create_system_bitmap, destroy_bitmap, is_memory_bitmap, clear_bitmap, clear_to_color.
Examples using this: ex12bit, exlights, exrgbhsv, extrans.
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.
See also: create_bitmap, create_bitmap_ex, destroy_bitmap, is_sub_bitmap, clear_bitmap, clear_to_color.
Examples using this: expat, exscroll, exswitch.
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 a pointer to the bitmap on success, or NULL if you have run out of video ram. Remember to destroy this bitmap before any subsequent call to set_gfx_mode().
See also: create_bitmap, create_bitmap_ex, create_system_bitmap, create_sub_bitmap, destroy_bitmap, screen, show_video_bitmap, gfx_capabilities, is_video_bitmap, clear_bitmap, clear_to_color.
Examples using this: ex3buf, exaccel, exflip, exupdate.
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().
See also: create_bitmap, create_bitmap_ex, create_video_bitmap, create_sub_bitmap, destroy_bitmap, is_system_bitmap, clear_bitmap, clear_to_color.
Examples using this: exupdate.
The bitmap must not have a mouse cursor shown on it at the time it is destroyed.
See also: create_bitmap, load_bitmap, show_mouse.
Examples using this: Available Allegro examples.
switch (bitmap_color_depth(screen)) { case 8: /* Access screen using optimized 8-bit code. */ break; default: /* Use generic slow functions. */ break; }
See also: set_color_depth, bitmap_mask_color.
Examples using this: ex3d, exlights, exscn3d, exswitch, extrans, exupdate, exzbuf.
/* 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.
Examples using this: ex3d, exmouse, expat.
See also: create_sub_bitmap.
See also: is_linear_bitmap, is_memory_bitmap.
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.
See also: is_linear_bitmap, is_planar_bitmap.
See also: screen, create_sub_bitmap.
See also: screen, create_video_bitmap, create_sub_bitmap.
See also: create_system_bitmap, create_sub_bitmap.
See also: create_sub_bitmap.
Note: You do never need to use acquire_bitmap on a memory bitmap, i.e. a normal bitmap created with create_bitmap. It will simply do nothing in that case.
It still can be useful, because e.g. under the current DirectDraw driver of Allegro, most drawing functions need to lock a video bitmap before drawing to it. But doing this 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, then call multiple drawing operations which need the bitmap locked, and only release it when done.
Multiple acquire calls may be nested, but you must make sure to match up the acquire_bitmap and release_bitmap calls. Be warned that DirectX and X11 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 functions, you should not call acquire_bitmap(). Such functions need an unlocked target bitmap under DirectX, so there is now just the opposite case from before - if the bitmap is already locked with acquire_bitmap, the drawing operation has to unlock it.
Note: For backwards compatibility, the unlocking behavior of such functions is permanent. That is, if you call acquire_bitmap first, then call e.g. an accelerated blit, the DirectX bitmap will be unlocked internally (it won't affect the nesting counter of acquire/release calls).
There is no clear cross-platform way in this Allegro version to know which drawing operations need a locked/unlocked state. For example a normal rectfill most probably is accelerated under DirectX, and therefore needs the screen unlocked, but an XOR rectfill, or one with blending activated, most probably is not, and therefore locks the screen. And while the DirectX driver will do automatic unlocking, there is no such thing under X11, where the function is used to synchronize X11 calls from different threads. Your best bet is to never use acquire_bitmap - changes are you are doing something in the wrong way if you think you need it.
Warning: This function can be very dangerous to use, since the whole program may get locked while the bitmap is locked. So the lock should only be held for a short time, and you should not call anything but drawing operations onto the locked video bitmap while a lock is in place. Especially don't call things like show_mouse (or scare_mouse which calls that) or readkey, since it will most likely deadlock your entire program.
See also: release_bitmap, acquire_screen, release_screen.
Examples using this: ex3buf, exaccel, expat, exquat, exscroll, exswitch, exupdate.
See also: acquire_bitmap, acquire_screen, release_screen.
Examples using this: ex3buf, exaccel, expat, exquat, exscroll, exswitch, exupdate.
See also: acquire_bitmap, release_bitmap, release_screen.
Examples using this: Available Allegro examples.
See also: acquire_bitmap, release_bitmap, acquire_screen.
Examples using this: Available Allegro examples.
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.
Examples using this: ex12bit, excamera.
See also: set_clip_rect, add_clip_rect, set_clip_state, get_clip_state.
See also: set_clip_rect, get_clip_rect, set_clip_state, get_clip_state.
See also: set_clip_rect, get_clip_rect, add_clip_rect, get_clip_state.
See also: set_clip_rect, get_clip_rect, add_clip_rect, set_clip_state.
See also: set_clip_rect, set_clip_state, getpixel.