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

FreeBSD Manual Pages


home | help
al_load_bitmap_flags(3)				       al_load_bitmap_flags(3)

       al_load_bitmap_flags - Allegro 5	API

	      #include <allegro5/allegro.h>

	      ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)

       Loads an	image file into	a new ALLEGRO_BITMAP(3).  The file type	is de-
       termined	by the extension, except if the	file has no extension in which
       case al_identify_bitmap(3) is used instead.

       Returns NULL on error.

       The flags parameter may be a combination	of the following constants:

	      By default, Allegro pre-multiplies the alpha channel of an image
	      with the images color data when it  loads	 it.   Typically  that
	      would look something like	this:

		     r = get_float_byte();
		     g = get_float_byte();
		     b = get_float_byte();
		     a = get_float_byte();

		     r = r * a;
		     g = g * a;
		     b = b * a;

		     set_image_pixel(x,	y, r, g, b, a);

	      The reason for this can be seen in the Allegro example ex_premu-
	      lalpha, ie, using	pre-multiplied alpha gives more	accurate color
	      results in some cases.  To use alpha blending with images	loaded
	      with pre-multiplied alpha, you would use	the  default  blending
	      mode, which is set with al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE,

	      The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being  set  will	ensure
	      that  images  are	 not loaded with alpha pre-multiplied, but are
	      loaded with color	values direct from the image.  That looks like

		     r = get_float_byte();
		     g = get_float_byte();
		     b = get_float_byte();
		     a = get_float_byte();

		     set_image_pixel(x,	y, r, g, b, a);

	      To  draw	such  an image using regular alpha blending, you would
	      use   al_set_blender(ALLEGRO_ADD,	  ALLEGRO_ALPHA,   ALLEGRO_IN-
	      VERSE_ALPHA) to set the correct blender.	This has some caveats.
	      First, as	mentioned above, drawing such an image can  result  in
	      less  accurate color blending (when drawing an image with	linear
	      filtering	on, the	edges will be darker  than  they  should  be).
	      Second,  the behaviour is	somewhat confusing, which is explained
	      in the example below.

		     //	Load and create	bitmaps	with an	alpha channel
		     //	Load some bitmap with alpha in it
		     bmp = al_load_bitmap("some_alpha_bitmap.png");
		     //	We will	draw to	this buffer and	then draw this buffer to the screen
		     tmp_buffer	= al_create_bitmap(SCREEN_W, SCREEN_H);
		     //	Set the	buffer as the target and clear it
		     al_clear_to_color(al_map_rgba_f(0,	0, 0, 1));
		     //	Draw the bitmap	to the temporary buffer
		     al_draw_bitmap(bmp, 0, 0, 0);
		     //	Finally, draw the buffer to the	screen
		     //	The output will	look incorrect (may take close inspection
		     //	depending on the bitmap	-- it may also be very obvious)
		     al_draw_bitmap(tmp_buffer,	0, 0, 0);

	      To explain further, if you have a	 pixel	with  0.5  alpha,  and
	      for blending, the	formula	is:

		     a = da * dst + sa * src

	      Expands to:

		     result_a =	dst_a *	(1-0.5)	+ 0.5 *	0.5

	      So if you	draw the image to the temporary	buffer,	it is  blended
	      once  resulting  in  0.75	alpha, then drawn again	to the screen,
	      blended in the same way, resulting in a pixel has	0.1875	as  an
	      alpha value.

	      Load the palette indices of 8-bit	.bmp and .pcx files instead of
	      the rgb colors.  Since 5.1.0.

	      Force the	resulting ALLEGRO_BITMAP(3) to use the same format  as
	      the file.

	      This is not yet honoured.

	      Note:  the  core Allegro library does not	support	any image file
	      formats by default.  You must use	the  allegro_image  addon,  or
	      register your own	format handler.



Allegro	reference manual			       al_load_bitmap_flags(3)


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

home | help