graphics.c File Reference

Functions for creating and showing graphics. More...

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/BaseMemoryLib.h>
#include <UEFIStarter/graphics.h>
#include <UEFIStarter/core/memory.h>
#include <UEFIStarter/core/logger.h>
#include <UEFIStarter/core/cmdline.h>
#include <UEFIStarter/core/timestamp.h>
#include <UEFIStarter/core/string.h>

Macros
#define	MIX_CHANNEL(CH)   rv.CH = corners[0].CH*sa + corners[1].CH*sb + corners[row_width].CH*sc + corners[row_width+1].CH*sd
	shortcut macro for weighted mixing of 4 pixels' values More...

Typedefs
typedef void	netpbm_pixel_parser_f(char *in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *out, unsigned int pixels, unsigned int width)
	internal: data type for netpbm parser functions

Functions
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...
static BOOLEAN	_validate_vsync (cmdline_value_t v)
	Validates the "vsync mode" command-line parameter. More...
static BOOLEAN	_validate_fps (cmdline_value_t v)
	Validates the "framerate limit" command-line parameter. More...
static BOOLEAN	_validate_display_handle (cmdline_value_t v)
	Validates the "display handle" command-line parameter. More...
static void	_parse_ppm_pixel_data (char *in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *out, unsigned int pixels, unsigned int width)
	internal: parses PPM pixel data More...
static void	_parse_pgm_pixel_data (char *in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *out, unsigned int pixels, unsigned int width)
	internal: parses PGM pixel data More...
static void	_parse_pbm_pixel_data (char *in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *out, unsigned int pixels, unsigned int width)
	internal: parses PBM pixel data More...
image_t *	create_image (INTN width, INTN height)
	Allocates and initializes an image. More...
static image_t *	_parse_netpbm_image_data (file_contents_t *contents, netpbm_pixel_parser_f *pixel_parser, char magic_digit, char has_maxval_row)
	internal: parses netpbm file contents into an image 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...
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...
COLOR	interpolate_2px (COLOR *colors, float ratio)
	Performs linear interpolation of a pixel value between 2 pixels. More...
void	rotate_image (SPRITE original, SPRITE rotated, INTN radius, float theta)
	Rotates an image by an arbitrary angle. More...
static image_t *	_load_netpbm_file (CHAR16 *filename, image_t *parse_f(file_contents_t *))
	internal: loads a netpbm image file. 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...
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...
void	print_graphics_modes (EFI_GRAPHICS_OUTPUT_PROTOCOL *gop)
	Prints the list of available graphics modes. 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...
EFI_GRAPHICS_OUTPUT_PROTOCOL *	get_graphics_protocol ()
	Fetches the UEFI graphics output protocol handle. 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...
static void	_parse_glyph_data (UINT8 *data, image_t *image, unsigned int left, unsigned int top)
	internal: parses a character from a font sprite sheet into glyph data. 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_glyph (SPRITE start, UINTN buffer_width, glyph_t *glyph, COLOR color)
	Draws a single glyph to a sprite or output buffer. 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	free_glyphs (glyph_list_t *glyphs)
	Frees a previously allocated list of glyphs. 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...
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_STATUS	init_graphics ()
	Initializes the graphics output. More...
void	shutdown_graphics ()
	Shuts down the graphics features. 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
EFI_GRAPHICS_OUTPUT_BLT_PIXEL *	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
static trig_func *	_sin =NULL
	pointer to sin() function
static trig_func *	_cos =NULL
	pointer to cos() function
cmdline_argument_t	graphics_argument_list []
	list of graphics-related command-line arguments More...
cmdline_argument_group_t	graphics_arguments ={ L"Graphics options" ,sizeof( graphics_argument_list )/sizeof(cmdline_argument_t), graphics_argument_list }
	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

Macro Definition Documentation

MIX_CHANNEL

#define MIX_CHANNEL

(

CH

)

rv.CH = corners[0].CH*sa + corners[1].CH*sb + corners[row_width].CH*sc + corners[row_width+1].CH*sd

