Tiny Graphics Interface

Ullrich von Bassewitz,
Stefan A. Haubenthal,
Greg King

The cc65 library provides functions for platform independent graphics. Include the tgi.h header file to get the necessary definitions, see also samples/tgidemo.c and samples/mandelbrot.c.

1. tgi.h

1. tgi.h

1.1 tgi_arc

Function

Draw an elliptic arc in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_arc (int x, int y, unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);

Description

The function draws an elliptic arc with center at x/y and radii rx/ry using the current drawing color. The arc covers the angle between sa and ea (startangle and endangle), which must be in the range 0..360.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function behaves unexpectedly or may crash if the angles are out of range.

Availability

cc65

See also

tgi_bar, tgi_circle, tgi_ellipse, tgi_pieslice, tgi_setcolor

Example

/* Draw the upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_arc (50, 50, 40, 20, 0, 180);

1.2 tgi_bar

Function

The function fills a rectangle on the drawpage with the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_bar (int x1, int y1, int x2, int y2);

Description

The function fills a rectangle on the drawpage with the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi function

Example

tgi_setcolor(TGI_COLOR_GREEN);
tgi_bar(10, 10, 100, 60);

1.3 tgi_circle

Function

The function draws a circle in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_circle (int x, int y, unsigned char radius);

Description

The function draws a circle in the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_ellipse, tgi_pieslice, tgi_setcolor

Example

tgi_setcolor(TGI_COLOR_BLACK);
tgi_circle(50, 40, 40);

1.4 tgi_clear

Function

Clear the drawpage

Header

tgi.h

Declaration

void tgi_clear (void);

Description

Clear the drawpage

Availability

cc65

See also

Other tgi functions

Example

None.

1.5 tgi_done

Function

End graphics mode, switch back to text mode. Will NOT uninstall or unload the driver!

Header

tgi.h

Declaration

void tgi_done (void);

Description

End graphics mode, switch back to text mode. Will NOT uninstall or unload the driver!

Availability

cc65

See also

Other tgi functions

Example

None.

1.6 tgi_ellipse

Function

The function draws an ellipse in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_ellipse (int x, int y, unsigned char rx, unsigned char ry);

Description

The function draws an ellipse at position x/y with radii rx and ry, using the current drawing color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_circle, tgi_pieslice, tgi_setcolor

Example

tgi_setcolor(TGI_COLOR_RED);
tgi_ellipse (50, 40, 40, 20);

1.7 tgi_free_vectorfont

Function

Free a vector font that was previously loaded into memory.

Header

tgi.h

Declaration

void __fastcall__ tgi_free_vectorfont (const tgi_vectorfont* font);

Description

Free a vector font that was previously loaded into memory.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_vectorfont, tgi_install_vectorfont

Example

None.

1.8 tgi_getaspectratio

Function

Return the pixel aspect ratio.

Header

tgi.h

Declaration

unsigned tgi_getaspectratio (void);

Description

The function returns the pixel aspect ratio for the current driver and display as an 8.8 fixed point value. It may be used to correct geometric shapes so they look correct on the display. As an example, a circle with a radius of 100 pixels may look elliptic on some driver/display combinations if the aspect ratio is not 1.00.

Notes

  • The aspect ratio is encoded in the TGI driver which assumes a "standard" monitor for the given platform. The aspect ratio may be wrong if another monitor is used.
  • No TGI function will use the aspect ratio. It is up to the programmer to make use of it.
  • The tgi_setaspectratio function can be used to change the aspect ratio for a loaded driver. The value is not reset by tgi_init, so if a driver is linked statically to an application, switching into and out of graphics mode will not restore the original aspect ratio.

Availability

cc65

See also

tgi_setaspectratio

Example

None.

1.9 tgi_getcolor

Function

Return the current drawing color.

Header

tgi.h

Declaration

unsigned char tgi_getcolor (void);

Description

The actual color is an index to a palette. During tgi_init you will get a default palette. The number of colors depend on the platform. All platforms recognize at least TGI_COLOR_BLACK and TGI_COLOR_WHITE. But some platforms have many more predefined colors. If you paint using TGI_COLOR_GREEN and then you change the green of the palette to blue using tgi_setpalette then after this painting in TGI_COLOR_GREEN will actually be blue.

Availability

cc65

See also

Other tgi functions

Example

color = tgi_getcolor();

1.10 tgi_getcolorcount

Function

Get the number of available colors.

Header

tgi.h

Declaration

unsigned char tgi_getcolorcount (void);

Description

TGI platforms use indexed color palettes. This function returns the number of entries we can use in the palette.

tgi_setcolor() can accept numbers from 0 to 255. That is 256 possible colors, but an (unsigned char) cannot hold that number. Therefore, the number zero is used to indicate when a palette has 256 entries. A portable program should test for that number, and do appropriate actions. A program might assign the count to an unsigned int (and change a zero to a 256). Or, it might rely on the fact that (unsigned char) will "wrap-around" when it is incremented beyond 255.

Availability

cc65

See also

tgi_getcolor(), tgi_getdefpalette(), tgi_getmaxcolor(), tgi_getpalette(), tgi_setcolor(), tgi_setpalette()

Examples

if (tgi_getcolorcount() == 2) {
  printf("Only monochrome graphics is supported\n");
}

static unsigned char num_colors;
static unsigned char color;
...
num_colors = tgi_getcolorcount();
...
++color;
if (num_colors == 0) {
  tgi_setcolor(color);
} else {
  tgi_setcolor(color % num_colors);
}

1.11 tgi_getdefpalette

Function

Get the palette installed by default.

Header

tgi.h

Declaration

const unsigned char* tgi_getdefpalette (void);

Description

The tgi driver has a default palette that is active at startup. The named colors TGI_COLOR_BLACK, TGI_COLOR_WHITE, TGI_COLOR_RED... need this palette to work correctly.

Availability

cc65

See also

Other tgi functions

Example

None.

1.12 tgi_geterror

Function

Return the error code for the last operation. This will also clear the error.

Header

tgi.h

Declaration

unsigned char tgi_geterror (void);

Description

Return the error code for the last operation. This will also clear the error.

Availability

cc65

See also

Other tgi functions

Example

None.

1.13 tgi_geterrormsg

Function

Get an error message describing the error.

Header

tgi.h

Declaration

const char* __fastcall__ tgi_geterrormsg (unsigned char code);

Description

Get an error message describing the error.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions

Example

None.

1.14 tgi_getmaxcolor

Function

Get the highest index of the palette.

Header

tgi.h

Declaration

unsigned char tgi_getmaxcolor (void);

Description

Get the highest index of the palette.

Availability

cc65

See also

tgi_getcolor(), tgi_getcolorcount(), tgi_getdefpalette(), tgi_getpalette(), tgi_setcolor(), tgi_setpalette()

Example

None.

1.15 tgi_getmaxx

Function

Get the maximum x coordinate that can be used on this screen.

Header

tgi.h

Declaration

unsigned tgi_getmaxx (void);

Description

Get the maximum x coordinate that can be used on this screen.

Availability

cc65

See also

Other tgi functions

Example

None.

1.16 tgi_getmaxy

Function

Get the maximum y coordinate that can be used on this screen.

Header

tgi.h

Declaration

unsigned tgi_getmaxy (void);

Description

Get the maximum y coordinate that can be used on this screen.

Availability

cc65

See also

Other tgi functions

Example

None.

1.17 tgi_getpagecount

Function

Return the number of screen pages available.

Header

tgi.h

Declaration

unsigned tgi_getpagecount (void);

Description

Return the number of screen pages available.

Availability

cc65

See also

tgi_setdrawpage, tgi_setviewpage

Example

None.

1.18 tgi_getpalette

Function

Get the palette installed.

Header

tgi.h

Declaration

const unsigned char* tgi_getpalette (void);

Description

Get the palette installed.

Availability

cc65

See also

Other tgi functions

Example

None.

1.19 tgi_getpixel

Function

Get the color of a pixel from the viewpage.

Header

tgi.h

Declaration

unsigned char __fastcall__ tgi_getpixel (int x, int y);

Description

Get the color of a pixel from the viewpage.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.20 tgi_gettextheight

Function

Calculate the height of the text in pixels according to the current text style.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_gettextheight (const char* s);

Description

Calculate the height of the text in pixels according to the current text style.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.21 tgi_gettextwidth

Function

Calculate the width of the text in pixels according to the current text style.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_gettextwidth (const char* s);

Description

Calculate the width of the text in pixels according to the current text style.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.22 tgi_getxres

Function

Get number of horisontal pixels on the screen.

Header

tgi.h

Declaration

unsigned tgi_getxres (void);

Description

Get number of horisontal pixels on the screen. This is same as tgi_maxx()+1.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.23 tgi_getyres

Function

Get number of vertical pixels on the screen.

Header

tgi.h

Declaration

unsigned tgi_getyres (void);

Description

Get number of vertical pixels on the screen. This is same as tgi_maxy()+1.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.24 tgi_gotoxy

Function

Set graphics cursor at x, y.

Header

tgi.h

Declaration

void __fastcall__ tgi_gotoxy (int x, int y);

Description

Set graphics cursor at x, y.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.25 tgi_init

Function

Initialize the already loaded graphics driver.

Header

tgi.h

Declaration

void tgi_init (void);

Description

The tgi_init function will set the default palette to the hardware.

Notes

  • tgi_init will not clear the screen. This allows switching between text and graphics mode on platforms that have separate memory areas for the screens. If you want the screen cleared, call tgi_clear after tgi_init.

Availability

cc65

See also

Other tgi functions.

Example

tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it.
tgi_init(); //Set up the default palette and clear the screen.

1.26 tgi_install

Function

Install an already loaded driver and return an error code.

Header

tgi.h

Declaration

unsigned char __fastcall__ tgi_install (const void* driver);

Description

The function installs a driver that was already loaded into memory (or linked statically to the program). It returns an error code (TGI_ERR_OK in case of success).

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_driver, tgi_uninstall, tgi_unload

Example

tgi_install(tgi_static_stddrv); //Include the driver statically instead of loading it.
tgi_init(); //Set up the default palette and clear the screen.

1.27 tgi_install_vectorfont

Function

Install an already loaded driver and return an error code.

Header

tgi.h

Declaration

void __fastcall__ tgi_install_vectorfont (const tgi_vectorfont* font);

Description

Install a vector font for use. More than one vector font can be loaded, but only one can be active. This function is used to tell which one. Call with a NULL pointer to uninstall the currently installed font.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_load_vectorfont, tgi_free_vectorfont

Example

None.

1.28 tgi_ioctl

Function

Platform dependent code extensions.

Header

tgi.h

Declaration

unsigned __fastcall__ tgi_ioctl (unsigned char code, void* data);

Description

Some platforms have extra display hardware that is not supported by standard tgi functions. You can extend the driver to support this extra hardware using tgi_ioctl functions.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • These functions are not easily portable to other cc65 platforms.

Availability

cc65

See also

Other tgi functions.

Example

#define tgi_sprite(spr) tgi_ioctl(0, (void*)(spr))
#define tgi_flip() tgi_ioctl(1, (void*)0)
#define tgi_setbgcolor(bgcol) tgi_ioctl(2, (void*)(bgcol))
#define tgi_setframerate(rate) tgi_ioctl(3, (void*)(rate))
#define tgi_busy() tgi_ioctl(4, (void*)0)
#define tgi_updatedisplay() tgi_ioctl(4, (void*)1)
if (!tgi_busy()) {
  tgi_sprite(&background);
  tgi_setcolor(TGI_COLOR_BLUE);
  tgi_outttextxy(20,40,"Hello World");
  tgi_updatedisplay();
}

1.29 tgi_line

Function

Draw a line in the current drawing color. The graphics cursor will be set to x2/y2 by this call.

Header

tgi.h

Declaration

void __fastcall__ tgi_line (int x1, int y1, int x2, int y2);

Description

Draw a line in the current drawing color. The graphics cursor will be set to x2/y2 by this call.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.30 tgi_lineto

Function

Draw a line in the current drawing color from the graphics cursor to the new end point. The graphics cursor will be updated to x2/y2.

Header

tgi.h

Declaration

void __fastcall__ tgi_lineto (int x2, int y2);

Description

Draw a line in the current drawing color from the graphics cursor to the new end point. The graphics cursor will be updated to x2/y2.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.31 tgi_load_driver

Function

Load and install the given driver.

Header

tgi.h

Declaration

void __fastcall__ tgi_load_driver (const char *name);

Description

Load and install the driver by name. Will just load the driver and check if loading was successful. Will not switch to graphics mode.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.32 tgi_load_vectorfont

Function

Load the given vector font.

Header

tgi.h

Declaration

const tgi_vectorfont* __fastcall__ tgi_load_vectorfont (const char* name);

Description

Load a vector font into memory and return it. In case of errors, NULL is returned and an error is set, which can be retrieved using tgi_geterror. To use the font, it has to be installed using tgi_install_vectorfont.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_install_vectorfont, tgi_free_vectorfont

Example

None.

1.33 tgi_outtext

Function

Output text at the current graphics cursor position. The graphics cursor is moved to the end of the text.

Header

tgi.h

Declaration

void __fastcall__ tgi_outtext (const char* s);

Description

Output text at the current graphics cursor position. The graphics cursor is moved to the end of the text.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.34 tgi_outtextxy

Function

Output text at the given cursor position. The graphics cursor is moved to the end of the text.

Header

tgi.h

Declaration

void __fastcall__ tgi_outtextxy (int x, int y, const char* s);

Description

Output text at the given cursor position. The graphics cursor is moved to the end of the text.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.35 tgi_pieslice

Function

Draw an elliptic pie slice in the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_pie slice (int x, int y, unsigned char rx, unsigned char ry, unsigned sa, unsigned ea);

Description

The function draws an elliptic pie slice with center at x/y and radii rx/ry using the current drawing color. The pie slice covers the angle between sa and ea (startangle and endangle), which must be in the range 0..360.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.
  • The function behaves unexpectedly or may crash if the angles are out of range.

Availability

cc65

See also

tgi_arc, tgi_bar, tgi_circle, tgi_ellipse, tgi_setcolor

Example

/* Draw the closed upper half of an ellipse */
tgi_setcolor(TGI_COLOR_BLUE);
tgi_pieslice (50, 50, 40, 20, 0, 180);

