Functions for creating and showing graphics. More...

#include <Uefi.h>
#include <Protocol/GraphicsOutput.h>
#include "core/cmdline.h"
#include "core/files.h"
#include "core/logger.h"

Data Structures
struct	image_t
	data type for image data, size is dynamic More...

struct	image_asset_t
	data type for image assets More...

struct	glyph_t
	data type for individual 8x15 font glyphs More...

struct	glyph_list_t
	data type for list of glyphs, size is dynamic More...

Macros
#define	COLOR EFI_GRAPHICS_OUTPUT_BLT_PIXEL
	shortcut macro: indicates pixel data is intended to be used as paint color

#define	SPRITE EFI_GRAPHICS_OUTPUT_BLT_PIXEL *
	shortcut macro: indicates pixel data is intended to be as a drawable image

#define	GFX_BUFFER EFI_GRAPHICS_OUTPUT_BLT_PIXEL *
	shortcut macro: indicates pixel data is intended to be used as a screen buffer

#define	ARG_MODE graphics_argument_list[0].value.uint64
	helper macro to access the "graphics mode" command-line argument's value

#define	ARG_VSYNC graphics_argument_list[1].value.uint64
	helper macro to access the "vsync mode" command-line argument's value

#define	ARG_FPS graphics_argument_list[2].value.uint64
	helper macro to access the "framerate limit" command-line argument's value

#define	ARG_DISPLAY graphics_argument_list[3].value.uint64
	helper macro to access the "display handle" command-line argument's value

Typedefs
typedef double	trig_func(double)
	data type for trigonometry function pointers

Functions
EFI_STATUS	init_graphics ()
	Initializes the graphics output. More...

void	shutdown_graphics ()
	Shuts down the graphics features. More...

GFX_BUFFER	create_graphics_fs_buffer ()
	Creates a full-screen graphics buffer. More...

void	free_graphics_fs_buffer (void *addr)
	Frees a full-screen graphics buffer. More...

EFI_STATUS	graphics_fs_blt (GFX_BUFFER buffer)
	Outputs a full-screen graphics buffer to the graphics display. More...

EFI_GRAPHICS_OUTPUT_PROTOCOL *	get_graphics_protocol ()
	Fetches the UEFI graphics output protocol handle. More...

EFI_STATUS	draw_filled_rect (EFI_GRAPHICS_OUTPUT_PROTOCOL gop, UINTN x, UINTN y, UINTN width, UINTN height, COLOR color)
	Draws an unbuffered rectangle to the screen. More...

void	print_graphics_modes (EFI_GRAPHICS_OUTPUT_PROTOCOL *gop)
	Prints the list of available graphics modes. More...

EFI_STATUS	set_graphics_mode (EFI_GRAPHICS_OUTPUT_PROTOCOL *gop, int mode)
	Sets the graphics mode. More...

EFI_STATUS	query_current_mode (EFI_GRAPHICS_OUTPUT_PROTOCOL gop, EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *info)
	Fetches information about the current graphics mode. More...

void	wait_vsync ()
	Waits for the graphics card's vertical synchronisation event. More...

BOOLEAN	limit_framerate (UINT64 *previous, UINT64 minimum_frame_ticks)
	Limits graphics animation framerates. More...

void	set_graphics_sin_func (trig_func *f)
	Sets the sin() function pointer to use in graphics operations. More...

void	set_graphics_cos_func (trig_func *f)
	Sets the cos() function pointer to use in graphics operations. More...

image_t *	parse_ppm_image_data (file_contents_t *contents)
	Parses a PPM (color) image. More...

image_t *	parse_pgm_image_data (file_contents_t *contents)
	Parses a PGM (grayscale) image. More...

image_t *	parse_pbm_image_data (file_contents_t *contents)
	Parses a PBM (black/white bitmap) image. More...

image_t *	load_ppm_file (CHAR16 *filename)
	Reads a netpbm PPM (color) file. More...

image_t *	load_pgm_file (CHAR16 *filename)
	Reads a netpbm PGM (grayscale) file. More...

image_t *	load_pbm_file (CHAR16 *filename)
	Reads a netpbm PBM (black/white bitmap) file. More...

image_t *	load_netpbm_file (CHAR16 *filename)
	Reads a netpbm file, determines the image format by the file's extension. More...

image_t *	create_image (INTN width, INTN height)
	Allocates and initializes an image. More...

