Rewrite BCPD description of the colour data format by quinnyo · Pull Request #662 · gbdev/pandocs

quinnyo · 2026-04-19T19:02:14Z

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 · 2026-04-19T22:18:54Z

I suggest we add an example:

ISSOtm · 2026-04-20T11:54:15Z

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 · 2026-04-20T15:16:58Z

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

nummacway · 2026-04-20T16:31:17Z

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 · 2026-04-20T16:44:38Z

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 · 2026-04-20T17:20:47Z

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 · 2026-04-20T19:59:25Z

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 · 2026-04-20T21:11:11Z

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 · 2026-04-20T21:15:09Z

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 · 2026-04-21T08:30:21Z

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 · 2026-04-21T16:23:04Z

The layer idea was: Small cables over wide cables.

ISSOtm · 2026-04-21T22:10:56Z

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.

[EDIT]: Updated with the state of the PR as of #662 (comment).

ISSOtm · 2026-05-06T18:21:04Z

Since there have been no replies to my last comment in the last two weeks, I'm going to push my changes to this PR, and we'll keep working from there. Anyone opposed to this, please voice your opinion (now or after) and those changes will be reverted.

- less ambiguous description of the colour data format - clarify meaning of endianness (byte order) - reverse the order of the bit table, so MSB appears first, matching others

Co-authored-by: Eldred Habert <me@eldred.fr>

Co-authored-by: "Janni K." <24881711+nummacway@users.noreply.github.com> Co-authored-by: Rangi42 <sylvie.oukaour+rangi42@gmail.com>

Those have been deprecated in newer `hardware.inc`, and really, the header names were hard to read with the duplicated names, especially the OBJ ones. Anyone being confused by old code should be able to deduce the alternate naming from their definitions in the accompanying `hardware.inc`, or they can look it up on older versions of Pan Docs, or they can ask and be explained. I nonetheless expect that the impact will be very low at this point.

ISSOtm · 2026-05-06T19:23:23Z

I'm now personally happy with the state of this PR, but I'd like opinions from @quinnyo and @nummacway before merging.

ISSOtm · 2026-05-06T19:25:00Z

Also @DelayRGC, since she opened the original issue.

avivace

Some minor comments

avivace · 2026-05-06T19:57:49Z

-byte of BGP0 color #1 via BCPD, which contains the color's blue and upper green bits.
+[^bit15]:
+The 16th bit, bit 15, is **ignored** by the hardware.
+In discussion, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white!


Suggested change

In discussion, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white!

Conventionally, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white.

'In discussion' sounds a bit confusing here, imo

also the ! is a bit off tone

I wanted to avoid implying that it would be convention outside of the programs themselves. Perhaps "in writing"?

Proposal (that is definitely not meant as a final idea, but maybe some words can be taken up):

When referring to a certain color, the 16-bit value is usually written with the highest bit set to 0, e.g. white will be referred to as $7FFF, not $FFFF.

(Also note the dollars.)

Suggested change

In discussion, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white!

