Re: [AD] "blend color" is wrong

[Evert Glebbeek <eglebbk@xxxxxxxxxx>]

On 8 Jun 2010, at 7:06 , Elias Pschernig wrote:
> So, the proposed change:
> 
> Option A:
> 
> Add two functions:
> 
> al_set_tint_color(ALLEGRO_COLOR color);
> ALLEGRO_COLOR al_get_tint_color();
> 
> Not sure about the name, maybe just "al_set_color" or more technical "al_multiply_color" would work better. They would set the very same per-display color which right now is set by the blending functions, which would lose their color parameter.

I prefer the "tint" name. Plain "al_set_color()" sounds a bit too generic for me, "multiply_colour" sounds a bit too technical (it sounds like an implementation detail).
For API consistentcy, the colour parameter to the blender functions could be removed once this is set, but these functions can be added without doing that.

> Option B:
> 
> Alternatively we could add a color parameter to the bitmap and text drawing functions (the solid primitives already have it). However for bitmap drawing I think it would be a bit awkward having to specity a color every time, so instead a _colored or _tinted variant would mean 5 new functions:
> 
> al_draw_tinted_bitmap
> al_draw_tinted_bitmap_region
> al_draw_tinted_rotated_bitmap
> al_draw_tinted_rotated_scaled_bitmap
> al_draw_tinted_scaled_bitmap
> 
> Each would have an additional "ALLEGRO_COLOR color" parameter added after the bitmap argument.
> 
> For text drawing, we had a color parameter in A4 as well, so it would work as additional parameter to all text functions:
> 
> al_draw_text
> al_draw_ustr
> al_draw_justified_text
> al_draw_justified_ustr
> al_draw_textf
> al_draw_justified_textf
> 
> Each of those would have an "ALLEGRO_COLOR color" parameter added after the font argument. There would be no per-display color any longer. The solid color primitives would lose the ability to multiply their color - you can already do that yourself.

I like both the tinted bitmap functions and the extra colour parameter for text drawing. Not having it there bothered me.
HOWEVER: we had a fairly long discussion a few years back on whether Allegro 5 would be "state based", like OpenGL (at the time anyway), or whether you would pass around arguments for things. Now, quite apart from who said what at the time, the decision then was to have a state-based API. Re-adding the colour as an argument will (partially) upset that. Do we want to do that (quite apart from the code being in feature-freeze now)?
That said, a *_tinted_* version of both the bitmap drawing functions and the text drawing functions can be added without breaking the API (in the sense of removing the current functions that just use the global colour) so those functions can easily be added for 5.2 if we want them.

The only ugly bit in the API, then, may be that the regular blitting functions are always affected by the global tint colour, which I take it is not the case in your proposal. However, the tinted version of the blitting functions would ignore the global colour. I suppose we can think of it as setting a "default" tint. Maybe that's what you want if you're tinting an entire scene anyway.

> We always have option C to just leave things as is of course. Below the surface not much would change either way, with option A it simply would be a different API function to specify the per-display color. With option B the color would come as a function parameter instead of from the current display.
> 
> 
> So, myself I can't really decide, given how we are in beta stage for 5.0 and the API is more or less frozen and option C would mean the least work it started growing on me while writing this email :) On the other hand now is the last time we can fix this - once 5.2 is out (the missing shaders addon in 5.0  pretty much guarantees we will need it soon) everyone will say this is not enough reason to break compatibility with 5.0 code.

Apart from separating the tint colour from the blender call (A), I don't think the API would need to break at all.
So, my proposal would be a bit of a compromise of the above 3 options:
1. Take a decision on (A). Personally I don't have a strong opinion either way, but if there is a strong feeling that the colour parameter should be separate, then we can decide to break the feature freeze. Either way, those independent functions could be added without changing the current API, which is admittedly a bit clunky.
2. Decide to implement the _tinted_ functions (for bot blitting and text rendering) for 5.1/5.2.
The current API is not otherwise broken.

Evert