1al_set_new_bitmap_flags(3) Library Functions Manual al_set_new_bitmap_flags(3)
2
6 al_set_new_bitmap_flags
7
9 #include <allegro5/allegro.h>
10 void al_set_new_bitmap_flags(int flags)
12
14 Sets the flags to use for newly created bitmaps. Valid flags are:
15 ALLEGRO_VIDEO_BITMAP
17 Creates a bitmap that resides in the video card memory. These
18 types of bitmaps receive the greatest benefit from hardware
19 acceleration. al_set_new_bitmap_flags(3) will implicitly set
20 this flag unless ALLEGRO_MEMORY_BITMAP is present.
21 ALLEGRO_MEMORY_BITMAP
23 Create a bitmap residing in system memory. Operations on, and
24 with, memory bitmaps will not be hardware accelerated. However,
25 direct pixel access can be relatively quick compared to video
26 bitmaps, which depend on the display driver in use.
27 Note: Allegro's software rendering routines are currently very
29 unoptimised.
30 ALLEGRO_KEEP_BITMAP_FORMAT
32 Only used when loading bitmaps from disk files, forces the
33 resulting ALLEGRO_BITMAP(3) to use the same format as the file.
34 This is not yet honoured.
36 ALLEGRO_FORCE_LOCKING
38 When drawing to a bitmap with this flag set, always use pixel
39 locking and draw to it using Allegro's software drawing primi‐
40 tives. This should never be used if you plan to draw to the
41 bitmap using Allegro's graphics primitives as it would cause
42 severe performance penalties. However if you know that the bit‐
43 map will only ever be accessed by locking it, no unneeded FBOs
44 will be created for it in the OpenGL drivers.
45 ALLEGRO_NO_PRESERVE_TEXTURE
47 Normally, every effort is taken to preserve the contents of bit‐
48 maps, since Direct3D may forget them. This can take extra pro‐
49 cessing time. If you know it doesn't matter if a bitmap keeps
50 its pixel data, for example its a temporary buffer, use this
51 flag to tell Allegro not to attempt to preserve its contents.
52 This can increase performance of your game or application, but
53 there is a catch. See ALLEGRO_EVENT_DISPLAY_LOST for further
54 information.
55 ALLEGRO_ALPHA_TEST
57 This is a driver hint only. It tells the graphics driver to do
58 alpha testing instead of alpha blending on bitmaps created with
59 this flag. Alpha testing is usually faster and preferred if
60 your bitmaps have only one level of alpha (0). This flag is
61 currently not widely implemented (i.e., only for memory bit‐
62 maps).
63 ALLEGRO_MIN_LINEAR
65 When drawing a scaled down version of the bitmap, use linear
66 filtering. This usually looks better. You can also combine it
67 with the MIPMAP flag for even better quality.
68 ALLEGRO_MAG_LINEAR
70 When drawing a magnified version of a bitmap, use linear filter‐
71 ing. This will cause the picture to get blurry instead of cre‐
72 ating a big rectangle for each pixel. It depends on how you
73 want things to look like whether you want to use this or not.
74 ALLEGRO_MIPMAP
76 This can only be used for bitmaps whose width and height is a
77 power of two. In that case, it will generate mipmaps and use
78 them when drawing scaled down versions. For example if the bit‐
79 map is 64x64, then extra bitmaps of sizes 32x32, 16x16, 8x8,
80 4x4, 2x2 and 1x1 will be created always containing a scaled down
81 version of the original.
82 ALLEGRO_NO_PREMULTIPLIED_ALPHA
84 By default, Allegro pre-multiplies the alpha channel of an image
85 with the images color data when it loads it. Typically that
86 would look something like this:
87 r = get_float_byte();
89 g = get_float_byte();
90 b = get_float_byte();
91 a = get_float_byte();
92 r = r * a;
94 g = g * a;
95 b = b * a;
96 set_image_pixel(x, y, r, g, b, a);
98 The reason for this can be seen in the Allegro example ex_premu‐
100 lalpha, ie, using pre-multiplied alpha gives more accurate color
101 results in some cases. To use alpha blending with images loaded
102 with pre-multiplied alpha, you would use the default blending
103 mode, which is set with al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE,
104 ALLEGRO_INVERSE_ALPHA).
105 The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure
107 that images are not loaded with alpha pre-multiplied, but are
108 loaded with color values direct from the image. That looks like
109 this:
110 r = get_float_byte();
112 g = get_float_byte();
113 b = get_float_byte();
114 a = get_float_byte();
115 set_image_pixel(x, y, r, g, b, a);
117 To draw such an image using regular alpha blending, you would
119 use al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLE‐
120 GRO_INVERSE_ALPHA) to set the correct blender. This has some
121 caveats. First, as mentioned above, drawing such an image can
122 result in less accurate color blending (when drawing an image
123 with linear filtering on, the edges will be darker than they
124 should be). Second, the behaviour is somewhat confusing, which
125 is explained in the example below.
126 // Load and create bitmaps with an alpha channel
128 al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
129 // Load some bitmap with alpha in it
130 bmp = al_load_bitmap("some_alpha_bitmap.png");
131 // We will draw to this buffer and then draw this buffer to the screen
132 tmp_buffer = al_create_bitmap(SCREEN_W, SCREEN_H);
133 // Set the buffer as the target and clear it
134 al_set_target_bitmap(tmp_buffer);
135 al_clear_to_color(al_map_rgba_f(0, 0, 0, 1));
136 // Draw the bitmap to the temporary buffer
137 al_draw_bitmap(bmp, 0, 0, 0);
138 // Finally, draw the buffer to the screen
139 // The output will look incorrect (may take close inspection
140 // depending on the bitmap -- it may also be very obvious)
141 al_set_target_bitmap(al_get_backbuffer(display));
142 al_draw_bitmap(tmp_buffer, 0, 0, 0);
143 To explain further, if you have a pixel with 0.5 alpha, and you're
145 using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending,
146 the formula is:
147 a = da * dst + sa * src
149 Expands to:
151 result_a = dst_a * (1-0.5) + 0.5 * 0.5;
153 So if you draw the image to the temporary buffer, it is blended once
155 resulting in 0.75 alpha, then drawn again to the screen, blended in the
156 same way, resulting in a pixel has 0.1875 as an alpha value.
157
159 al_get_new_bitmap_flags(3), al_get_bitmap_flags(3)
160Allegro reference manual al_set_new_bitmap_flags(3)