al_set_new_bitmap_flags(3)al_set_new_bitmap_flags(3)NAMEal_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(3) 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(3) 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 primi‐
tives. 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 bit‐
map 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 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
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 bit‐
maps).
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 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.
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 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.
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_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,
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, ALLE‐
GRO_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 ALSOal_get_new_bitmap_flags(3), al_get_bitmap_flags(3)Allegro reference manualal_set_new_bitmap_flags(3)
