Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
al_create_bitmap(3)					   al_create_bitmap(3)

       al_create_bitmap	- Allegro 5 API

	      #include <allegro5/allegro.h>

	      ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

       Creates	a new bitmap using the bitmap format and flags for the current
       thread.	Blitting between bitmaps of differing formats, or blitting be-
       tween memory bitmaps and	display	bitmaps	may be slow.

       Unless  you  set	 the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created
       for the current display.	 Blitting to another display may be slow.

       If a display bitmap is created, there may be limitations	on the allowed
       dimensions.  For	example	a DirectX or OpenGL backend usually has	a max-
       imum allowed texture size - so if bitmap	creation fails for very	 large
       dimensions,  you	 may want to re-try with a smaller bitmap.  Some plat-
       forms also dictate a minimum texture size, which	 is  relevant  if  you
       plan  to	use this bitmap	with the primitives addon.  If you try to cre-
       ate a bitmap smaller than this, this call will not  fail	 but  the  re-
       turned  bitmap  will  be	 a section of a	larger bitmap with the minimum
       size.  The minimum size that will work on all platforms is  32  by  32.
       There  is  an  experimental switch to turns this	padding	off by editing
       the system configuration	(see min_bitmap_size key in al_get_system_con-

       Some platforms do not directly support display bitmaps whose dimensions
       are not powers of two.  Allegro handles this by creating	a larger  bit-
       map  that  has  dimensions  that	are powers of two and then returning a
       section of that bitmap with the dimensions you requested.  This can  be
       relevant	 if  you plan to use this bitmap with the primitives addon but
       shouldn't be an issue otherwise.

       If you create a bitmap without ALLEGRO_MEMORY_BITMAP set	but  there  is
       no  current display, a temporary	memory bitmap will be created instead.
       You can later convert all such bitmap to	video bitmap and assign	 to  a
       display by calling al_convert_memory_bitmaps(3).

       On  some	 platforms the contents	of video bitmaps may be	lost when your
       application loses focus.	 Allegro has an	internal mechanism to  restore
       the contents of these video bitmaps, but	it is not foolproof (sometimes
       bitmap contents can get lost permanently) and has performance  implica-
       tions.  If you are using	a bitmap as an intermediate buffer this	mecha-
       nism may	be wasteful.  In this case, if you do not want Allegro to man-
       age the bitmap contents for you,	you can	disable	this mechanism by cre-
       ating the bitmap	with the ALLEGRO_NO_PRESERVE_TEXTURE flag.  The	bitmap
       contents	are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLE-
       GRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored	when  you  get
       the  ALLEGRO_EVENT_DISPLAY_FOUND	and when you call al_acknowledge_draw-
       ing_resume(3) (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event).   You
       can  use	 those events to implement your	own bitmap content restoration
       mechanism if Allegro's does not work well enough	for you	(for  example,
       you can reload them all from disk).

       Note:  The  contents of a newly created bitmap are undefined - you need
       to clear	the bitmap or make sure	 all  pixels  get  overwritten	before
       drawing it.

       When  you  are done with	using the bitmap you must call al_destroy_bit-
       map(3) on it to free any	resources allocated for	it.

       al_set_new_bitmap_format(3), al_set_new_bitmap_flags(3),	 al_clone_bit-
       map(3),	al_create_sub_bitmap(3),  al_convert_memory_bitmaps(3),	al_de-

Allegro	reference manual				   al_create_bitmap(3)


Want to link to this manual page? Use this URL:

home | help