1.36 tgi_setaspectratio

Function

Set the pixel aspect ratio.

Header

tgi.h

Declaration

void __fastcall__ tgi_setaspectratio (unsigned ratio);

Description

The function sets the pixel aspect ratio for the current driver and display. The argument is an 8.8 fixed point value. The aspect ratio may be used to correct geometric shapes so they look correct on a given display. As an example, a circle with a radius of 100 pixels may look elliptic on some driver/display combinations if the aspect ratio is not 1.00.

Notes

  • The aspect ratio is encoded in the TGI driver which assumes a "standard" monitor for the given platform. The aspect ratio may be wrong if another monitor is used.
  • No TGI function will use the aspect ratio. It is up to the programmer to make use of it.
  • The tgi_setaspectratio function can be used to change the aspect ratio for a loaded driver. The value is not reset by tgi_init, so if a driver is linked statically to an application, switching into and out of graphics mode will not restore the original aspect ratio.
  • The function is available only as a fastcall function; so, it may be used only in the presence of a prototype.

Availability

cc65

See also

tgi_getaspectratio

Example

None.

1.37 tgi_setcolor

Function

Set color to be used in future draw operations.

Header

tgi.h

Declaration

void __fastcall__ tgi_setcolor (unsigned char color);

Description

Set color to be used in future draw operations.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setcolor(TGI_COLOR_BLACK);
tgi_bar(0,0,30,30);
tgi_setcolor(TGI_COLOR_WHITE);
tgi_bar(10,10,20,20);

