2D Graphics

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

Files
file	graphics.c
	2D Graphics
file	surface.c
	Surface buffers used to draw images.
file	font.h
	Font Data.
file	graphics.h
	2D Graphics
file	sprite.h
	2D Graphics
file	surface.h
	Surface buffers used to draw images.

Data Structures
struct	color_t
	Generic color structure. More...

Macros
#define	__set_pixel(buffer, x, y, color)    (buffer)[(x) + ((y) * pix_stride)] = color
	Macro to set a pixel to a certain color in a buffer. More...
#define	__get_pixel(buffer, x, y)    (buffer)[(x) + ((y) * pix_stride)]
	Macro to get a pixel color from a buffer. More...
#define	__get_buffer(disp)   ((disp)->buffer)
	Get the correct video buffer given a display context. More...
#define	RGBA16(rx, gx, bx, ax)
	Create a color_t from the R,G,B,A components in the RGBA16 range (that is: RGB in 0-31, A in 0-1) More...
#define	RGBA32(rx, gx, bx, ax)
	Create a color_t from the R,G,B,A components in the RGBA32 range (0-255). More...

Functions
uint32_t	graphics_make_color (int r, int g, int b, int a)
	Return a packed 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 (surface_t *disp, int x, int y, uint32_t color)
	Draw a pixel to a given display context. More...
