On 9/12/16 6:51 PM, Walter Bright wrote:
> My last comment is what can I do with a color library that would not
> require some additional library?

Great question and well asked. It was mine as well but I could not put it as succinctly.  -- Andrei

On 13 September 2016 at 06:29, Random D user via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On Monday, 12 September 2016 at 04:14:27 UTC, Manu wrote:
>>
>> I think I'm about as happy with my colour lib as I'm going to be. It really needs reviews.
>>
>> - Manu
>
>
> Hi. I'm just a random forum lurker, but here's my feedback.
>
> It needs more docs/examples for the basic usage cases (i.e. how to skip docs
> and start working).
>
> Now at first glance it looks like working with RGBA (most common case (with
> srgb)) is complicated and while reading the docs I kind of felt like I'd
> just write my own.

You'll get it wrong though!

Can you describe what  you  perceive to be hard?

  import std.experimental.color;

  RGBA8 a(0xFF808000);
  RGBA8 b("GoldenRodYellow");
  auto r = a + b; // do normal operations

Or:
  auto image = new RGBA8[height][width];
  image[x][y] = RGBA8("Aquamarine");


> Few basic things I'd be interested in (examples):
> 1. How to pack/unpack color into uint/rgba channels.

auto c  = RGBA8(r, g, b, a);
uint r = c.r.value; // 'r' is a 'NormalizedInt", so you need '.value'
to get the raw integer value
float g = cast(float)c.g; // cast to float knows about the normalized 0-1 range

> Also can I swizzle channels directly?

I could add something like:
  auto brg =  c.swizzle!"brg";

The result would be strongly typed to the new arrangement.

> How would I extract a single channel from color?

uint r = c.r.value; // like this?

> 2. Can I just cast an array of bytes into a RGBA array and operate on that?

Yes. Of course, if the image library returned an array of colors, you wouldn't have an array of raw bytes in the first place.

> 3. How to scale color channels e.g. 5 bits to 8 bits and vice versa. How to convert color formats? Can I combine scale/conversion with single channel or channel swizzling?

alias CustomPackedColor = PackedRGB!("BGR_5_6_5", ubyte); // <- ordered bgr
CustomPackedColor[] image = loadPackedImage();

auto unpacked = cast(RGB8)image[0]; // unpack and swizzle

I'm not sure what you mean by "with single channel"?

> 4. Which way are RGBA format names defined ("byte array order" r is first byte or "uint order" r is in high bits)?

I describe formats in byte (bit) order. It's the only reasonable way
that works outside of a uint.

> 5. Is it the same for packed rgba formats?

Yes.

> I'm not sure if packedrgb is a necessary distinction. Aren't they all kind of packed (small structs)? There's no guarantee that 1 byte is not just a part of a bigger field.

RGBA8 has 4 ubytes, and you can operate on them.
  ubyte a, b; a += b; // <- is valid D code
Unpacked types can do maths. Packed types can't do maths, they need to
be unpacked before you can do anything, and you don't generally want
the result to be immediately packed again.
If I allowed maths on PackedRGB for instance, it would be expected
that the result is re-packed at the end of every operation, and that
would be useless.

PackedRGB is for storage, not for doing work. This is why they're distinct.

> Btw. Your RGBA8 example is a bit weird:
> static assert(RGBA8("0x908000FF") == RGBA8(0x80,0x00,0xFF,0x90));
> I'd assume RGBA8(r,g,b,a) would be either "uint order" r(0x90), g(0x80),
> b(0x00), a(0xFF) or "byte array order" (le) r(0xFF), g(0x00), b(0x80),
> a(0x90)

I'm showing that parsing colors from string's follow the web
convention. I can't redefine how colours are expressed on the web for
decades.
I think you've just highlighted that I need to remove the '0x'
notation though, that is definitely misleading! Use '#', that should
be clear.

> 6. Perhaps you should define all the usual color formats, since everybody
> and their cat has their own preference for rgba channel orders.
> In my experience all these 4 variants for RGBA8888 are pretty common:
> RGBA8888
> BGRA8888
> ARGB8888
> ABGR8888
> and their X and 24bit variants.

I don't think they're common at all. Only 2 are common (one of which
is deprecated), the other 2 are very niche.
I was trying to balance a tasteful amount of instantiations. I don't
really want to provide an instantiation of every single realtime
format I've ever encountered out of the box.


> For 16 bits fairly common are:
> RGB565 and RGBA5551, also sometimes you see one of RGBA4444 permutations
> (like RGBA8 above).

Nobody uses 16bit textures anymore. Compressed textures are both MUCH smaller, and generally higher quality.

> Also L16 is pretty common for heightfields or other data images/textures.

I could probably put that one.

> I guess there are also planar formats, but I think those are more of a Image problem space.

I think if people want to provide instantiations for convenience, it should be in the libs that interact with those formats.

For instance, I imagine in OpenGL binding there might be:
  alias C = ColorFor!GL_R11F_G11F_B10F; // <- instantiation of the
proper type for the GL enum.

