GBDK 2020 Docs API Documentation for GBDK 2020

Macros | Functions
cgb.h File Reference
`#include <types.h>`

Go to the source code of this file.

## Macros
#define | RGB(r, g, b) ((((UINT16)(b) & 0x1f) << 10) | (((UINT16)(g) & 0x1f) << 5) | (((UINT16)(r) & 0x1f) << 0))
#define | RGB_RED RGB(31, 0, 0)
#define | RGB_DARKRED RGB(15, 0, 0)
#define | RGB_GREEN RGB( 0, 31, 0)
#define | RGB_DARKGREEN RGB( 0, 15, 0)
#define | RGB_BLUE RGB( 0, 0, 31)
#define | RGB_DARKBLUE RGB( 0, 0, 15)
#define | RGB_YELLOW RGB(31, 31, 0)
#define | RGB_DARKYELLOW RGB(21, 21, 0)
#define | RGB_CYAN RGB( 0, 31, 31)
#define | RGB_AQUA RGB(28, 5, 22)
#define | RGB_PINK RGB(11, 0, 31)
#define | RGB_PURPLE RGB(21, 0, 21)
#define | RGB_BLACK RGB( 0, 0, 0)
#define | RGB_DARKGRAY RGB(10, 10, 10)
#define | RGB_LIGHTGRAY RGB(21, 21, 21)
#define | RGB_WHITE RGB(31, 31, 31)
#define | RGB_LIGHTFLESH RGB(30, 20, 15)
#define | RGB_BROWN RGB(10, 10, 0)
#define | RGB_ORANGE RGB(30, 20, 0)
#define | RGB_TEAL RGB(15, 15, 0)

## Functions
void | set_bkg_palette (UINT8 first_palette, UINT8 nb_palettes, UINT16 *rgb_data) NONBANKED
void | set_sprite_palette (UINT8 first_palette, UINT8 nb_palettes, UINT16 *rgb_data) NONBANKED
void | set_bkg_palette_entry (UINT8 palette, UINT8 entry, UINT16 rgb_data)
void | set_sprite_palette_entry (UINT8 palette, UINT8 entry, UINT16 rgb_data)
void | cpu_slow (void)
void | cpu_fast (void)
void | cgb_compatibility (void)

## Detailed Description

Support for the Color GameBoy (CGB).

Enabling CGB features

To unlock and use CGB features and registers you need to change byte 0143h in the cartridge header. Otherwise, the CGB will operate in monochrome "Non CGB" compatibility mode.

- Use a value of 80h for games that support CGB and monochrome gameboys
  (with Lcc: -Wm-yc, or makebin directly: -yc)
- Use a value of C0h for CGB only games.
  (with Lcc: -Wm-yC, or makebin directly: -yC)

See the Pan Docs for more information CGB features.

## Macro Definition Documentation

## ◆ RGB

#define RGB | ( |  | r,
|  |  | g,
|  |  | b
| ) |  | ((((UINT16)(b) & 0x1f) << 10) | (((UINT16)(g) & 0x1f) << 5) | (((UINT16)(r) & 0x1f) << 0))

Macro to create a CGB palette color entry out of the color components.

Parameters

  r | Red Component, range 0 - 31 (31 brightest)
  g | Green Component, range 0 - 31 (31 brightest)
  b | Blue Component, range 0 - 31 (31 brightest)

The resulting format is BGR 15bpp.

See also
  set_bkg_palette(), set_sprite_palette()

## ◆ RGB_RED

#define RGB_RED RGB(31, 0, 0)

Common colors based on the EGA default palette.

## ◆ RGB_DARKRED

#define RGB_DARKRED RGB(15, 0, 0)

## ◆ RGB_GREEN

#define RGB_GREEN RGB( 0, 31, 0)

## ◆ RGB_DARKGREEN

#define RGB_DARKGREEN RGB( 0, 15, 0)

## ◆ RGB_BLUE

#define RGB_BLUE RGB( 0, 0, 31)

## ◆ RGB_DARKBLUE

#define RGB_DARKBLUE RGB( 0, 0, 15)

## ◆ RGB_YELLOW

#define RGB_YELLOW RGB(31, 31, 0)

## ◆ RGB_DARKYELLOW

#define RGB_DARKYELLOW RGB(21, 21, 0)

## ◆ RGB_CYAN

#define RGB_CYAN RGB( 0, 31, 31)

## ◆ RGB_AQUA

#define RGB_AQUA RGB(28, 5, 22)

## ◆ RGB_PINK

#define RGB_PINK RGB(11, 0, 31)

## ◆ RGB_PURPLE

#define RGB_PURPLE RGB(21, 0, 21)

