Rewrite BCPD description of the colour data format#662
Conversation
|
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
left a comment
There was a problem hiding this comment.
Thank you for the wording improvements!
|
rgb555_encoding(1)(1).drawio |
|
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. |
|
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? |
|
Didn't know draw.io was preferred. |
|
This is only the top part of the original file. For those who don't want to open drawio, here's a screenshot: |
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. |
|
I like the diagram, but it took me a little while to understand where you're coming from. 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! |
|
The layer idea was: Small cables over wide cables. |
|
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). |
This comment was marked as resolved.
This comment was marked as resolved.
|
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: 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.
|
I'm now personally happy with the state of this PR, but I'd like opinions from @quinnyo and @nummacway before merging. |
|
Also @DelayRGC, since she opened the original issue. |
| 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! |
There was a problem hiding this comment.
| 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
There was a problem hiding this comment.
I wanted to avoid implying that it would be convention outside of the programs themselves. Perhaps "in writing"?
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
| 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
"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." ?
There was a problem hiding this comment.
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.)
There was a problem hiding this comment.
I'm not sure if the point here is truly about this "convention" or if this note is intended as a way to illustrate that bit 15 is not used by the system.
- If it's about convention, I'd recommend removing the statement entirely. This is because (I think that) Pan Docs can/should avoid commenting on, relying on, or defining convention whereever possible/reasonable.
- If it's an illustrative example, remove the reference/s to convention/canon. Strictly speaking, the reader already has the information, so rephrase this as a caution/tip.
- Possibly focusing more on (not) making assumptions about bit 15, one way or the other, rather than just about
$FFFFand$7FFFboth being white.
- Possibly focusing more on (not) making assumptions about bit 15, one way or the other, rather than just about
dollar prefix:
I'd prefer to see the dollar sign here. Maybe this isn't as common as I'd expect, but to me these prefixes are just a way to tell the parser (human or otherwise) that the value is rendered in a particular way. So 0x or $ just signifies "hexadecimal nybbles follow", not really anything about the meaning of the data.
A (two's complement) signed integer must have the same issue -- in other words, the signed integer $FFFF is not rendered as a number. You have to expend mental effort to interpret it.
I'm not calling them colors!
I agree. I began using the term 'colour word' in my initial changes. I chose to not use 'colour value', though, because of the existing meaning/s of 'value' in colour theory / visual art / HSV.
| 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. |
There was a problem hiding this comment.
| 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
There was a problem hiding this comment.
"by" changes the meaning of the sentence. Maybe "for" would work better?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
What do you think of "for a soft-reset mechanic" rather than "for/by/if implementing a soft-reset mechanic"?
There was a problem hiding this comment.
Yes, changing it to "by" would make it have a different, also undesirable/confusing meaning. But the "if implementing" thing is odd, and the whole point being made is a bit strange, actually:
When wouldn't it be a good idea to initialise all the colours yourself? If they are all white you can't see anything.
Regardless of the behaviour of the boot ROM, it's a "good idea" to initialise the palettes, because you want your palettes to be the ones being used. At least I think so.
[Note: I don't actually know how true the boot ROM statement is, I assume someone checked.]
I know this behaviour is specific to the BG colours, but this "tip" (and the similar one for OB) could be moved up to the general explanation above -- it's really not specific to the register/s.
|
Hi, sorry I haven't been around, I'll be able to have a look at this in a day or so! |
|
Ping? |
|
Reviewing now, sorry! |
quinnyo
left a comment
There was a problem hiding this comment.
It's pretty much there.
The structural change -- moving the explanation out from under the register headings -- is a very welcome one. Good move.
Also good to settle on one set of register names (and on the more sensible Index and Data ones).
The biggest issue I see is not really introduced by this change, but is made more apparent by it -- the lack of basic introductory information about the CGB colours/palettes.
[possible further work] The bit 15 discussion seems to suggest there might be value in adding something about reading/writing hexadecimal colour words. Specifically about the nybbles not being aligned with the R,G,B components and the difficulty in interpreting that.
|
|
||
| The color palettes are stored in two dedicated banks of palette RAM (or <abbr title="Color RAM">CRAM</abbr> for *color RAM*), 64 bytes each[^cram_size]: one for background/window palettes and the other for OBJ palettes. | ||
|
|
||
| The two bytes of each color are stored **little-endian**, meaning that the low byte comes first. |
There was a problem hiding this comment.
explicit byte order -- avoid confusion about most/least significant bit
| The two bytes of each color are stored **little-endian**, meaning that the low byte comes first. | |
| The two bytes of each color are stored in **little-endian** byte order, meaning that the low byte comes first. |
| BGP1 color number 0, and so on. Thus, address $03 allows accessing the second (upper) | ||
| 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. |
There was a problem hiding this comment.
It's real though, right? I mean it's stored somewhere. The PPU "ignores" it, I suppose:
| The 16th bit, bit 15, is **ignored** by the hardware. | |
| The 16th bit, bit 15, has no effect on the colour and is not used for any other purpose by the system. |
| ## LCD Color Palettes (CGB only) | ||
|
|
There was a problem hiding this comment.
Introduction? CGB has colours, palettes.
The old bit summing up the CRAM size was essentially doing this before. (Not that that was a good solution)
|
|
||
| {{#include imgs/src/rgb555.svg}} | ||
|
|
||
| The color palettes are stored in two dedicated banks of palette RAM (or <abbr title="Color RAM">CRAM</abbr> for *color RAM*), 64 bytes each[^cram_size]: one for background/window palettes and the other for OBJ palettes. |
There was a problem hiding this comment.
Palettes haven't really been introduced at this point, but this reads like they have been.
| 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! |
There was a problem hiding this comment.
I'm not sure if the point here is truly about this "convention" or if this note is intended as a way to illustrate that bit 15 is not used by the system.
- If it's about convention, I'd recommend removing the statement entirely. This is because (I think that) Pan Docs can/should avoid commenting on, relying on, or defining convention whereever possible/reasonable.
- If it's an illustrative example, remove the reference/s to convention/canon. Strictly speaking, the reader already has the information, so rephrase this as a caution/tip.
- Possibly focusing more on (not) making assumptions about bit 15, one way or the other, rather than just about
$FFFFand$7FFFboth being white.
- Possibly focusing more on (not) making assumptions about bit 15, one way or the other, rather than just about
dollar prefix:
I'd prefer to see the dollar sign here. Maybe this isn't as common as I'd expect, but to me these prefixes are just a way to tell the parser (human or otherwise) that the value is rendered in a particular way. So 0x or $ just signifies "hexadecimal nybbles follow", not really anything about the meaning of the data.
A (two's complement) signed integer must have the same issue -- in other words, the signed integer $FFFF is not rendered as a number. You have to expend mental effort to interpret it.
I'm not calling them colors!
I agree. I began using the term 'colour word' in my initial changes. I chose to not use 'colour value', though, because of the existing meaning/s of 'value' in colour theory / visual art / HSV.
| This register is used to address a byte in the CGB's background palette RAM. | ||
| Since there are 8 palettes, 8 palettes × 4 colors/palette × 2 bytes/color = 64 bytes | ||
| can be addressed. | ||
| Unlike VRAM, OAM, or wave RAM, CRAM cannot be accessed directly, but instead through pairs of registers: one “data” register provides a one-byte view into CRAM, while the corresponding “index” register controls which CRAM address the data register is bound to. |
There was a problem hiding this comment.
split long sentence
index before access
| Unlike VRAM, OAM, or wave RAM, CRAM cannot be accessed directly, but instead through pairs of registers: one “data” register provides a one-byte view into CRAM, while the corresponding “index” register controls which CRAM address the data register is bound to. | |
| Unlike VRAM, OAM, or wave RAM, CRAM is not exposed in the memory map and cannot be accessed directly. | |
| Instead, each bank of CRAM is accessed through a pair of registers: one register is used to select a CRAM address, and the other provides read/write access to the byte at that address. |
| Since there are 8 palettes, 8 palettes × 4 colors/palette × 2 bytes/color = 64 bytes | ||
| can be addressed. | ||
| Unlike VRAM, OAM, or wave RAM, CRAM cannot be accessed directly, but instead through pairs of registers: one “data” register provides a one-byte view into CRAM, while the corresponding “index” register controls which CRAM address the data register is bound to. | ||
| Much like VRAM, CRAM is inaccessible when the PPU is reading from it, that is, during [Mode 3](<#PPU modes>): writes are ignored, and reads return $FF. |
There was a problem hiding this comment.
With the prior point starting "Unlike VRAM, ..." this one starting "Much like VRAM" makes a slightly off balance contrast.
You could put a "However, ..." at the start, but that reinforces it as an intentional contrast, which doesn't really make sense.
| 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. |
There was a problem hiding this comment.
Yes, changing it to "by" would make it have a different, also undesirable/confusing meaning. But the "if implementing" thing is odd, and the whole point being made is a bit strange, actually:
When wouldn't it be a good idea to initialise all the colours yourself? If they are all white you can't see anything.
Regardless of the behaviour of the boot ROM, it's a "good idea" to initialise the palettes, because you want your palettes to be the ones being used. At least I think so.
[Note: I don't actually know how true the boot ROM statement is, I assume someone checked.]
I know this behaviour is specific to the BG colours, but this "tip" (and the similar one for OB) could be moved up to the general explanation above -- it's really not specific to the register/s.
Co-authored-by: Quinn <3379314+quinnyo@users.noreply.github.com>
|
FWIW, my focus is currently on doing some drawing in order to take a break from programming, so I'll review quinn's contributions to the PR after some days. I'll keep it under two weeks though. |
Co-authored-by: Quinn <3379314+quinnyo@users.noreply.github.com>
Fix wildy incorrect arithmetic Co-authored-by: Eldred Habert <me@eldred.fr>


This is a rewrite of the BCPD section to hopefully reduce possible confusion and make the colour data format less ambiguous.
Particularly:
Fixes #643 (I think)