Most people really just want RGB8, or RGBA8. If you're interacting with PackedRGB, you're already in specialist territory.


> Just as a completely random idea - How about aliases for HDR formats like HDR10 and Dolby Vision? Kind of looks like they're just combinations what you already have.

This is very specialist. Instantiations are expensive. If they're not used, it's a waste of compiler effort.

On 13 September 2016 at 08:51, Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/11/2016 9:14 PM, Manu via Digitalmars-d wrote:
>>
>> I think I'm about as happy with my colour lib as I'm going to be. It really needs reviews.
>
>
> I have zero expertise in color programming, and have no idea what a color library might do or what it would be used for.
>
> I looked at the front page of the documentation. I would like to see some sort of explanation of who, what, where, why and how of a color library. Like what is a color space, etc. Maybe add some links to explanatory Wikipedia pages?
>
> "Set of colors defined by X11, adopted by the W3C, SVG, and other popular libraries."
>
> Would be a great place to add clickable links for the relevant X11, W3C, SVG, etc. specification pages.
>
> It really, really needs a "References:" section, with links like:
>
>     https://en.wikipedia.org/wiki/RGB_color_model
>
> Are there any definitive books on the topic?
>
> What is a BGR color type? What is a UV color type? What is a UVW color type? What is an alpha color type? What is luminance?
>
> "This module implements HSV, HSL, HSI, HCY, HWB, HCG color types." "angular color spaces"
>
> Some references to what these are would be nice.
>
> Contrast with:
>
>     http://dlang.org/phobos/std_regex.html
>
> where general information is given and links for more are provided (although that is weak and could be improved).

Okay. I'll work on this feedback.


> My last comment is what can I do with a color library that would not require some additional library?

With color, ndslice, and std.algorithm, you can do quite a lot of
useful image processing already.
But my point before was that I see this primarily as an enabler. We
really need a graph/plot library for instance! Also, multimedia
libraries will all become naturally compatible when the primitive
working type is defined in phobos.

On Monday, 12 September 2016 at 22:55:01 UTC, Walter Bright wrote:
>
> Thanks for the rationale. I'm glad to see you're planning follow-on libraries! I'd use a graph/plot library myself. Some of the rationale above should go into the documentation for the library.

You might try
https://github.com/BlackEdder/ggplotd

On 13 September 2016 at 07:00, Marco Leise via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> Am Tue, 13 Sep 2016 00:37:22 +1000
> schrieb Manu via Digitalmars-d <digitalmars-d@puremagic.com>:
>> I flip-flopped on this multiple times.
>> It's not so simple.
>> 1. Alpha doesn't necessarily mean transparently, that's just one
>> (extremely common) use
>> 2. 1 is the multiplication identity, but 0 is the additive identity. I
>> cant find either addition or multiplication to take precedence over
>> eachother.
>> 3. With those 2 points above already making me feel a bit worried
>> about it, I think that appearing numbers out of nowhere is just
>> generally bad, so I went with a=0.
>
>> If alpha defaults to 1, then a*b works as expected (object does not
>> become transparent by this operation).
>> If alpha defaults to 0, then b-a works as expected (object does not
>> become transparent by this operation).
>
> Additive color components can work like that, but the alpha component just doesn't represent an amount of light. Don't try too hard to make the arithmetics make sense, when the practical use lies in 100% alpha by default.

I understand the argument, I have stressed over this to no end. I still think it's just not 'right'. :/


> Converting every
> color to full transparent is not helpful when you want to save
> a 24-bit BMP as 32-bit PNG or get an RGBA color from an RGB
> texture.

What is the worth of storing alpha data if it's uniform 0xFF anyway?
It sounds like you mean rgbx, not rgba (ie, 32bit, but no alpha).
There should only be an alpha channel if there's actually alpha data... right?


> I don't know who declared that 100% alpha means opaque. For
> what it's worth it could have been the other way around and
> all the (1-a) and (a) in blending functions swapped.
> And a blending function is what is needed here to give any
> meaning at all to arithmetics on alpha. An additive one may be:
>
>   color = color_dst + color_src * alpha_src
>   alpha = alpha_dst

I thought about adding blend's, but I stopped short on that. I think
that's firmly entering image processing territory, and I felt that was
one step beyond the MO of this particular lib... no?
Blending opens up a whole world.


>> With that in mind, you realise alpha will *always* require explicit handling... so I think 0 is a better default at that stage. It may be possible to convince me otherwise ;)
>
> I fully agree with the first line, I just think that for practical uses alpha is considered to be 100% in pixel formats without alpha channel.

'rgbx' is for image formats without alpha channels...


> Otherwise the most popular blending
> functions would do nothing on RGB colors.

'rgbx' colors fed through a blend function would always properly imply alpha=1.


> SDL for example also uses 100% alpha by default: "If the specified pixel format has an alpha component it will be returned as all 1 bits (fully opaque)."

>From which functions? Link me?
I'd love to see more precedents.


