gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
gbdk-lib/include/gb/cgb.h
1 /** @file gb/cgb.h
2 Support for the Color GameBoy (CGB).
3
4 __Enabling CGB features__
5
6 To unlock and use CGB features and registers you need to
7 change byte 0143h in the cartridge header. Otherwise, the CGB
8 will operate in monochrome "Non CGB" compatibility mode.
9 \li Use a value of __80h__ for games that support CGB and monochrome gameboys
10 \n (with Lcc: __-Wm-yc__, or makebin directly: __-yc__)
11 \li Use a value of __C0h__ for CGB only games.
12 \n (with Lcc: __-Wm-yC__, or makebin directly: __-yC__)
13
14 See the Pan Docs for more information CGB features.
15 */
16
17 #ifndef _CGB_H
18 #define _CGB_H
19
20 #include <types.h>
21 #include <stdint.h>
22
23 /** Macro to create a CGB palette color entry out of 5-bit color components.
24
25 @param r 5-bit Red Component, range 0 - 31 (31 brightest)
26 @param g 5-bit Green Component, range 0 - 31 (31 brightest)
27 @param b 5-bit Blue Component, range 0 - 31 (31 brightest)
28
29 The resulting format is bitpacked BGR-555 in a uint16_t.
30
31 @see set_bkg_palette(), set_sprite_palette(), RGB8(), RGBHTML()
32 */
33 #define RGB(r, g, b) ((uint16_t)((((b) & 0x1f) << 10) | ((uint16_t)(((g) & 0x1f) << 5)) | ((r) & 0x1f)))
34
35 /** Macro to create a CGB palette color entry out of 8-bit color components.
36
37 @param r 8-bit Red Component, range 0 - 255 (255 brightest)
38 @param g 8-bit Green Component, range 0 - 255 (255 brightest)
39 @param b 8-bit Blue Component, range 0 - 255 (255 brightest)
40
41 The resulting format is bitpacked BGR-555 in a uint16_t.
42
43 The lowest 3 bits of each color component are dropped during conversion.
44
45 @see set_bkg_palette(), set_sprite_palette(), RGB(), RGBHTML()
46 */
47 #define RGB8(r, g, b) (((uint16_t)((((b) >> 3) & 0x1f) << 10)) | ((uint16_t)((((g) >> 3) & 0x1f) << 5)) | (((r) >> 3) & 0x1f))
48
49 /** Macro to convert a 24 Bit RGB color to a CGB palette color entry.
50
51 @param RGB24bit Bit packed RGB-888 color (0-255 for each color component).
52
53 The resulting format is bitpacked BGR-555 in a uint16_t.
54
55 The lowest 3 bits of each color component are dropped during conversion.
56
57 @see set_bkg_palette(), set_sprite_palette(), RGB(), RGB8()
58 */
59 #define RGBHTML(RGB24bit) (RGB8((((RGB24bit) >> 16) & 0xff), (((RGB24bit) >> 8) & 0xff), ((RGB24bit) & 0xff)))
60
61 /** Common colors based on the EGA default palette.
62 */
63 #define RGB_RED RGB(31, 0, 0)
64 #define RGB_DARKRED RGB(15, 0, 0)
65 #define RGB_GREEN RGB( 0, 31, 0)
66 #define RGB_DARKGREEN RGB( 0, 15, 0)
67 #define RGB_BLUE RGB( 0, 0, 31)
68 #define RGB_DARKBLUE RGB( 0, 0, 15)
69 #define RGB_YELLOW RGB(31, 31, 0)
70 #define RGB_DARKYELLOW RGB(21, 21, 0)
71 #define RGB_CYAN RGB( 0, 31, 31)
72 #define RGB_AQUA RGB(28, 5, 22)
73 #define RGB_PINK RGB(31, 0, 31)
74 #define RGB_PURPLE RGB(21, 0, 21)
75 #define RGB_BLACK RGB( 0, 0, 0)
76 #define RGB_DARKGRAY RGB(10, 10, 10)
77 #define RGB_LIGHTGRAY RGB(21, 21, 21)
78 #define RGB_WHITE RGB(31, 31, 31)
79
80 #define RGB_LIGHTFLESH RGB(30, 20, 15)
81 #define RGB_BROWN RGB(10, 10, 0)
82 #define RGB_ORANGE RGB(30, 20, 0)
83 #define RGB_TEAL RGB(15, 15, 0)
84
85 typedef uint16_t palette_color_t; /**< 16 bit color entry */
86
87 /** Set CGB background palette(s).
88
89 @param first_palette Index of the first palette to write (0-7)
90 @param nb_palettes Number of palettes to write (1-8, max depends on first_palette)
91 @param rgb_data Pointer to source palette data
92
93 Writes __nb_palettes__ to background palette data starting
94 at __first_palette__, Palette data is sourced from __rgb_data__.
95
96 \li Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry.
97 \li Each color (4 per palette) is packed as BGR-555 format (1:5:5:5, MSBit [15] is unused).
98 \li Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest.
99
100 @see RGB(), set_bkg_palette_entry()
101 @see BKGF_CGB_PAL0, BKGF_CGB_PAL1, BKGF_CGB_PAL2, BKGF_CGB_PAL3
102 @see BKGF_CGB_PAL4, BKGF_CGB_PAL5, BKGF_CGB_PAL6, BKGF_CGB_PAL7
103 */
104 void set_bkg_palette(uint8_t first_palette, uint8_t nb_palettes, const palette_color_t *rgb_data) PRESERVES_REGS(b, c);
105
106 /** Set CGB sprite palette(s).
107
108 @param first_palette Index of the first palette to write (0-7)
109 @param nb_palettes Number of palettes to write (1-8, max depends on first_palette)
110 @param rgb_data Pointer to source palette data
111
112 Writes __nb_palettes__ to sprite palette data starting
113 at __first_palette__, Palette data is sourced from __rgb_data__.
114
115 \li Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry.
116 \li Each color (4 per palette) is packed as BGR-555 format (1:5:5:5, MSBit [15] is unused).
117 \li Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest.
118
119 @see RGB(), set_sprite_palette_entry()
120 @see OAMF_CGB_PAL0, OAMF_CGB_PAL1, OAMF_CGB_PAL2, OAMF_CGB_PAL3
121 @see OAMF_CGB_PAL4, OAMF_CGB_PAL5, OAMF_CGB_PAL6, OAMF_CGB_PAL7
122 */
123 void set_sprite_palette(uint8_t first_palette, uint8_t nb_palettes, const palette_color_t *rgb_data) PRESERVES_REGS(b, c);
124
125 /** Sets a single color in the specified CGB background palette.
126
127 @param palette Index of the palette to modify (0-7)
128 @param entry Index of color in palette to modify (0-3)
129 @param rgb_data New color data in BGR 15bpp format.
130
131 @see set_bkg_palette(), RGB()
132 @see BKGF_CGB_PAL0, BKGF_CGB_PAL1, BKGF_CGB_PAL2, BKGF_CGB_PAL3
133 @see BKGF_CGB_PAL4, BKGF_CGB_PAL5, BKGF_CGB_PAL6, BKGF_CGB_PAL7
134 */
135
136 void set_bkg_palette_entry(uint8_t palette, uint8_t entry, uint16_t rgb_data) PRESERVES_REGS(b, c);
137
138 /** Sets a single color in the specified CGB sprite palette.
139
140 @param palette Index of the palette to modify (0-7)
141 @param entry Index of color in palette to modify (0-3)
142 @param rgb_data New color data in BGR 15bpp format.
143
144 @see set_sprite_palette(), RGB()
145 @see OAMF_CGB_PAL0, OAMF_CGB_PAL1, OAMF_CGB_PAL2, OAMF_CGB_PAL3
146 @see OAMF_CGB_PAL4, OAMF_CGB_PAL5, OAMF_CGB_PAL6, OAMF_CGB_PAL7
147 */
148 void set_sprite_palette_entry(uint8_t palette, uint8_t entry, uint16_t rgb_data) PRESERVES_REGS(b, c);
149
150 /** Set CPU speed to slow (Normal Speed) operation.
151
152 Interrupts are temporarily disabled and then re-enabled during this call.
153
154 In this mode the CGB operates at the same speed as the DMG/Pocket/SGB models.
155
156 \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function.
157
158 @see cpu_fast()
159 */
160 void cpu_slow(void);
161
162 /** Set CPU speed to fast (CGB Double Speed) operation.
163
164 On startup the CGB operates in Normal Speed Mode and can be switched
165 into Double speed mode (faster processing but also higher power consumption).
166 See the Pan Docs for more information about which hardware features
167 operate faster and which remain at Normal Speed.
168
169 \li Interrupts are temporarily disabled and then re-enabled during this call.
170 \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function.
171
172 @see cpu_slow(), _cpu
173 */
174 void cpu_fast(void);
175
176 /** Sets CGB palette 0 to be compatible with the DMG/GBP.
177
178 The default/first CGB palettes for sprites and backgrounds are
179 set to a similar default appearance as on the DMG/Pocket/SGB models.
180 (White, Light Gray, Dark Gray, Black)
181
182 \li You can check to see if @ref _cpu == @ref CGB_TYPE before using this function.
183 */
184 void set_default_palette(void);
185
186 /** Obsolete. This function has been replaced by set_default_palette(), which has identical behavior.
187 */
188 void cgb_compatibility(void);
189
190 #endif /* _CGB_H */
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.