Rewrite BCPD description of the colour data format

[quinnyo]

This is a rewrite of the BCPD section to hopefully reduce possible confusion and make the colour data format less ambiguous.
Particularly:

• avoid relying on reader interpretation of 'RGB555'
• make explicit that "little-endian" is about byte order of the 16 bit colour word
• reverse the bit table so MSB is first (this table is just about the only one that used the LSB order)
• explicitly state that you access one byte at a time (need to read/write twice per colour)

Fixes #643 (I think)

[nummacway]

I suggest we add an example:

[ISSOtm]

That's actually a pretty good idea! A visual representation of how the encoding is transformed is very helpful.

What I would like, actually, is to add a third layer, which shows how the colour is converted into RGB555 format, and then shows the two bytes being swapped in memory. Is the above image available in SVG form? I'd like to tweak it to propose some further improvements. (Perhaps we can add that in a follow-up PR, but still.)

[ISSOtm]

Thank you for the wording improvements!

[avivace]

rgb555_encoding(1)(1).drawio
I've started trying to redraw it in draw.io @ISSOtm

[nummacway]

Are these two distinct proposals? Or are they two distinct pictures that are both to be added?

For my design, I actually like my "ATA/ATAPI cable" style because it is immediately clear which and how many bits are involved.

[avivace]

I like the cable design as well @nummacway but I couldn't find a way to reproduce it in draw.io (which keeps the diagrams in a 'editable' project XML files so it's a preferred format here) :/

How was your diagram drawn?

[nummacway]

Didn't know draw.io was preferred.
I'll change your diagram to snap to grid, to make future updates easier, and will try to have it import my shapes. I found no way to draw this with draw.io's tools.
I drew them in Affinity, because that's what I use. Because the way it exports text, it was never meant as the final result, and I would have recreated it with a text editor.

[nummacway]

This is only the top part of the original file.
Farbberechnung.drawio
I found no way of inserting an editable SVG, so I had to recreate my four custom shapes with drawio's language. For reference, these are their source codes (concatenated in a single file):
ataatapi-shapes.xml
I do find my two separate colors for the green "cables" nice, but I have no idea which colors to use to align with Pan Docs. I leave that to you.

For those who don't want to open drawio, here's a screenshot:

[ISSOtm]

I've started transcribing the design as a themable SVG (since no matter how much I try, I can't edit SVGs in graphical editors ^^') I'll host a rendered version online when I've gotten parity, though I also have design changes to suggest. In particular, this uses Pan Docs' font, which has different glyph widths, thus we may consider tweaking the font size? (Though I'm also thinking of swapping the values of the red and green components, simply to balance the amount of characters? xD)

(Disregard the misaligned digits, I haven't bothered fixing those yet.) One change I've made is that the “ATA ribbons” are drawn behind the borders, which I'm not fully sure about. One possible change is to squish the ribbons vertically by 1 pixel at each edge, so that the black edges still render there. Feel free to throw feedback!

[ISSOtm]

I do find my two separate colors for the green "cables" nice, but I have no idea which colors to use to align with Pan Docs. I leave that to you.

One layout idea I had was to separate the format conversion and the RAM encoding into two separate layers, so there'd be three total: the RGB8 colour, the RGB555 version (still with the “ribbon cables”, and then two arrows pointing out how the bytes are swapped in memory order, and also dotted lines going left and right to suggest that there are more memory cells around.

[quinnyo]

I like the diagram, but it took me a little while to understand where you're coming from.
I see now that it's about the relationship or converting between 24-bit RGB and the CGB. I did not think about 24-bit colour or really any other format or conversion at all while I was working on this. [This probably says more about me than anything else.]

So I don't think I'm really the target audience for the diagram but I can see the value in it because a lot of people would be coming into this more familiar with this flavour of 24-bit colour than any other. It's a good way to illustrate "what RGB555 means" on a technical level.

---

I've got one issue with the diagram itself: the order of the ribbon layers. Could the blue ribbon be on a higher layer than the green one? (blue should occlude green) RGB --> R, G_low, G_high, B

---

@ISSOtm @avivace thanks for the review and patches!
[every time I write 'N(-)bit(s)' I have to check what I'm supposed to do, and this time I didn't! 🐧]

[nummacway]

The layer idea was: Small cables over wide cables.

[ISSOtm]

My current iteration of the diagrams can be viewed online at https://eldred.fr/pandocs+662/Palettes.html#lcd-color-palettes-cgb-only; criticism welcome.

[nummacway]

"5-bit red" is 16 not 17.