void	graphics_draw_pixel_trans (surface_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 (surface_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 (surface_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 (surface_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 (surface_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 (surface_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 (surface_t *disp, int x, int y, char ch)
	Draw a character to the screen using the built-in font. More...
void	graphics_draw_text (surface_t *disp, int x, int y, const char *const msg)
	Draw a null terminated string to a display context. More...
void	graphics_draw_sprite (surface_t *disp, int x, int y, sprite_t *sprite)
	Draw a sprite to a display context. More...
void	graphics_draw_sprite_stride (surface_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 (surface_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 (surface_t *disp, int x, int y, sprite_t *sprite, int offset)
	Draw a sprite from a spritemap to a display context. More...
uint16_t	color_to_packed16 (color_t c)
	Convert a color_t to the 16-bit packed format used by a FMT_RGBA16 surface (RGBA 5551)
uint32_t	color_to_packed32 (color_t c)
	Convert a color_t to the 32-bit packed format used by a FMT_RGBA32 surface (RGBA 8888)
color_t	color_from_packed16 (uint16_t c)
	Create a color_t from the 16-bit packed format used by a FMT_RGBA16 surface (RGBA 5551)
color_t	color_from_packed32 (uint32_t c)
	Create a color_t from the 32-bit packed format used by a FMT_RGBA32 surface (RGBA 8888)

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 context using display_get. 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 variety 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.

Macro Definition Documentation

__set_pixel

#define __set_pixel	(		buffer,
			x,
			y,
			color
	)		(buffer)[(x) + ((y) * pix_stride)] = 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]	buffer	Pointer to a uint16_t or uint32_t array treated as a video buffer
[in]	x	X coordinate in pixels to place the color
[in]	y	Y coordinate in pixels to place the color
[in]	color	A 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,
			y
	)		(buffer)[(x) + ((y) * pix_stride)]

Macro to get a pixel color from a buffer.

Parameters

[in]	buffer	Pointer to a uint16_t or uint32_t array treated as a video buffer
[in]	x	X coordinate in pixels to grab the color from
[in]	y	Y 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

(

disp

)

((disp)->buffer)

Get the correct video buffer given a display context.

Parameters

[in]

disp

The current display context

Returns

A pointer to the current drawing surface for the display context

RGBA16

#define RGBA16	(		rx,
			gx,
			bx,
			ax
	)

Value:

    ({ \
    int rx1 = rx, gx1 = gx, bx1 = bx; \
    (color_t){.r=(rx1<<3)|(rx1>>3), .g=(gx1<<3)|(gx1>>3), .b=(bx1<<3)|(bx1>>3), .a=ax ? 0xFF : 0}; \
})

Create a color_t from the R,G,B,A components in the RGBA16 range (that is: RGB in 0-31, A in 0-1)

RGBA32

#define RGBA32	(		rx,
			gx,
			bx,
			ax
	)

Value:

    ({ \
    (color_t){.r=rx, .g=gx, .b=bx, .a=ax}; \
})

Create a color_t from the R,G,B,A components in the RGBA32 range (0-255).

Function Documentation

graphics_make_color()

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

Return a packed 32-bit representation of an RGBA color.

This is exactly the same as calling graphics_convert_color(RGBA32(r,g,b,a)). Refer to graphics_convert_color for more information.

Parameters

[in]	r	8-bit red value
[in]	g	8-bit green value
[in]	b	8-bit blue value
[in]	a	8-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

See also

graphics_convert_color

graphics_convert_color()

uint32_t graphics_convert_color

(

color_t

color

)

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

This function is similar to color_to_packed16 and color_to_packed32, but automatically picks the version matching with the current display configuration. Notice that this might be wrong if you are drawing to an arbitrary surface rather than a framebuffer.

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. In general, this is not necessary. However, for drawing with the old deprecated RDP API (in particular, rdp_set_primitive_color), this is still required.

Parameters

[in]

color

A 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]	forecolor	32-bit RGBA color to use as the text color. Use graphics_convert_color or graphics_make_color to generate this value.
[in]	backcolor	32-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	(	surface_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]	disp	The currently active display context.
[in]	x	The x coordinate of the pixel.
[in]	y	The y coordinate of the pixel.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	x	The x coordinate of the pixel.
[in]	y	The y coordinate of the pixel.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	x0	The x coordinate of the start of the line.
[in]	y0	The y coordinate of the start of the line.
[in]	x1	The x coordinate of the end of the line.
[in]	y1	The y coordinate of the end of the line.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	x0	The x coordinate of the start of the line.
[in]	y0	The y coordinate of the start of the line.
[in]	x1	The x coordinate of the end of the line.
[in]	y1	The y coordinate of the end of the line.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	x	The x coordinate of the top left of the box.
[in]	y	The y coordinate of the top left of the box.
[in]	width	The width of the box in pixels.
[in]	height	The height of the box in pixels.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	x	The x coordinate of the top left of the box.
[in]	y	The y coordinate of the top left of the box.
[in]	width	The width of the box in pixels.
[in]	height	The height of the box in pixels.
[in]	color	The 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	(	surface_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]	disp	The currently active display context.
[in]	c	The 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]

font

Sprite font to be used.

graphics_draw_character()

void graphics_draw_character	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the character drawn.
[in]	y	The Y coordinate to place the top left pixel of the character drawn.
[in]	ch	The ASCII character to draw to the screen.

graphics_draw_text()

void graphics_draw_text	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the character drawn.
[in]	y	The Y coordinate to place the top left pixel of the character drawn.
[in]	msg	The ASCII null terminated string to draw to the screen.

graphics_draw_sprite()

void graphics_draw_sprite	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]	y	The Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]	sprite	Pointer to a sprite structure to display to the screen.

graphics_draw_sprite_stride()

void graphics_draw_sprite_stride	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]	y	The Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]	sprite	Pointer to a sprite structure to display to the screen.
[in]	offset	Offset 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	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]	y	The Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]	sprite	Pointer to a sprite structure to display to the screen.

graphics_draw_sprite_trans_stride()

void graphics_draw_sprite_trans_stride	(	surface_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]	disp	The currently active display context.
[in]	x	The X coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped horizontally.
[in]	y	The Y coordinate to place the top left pixel of the sprite. This can be negative if the sprite is clipped vertically.
[in]	sprite	Pointer to a sprite structure to display to the screen.
[in]	offset	Offset 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