colour lib needs reviewers

Tue Sep 13 11:10:48 PDT 2016

On Tuesday, 13 September 2016 at 01:05:56 UTC, Manu wrote:
>
> Can you describe what  you  perceive to be hard?

Well, I just skimmed through the docs and I didn't look at the 
code, so that sense it was an "honest" view for phobos proposal. 
Also I was trying to convey that based on the docs it "looks 
hard", although I was suspecting that it isn't really.

So the list of things was a list of examples that I would've 
wanted to see in the docs. Maybe in an overview or "here's how 
you use it" page. I can read the details if I really need them, 
but I think it's important to have a cook book examples for quick 
start.

In general, I think basics should be dead simple (even over 
simplified for the very basic case), but the API and the docs 
should provide me layers of increasing detail and sophistication, 
which I can study if (or when) I really need control and care 
about the details.

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

Let's put these in the docs.

>
>> Also can I swizzle channels directly?
>
> I could add something like:
>   auto brg =  c.swizzle!"brg";

It's just a nicety. I guess I could just define exact color 
formats and convert (let the lib do the rest), or just unpack and 
repack.

Also the docs might want to mention which way is the 
preferred/designed way.

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

Cool. I just wanted to make sure something like this possible.

Also should be in the docs as an example, so that people don't 
have to try this out themselves.
Or search through github for details.

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

For example if you first unpack RGBA_uint32 into R,G,B,A then you 
want to take G (or just swizzle color.g) and scale that to 5 bits 
or 16 bits for what ever use case you might have.

Looks to me like this can be handled with something like 
PackedRGB!("G_5") and then do color conversion into that.

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

Agreed. This should be in the docs, so that it's clear to users. 
(especially, since RGBA8888 is the common case and it does fit 
into uint)

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

Right. I was interpreting 0x........ as c hex literal. You should 
document that it's following the web convention.

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

Deprecated by who? Shouldn't phobos grade lib include all 
reasonable platforms?

I agree that you probably don't see too much variation within 
windows APIs, images (BMP etc.) or with D3D GPU textures (they're 
compressed anyway and asset pipelines to do the conversions 
beforehand), but I was more of thinking image libraries and the 
numerous, sometimes old and quirky, image formats. Or perhaps 
someone wants to implement a software blitter for their favorite 
toy device/embedded project.

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

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

Sure, agreed. These are not too useful as GPU textures these days 
(even on mobile), but if you do software 2d, load older image 
formats (image viewer etc.) or something even more specialized, 
these are pretty useful.

I guess I was going for comprehensive (within reason), where as 
you were going for "90% of 2016 colors/image data", which is fine.

Anyways, it would be nice to see color (and hopefully image + 
simple blitter) in phobos.
There's no need to write the same convert/copy/stretch/blend loop 
over and over again. And cpu-side code is nice to have for quick 
prototyping and small-scale work.

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

HDR TVs and displays are coming fast and with that I'm sure HDR 
editing and photography will be common, which of course means HDR 
color formats and apps. But these can be added later.