Re: [AD] "blend color" is wrong

[Elias Pschernig <elias.pschernig@xxxxxxxxxx>]

On Tue, 2010-06-08 at 08:52 -0400, Evert Glebbeek wrote:
> On 8 Jun 2010, at 7:06 , Elias Pschernig wrote:
> > So, the proposed change:
> > 
> > Option A:
> > 
[...]
> 
> 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.

Yes. We could recommend in the documentation of al_set_blender that it's
not recommended to pass in anything else but solid white. Still, I
somehow don't like that :P

> > Option B:
> > 
[...]
> 
> I like both the tinted bitmap functions and the extra colour parameter
> for text drawing. Not having it there bothered me.

Peter also seems to like the idea of a color parameter to text drawing.
And if we want a fixed color parameter for text drawing, so an API
change affecting all text drawing, we might as well go for option B
completely I'd say.

> 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)?

Yes, that's the question.

The discussion only about whether the current display should be passed
in to each function or not, from what I remember. Color never was
considered to be a state. Bob's gfx API however did not have font
drawing in it so when we got the font addons... they were missing color,
probably because it worked in such a neat way with this blend color
already :P

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

Yes, but having two ways to do the same thing might not be the best
idea. (In Python where I come from that's one of the base principles.)

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

Probably not. For example if you do something like blend one scene into
the next by changing the global alpha, you wouldn't want to manually
have to "fix" a few of the functions when it works for most. The
expected outcome would be to work like blending or transformations do.

[...]
> 
> 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.
> 

Adding a few _tinted functions would not break any existing code, while
removing that color parameter would break every current use of text
drawing. So I'd say if we go for removing the color parameter, we can do
the complete option (A) or complete option (B) without any second
thoughts.

Siegelord in #allegro identified another inconsistency with having a
color state in general - al_draw_prim ignores it. The only way to "fix"
that would be to go through each ALLEGRO_VERTEX the user provides and
pre-multiply the rgba values with our color - but with al_draw_prim
being such a low level function, with custom vertex declarations and so
on, that wouldn't be ideal.

So I'm leaning towards option B now. It's the one easiest to describe in
the documentation, with no special cases add all: If you want to specify
the color of something, that is done (and can only be done) by passing
in an ALLEGRO_COLOR parameter.

-- 
Elias Pschernig <elias.pschernig@xxxxxxxxxx>