1.38 tgi_setdrawpage

Function

Set the page for drawing.

Header

tgi.h

Declaration

void __fastcall__ tgi_setdrawpage (unsigned char page);

Description

If the drawpage and the viewpage are the same then all drawing is seen immediately as it is drawn. For double buffered games you can set the drawpage to a different page than the viewpage. This lets you draw the next screen in the background and when the screen is ready you display it.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0

1.39 tgi_setpalette

Function

Set the palette (not available with all drivers/hardware). Palette is a pointer to as many entries as there are colors.

Header

tgi.h

Declaration

void __fastcall__ tgi_setpalette (const unsigned char* palette);

Description

Set the palette (not available with all drivers/hardware). Palette is a pointer to as many entries as there are colors.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.40 tgi_setpixel

Function

Plot a pixel on the drawpage with the current color.

Header

tgi.h

Declaration

void __fastcall__ tgi_setpixel (int x, int y);

Description

Plot a pixel on the drawpage with the current color.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.41 tgi_settextscale

Function

Set the scaling for text output.

Header

tgi.h

Declaration

void __fastcall__ tgi_settextscale (unsigned width, unsigned height);

Description

Set the scaling for text output. The scaling factors for width and height are 8.8 fixed point values. This means that $100 = 1 $200 = 2 etc.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_settextstyle

