Is there a function in Allegro that allows me to "mask" or combine two bitmaps? For example, if I have a bitmap with an image of a black star on a transparent background, is there a way to mix that with a picture of some water to make a "water star"? So that the black area on the star is preserved to look like water and the surrounding transparent part is just left as transparent.

(That's just an example, it doesn't matter to me if the mask uses black, white, transparency, or whatever.)

For more information about what I'm doing specifically: I'm working on a game where you use colored stars to clear colored blocks (see screenshot). And I'm tired of creating stars and blocks of different colors and animated in different ways. So instead, I'd like to create just a couple of "block masks" and "star masks" and then a few dozen "textures" that can be generated in game (at startup) as star and blocks.

EDIT: I think I'm making progress! Something like this, right?

Shaders can do it. Without shaders, you could clone your water bitmap and then the star bitmap onto it with a blender that only draws the alpha channel, something like this:

al_set_separate_blender(ALLEGRO_ADD, ALLEGRO_ZERO, ALLEGRO_ONE, ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);

The resultant bitmap will have colors from your water bitmap, but alpha from your star bitmap.

Hm, that's a neat trick, SiegeLord. I was looking for a way to implement a "Complex" primitive (basically a filled circle cut out of a rectangle, the circle is transparent), using the separate blenders seems like a good starting point.

Thank you for your ideas. I still have a few questions...

So, I'm able to get a proper cutout, in the shape I need. So, alpha is all set.

Next, I can use al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE); to lighten up part of the bitmap (by blending it with some light gray).

But, how can I darken part of the image, to add some shading??

It seems like no matter what parameters I set the blender to it always just lightens it up...