libdragon
Files | Data Structures | Macros | Functions | Variables

Software routines for manipulating graphics in a display context. More...

Files

file  graphics.c
 2D Graphics
 
file  font.h
 Font Data.
 
file  graphics.h
 2D Graphics
 

Data Structures

struct  color_t
 Generic color structure. More...
 
struct  sprite_t
 Sprite structure. More...
 

Macros

#define __set_pixel(buffer, x, y, color)    (buffer)[(x) + ((y) * __width)] = color
 Macro to set a pixel to a certain color in a buffer. More...
 
#define __get_pixel(buffer, x, y)    (buffer)[(x) + ((y) * __width)]
 Macro to get a pixel color from a buffer. More...
 
#define __get_buffer(x)   __safe_buffer[(x)-1]
 Get the correct video buffer given a display context. More...
 

Functions

uint32_t graphics_make_color (int r, int g, int b, int a)
 Return a 32-bit representation of an RGBA color. More...
 
uint32_t graphics_convert_color (color_t color)
 Convert a color structure to a 32-bit representation of an RGBA color. More...
 
void graphics_set_color (uint32_t forecolor, uint32_t backcolor)
 Set the current forecolor and backcolor for text operations. More...
 
void graphics_draw_pixel (display_context_t disp, int x, int y, uint32_t color)
 Draw a pixel to a given display context. More...
 
void graphics_draw_pixel_trans (display_context_t disp, int x, int y, uint32_t color)
 Draw a pixel to a given display context with alpha support. More...
 
void graphics_draw_line (display_context_t disp, int x0, int y0, int x1, int y1, uint32_t color)
 Draw a line to a given display context. More...
 
void graphics_draw_line_trans (display_context_t disp, int x0, int y0, int x1, int y1, uint32_t color)
 Draw a line to a given display context with alpha support. More...
 
void graphics_draw_box (display_context_t disp, int x, int y, int width, int height, uint32_t color)
 Draw a filled rectangle to a display context. More...
 
void graphics_draw_box_trans (display_context_t disp, int x, int y, int width, int height, uint32_t color)
 Draw a filled rectangle to a display context. More...
 
void graphics_fill_screen (display_context_t disp, uint32_t c)
 Fill the entire screen with a particular color. More...
 
void graphics_set_default_font (void)
 Set the font to the default.
 
void graphics_set_font_sprite (sprite_t *font)
 Set the current font. Should be set before using any of the draw function. More...
 
void graphics_draw_character (display_context_t disp, int x, int y, char ch)
 Draw a character to the screen using the built-in font. More...
 
void graphics_draw_text (display_context_t disp, int x, int y, const char *const msg)
 Draw a null terminated string to a display context. More...
 
void graphics_draw_sprite (display_context_t disp, int x, int y, sprite_t *sprite)
 Draw a sprite to a display context. More...
 
void graphics_draw_sprite_stride (display_context_t disp, int x, int y, sprite_t *sprite, int offset)
 Draw a sprite from a spritemap to a display context. More...
 
void graphics_draw_sprite_trans (display_context_t disp, int x, int y, sprite_t *sprite)
 Draw a sprite to a display context with alpha transparency. More...
 
void graphics_draw_sprite_trans_stride (display_context_t disp, int x, int y, sprite_t *sprite, int offset)
 Draw a sprite from a spritemap to a display context. More...
 

Variables

uint32_t __bitdepth
 Currently active bit depth.
 
uint32_t __width
 Currently active video width (calculated)
 
uint32_t __height
 Currently active video height (calculated)
 
void * __safe_buffer []
 Pointer to uncached 16-bit aligned version of buffers.
 

Detailed Description

Software routines for manipulating graphics in a display context.

The graphics subsystem is responsible for software manipulation of a display context as returned from the Display Subsystem. All of the functions use a pure software drawing method and are thus much slower than hardware sprite support. However, they are slightly more flexible and offer no hardware limitations in terms of sprite size.

Code wishing to draw to the screen should first acquire a display contect using display_lock. Once the display context is acquired, code may draw to the context using any of the graphics functions present. Wherever practical, two versions of graphics functions are available: a transparent variety and a non-transparent variety. Code that wishes to display sprites without transparency can get a slight performance boost by using the non-transparent viariety of calls since no software alpha blending needs to occur. Once code has finished drawing to the display context, it can be displayed to the screen using display_show.