Example

None.

1.42 tgi_settextstyle

Function

Set the style for text output.

Header

tgi.h

Declaration

void __fastcall__ tgi_settextstyle (unsigned char magx, unsigned char magy, unsigned char dir, unsigned char font);

Description

Set the style for text output.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

tgi_settextscale

Example

None.

1.43 tgi_setviewpage

Function

Set page to be visible on screen.

Header

tgi.h

Declaration

void __fastcall__ tgi_setviewpage (unsigned char page);

Description

If the drawpage and the viewpage are the same then all drawing is seen immediately as it is drawn. For double buffered games you can set the drawpage to a different page than the viewpage. This lets you draw the next screen in the background and when the screen is ready you display it.

Notes

  • The function is only available as fastcall function, so it may only be used in presence of a prototype.

Availability

cc65

See also

Other tgi functions.

Example

tgi_setdrawpage(1);
tgi_outtextxy(10, 10, "Hello World");
tgi_setviewpage(1); // Show page 1
tgi_setdrawpage(0);
tgi_outtextxy(10, 10, "Creating next frame");
...
tgi_setviewpage(0); // Show page 0

1.44 tgi_uninstall

Function

Uninstall the currently loaded driver but do not unload it. Will call tgi_done if necessary.

Header

tgi.h

Declaration

void tgi_uninstall (void);

Description

Uninstall the currently loaded driver but do not unload it. Will call tgi_done if necessary.

Availability

cc65

See also

Other tgi functions.

Example

None.

1.45 tgi_unload

Function

Uninstall, then unload the currently loaded driver. Will call tgi_done if necessary.

Header

tgi.h

Declaration

void tgi_unload (void);

Description

Uninstall, then unload the currently loaded driver. Will call tgi_done if necessary.

Availability

cc65

See also

Other tgi functions.

Example

None.