GBDK 2020 Docs 4.4.0 API Documentation for GBDK 2020

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

Go to the source code of this file.

## Macros
#define | GRAPHICS_WIDTH 160
#define | GRAPHICS_HEIGHT 144
#define | SOLID 0x00 /* Overwrites the existing pixels */
#define | OR 0x01 /* Performs a logical OR */
#define | XOR 0x02 /* Performs a logical XOR */
#define | AND 0x03 /* Performs a logical AND */
#define | WHITE 0
#define | LTGREY 1
#define | DKGREY 2
#define | BLACK 3
#define | M_NOFILL 0
#define | M_FILL 1
#define | SIGNED 1
#define | UNSIGNED 0

## Functions
void | gprint (char *str) NONBANKED
void | gprintln (int16_t number, int8_t radix, int8_t signed_value) NONBANKED
void | gprintn (int8_t number, int8_t radix, int8_t signed_value) NONBANKED
int8_t | gprintf (char *fmt,...) NONBANKED
void | plot (uint8_t x, uint8_t y, uint8_t colour, uint8_t mode) OLDCALL
void | plot_point (uint8_t x, uint8_t y) OLDCALL
void | switch_data (uint8_t x, uint8_t y, uint8_t *src, uint8_t *dst) OLDCALL
void | draw_image (uint8_t *data)
void | line (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2) OLDCALL
void | box (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, uint8_t style) OLDCALL
void | circle (uint8_t x, uint8_t y, uint8_t radius, uint8_t style) OLDCALL
uint8_t | getpix (uint8_t x, uint8_t y) OLDCALL
void | wrtchr (char chr) OLDCALL
void | gotogxy (uint8_t x, uint8_t y) OLDCALL
void | color (uint8_t forecolor, uint8_t backcolor, uint8_t mode) OLDCALL

## Detailed Description

All Points Addressable (APA) mode drawing library.

Drawing routines originally by Pascal Felber Legendary overhall by Jon Fuge : https://github.com/jf1452 Commenting by Michael Hope

Note: The standard text printf() and putchar() cannot be used in APA mode - use gprintf() and wrtchr() instead.

Note: Using drawing.h will cause it's custom VBL and LCD ISRs (`drawing_vbl` and `drawing_lcd`) to be installed. Changing the mode (`mode(M_TEXT_OUT);`) will cause them to be de-installed.

The valid coordinate ranges are from (x,y) 0,0 to 159,143. There is no built-in clipping, so drawing outside valid coordinates will likely produce undesired results (wrapping/etc).

Important note for the drawing API :

The Game Boy graphics hardware is not well suited to frame-buffer style graphics such as the kind provided in `drawing.h`. Due to that, most drawing functions (rectangles, circles, etc) will be slow . When possible it's much faster and more efficient to work with the tiles and tile maps that the Game Boy hardware is built around.

## Macro Definition Documentation

## ◆ GRAPHICS_WIDTH

#define GRAPHICS_WIDTH 160

Size of the screen in pixels

## ◆ GRAPHICS_HEIGHT

#define GRAPHICS_HEIGHT 144

## ◆ SOLID

#define SOLID 0x00 /* Overwrites the existing pixels */

## ◆ OR

#define OR 0x01 /* Performs a logical OR */

## ◆ XOR

#define XOR 0x02 /* Performs a logical XOR */

## ◆ AND

#define AND 0x03 /* Performs a logical AND */

## ◆ WHITE

#define WHITE 0

Possible drawing colours

## ◆ LTGREY

#define LTGREY 1

## ◆ DKGREY

#define DKGREY 2

## ◆ BLACK

#define BLACK 3

## ◆ M_NOFILL

#define M_NOFILL 0

Possible fill styles for box() and circle()

## ◆ M_FILL

#define M_FILL 1

## ◆ SIGNED

#define SIGNED 1

Possible values for signed_value in gprintln() and gprintn()

## ◆ UNSIGNED

#define UNSIGNED 0

## Function Documentation

## ◆ gprint()

void gprint | ( | char * | str | ) |

Print the string 'str' with no interpretation

See also
  gotogxy()

## ◆ gprintln()

void gprintln | ( | int16_t | number,
|  | int8_t | radix,
|  | int8_t | signed_value
| ) |  |

Print 16 bit number in radix (base) in the default font at the current text position.

Parameters

  number | number to print
  radix | radix (base) to print with
  signed_value | should be set to SIGNED or UNSIGNED depending on whether the number is signed or not

The current position is advanced by the numer of characters printed.

See also
  gotogxy()

## ◆ gprintn()

void gprintn | ( | int8_t | number,
|  | int8_t | radix,
|  | int8_t | signed_value
| ) |  |

Print 8 bit number in radix (base) in the default font at the current text position.

See also
  gprintln(), gotogxy()

## ◆ gprintf()

int8_t gprintf | ( | char * | fmt,
|  |  | ...
| ) |  |

Print the string and arguments given by fmt with arguments __...__

Parameters

  fmt | The format string as per printf
  ... | params

Currently supported:

- %c (character)
- %u (int)
- %d (int8_t)
- %o (int8_t as octal)
- %x (int8_t as hex)
- %s (string)

Returns
  Returns the number of items printed, or -1 if there was an error.

See also
  gotogxy()

## ◆ plot()

void plot | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | colour,
|  | uint8_t | mode
| ) |  |

Old style plot - try plot_point()

## ◆ plot_point()

void plot_point | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Plot a point in the current drawing mode and colour at x,y

## ◆ switch_data()

void switch_data | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t * | src,
|  | uint8_t * | dst
| ) |  |

Exchanges the tile on screen at x,y with the tile pointed by src, original tile is saved in dst. Both src and dst may be NULL - saving or copying to screen is not performed in this case.

## ◆ draw_image()

void draw_image | ( | uint8_t * | data | ) |

Draw a full screen image at data

## ◆ line()

void line | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2
| ) |  |

Draw a line in the current drawing mode and colour from x1,y1 to x2,y2

## ◆ box()

void box | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2,
|  | uint8_t | style
| ) |  |

Draw a box (rectangle) with corners x1,y1 and x2,y2 using fill mode style (one of NOFILL or FILL)

## ◆ circle()

void circle | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | radius,
|  | uint8_t | style
| ) |  |

Draw a circle with centre at x,y and radius using fill mode style (one of NOFILL or FILL)

## ◆ getpix()

uint8_t getpix | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Returns the current colour of the pixel at x,y

## ◆ wrtchr()

void wrtchr | ( | char | chr | ) |

Prints the character chr in the default font at the current text position.

The current position is advanced by 1 after the character is printed.

See also
  gotogxy()

## ◆ gotogxy()

void gotogxy | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Sets the current text position to x,y.

Note: x and y have units of tiles (8 pixels per unit)

See also
  wrtchr()

## ◆ color()

void color | ( | uint8_t | forecolor,
|  | uint8_t | backcolor,
|  | uint8_t | mode
| ) |  |

Set the current forecolor colour, backcolor colour, and draw mode

Parameters

  forecolor | The primary drawing color (outlines of rectangles with box(), letter color with gprintf(), etc).
  backcolor | Secondary or background color where applicable (fill color of rectangles with box() when M_FILL is specifed, background color of text with gprintf(), etc).
  mode | Drawing style to use. Several settings are available `SOLID`, `OR`, `XOR`, `AND`.

In order to completely overwrite existing pixels use `SOLID` for mode