The graphics subsystem makes use of the same contexts as the Hardware Display Interface. Thus, with careful coding, both hardware and software routines can be used to draw to the display context with no ill effects. The colors returned by graphics_make_color and graphics_convert_color are also compatible with both hardware and software graphics routines.


Data Structure Documentation

◆ color_t

struct color_t

Generic color structure.

Data Fields
uint8_t r Red component.
uint8_t g Green component.
uint8_t b Blue component.
uint8_t a Alpha component.

◆ sprite_t

struct sprite_t

Sprite structure.

Data Fields
uint16_t width Width in pixels.
uint16_t height Height in pixels.
uint8_t bitdepth Bit depth expressed in bytes.

A 32 bit sprite would have a value of '4' here

uint8_t format Sprite format.
Note
Currently unused
uint8_t hslices Number of horizontal slices for spritemaps.
uint8_t vslices Number of vertical slices for spritemaps.
uint32_t data[0] Start of graphics data.

Macro Definition Documentation

◆ __set_pixel

#define __set_pixel (   buffer,
  x,
  y,
  color 
)     (buffer)[(x) + ((y) * __width)] = color

Macro to set a pixel to a certain color in a buffer.

Note
This macro uses the currently calculated video width as the implicit width of the video buffer, so it is not applicable to be used on arbitrary buffers.
Parameters
[out]bufferPointer to a uint16_t or uint32_t array treated as a video buffer
[in]xX coordinate in pixels to place the color
[in]yY coordinate in pixels to place the color
[in]colorA 16 or 32 bit color value to set the requested pixel to. Must match the buffer in pixel bit width.

◆ __get_pixel

#define __get_pixel (   buffer,
  x,
 
)     (buffer)[(x) + ((y) * __width)]

Macro to get a pixel color from a buffer.

Parameters
[in]bufferPointer to a uint16_t or uint32_t array treated as a video buffer
[in]xX coordinate in pixels to grab the color from
[in]yY coordinate in pixels to grab the color from
Returns
The 16 or 32 bit color of the pixel at (x, y)

◆ __get_buffer

#define __get_buffer (   x)    __safe_buffer[(x)-1]

Get the correct video buffer given a display context.

Note
This macro requires that display contexts be integers. If display contexts turn into structures or pointers to structures, this function will need updating.
Parameters
[in]xThe current display context
Returns
A pointer to the current drawing surface for the display context

Function Documentation

◆ graphics_make_color()

uint32_t graphics_make_color ( int  r,
int  g,
int  b,
int  a 
)

Return a 32-bit representation of an RGBA color.

Note
In 16 bpp mode, this function will return a packed 16-bit color in BOTH the lower 16 bits and the upper 16 bits. For software color assignment, this doesn't matter. However, for drawing solid shapes using the RDP, this is required.
Parameters
[in]r8-bit red value
[in]g8-bit green value
[in]b8-bit blue value
[in]a8-bit alpha value. Note that 255 is opaque and 0 is transparent
Returns
a 32-bit representation of the color suitable for blitting in software or hardware

◆ graphics_convert_color()

uint32_t graphics_convert_color ( color_t  color)

Convert a color structure to a 32-bit representation of an RGBA color.

Parameters
[in]colorA color structure representing an RGBA color
Returns
a 32-bit representation of the color suitable for blitting in software or hardware

◆ graphics_set_color()

void graphics_set_color ( uint32_t  forecolor,
uint32_t  backcolor 
)

Set the current forecolor and backcolor for text operations.

Parameters
[in]forecolor32-bit RGBA color to use as the text color. Use graphics_convert_color or graphics_make_color to generate this value.
[in]backcolor32-bit RGBA color to use as the background color for text. Use graphics_convert_color or graphics_make_color to generate this value. Note that if the color given is transparent, text can be written over other graphics without background colors showing.

◆ graphics_draw_pixel()

void graphics_draw_pixel ( display_context_t  disp,
int  x,
int  y,
uint32_t  color 
)

Draw a pixel to a given display context.