void	free_image (image_t *image)
	Frees an image resource. More...

void	load_image_assets (UINTN count, image_asset_t *assets)
	Loads a list of image assets. More...

void	free_image_assets (UINTN count, image_asset_t *assets)
	Frees a list of image assets. More...

COLOR	interpolate_2px (COLOR *colors, float ratio)
	Performs linear interpolation of a pixel value between 2 pixels. More...

COLOR	interpolate_4px (COLOR *corners, UINTN row_width, float x, float y)
	Performs bilinear interpolation of a pixel value within a square of 4 surrounding pixels. More...

void	rotate_image (SPRITE original, SPRITE rotated, INTN radius, float theta)
	Rotates an image by an arbitrary angle. More...

glyph_list_t *	parse_glyphs (image_t image, CHAR16 text)
	Parses a font sprite sheet. More...

glyph_list_t *	load_font ()
	Parses the font file. More...

void	draw_text (SPRITE buffer, UINTN buffer_width, glyph_list_t glyphs, UINT32 x, UINT32 y, COLOR color, CHAR16 text)
	Draws text to a sprite or output buffer. More...

void	draw_glyph (SPRITE start, UINTN buffer_width, glyph_t *glyph, COLOR color)
	Draws a single glyph to a sprite or output buffer. More...

void	free_glyphs (glyph_list_t *glyphs)
	Frees a previously allocated list of glyphs. More...

Variables
EFI_GRAPHICS_OUTPUT_PROTOCOL *	graphics_protocol
	UEFI's graphics output protocol.

EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *	graphics_info
	UEFI's graphics info.

UINTN	graphics_fs_width
	screen width, in pixels

UINTN	graphics_fs_height
	screen height, in pixels

GFX_BUFFER	graphics_fs_buffer
	full-screen output buffer

UINTN	graphics_fs_pages
	number of pages for output buffer

UINTN	graphics_fs_pixel_count
	number of pixels in output buffer

cmdline_argument_t	graphics_argument_list []
	list of graphics-related command-line arguments

cmdline_argument_group_t	graphics_arguments
	group for graphics-related arguments

Detailed Description

Functions for creating and showing graphics.

Author: Richard Nusser

Copyright: 2017-2018 Richard Nusser

