Provided by: allegro5-doc_5.0.10-2_all bug

NAME

       al_set_new_bitmap_flags - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

              void al_set_new_bitmap_flags(int flags)

DESCRIPTION

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

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

       ALLEGRO_MEMORY_BITMAP
              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 unoptimised.

       ALLEGRO_KEEP_BITMAP_FORMAT
              Only  used  when  loading  bitmaps  from   disk   files,   forces   the   resulting
              ALLEGRO_BITMAP(3alleg5) to use the same format as the file.

              This is not yet honoured.

       ALLEGRO_FORCE_LOCKING
              When  drawing  to a bitmap with this flag set, always use pixel locking and draw to
              it using Allegro's software drawing primitives.  This should never be used  if  you
              plan  to  draw  to the bitmap using Allegro's graphics primitives as it would cause
              severe 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.

       ALLEGRO_NO_PRESERVE_TEXTURE
              Normally, every effort is taken to preserve the contents of bitmaps, since Direct3D
              may  forget  them.   This  can  take extra processing 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 information.

       ALLEGRO_ALPHA_TEST
              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 bitmaps).

       ALLEGRO_MIN_LINEAR
              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.

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

       ALLEGRO_MIPMAP
              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 bitmap 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.

       ALLEGRO_NO_PREMULTIPLIED_ALPHA
              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_premulalpha, 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,
              ALLEGRO_INVERSE_ALPHA).

              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 this:

                     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_INVERSE_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
                     al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
                     // 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_set_target_bitmap(tmp_buffer);
                     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_set_target_bitmap(al_get_backbuffer(display));
                     al_draw_bitmap(tmp_buffer, 0, 0, 0);

       To explain further, if you have a pixel with 0.5 alpha,  and  you're  using  (ALLEGRO_ADD,
       ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) 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.

SEE ALSO

       al_get_new_bitmap_flags(3alleg5), al_get_bitmap_flags(3alleg5)