>> > It seems inconsistent that you can specify all kinds of exponents when the exponent is shared but are forced to 5 bit exponents when mixed into each component, while the mantissa can still be adjusted. Would m7e3 have worked? (With f* being the IEEE standard formats.)
>>
>> I was thinking that, and mentioned as such in the comments near those lines ;)
>> Thing is, there are no realtime small floats with exponent != 5bits
>> except the unique 7e3 format on xbox 360.
>> I can extend this in an unbreaking way.
>> I might: f## =  ieee-like, s##e# = signed float, (u)##e# = unsgned float.
>> It's just pretty verbose is all: "rgb_11e5_11e5_10e5". I mean, it's
>> fine... but maybe people wouldn't find this intuitive? Many
>> programmers don't know what an 'exponent' or 'mantissa' is... :/
>
> Yeah I thought that the common formats would be the IEEE ones, especially f16 and that anything less are very niche custom formats that come and go and need verbose descriptions. Well, either way works.

The verbose idea I said above is my best idea. I'll roll with that if
enough people agree.
There was the other fellow who posted before who feels like it's
already too complicated for him though.

I've been very carefully trying to put the complicated bits just one
level back from arms reach, so a casual user isn't confronted with
those details.
Putting that complexity in the format string makes it very
user-facing. That's the part I'm not wild about.


>> > The final package should contain a fair amount of documentation, in my opinion also on the topics of sRGB vs. linear and what "hybrid gamma" is.
>>
>> Yeah, but is it really my job to teach someone about colour space?
>> Wikipedia can do that much better than I can... :/
>> I agree, but I don't really know where to draw the line, or how to organise it.
>>
>> Perhaps people with strong opinions on how this should be presented can create a PR?
>
> Alright, but hybrid gamma is really not something that can be googled. Or rather I end up at Toyota's Gamma Hybrid product page. :D

True. I'm not even sure what the technical term for this sort of gamma
function is... I just made that up! :/
As Walter and others have asked, I'll have to start adding links to
reference material I guess, although that still feels really weird to
me for some reason.

On 9/12/2016 6:11 PM, Manu via Digitalmars-d wrote:
> Okay. I'll work on this feedback.

Wonderful!


>> My last comment is what can I do with a color library that would not require
>> some additional library?
>
> With color, ndslice, and std.algorithm, you can do quite a lot of
> useful image processing already.

Ok, but I have no idea how. Perhaps include something as an example? Phobos in general lacks short, pithy, and *useful* examples. Such can go a long way towards selling the color library to users.


> But my point before was that I see this primarily as an enabler. We
> really need a graph/plot library for instance! Also, multimedia
> libraries will all become naturally compatible when the primitive
> working type is defined in phobos.

I had read your post on this topic after making my post. I think it's a strong answer.

On 9/12/2016 2:08 PM, John Colvin wrote:
> On Monday, 12 September 2016 at 19:59:58 UTC, Edwin van Leeuwen wrote:
>> On Monday, 12 September 2016 at 19:55:57 UTC, Guillaume Piolat wrote:
>>> - I've wanted a function like colorFromString many times. It's especially
>>> nice with the added #RGBA and #RRGGBBAA syntax that eg. SVG lacks.
>>
>> What happens when the string is invalid? Does it throw an error?
>
> It should be integrated with std.conv.parse and std.conv.to and follow their
> conventions.

I'm not so sure. Follow the conventions, ok, but integrating them in - they are already large and complex.

On 9/12/2016 7:03 PM, Walter Bright wrote:
> On 9/12/2016 6:11 PM, Manu via Digitalmars-d wrote:
>> Okay. I'll work on this feedback.
>
> Wonderful!

BTW, linking to authoritative reference material has the effect of reassuring the user that the library is designed by someone who knows his stuff. It has the same effect as notes and references appendices have in any good technical book.

On 13 September 2016 at 12:05, Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> On 9/12/2016 2:08 PM, John Colvin wrote:
>>
>> On Monday, 12 September 2016 at 19:59:58 UTC, Edwin van Leeuwen wrote:
>>>
>>> On Monday, 12 September 2016 at 19:55:57 UTC, Guillaume Piolat wrote:
>>>>
>>>> - I've wanted a function like colorFromString many times. It's
>>>> especially
>>>> nice with the added #RGBA and #RRGGBBAA syntax that eg. SVG lacks.
>>>
>>>
>>> What happens when the string is invalid? Does it throw an error?
>>
>>
>> It should be integrated with std.conv.parse and std.conv.to and follow
>> their
>> conventions.
>
>
> I'm not so sure. Follow the conventions, ok, but integrating them in - they are already large and complex.

std.conv.to  seems to 'just work' for color type conversion.
I'd like to support string -> color conversion via std.conv.to; ie:
auto c = "#FFFF00".to!RGB8;
Is there a simple way to do that?

On Tuesday, 13 September 2016 at 01:05:56 UTC, Manu wrote:
>> Also can I swizzle channels directly?
>
> I could add something like:
>   auto brg =  c.swizzle!"brg";
>
> The result would be strongly typed to the new arrangement.

Perfect use-case for opDispatch like in gl3n.