shortcut macro for weighted mixing of 4 pixels' values

Parameters

CH	the color channel's name

Function Documentation

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

_validate_vsync()

static BOOLEAN _validate_vsync ( cmdline_value_t  v )

static

Validates the "vsync mode" command-line parameter.

Parameters

v	the input to check

Returns

whether the input is a valid vsync mode

_validate_fps()

static BOOLEAN _validate_fps ( cmdline_value_t  v )

static

Validates the "framerate limit" command-line parameter.

Parameters

v	the input to check

Returns

whether the input is a valid framerate limit

_validate_display_handle()

static BOOLEAN _validate_display_handle ( cmdline_value_t  v )

static

Validates the "display handle" command-line parameter.

Parameters

v	the input to check

Returns

whether the input is a valid display handle

_parse_ppm_pixel_data()

static void _parse_ppm_pixel_data ( char *  in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *  out, unsigned int  pixels, unsigned int  width  )

static

internal: parses PPM pixel data

Parameters

in	the pixel data to parse, as bytes
out	the output sprite to write to
pixels	the number of pixels in the image
width	(unused) the image's width, in pixels

_parse_pgm_pixel_data()

static void _parse_pgm_pixel_data ( char *  in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *  out, unsigned int  pixels, unsigned int  width  )

static

internal: parses PGM pixel data

Parameters

in	the pixel data to parse, as bytes
out	the output sprite to write to
pixels	the number of pixels in the image
width	(unused) the image's width, in pixels

_parse_pbm_pixel_data()

static void _parse_pbm_pixel_data ( char *  in, EFI_GRAPHICS_OUTPUT_BLT_PIXEL *  out, unsigned int  pixels, unsigned int  width  )

static

internal: parses PBM pixel data

Parameters

in	the pixel data to parse, as bytes
out	the output sprite to write to
pixels	the number of pixels in the image
width	the image's width, in pixels

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

_parse_netpbm_image_data()

static image_t* _parse_netpbm_image_data ( file_contents_t *  contents, netpbm_pixel_parser_f *  pixel_parser, char  magic_digit, char  has_maxval_row  )

static

internal: parses netpbm file contents into an image

Parameters

contents	the file contents to parse
pixel_parser	the pixel parser function to use
magic_digit	the file's expected netpbm magic digit (indicates pixel format)
has_maxval_row	whether the file has a row indicating pixels' maximum values

Returns

the parsed image, or NULL on error

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

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

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

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

_load_netpbm_file()

static image_t* _load_netpbm_file ( CHAR16 *  filename, image_t *  parse_ffile_contents_t *  )

static

internal: loads a netpbm image file.

Parameters

filename	the filename to read the image from
parse_f	the parser function to use

Returns

the loaded image, 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

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

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

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

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.

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

_parse_glyph_data()

static void _parse_glyph_data ( UINT8 *  data, image_t *  image, unsigned int  left, unsigned int  top  )

static

internal: parses a character from a font sprite sheet into glyph data.

Todo:

this currently only reads the red color channel, the source image should be grayscale anyway. Could check or average all channels just to be safe.

Parameters

data	the glyph data to write to
image	the sprite sheet to read from
left	the left offset to start reading from
top	the top offset to start reading from

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_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

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

free_glyphs()

void free_glyphs

(

glyph_list_t *

glyphs

)

Frees a previously allocated list of glyphs.

Parameters

glyphs

the list to free

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

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

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.

Variable Documentation

graphics_argument_list

cmdline_argument_t graphics_argument_list[]

Initial value:

= {
  {{uint64:2},  ARG_INT,NULL,                    L"-mode",   L"Select graphics mode"}, 
  {{uint64:0},  ARG_INT,_validate_vsync,         L"-vsync",  L"Select vsync mode: 0=off, 1,2=either, 3=both"},
  {{uint64:100},ARG_INT,_validate_fps,           L"-fps",    L"Set approximate frames per second limit"},
  {{uint64:0},  ARG_INT,_validate_display_handle,L"-display",L"Select display handle"}, 
}

list of graphics-related command-line arguments