License: GPLv3 (see http://www.gnu.org/licenses/)

See also: https://github.com/rinusser/UEFIStarter

Function Documentation

◆ init_graphics()

EFI_STATUS init_graphics ( )

Initializes the graphics output.

Call this function at the start of graphical applications.

Returns: the resulting status, EFI_SUCCESS on success

◆ shutdown_graphics()

void shutdown_graphics ( )

Shuts down the graphics features.

Call this at the end of graphical applications.

◆ create_graphics_fs_buffer()

GFX_BUFFER create_graphics_fs_buffer ( )

Creates a full-screen graphics buffer.

Make sure you have set the target graphics mode first.

Returns: the buffer, or NULL on error

◆ free_graphics_fs_buffer()

void free_graphics_fs_buffer ( void * addr )

Frees a full-screen graphics buffer.

Parameters

addr	the buffer to free

◆ graphics_fs_blt()

EFI_STATUS graphics_fs_blt ( GFX_BUFFER buffer )

Outputs a full-screen graphics buffer to the graphics display.

Parameters

buffer the graphics buffer to output

Returns: the resulting status

◆ get_graphics_protocol()

EFI_GRAPHICS_OUTPUT_PROTOCOL* get_graphics_protocol ( )

Fetches the UEFI graphics output protocol handle.

This is the main access point for UEFI graphics functions.

Returns: the protocol handle, or NULL on error.

◆ draw_filled_rect()

EFI_STATUS draw_filled_rect	(	EFI_GRAPHICS_OUTPUT_PROTOCOL *	gop,
		UINTN	x,
		UINTN	y,
		UINTN	width,
		UINTN	height,
		COLOR *	color
	)

Draws an unbuffered rectangle to the screen.

Parameters

gop	the UEFI graphics output protocol handle
x	the rectangle's left x coordinate
y	the rectangle's top y coordinate
width	the rectangle's width, in pixels
height	the rectangle's height, in pixels
color	the rectangle's color

Returns: the EFI status, EFI_SUCCESS on success

◆ print_graphics_modes()

void print_graphics_modes ( EFI_GRAPHICS_OUTPUT_PROTOCOL * gop )

Prints the list of available graphics modes.

Parameters

gop	the UEFI graphics output protocol handle

◆ set_graphics_mode()

EFI_STATUS set_graphics_mode	(	EFI_GRAPHICS_OUTPUT_PROTOCOL *	gop,
		int	mode
	)

Sets the graphics mode.

Parameters

gop	the UEFI graphics output protocol handle
mode	the graphics mode to set

Returns: the resulting status code

◆ query_current_mode()

EFI_STATUS query_current_mode	(	EFI_GRAPHICS_OUTPUT_PROTOCOL *	gop,
		EFI_GRAPHICS_OUTPUT_MODE_INFORMATION **	info
	)

Fetches information about the current graphics mode.

Parameters

gop	the UEFI graphics output protocol handle
info	the graphics mode info structure to write to

Returns: the resulting status code

◆ wait_vsync()

void wait_vsync ( )

Waits for the graphics card's vertical synchronisation event.

How and if this works depends on your hardware. If you're running the application in a virtual environment it might not work at all.

◆ limit_framerate()

BOOLEAN limit_framerate	(	UINT64 *	previous,
		UINT64	minimum_frame_ticks
	)

Limits graphics animation framerates.

This works by keeping track of timestamps: a given number of ticks needs to have elapsed between frames. If vsync is enabled this function additionally waits for the next vsync event.

Parameters

previous	the previous timestamp value, will be updated when done waiting
minimum_frame_ticks	the number of ticks that must have elapsed since the previous timestamp

Returns: TRUE on success, FALSE otherwise

◆ set_graphics_sin_func()

void set_graphics_sin_func ( trig_func * f )

Sets the sin() function pointer to use in graphics operations.

Parameters

f	pointer to the function to use

◆ set_graphics_cos_func()

void set_graphics_cos_func ( trig_func * f )

Sets the cos() function pointer to use in graphics operations.

Parameters

f	pointer to the function to use

◆ parse_ppm_image_data()

image_t* parse_ppm_image_data ( file_contents_t * contents )

Parses a PPM (color) image.

Parameters

contents the file contents to parse

Returns: the parsed images, or NULL on error

◆ parse_pgm_image_data()

image_t* parse_pgm_image_data ( file_contents_t * contents )

Parses a PGM (grayscale) image.

Parameters

contents the file contents to parse

Returns: the parsed images, or NULL on error

◆ parse_pbm_image_data()

image_t* parse_pbm_image_data ( file_contents_t * contents )

Parses a PBM (black/white bitmap) image.

Parameters

contents the file contents to parse

Returns: the parsed images, or NULL on error

◆ load_ppm_file()

image_t* load_ppm_file ( CHAR16 * filename )

Reads a netpbm PPM (color) file.

Parameters

filename the image's filename

Returns: the image, or NULL on error

◆ load_pgm_file()

image_t* load_pgm_file ( CHAR16 * filename )

Reads a netpbm PGM (grayscale) file.

Parameters

filename the image's filename

Returns: the image, or NULL on error

◆ load_pbm_file()

image_t* load_pbm_file ( CHAR16 * filename )

Reads a netpbm PBM (black/white bitmap) file.

Parameters

filename the image's filename

Returns: the image, or NULL on error

◆ load_netpbm_file()

image_t* load_netpbm_file ( CHAR16 * filename )

Reads a netpbm file, determines the image format by the file's extension.

Parameters

filename the image's filename

Returns: the image, or NULL on error

◆ create_image()

image_t* create_image	(	INTN	width,
		INTN	height
	)

Allocates and initializes an image.

Parameters

width	the image's width
height	the image's height

Returns: the image

◆ free_image()

void free_image ( image_t * image )

Frees an image resource.

Parameters

image the image to free

◆ load_image_assets()

void load_image_assets	(	UINTN	count,
		image_asset_t *	assets
	)

Loads a list of image assets.

Image assets are a handy way of loading e.g. sprites in a graphical application.

Parameters

count	the number of assets to load
assets	the list of assets to load

◆ free_image_assets()

void free_image_assets	(	UINTN	count,
		image_asset_t *	assets
	)

Frees a list of image assets.

Parameters

count	the number of assets to free
assets	the list of assets to free

◆ interpolate_2px()

COLOR interpolate_2px	(	COLOR *	colors,
		float	ratio
	)

Performs linear interpolation of a pixel value between 2 pixels.

Works like interpolate_2px(), only with 1 dimension.

Parameters

colors	pointer to 2 pixels to interpolate between
ratio	the position to interpolate at, within [0..1], 0.0 being colors[0] and 1.0 being colors[1]

Returns: the interpolated pixel

◆ interpolate_4px()

COLOR interpolate_4px	(	COLOR *	corners,
		UINTN	row_width,
		float	x,
		float	y
	)

Performs bilinear interpolation of a pixel value within a square of 4 surrounding pixels.

This illustrates the required parameters to interpolate a new pixel P:

corners[0]
  |
  |  x
  v--|
 -0         1         px        px
y|
 -   P

  2         3         px        px
  |------------------------------|
             row_width

Parameters

corners	pointer to the pixel data to interpolate between, starting at top left pixel's offset
row_width	the source image's row width, in pixels
x	the horizontal position to interpolate at, within [0..1], 0 being left
y	the vertical position to interpolate at, within [0..1], 0 being top

Returns: the interpolated pixel

◆ rotate_image()

void rotate_image	(	SPRITE	original,
		SPRITE	rotated,
		INTN	radius,
		float	theta
	)

Rotates an image by an arbitrary angle.

Make sure you set trigonometry function pointers with set_graphics_sin_func() and set_graphics_cos_func() before using this. This is necessary to avoid having to link StdLib into all graphical applications.

Parameters

original	the source image to rotate, must be square with 2*radius+1 pixels width and height
rotated	the output image to write the rotated image to
radius	the inner circle's radius, should be (square's side length-1)/2
theta	the clockwise angle to rotate by, in radians

