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

FreeBSD Manual Pages


home | help
al_set_new_bitmap_flags(3)			    al_set_new_bitmap_flags(3)

       al_set_new_bitmap_flags - Allegro 5 API

	      #include <allegro5/allegro.h>

	      void al_set_new_bitmap_flags(int flags)

       Sets the	flags to use for newly created bitmaps.	 Valid flags are:

	      Creates  a  bitmap that resides in the video card	memory.	 These
	      types of bitmaps receive the greatest benefit from hardware  ac-
	      celeration.  al_set_new_bitmap_flags(3) will implicitly set this
	      flag unless ALLEGRO_MEMORY_BITMAP	is present.

	      Create a bitmap residing in system memory.  Operations  on,  and
	      with, memory bitmaps will	not be hardware	accelerated.  However,
	      direct pixel access can be relatively quick  compared  to	 video
	      bitmaps, which depend on the display driver in use.

	      Note:  Allegro's	software rendering routines are	currently very

	      Only used	when loading bitmaps from disk files, forces  the  re-
	      sulting ALLEGRO_BITMAP(3)	to use the same	format as the file.

	      This is not yet honoured.

	      When  drawing  to	 a bitmap with this flag set, always use pixel
	      locking and draw to it using Allegro's software  drawing	primi-
	      tives.   This  should  never  be used if you plan	to draw	to the
	      bitmap using Allegro's graphics primitives as it would cause se-
	      vere performance penalties.  However if you know that the	bitmap
	      will only	ever be	accessed by locking it,	no unneeded FBOs  will
	      be created for it	in the OpenGL drivers.

	      Normally,	every effort is	taken to preserve the contents of bit-
	      maps, since Direct3D may forget them.  This can take extra  pro-
	      cessing  time.   If you know it doesn't matter if	a bitmap keeps
	      its pixel	data, for example its a	 temporary  buffer,  use  this
	      flag  to	tell  Allegro not to attempt to	preserve its contents.
	      This can increase	performance of your game or  application,  but
	      there  is	 a  catch.  See	ALLEGRO_EVENT_DISPLAY_LOST for further

	      This is a	driver hint only.  It tells the	graphics driver	to  do
	      alpha  testing instead of	alpha blending on bitmaps created with
	      this flag.  Alpha	testing	is usually  faster  and	 preferred  if
	      your  bitmaps  have  only	 one level of alpha (0).  This flag is
	      currently	not widely implemented (i.e.,  only  for  memory  bit-

	      When  drawing  a	scaled	down version of	the bitmap, use	linear
	      filtering.  This usually looks better.  You can also combine  it
	      with the MIPMAP flag for even better quality.

	      When drawing a magnified version of a bitmap, use	linear filter-
	      ing.  This will cause the	picture	to get blurry instead of  cre-
	      ating  a	big  rectangle	for each pixel.	 It depends on how you
	      want things to look like whether you want	to use this or not.

	      This can only be used for	bitmaps	whose width and	 height	 is  a
	      power  of	 two.	In that	case, it will generate mipmaps and use
	      them when	drawing	scaled down versions.  For example if the bit-
	      map  is  64x64,  then  extra bitmaps of sizes 32x32, 16x16, 8x8,
	      4x4, 2x2 and 1x1 will be created always containing a scaled down
	      version of the original.

	      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 you're  us-
       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.

       al_get_new_bitmap_flags(3), al_get_bitmap_flags(3)

Allegro	reference manual			    al_set_new_bitmap_flags(3)


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

home | help