Colors are conventionally referred to with that bit set to 0 (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: thus, it's fine to fill color RAM with $FF bytes to set it to all-white.

I think it's better not to use the dollars here, as they'd imply numbers slightly more than colours. But that's fairly nitpicky.

Can we get an "e.g." after the colon?

Is this better?

I'm undecided on that one.

I would like to add one thing about the dollar sign: The notation without it could become ambiguous if no A-F digits are present. I think we need some way to mark that the color values (I'm not calling them colors!) are hexadecimal. Since we don't have the power (or need) for a unique notation like CSS's #, $ will do.

"referred to with that bit set to 0" sounds even more quirky, IMO

what about "The canonical form of a color value has that bit set to 0." ?

Again, no, since that implies that this is also the form that should be stuck to on the hardware itself. I'm trying to keep it clear that this is only the case in literature. (I switched to “that bit set to 0” because “that bit clear” is easy to misread, I've found.)

avivace · 2026-05-06T19:59:40Z

-All background colors are initialized as white by the boot ROM, however it is a
-good idea to initialize all colors yourself, e.g. if implementing
-a soft-reset mechanic.
+All background colors are initialized as white by the boot ROM, however it is a good idea to initialize all colors yourself, e.g. if implementing a soft-reset mechanic.


Suggested change

All background colors are initialized as white by the boot ROM, however it is a good idea to initialize all colors yourself, e.g. if implementing a soft-reset mechanic.

All background colors are initialized as white by the boot ROM, however it is a good idea to initialize all colors yourself, e.g. by implementing a soft-reset mechanic.

e.g. if implementing ... doesn't sound good

"by" changes the meaning of the sentence. Maybe "for" would work better?

That would also change the meaning of the sentence. The point is that it's a good idea to set all palettes yourself if there's any chance that the init code may run more than once, such as if the game has a soft-reset mechanism.

What do you think of "for a soft-reset mechanic" rather than "for/by/if implementing a soft-reset mechanic"?

I like Isso's original proposal.

quinnyo · 2026-05-08T15:25:44Z

Hi, sorry I haven't been around, I'll be able to have a look at this in a day or so!

ISSOtm · 2026-05-29T21:03:40Z

Ping?

ISSOtm requested changes Apr 20, 2026

View reviewed changes

Comment thread src/Palettes.md Outdated

Comment thread src/Palettes.md Outdated

Comment thread src/Palettes.md Outdated

Comment thread src/Palettes.md Outdated

Comment thread src/Palettes.md Outdated

This comment was marked as resolved.

Sign in to view

ISSOtm force-pushed the bcpd-colour-format branch from c2fcdb5 to 1b7a344 Compare May 6, 2026 18:23

quinnyo and others added 7 commits May 6, 2026 20:47

Rewrite BCPD description of the colour data format

2028576

- less ambiguous description of the colour data format - clarify meaning of endianness (byte order) - reverse the order of the bit table, so MSB appears first, matching others

Update src/Palettes.md

bbd0384

Co-authored-by: Eldred Habert <me@eldred.fr>

Apply suggestions from code review

caeded6

Co-authored-by: Eldred Habert <me@eldred.fr>

Add SVG diagrams describing GBC colour format

137fdf9

Co-authored-by: "Janni K." <24881711+nummacway@users.noreply.github.com> Co-authored-by: Rangi42 <sylvie.oukaour+rangi42@gmail.com>

Move description of color format outside of BGPI/BGPD

c63587d

Touch up description of CGB pal regs

91b846c

ISSOtm force-pushed the bcpd-colour-format branch from 1b7a344 to f924874 Compare May 6, 2026 19:17

ISSOtm requested a review from avivace May 6, 2026 19:23

avivace requested changes May 6, 2026

View reviewed changes

avivace added 2 commits May 7, 2026 09:34

Update src/Palettes.md

f2f8b95

Update src/Palettes.md

ffc5c4d

avivace approved these changes May 29, 2026

View reviewed changes

	In discussion, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white!
	Conventionally, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white.

	In discussion, that bit is generally clear (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: it's fine to fill color RAM with $FF bytes to set it to all-white!
	Colors are conventionally referred to with that bit set to 0 (for example, the canonical pure white is `7FFF` and not `FFFF`), but the hardware treats both identically: thus, it's fine to fill color RAM with $FF bytes to set it to all-white.

	All background colors are initialized as white by the boot ROM, however it is a good idea to initialize all colors yourself, e.g. if implementing a soft-reset mechanic.
	All background colors are initialized as white by the boot ROM, however it is a good idea to initialize all colors yourself, e.g. by implementing a soft-reset mechanic.

Uh oh!

Conversation

quinnyo commented Apr 19, 2026

Uh oh!

nummacway commented Apr 19, 2026

Uh oh!

ISSOtm commented Apr 20, 2026

Uh oh!

ISSOtm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivace commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nummacway commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avivace commented Apr 20, 2026

Uh oh!

nummacway commented Apr 20, 2026

Uh oh!

nummacway commented Apr 20, 2026

Uh oh!

ISSOtm commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ISSOtm commented Apr 20, 2026

Uh oh!

quinnyo commented Apr 21, 2026

Uh oh!

nummacway commented Apr 21, 2026

Uh oh!

ISSOtm commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

ISSOtm commented May 6, 2026

Uh oh!

ISSOtm commented May 6, 2026

Uh oh!

ISSOtm commented May 6, 2026

Uh oh!

avivace left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ISSOtm May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

avivace commented Apr 20, 2026 •

edited

Loading

nummacway commented Apr 20, 2026 •

edited

Loading

ISSOtm commented Apr 20, 2026 •

edited

Loading

ISSOtm commented Apr 21, 2026 •

edited

Loading

ISSOtm May 6, 2026 •

edited

Loading