## ◆ RGB_BLACK

#define RGB_BLACK RGB( 0, 0, 0)

## ◆ RGB_DARKGRAY

#define RGB_DARKGRAY RGB(10, 10, 10)

## ◆ RGB_LIGHTGRAY

#define RGB_LIGHTGRAY RGB(21, 21, 21)

## ◆ RGB_WHITE

#define RGB_WHITE RGB(31, 31, 31)

## ◆ RGB_LIGHTFLESH

#define RGB_LIGHTFLESH RGB(30, 20, 15)

## ◆ RGB_BROWN

#define RGB_BROWN RGB(10, 10, 0)

## ◆ RGB_ORANGE

#define RGB_ORANGE RGB(30, 20, 0)

## ◆ RGB_TEAL

#define RGB_TEAL RGB(15, 15, 0)

## Function Documentation

## ◆ set_bkg_palette()

void set_bkg_palette | ( | UINT8 | first_palette,
|  | UINT8 | nb_palettes,
|  | UINT16 * | rgb_data
| ) |  |

Set CGB background palette(s).

Parameters

  first_palette | Index of the first palette to write (0-7)
  nb_palettes | Number of palettes to write (1-8, max depends on first_palette)
  rgb_data | Pointer to source palette data

Writes nb_palettes to background palette data starting at first_palette, Palette data is sourced from rgb_data.

- Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry.
- Each color (4 per palette) is packed as BGR 15bpp format (1:5:5:5, MSBit [15] is unused).
- Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest.

See also
  RGB(), set_bkg_palette_entry()

## ◆ set_sprite_palette()

void set_sprite_palette | ( | UINT8 | first_palette,
|  | UINT8 | nb_palettes,
|  | UINT16 * | rgb_data
| ) |  |

Set CGB sprite palette(s).

Parameters

  first_palette | Index of the first palette to write (0-7)
  nb_palettes | Number of palettes to write (1-8, max depends on first_palette)
  rgb_data | Pointer to source palette data

Writes nb_palettes to sprite palette data starting at first_palette, Palette data is sourced from rgb_data.

- Each Palette is 8 bytes in size: 4 colors x 2 bytes per palette color entry.
- Each color (4 per palette) is packed as BGR 15bpp format (1:5:5:5, MSBit [15] is unused).
- Each component (R, G, B) may have values from 0 - 31 (5 bits), 31 is brightest.

See also
  RGB(), set_sprite_palette_entry()

## ◆ set_bkg_palette_entry()

void set_bkg_palette_entry | ( | UINT8 | palette,
|  | UINT8 | entry,
|  | UINT16 | rgb_data
| ) |  |

Sets a single color in the specified CGB background palette.

Parameters

  palette | Index of the palette to modify (0-7)
  entry | Index of color in palette to modify (0-3)
  rgb_data | New color data in BGR 15bpp format.

See also
  set_bkg_palette(), RGB()

## ◆ set_sprite_palette_entry()

void set_sprite_palette_entry | ( | UINT8 | palette,
|  | UINT8 | entry,
|  | UINT16 | rgb_data
| ) |  |

Sets a single color in the specified CGB sprite palette.

Parameters

  palette | Index of the palette to modify (0-7)
  entry | Index of color in palette to modify (0-3)
  rgb_data | New color data in BGR 15bpp format.

See also
  set_sprite_palette(), RGB()

## ◆ cpu_slow()

void cpu_slow | ( | void |  | ) |

Set CPU speed to slow (Normal Speed) operation.

Interrupts are temporarily disabled and then re-enabled during this call.

In this mode the CGB operates at the same speed as the DMG/Pocket/SGB models.

- You can check to see if _cpu == CGB_TYPE before using this function.

See also
  cpu_fast()

## ◆ cpu_fast()

void cpu_fast | ( | void |  | ) |

Set CPU speed to fast (CGB Double Speed) operation.

On startup the CGB operates in Normal Speed Mode and can be switched into Double speed mode (faster processing but also higher power consumption). See the Pan Docs for more information about which hardware features operate faster and which remain at Normal Speed.

- Interrupts are temporarily disabled and then re-enabled during this call.
- You can check to see if _cpu == CGB_TYPE before using this function.

See also
  cpu_slow(), _cpu

## ◆ cgb_compatibility()

void cgb_compatibility | ( | void |  | ) |

Set defaults compatible with the normal GameBoy models.

The default/first CGB palettes for sprites and backgrounds are set to a similar default appearance as on the DMG/Pocket/SGB models. (White, Light Gray, Dark Gray, Black)

- You can check to see if _cpu == CGB_TYPE before using this function.