Document the CGB OAM vs BG priority

[alloncm]

Hi,
when adding support for CGB to my GameBoy emulator, I noticed in the development of the new PPU that in the CGB mode the priority between the background layer and the sprites layer is not documented well and I couldn't figure out exactly the correct behavior and besides cgb-acid2 which really helped me there were no resources (at least that I found) so I decided to try and test it myself.

I wrote a test rom for this and documented the expected behavior in the readme of the project but I thought maybe it will better to upstream this to the Pandocs as well.

Wanted to verify that this indeed is a requested feature before I actually add this and open a PR.

Thanks

[ISSOtm]

It is documented under the OBJ priority section (the green box). Is the location not appropriate?

Regardless, the test ROM would be appreciated!

[alloncm]

The location is nice (even though I'm not a UX person at all), I read this section when searching for documentation.
Perhaps Im missing something but this section is not complete and as far I understand there is more this topic than just that.

On the CGB the there are 3 different places where this priority is declared (this section refers to only 1 of them):

1. OAM Attributes bit 7 - source
2. LCDC bit 0 - in Gameboy Color this bit changes its purpose and defines the priority of the background - source
3. BG Map Attribute bit 7 - source

You can read more about in the readme of my test rom (I didn't want to copy paste it all here)

The bottom line is that as far as I understand the relations and priorities between all those flags is not described at the Pandocs and I wanted to add an explanation for this (not sure where though).

Regardless of this you are free to use my test rom - https://github.com/alloncm/MagenTests (or tell me how to integrate it to this project myself).

[ISSOtm]

Okay, I think I see what you mean. I believe this is described by #379:

pandocs/src/Rendering_Internals.md

Lines 252 to 258 in bbdc0ef

	The selection follows the following rules:
	1. **In CGB Mode**, if [`LCDC` bit 0 (priority enable)](<#CGB Mode: BG and Window master priority>) is reset, pick the BG pixel.
	1. **In Non-CGB Mode**, if [`LCDC` bit 0 (BG & Window enable)](<#Non-CGB Mode (DMG, SGB and CGB in compatibility mode): BG and Window display>) is reset, pick the OBJ pixel.
	1. If [`LCDC` bit 1 (OBJ enable)](<#LCDC.1 — OBJ enable>) is reset, pick the BG pixel. ⚠️ See [above](<#OBJ fetcher>) for a note about this bit.
	1. **In CGB Mode**, if the BG pixel has [its priority bit](<#BG Map attributes (CGB Mode only)>) set, and its ID is not 0, pick the BG pixel.
	1. If the OBJ pixel has [its priority bit](<#Byte 3 — Attributes/Flags>) set, and the BG pixel's ID is not 0, pick the BG pixel.
	1. If the OBJ pixel is 0, pick the BG pixel; otherwise, pick the OBJ pixel.

Is that suitable?

[alloncm]

This is kind of what I meant but I have a few comments on this

1. If my test rom is correct (tested against SameBoy and BGB but unfortunately not against original hardware) then those heuristics are incomplete and some are not accurate (I can elaborate on this if necessary).
2. The relations between the three flags are not described explicitly and the correct behavior in case one or more flags is set is ambiguous.
3. In my opinion this info should not be part of the rendering internal (which seems to me like an awesome enrichment section) but rather a crucial detail about the CGB PPU that is important in order to use and debug it correctly.

Anyway I do believe this info is important for a correct use of the CGB PPU and could be added even before this PR is merged (which could take some time as I understand).

BTW I can't wait for this awesome PR to be merged already (it could have really helped me with my emulator).

[ISSOtm]

I confirmed the test ROM yields the same results on BGB than on my CGB-B and AGB.

I'd put the interaction between all of these priorities either in a dedicated "overview" page, or next to the CGB-only BG attributes (since there is only a single source of priority on DMG, hence this problem does not apply there).