◆ parse_glyphs()

glyph_list_t* parse_glyphs	(	image_t *	image,
		CHAR16 *	text
	)

Parses a font sprite sheet.

Parameters

image	the sprite sheet to read from
text	the text printed in the sprite sheet, use `\n` to indicate line breaks

Returns: the parsed list of glyphs, make sure to free this when you're done

◆ load_font()

glyph_list_t* load_font ( )

Parses the font file.

There's currently just one font file with a hardcoded text. The font file is a netpbm image with known text printed in it.

Returns: the loaded font, or NULL on error

◆ draw_text()

void draw_text	(	SPRITE	buffer,
		UINTN	buffer_width,
		glyph_list_t *	glyphs,
		UINT32	x,
		UINT32	y,
		COLOR	color,
		CHAR16 *	text
	)

Draws text to a sprite or output buffer.

Parameters

buffer	the output image to write to
buffer_width	the output image's width, in pixels
glyphs	the glyph list (font) to use
x	the x coordinate to start writing at
y	the y coordinate to start writing at
color	the color to draw the text with
text	the text to write, as UTF-16

Todo:: warn about exceeding width, then either do a line break or clip current line

◆ draw_glyph()

void draw_glyph	(	SPRITE	start,
		UINTN	buffer_width,
		glyph_t *	glyph,
		COLOR	color
	)

Draws a single glyph to a sprite or output buffer.

Parameters

start	the first pixel to write to
buffer_width	the width of the output buffer, in pixels
glyph	the glyph to draw
color	the color to draw with

◆ free_glyphs()

void free_glyphs ( glyph_list_t * glyphs )

Frees a previously allocated list of glyphs.

Parameters

glyphs the list to free

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Function Documentation

◆ init_graphics()

◆ shutdown_graphics()

◆ create_graphics_fs_buffer()

◆ free_graphics_fs_buffer()

◆ graphics_fs_blt()

◆ get_graphics_protocol()

◆ draw_filled_rect()

◆ print_graphics_modes()

◆ set_graphics_mode()

◆ query_current_mode()

◆ wait_vsync()

◆ limit_framerate()

◆ set_graphics_sin_func()

◆ set_graphics_cos_func()

◆ parse_ppm_image_data()

◆ parse_pgm_image_data()

◆ parse_pbm_image_data()

◆ load_ppm_file()

◆ load_pgm_file()

◆ load_pbm_file()

◆ load_netpbm_file()

◆ create_image()

◆ free_image()

◆ load_image_assets()

◆ free_image_assets()

◆ interpolate_2px()

◆ interpolate_4px()

◆ rotate_image()

◆ parse_glyphs()

◆ load_font()

◆ draw_text()

◆ draw_glyph()

◆ free_glyphs()