Note
This function does not support transparency for speed purposes. To draw a transparent or translucent pixel, use graphics_draw_pixel_trans.
Parameters
[in]dispThe currently active display context.
[in]xThe x coordinate of the pixel.
[in]yThe y coordinate of the pixel.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_draw_pixel_trans()

void graphics_draw_pixel_trans ( display_context_t  disp,
int  x,
int  y,
uint32_t  color 
)

Draw a pixel to a given display context with alpha support.

Note
This function is much slower than graphics_draw_pixel for 32-bit pixels due to the need to sample the current pixel to do software alpha-blending.
Parameters
[in]dispThe currently active display context.
[in]xThe x coordinate of the pixel.
[in]yThe y coordinate of the pixel.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_draw_line()

void graphics_draw_line ( display_context_t  disp,
int  x0,
int  y0,
int  x1,
int  y1,
uint32_t  color 
)

Draw a line to a given display context.

Note
This function does not support transparency for speed purposes. To draw a transparent or translucent line, use graphics_draw_line_trans.
Parameters
[in]dispThe currently active display context.
[in]x0The x coordinate of the start of the line.
[in]y0The y coordinate of the start of the line.
[in]x1The x coordinate of the end of the line.
[in]y1The y coordinate of the end of the line.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_draw_line_trans()

void graphics_draw_line_trans ( display_context_t  disp,
int  x0,
int  y0,
int  x1,
int  y1,
uint32_t  color 
)

Draw a line to a given display context with alpha support.

Note
This function is much slower than graphics_draw_line for 32-bit buffers due to the need to sample the current pixel to do software alpha-blending.
Parameters
[in]dispThe currently active display context.
[in]x0The x coordinate of the start of the line.
[in]y0The y coordinate of the start of the line.
[in]x1The x coordinate of the end of the line.
[in]y1The y coordinate of the end of the line.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_draw_box()

void graphics_draw_box ( display_context_t  disp,
int  x,
int  y,
int  width,
int  height,
uint32_t  color 
)

Draw a filled rectangle to a display context.

Note
This function does not support transparency for speed purposes. To draw a transparent or translucent box, use graphics_draw_box_trans.
Parameters
[in]dispThe currently active display context.
[in]xThe x coordinate of the top left of the box.
[in]yThe y coordinate of the top left of the box.
[in]widthThe width of the box in pixels.
[in]heightThe height of the box in pixels.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_draw_box_trans()

void graphics_draw_box_trans ( display_context_t  disp,
int  x,
int  y,
int  width,
int  height,
uint32_t  color 
)

Draw a filled rectangle to a display context.

Note
This function is much slower than graphics_draw_box for 32-bit buffers due to the need to sample the current pixel to do software alpha-blending.
Parameters
[in]dispThe currently active display context.
[in]xThe x coordinate of the top left of the box.
[in]yThe y coordinate of the top left of the box.
[in]widthThe width of the box in pixels.
[in]heightThe height of the box in pixels.
[in]colorThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_fill_screen()

void graphics_fill_screen ( display_context_t  disp,
uint32_t  c 
)

Fill the entire screen with a particular color.

Note
Since this function is designed for blanking the screen, alpha values for colors are ignored.
Parameters
[in]dispThe currently active display context.
[in]cThe 32-bit RGBA color to draw to the screen. Use graphics_convert_color or graphics_make_color to generate this value.

◆ graphics_set_font_sprite()

void graphics_set_font_sprite ( sprite_t font)

Set the current font. Should be set before using any of the draw function.

The sprite font should be imported using hslices/vslices according to the amount of characters it has. The amount of hslices vs vslices does not matter for this, but it should include the whole ASCII range that you will want to use, including characters from the 0 to 32 range. Normally the sprite should have 127 slices to cover the normal ASCII range.

During rendering, the slice used will be the same number as the char (eg.: character 'A' will use slice 65).

You can see an example of a sprite font (that has the default font double sized) under examples/customfont.

Parameters
[in]fontSprite font to be used.

◆ graphics_draw_character()

void graphics_draw_character ( display_context_t  disp,
int  x,
int  y,
char  ch 
)

Draw a character to the screen using the built-in font.

Draw a character from the built-in font to the screen. This function does not support alpha blending, only binary transparency. If the background color is fully transparent, the font is drawn with no background. Otherwise, the font is drawn on a fully colored background. The foreground and background can be set using graphics_set_color.

Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the character drawn.
[in]yThe Y coordinate to place the top left pixel of the character drawn.
[in]chThe ASCII character to draw to the screen.

