[GRASS5] Suggested color function names

[Glynn Clements]

Hamish wrote:

> > In what context does a colour of "none" make sense?
> > 
> > If you have a particular situation where you need additional
> > information other than just a colour, then create your own type for
> > that purpose.
> 
> 
> Many of the display modules use a color of "none" to switch off the
> drawing of some feature.
> 
> e.g. d.barscale background color.
> e.g. d.vect fill or outline color. (vector area or symbol)
> e.g. d.rast.arrow grid color.
> 
> Typically in a d.* module the color is taken from the command line:
>     color  either a standard GRASS color, R:G:B triplet, or "none"
>            default: white
> 
> which is then parsed and the result passed on to an external draw fn:
>    do_plot(,,,, color);
> 
> 
> If this was only used sparsely I can see the point of keeping RGBA_Color
> compact and simple, but in practical use we'd use it all the time, and
> you'd either have to define a new struct 50% of the time; change a large
> number of function calls to add a really_draw_it flag; or start adding
> the really_draw_it flag as a global variable. A "none" flag (aka draw
> nothing/be transparent) in the color struct makes defining this
> situation much more elegant- nan:nan:nan. Also it's a lot clearer to the
> casual code reader seeing color.set=RGBA_COLOR_NONE; versus color.a=0;,
> and I don't like conceptually mixing boolean tests with full fledged
> int/char variables. [ if(color.a) draw_it(); ]

In the case where "none" means "completely transparent" (i.e. not
drawn), I would suggest using the alpha component.

To me, a "set" field implies "the data in this structure is/isn't
valid" (i.e. "undefined"). If a function fills in caller-provided
structures, the field being zero means "I haven't filled this in",
while an input having the field set zero means "ignore this value"
(e.g. leave the previous setting unchanged).

If you're concerned about code clarity, using "if (color.a > 0)" may
be clearer. Or even making the display (D_*) functions perform this
optimisation internally (the application always calls the "draw"
function, but the library would skip drawing if the current colour is
transparent).

Alternatively, provide R/G/B/A and R/G/B/Set types, both 32 bits.

> > There's no reason why everything which deals with colours needs to
> > carry that field around because something which uses colours needs it.
> 
> What future plans do you have for widespead use of the RGBA_Color struct
> which would make the above a corner case?
> 
> I can see the point about making it fit into 32 bytes etc if it is
> destined for core use in the heart of the graphics engine*, but for the
> current use I think the extra bloat justifies itself well.

Well, the more it's used, the more it makes sense for it to fit into a
32-bit word.

Lots of graphic APIs have RGB/RGBA colour structures, and most of them
don't have a "set" field.

-- 
Glynn Clements <glynn at gclements.plus.com>