◆ graphics_draw_text()

void graphics_draw_text ( display_context_t  disp,
int  x,
int  y,
const char *const  msg 
)

Draw a null terminated string to a display context.

Draw a string to the screen, following a few simple rules. Standard ASCII is supported, as well as \r, \n, space and tab. \r and \n will both cause the next character to be rendered one line lower and at the x coordinate specified in the parameters. The tab character inserts five spaces.

This function does not support alpha blending, only binary transparency. If the background color is fully transparent, the font is drawn with no background. Otherwise, the font is drawn on a fully colored background. The foreground and background can be set using graphics_set_color.

Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the character drawn.
[in]yThe Y coordinate to place the top left pixel of the character drawn.
[in]msgThe ASCII null terminated string to draw to the screen.

◆ graphics_draw_sprite()

void graphics_draw_sprite ( display_context_t  disp,
int  x,
int  y,
sprite_t sprite 
)

Draw a sprite to a display context.

Given a sprite structure, this function will draw a sprite to the display context with clipping support.

Note
This function does not support alpha blending for speed purposes. For alpha blending support, please see graphics_draw_sprite_trans
Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]yThe Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]spritePointer to a sprite structure to display to the screen.

◆ graphics_draw_sprite_stride()

void graphics_draw_sprite_stride ( display_context_t  disp,
int  x,
int  y,
sprite_t sprite,
int  offset 
)

Draw a sprite from a spritemap to a display context.

Given a sprite structure, this function will draw a sprite out of a larger spritemap to the display context with clipping support. This function is useful for software tilemapping. If a sprite was generated as a spritemap (it has more than one horizontal or vertical slice), this function can display a slice of the sprite as a standalone sprite.

Given a sprite with 3 horizontal slices and 2 vertical slices, the offsets would be as follows:

*---*---*---*
| 0 | 1 | 2 |
*---*---*---*
| 3 | 4 | 5 |
*---*---*---*
Note
This function does not support alpha blending for speed purposes. For alpha blending support, please see graphics_draw_sprite_trans_stride
Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]yThe Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]spritePointer to a sprite structure to display to the screen.
[in]offsetOffset of the sprite to display out of the spritemap. The offset is counted starting from 0. The top left sprite in the map is 0, the next one to the right is 1, and so on.

◆ graphics_draw_sprite_trans()

void graphics_draw_sprite_trans ( display_context_t  disp,
int  x,
int  y,
sprite_t sprite 
)

Draw a sprite to a display context with alpha transparency.

Given a sprite structure, this function will draw a sprite to the display context with clipping support.

Note
This function supports alpha blending and is much slower for 32-bit sprites. If you do not need alpha blending support, please see graphics_draw_sprite.
Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]yThe Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]spritePointer to a sprite structure to display to the screen.

◆ graphics_draw_sprite_trans_stride()

void graphics_draw_sprite_trans_stride ( display_context_t  disp,
int  x,
int  y,
sprite_t sprite,
int  offset 
)

Draw a sprite from a spritemap to a display context.

Given a sprite structure, this function will draw a sprite out of a larger spritemap to the display context with clipping support. This function is useful for software tilemapping. If a sprite was generated as a spritemap (it has more than one horizontal or vertical slice), this function can display a slice of the sprite as a standalone sprite.

Given a sprite with 3 horizontal slices and 2 vertical slices, the offsets would be as follows:

*---*---*---*
| 0 | 1 | 2 |
*---*---*---*
| 3 | 4 | 5 |
*---*---*---*
Note
This function supports alpha blending and is much slower for 32-bit sprites. If you do not need alpha blending support, please see graphics_draw_sprite_stride.
Parameters
[in]dispThe currently active display context.
[in]xThe X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]yThe Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]spritePointer to a sprite structure to display to the screen.
[in]offsetOffset of the sprite to display out of the spritemap. The offset is counted starting from 0. The top left sprite in the map is 0, the next one to the right is 1, and so on.

Variable Documentation

◆ 

sprite_t* { ... } ::sprite

◆ 

int { ... } ::font_width

◆ 

int { ... } ::font_height