Tfblib's main header file. More...

#include <stdbool.h>
#include <string.h>
#include <stdint.h>
#include "tfb_errors.h"
#include "tfb_inline_funcs.h"

Data Structures
struct	tfb_font_info
	Font info structure. More...

Macros
#define	u8 uint8_t
	Convenience macro used to shorten the signatures. Undefined at the end.

#define	u32 uint32_t
	Convenience macro used to shorten the signatures. Undefined at the end.

#define	TFB_FL_NO_TTY_KD_GRAPHICS (1 << 0)
	Do NOT put TTY in graphics mode. More...

#define	TFB_FL_USE_DOUBLE_BUFFER (1 << 1)
	Do NOT write directly onto the framebuffer. More...

#define	TFB_FONT_ANY_WIDTH 0
	When passed to the 'w' param of tfb_set_font_by_size(), means that any font width is acceptable.

#define	TFB_FONT_ANY_HEIGHT 0
	When passed to the 'h' param of tfb_set_font_by_size(), means that any font height is acceptable.

#define	TFB_HUE_DEGREE 256
	Value for 1 degree (of 360) of hue, when passed to tfb_make_color_hsv()

Typedefs
typedef void *	tfb_font_t
	Opaque font type.

typedef bool(*	tfb_font_iter_func) (tfb_font_info cb, void user_arg)
	Callback type accepted by tfb_iterate_over_fonts().

Functions
int	tfb_acquire_fb (u32 flags, const char fb_device, const char tty_device)
	Opens and maps the framebuffer device in the current address space. More...

void	tfb_release_fb (void)
	Release the framebuffer device. More...

int	tfb_set_window (u32 x, u32 y, u32 w, u32 h)
	Limit the drawing to a window at (x, y) having size (w, h) More...

int	tfb_set_center_window_size (u32 w, u32 h)
	Limit the drawing to a window having size (w, h) at the center of the screen. More...

void	tfb_iterate_over_fonts (tfb_font_iter_func cb, void *user_arg)
	Iterate over the fonts embedded in the library. More...

int	tfb_set_current_font (tfb_font_t font_id)
	Set the font used by the functions for drawing text. More...

int	tfb_dyn_load_font (const char file, tfb_font_t font_id)
	Load dynamically a PSF font file. More...

int	tfb_dyn_unload_font (tfb_font_t font_id)
	Unload a dynamically-loaded font. More...

int	tfb_set_font_by_size (int w, int h)
	Select the first font matching the given (w, h) criteria. More...

int	tfb_get_curr_font_width (void)
	Get current font's width. More...

int	tfb_get_curr_font_height (void)
	Get current font's height. More...

u32	tfb_make_color (u8 r, u8 g, u8 b)
	Get a representation of the RGB color (r, g, b) for the current video mode. More...

u32	tfb_make_color_hsv (u32 h, u8 s, u8 v)
	Get a representation of the HSV color (h, s, v) for the current video mode. More...

void	tfb_draw_pixel (int x, int y, u32 color)
	Set the color of the pixel at (x, y) to 'color'. More...

void	tfb_draw_hline (int x, int y, int len, u32 color)
	Draw a horizonal line on-screen. More...

void	tfb_draw_vline (int x, int y, int len, u32 color)
	Draw a vertical line on-screen. More...

void	tfb_draw_line (int x0, int y0, int x1, int y1, u32 color)
	Draw a line on-screen. More...

void	tfb_draw_rect (int x, int y, int w, int h, u32 color)
	Draw an empty rectangle on-screen. More...

void	tfb_fill_rect (int x, int y, int w, int h, u32 color)
	Draw filled rectangle on-screen. More...

void	tfb_draw_circle (int cx, int cy, int r, u32 color)
	Draw an empty circle on-screen. More...

void	tfb_fill_circle (int cx, int cy, int r, u32 color)
	Draw a filled circle on-screen. More...

void	tfb_draw_char (int x, int y, u32 fg, u32 bg, u8 c)
	Draw a single character on-screen at (x, y) More...

void	tfb_draw_string (int x, int y, u32 fg, u32 bg, const char *s)
	Draw a NUL-terminated string on-screen at (x, y) More...

void	tfb_draw_xcenter_string (int cx, int y, u32 fg, u32 bg, const char *s)
	Draw a NUL-terminated string on-screen having its X-center at 'cx'. More...

void	tfb_draw_char_scaled (int x, int y, u32 fg, u32 bg, int xscale, int yscale, u8 c)
	Draw a single character on-screen at (x, y) scaled by (xscale, yscale) More...

void	tfb_draw_string_scaled (int x, int y, u32 fg, u32 bg, int xscale, int yscale, const char *s)
	Draw a NUL-terminated string on-screen at (x, y) scaled by (xscale, yscale) More...

void	tfb_draw_xcenter_string_scaled (int cx, int y, u32 fg, u32 bg, int xscale, int yscale, const char *s)
	Draw a NUL-terminated string on-screen having its X-center at 'cx' (scaled) More...

void	tfb_clear_screen (u32 color)
	Set all the pixels of the screen to the supplied color. More...

void	tfb_clear_win (u32 color)
	Set all the pixels of the current window to the supplied color. More...

u32	tfb_screen_width (void)
	Get screen's width. More...

u32	tfb_screen_height (void)
	Get screen's height. More...

u32	tfb_win_width (void)
	Get current window's width. More...

u32	tfb_win_height (void)
	Get current window's height. More...

void	tfb_flush_rect (int x, int y, int w, int h)
	Flush a given region to the actual framebuffer. More...

void	tfb_flush_window (void)
	Flush the current window to the actual framebuffer. More...

Detailed Description

Tfblib's main header file.

Function Documentation

◆ tfb_acquire_fb()

int tfb_acquire_fb	(	u32	flags,
		const char *	fb_device,
		const char *	tty_device
	)

Opens and maps the framebuffer device in the current address space.

A successful call to tfb_acquire_fb() is mandatory before calling any drawing functions, including the tfb_clear_* and tfb_flush_* functions.

Parameters

[in]	flags	One or more among: TFB_FL_NO_TTY_KD_GRAPHICS, TFB_FL_USE_DOUBLE_BUFFER.
[in]	fb_device	The framebuffer device file. Can be NULL. Defaults to /dev/fb0.
[in]	tty_device	The tty device file to use for setting tty in graphics mode. Can be NULL. Defaults to /dev/tty.

Returns: TFB_SUCCESS in case of success or one of the following errors: TFB_ERR_OPEN_FB, TFB_ERR_IOCTL_FB, TFB_ERR_UNSUPPORTED_VIDEO_MODE, TFB_ERR_TTY_GRAPHIC_MODE, TFB_ERR_MMAP_FB, TFB_ERR_OUT_OF_MEMORY.

Note: This function does not affect the kb mode. tfb_set_kb_raw_mode() can be called before or after tfb_acquire_fb().

◆ tfb_release_fb()

void tfb_release_fb ( void )

Release the framebuffer device.

Note: The function must be called before exiting, otherwise the TTY will remain in graphics mode and be unusable.; This function does not affect the kb mode. If tfb_set_kb_raw_mode() has been used, tfb_restore_kb_mode() must be called to restore the kb mode to its original value.

◆ tfb_set_window()

int tfb_set_window	(	u32	x,
		u32	y,
		u32	w,
		u32	h
	)

Limit the drawing to a window at (x, y) having size (w, h)

In case the application does not want to use the whole screen, it can call this function to get the coordinate system shifted by (+x, +y) and everything outside of it just cut off. Using windows smaller than then screen could improve application's performance.

Parameters

[in]	x	X coordinate of the window, in pixels
[in]	y	Y coordinate of the window, in pixels
[in]	w	Width of the window, in pixels
[in]	h	Height of the window, in pixels

Returns: TFB_SUCCESS in case of success or TFB_ERR_INVALID_WINDOW.

◆ tfb_set_center_window_size()

int tfb_set_center_window_size	(	u32	w,
		u32	h
	)

Limit the drawing to a window having size (w, h) at the center of the screen.

tfb_set_center_window_size() is a wrapper of tfb_set_window() which just calculates the (x, y) coordinates of the window in order it to be at the center of the screen.

Parameters

[in]	w	Width of the window, in pixels
[in]	h	Height of the window, in pixels

Returns: TFB_SUCCESS in case of success or TFB_ERR_INVALID_WINDOW.

◆ tfb_iterate_over_fonts()

void tfb_iterate_over_fonts	(	tfb_font_iter_func	cb,
		void *	user_arg
	)

Iterate over the fonts embedded in the library.

tfb_iterate_over_fonts() calls 'cb' once for each embedded font passing to it a pointer a tfb_font_info structure and the user_arg until either the font list is over or the callback returned false.

Parameters

[in]	cb	An user callback function
[in]	user_arg	An arbitrary user pointer that will be passed to the callback function.

◆ tfb_set_current_font()

int tfb_set_current_font ( tfb_font_t font_id )

Set the font used by the functions for drawing text.

Parameters

[in] font_id An opaque identifier provided by the library either as a member of tfb_font_info, or returned as an out parameter by tfb_dyn_load_font().

Returns: TFB_SUCCESS in case of success or TFB_ERR_INVALID_FONT_ID otherwise.

◆ tfb_dyn_load_font()

int tfb_dyn_load_font	(	const char *	file,
		tfb_font_t *	font_id
	)

Load dynamically a PSF font file.

Parameters

[in]	file	File path
[in,out]	font_id	Address of a tfb_font_t variable that will be set by the function in case of success.

Returns: TFB_SUCCESS in case of success or one of the following errors: TFB_ERR_READ_FONT_FILE_FAILED, TFB_ERR_OUT_OF_MEMORY.

◆ tfb_dyn_unload_font()

int tfb_dyn_unload_font ( tfb_font_t font_id )

Unload a dynamically-loaded font.

Parameters

[in] font_id Opaque pointer returned by tfb_dyn_load_font()

Returns: TFB_SUCCESS in case of success or TFB_ERR_NOT_A_DYN_LOADED_FONT if the caller passed to it the font_id of an embedded font.

◆ tfb_set_font_by_size()

int tfb_set_font_by_size	(	int	w,
		int	h
	)

Select the first font matching the given (w, h) criteria.

The tfb_set_font_by_size() function iterates over the fonts embedded in the library and sets the first font having width = w and height = h.

Parameters

[in]	w	Desired width of the font. The caller may pass TFB_FONT_ANY_WIDTH to tell the function that any font width is acceptable.
[in]	h	Desired height of the font. The caller may pass TFB_FONT_ANY_HEIGHT to tell the function that any font width is acceptable.

Returns: TFB_SUCCESS in case a font matching the given criteria has been found or TFB_ERR_FONT_NOT_FOUND otherwise.

◆ tfb_get_curr_font_width()

int tfb_get_curr_font_width ( void )

Get current font's width.

Returns: the width (in pixels) of the current font or 0 in case there is no currently selected font.

◆ tfb_get_curr_font_height()

int tfb_get_curr_font_height ( void )

Get current font's height.

Returns: the height (in pixels) of the current font or 0 in case there is no currently selected font.

◆ tfb_make_color()

u32 tfb_make_color	(	u8	r,
		u8	g,
		u8	b
	)

inline

Get a representation of the RGB color (r, g, b) for the current video mode.

Parameters

[in]	r	Red color component [0, 255]
[in]	g	Green color component [0, 255]
[in]	b	Blue color component [0, 255]

Returns: A framebuffer-specific representation of the RGB color passed using the r, g, b parameters.

◆ tfb_make_color_hsv()

u32 tfb_make_color_hsv	(	u32	h,
		u8	s,
		u8	v
	)

Get a representation of the HSV color (h, s, v) for the current video mode.

Parameters

[in]	h	Hue [0, 360 * TFB_HUE_DEGREE]
[in]	s	Saturation [0, 255]
[in]	v	Value (Brightness) [0, 255]

Returns: A framebuffer-specific representation of the HSV color passed using the h, s, v parameters.

Note: 1 degree of hue is TFB_HUE_DEGREE, not simply 1. This is necessary in order to increase the precision of the internal integer-only computations.

◆ tfb_draw_pixel()

void tfb_draw_pixel	(	int	x,
		int	y,
		u32	color
	)

inline

Set the color of the pixel at (x, y) to 'color'.

Parameters

[in]	x	Window-relative X coordinate of the pixel
[in]	y	Window-relative Y coordinate of the pixel
[in]	color	A color returned by tfb_make_color()

Note: By default, the library uses as "window" the whole screen, therefore by default the point (x, y) corresponds to the pixel at (x, y) on the screen. But, after calling tfb_set_window() the origin of the coordinate system gets shifted.

◆ tfb_draw_hline()

void tfb_draw_hline	(	int	x,
		int	y,
		int	len,
		u32	color
	)

Draw a horizonal line on-screen.

Parameters

[in]	x	Window-relative X coordinate of line's first point
[in]	y	Window-relative Y coordinate of line's first point
[in]	len	Length of the line, in pixels
[in]	color	Color of the line. See tfb_make_color().

Calling tfb_draw_hline(x, y, len, color) is equivalent to calling: tfb_draw_line(x, y, x + len, y, color)

The only difference between the two functions is in the implementation: given the simpler task of tfb_draw_hline(), it can be implemented in much more efficient way.

◆ tfb_draw_vline()

void tfb_draw_vline	(	int	x,
		int	y,
		int	len,
		u32	color
	)

Draw a vertical line on-screen.

Parameters

[in]	x	Window-relative X coordinate of line's first point
[in]	y	Window-relative Y coordinate of line's first point
[in]	len	Length of the line, in pixels
[in]	color	Color of the line. See tfb_make_color().

Calling tfb_draw_vline(x, y, len, color) is equivalent to calling: tfb_draw_line(x, y, x, y + len, color)

The only difference between the two functions is in the implementation: given the simpler task of tfb_draw_vline(), it can be implemented in much more efficient way.

◆ tfb_draw_line()

void tfb_draw_line	(	int	x0,
		int	y0,
		int	x1,
		int	y1,
		u32	color
	)

Draw a line on-screen.

Parameters

[in]	x0	Window-relative X coordinate of line's first point
[in]	y0	Window-relative Y coordinate of line's first point
[in]	x1	Window-relative X coordinate of line's second point
[in]	y1	Window-relative Y coordinate of line's second point
[in]	color	Color of the line. See tfb_make_color().

◆ tfb_draw_rect()

void tfb_draw_rect	(	int	x,
		int	y,
		int	w,
		int	h,
		u32	color
	)

Draw an empty rectangle on-screen.

Parameters

[in]	x	Window-relative X coordinate of rect's top-left corner
[in]	y	Window-relative Y coordinate of rect's top-left corner
[in]	w	Width of the rectangle
[in]	h	Height of the rectangle
[in]	color	Color of the rectangle

◆ tfb_fill_rect()

void tfb_fill_rect	(	int	x,
		int	y,
		int	w,
		int	h,
		u32	color
	)

Draw filled rectangle on-screen.

Parameters

[in]	x	Window-relative X coordinate of rect's top-left corner
[in]	y	Window-relative Y coordinate of rect's top-left corner
[in]	w	Width of the rectangle
[in]	h	Height of the rectangle
[in]	color	Color of the rectangle

◆ tfb_draw_circle()

void tfb_draw_circle	(	int	cx,
		int	cy,
		int	r,
		u32	color
	)

Draw an empty circle on-screen.

Parameters

[in]	cx	X coordinate of circle's center
[in]	cy	Y coordinate of circle's center
[in]	r	Circle's radius
[in]	color	Circle's color

◆ tfb_fill_circle()

void tfb_fill_circle	(	int	cx,
		int	cy,
		int	r,
		u32	color
	)

Draw a filled circle on-screen.

Parameters

[in]	cx	X coordinate of circle's center
[in]	cy	Y coordinate of circle's center
[in]	r	Circle's radius
[in]	color	Circle's color

◆ tfb_draw_char()

void tfb_draw_char	(	int	x,
		int	y,
		u32	fg,
		u32	bg,
		u8	c
	)

Draw a single character on-screen at (x, y)

Parameters

[in]	x	Window-relative X coordinate of character's position
[in]	y	Window-relative Y coordinate of character's position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	c	The character to draw on-screen

◆ tfb_draw_string()

void tfb_draw_string	(	int	x,
		int	y,
		u32	fg,
		u32	bg,
		const char *	s
	)

Draw a NUL-terminated string on-screen at (x, y)

Parameters

[in]	x	Window-relative X coordinate of text's position
[in]	y	Window-relative Y coordinate of text's position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	s	A char pointer to the string

◆ tfb_draw_xcenter_string()

void tfb_draw_xcenter_string	(	int	cx,
		int	y,
		u32	fg,
		u32	bg,
		const char *	s
	)

Draw a NUL-terminated string on-screen having its X-center at 'cx'.

Parameters

[in]	cx	Window-relative X coordinate of text's X center
[in]	y	Window-relative Y coordinate of text's Y position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	s	A char pointer to the string

This function draws the given string by centering it horizonally at 'cx', while 'y' coordinate is used as-it-is. In other words, 'y' is the distance in pixels from the top of the current window to the top of the text.

    (Window -> the whole screen by default)
#=======================================================#-------+
#                                                       #       |
#                                                       #       | y
#     (x0, y)           (cx, y)                         #       |
#        +-----------------+-----------------+ ---------#-------+
#        | This is some text string centered |          #
#        +-----------------+-----------------+          #
#                          |                            #
#                          |                            #
#=======================================================#
|                          |
+--------------------------+
             cx

x0 is calculated as:
      cx - curr_font_width * string_length / 2

◆ tfb_draw_char_scaled()

void tfb_draw_char_scaled	(	int	x,
		int	y,
		u32	fg,
		u32	bg,
		int	xscale,
		int	yscale,
		u8	c
	)

Draw a single character on-screen at (x, y) scaled by (xscale, yscale)

Parameters

[in]	x	Window-relative X coordinate of character's position
[in]	y	Window-relative Y coordinate of character's position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	xscale	Horizontal scale
[in]	yscale	Vertical scale
[in]	c	The character to draw on-screen

Like tfb_draw_char() but the current font is graphically scaled xscale times horizontally and yscale times vertically. This useful when a font much bigger than any available is needed. Also, it might be useful to create a simple special effect by stretching a font only in one dimention (e.g. xscale=2, yscale=1).

Note: Because of the scaling, tfb_draw_char_scaled() as well as all the other tfb_draw_*_scaled() functions, is slower than their non-scaled versions. Avoid using xscale=1 and yscale=1 (for performance reasons).

◆ tfb_draw_string_scaled()

void tfb_draw_string_scaled	(	int	x,
		int	y,
		u32	fg,
		u32	bg,
		int	xscale,
		int	yscale,
		const char *	s
	)

Draw a NUL-terminated string on-screen at (x, y) scaled by (xscale, yscale)

Parameters

[in]	x	Window-relative X coordinate of text's position
[in]	y	Window-relative Y coordinate of text's position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	xscale	Horizontal scale
[in]	yscale	Vertical scale
[in]	s	A char pointer to the string

Like tfb_draw_string(), but scaled.

See also: tfb_draw_char_scaled().

◆ tfb_draw_xcenter_string_scaled()

void tfb_draw_xcenter_string_scaled	(	int	cx,
		int	y,
		u32	fg,
		u32	bg,
		int	xscale,
		int	yscale,
		const char *	s
	)

Draw a NUL-terminated string on-screen having its X-center at 'cx' (scaled)

Parameters

[in]	cx	Window-relative X coordinate of text's X center
[in]	y	Window-relative Y coordinate of text's Y position
[in]	fg	Foreground text color
[in]	bg	Background text color
[in]	xscale	Horizontal scale
[in]	yscale	Vertical scale
[in]	s	A char pointer to the string

Like tfb_draw_xcenter_string(), but scaled.

See also: tfb_draw_char_scaled().

◆ tfb_clear_screen()

void tfb_clear_screen ( u32 color )

Set all the pixels of the screen to the supplied color.

Parameters

[in] color The color. See tfb_make_color().

◆ tfb_clear_win()

void tfb_clear_win ( u32 color )

Set all the pixels of the current window to the supplied color.

Parameters

[in] color The color. See tfb_make_color().

Note: Unless tfb_set_window() has been called, the current window is by default large as the whole screen.

◆ tfb_screen_width()

u32 tfb_screen_width ( void )

inline

Get screen's width.

Returns: the width of the screen in pixels

◆ tfb_screen_height()

u32 tfb_screen_height ( void )

inline

Get screen's height.

Returns: the height of the screen in pixels

◆ tfb_win_width()

u32 tfb_win_width ( void )

inline

Get current window's width.

Returns: the width of the current window

See also: tfb_set_window()

◆ tfb_win_height()

u32 tfb_win_height ( void )

inline

Get current window's height.

Returns: the height of the current window

See also: tfb_set_window()

◆ tfb_flush_rect()

void tfb_flush_rect	(	int	x,
		int	y,
		int	w,
		int	h
	)

Flush a given region to the actual framebuffer.

Parameters

[in]	x	Window-relative X coordinate of region's position
[in]	y	Window-relative Y coordinate of region's position
[in]	w	Width of the region (in pixels)
[in]	h	Height of the region (in pixels)

In case tfb_acquire_fb() has been called with TFB_FL_USE_DOUBLE_BUFFER, this function copies the pixels in the specified region to actual framebuffer. By default double buffering is not used and this function has no effect.

◆ tfb_flush_window()

void tfb_flush_window ( void )

Flush the current window to the actual framebuffer.

A shortcut for tfb_flush_rect(0, 0, tfb_win_width(), tfb_win_height()).

See also: tfb_flush_rect; tfb_set_window

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ tfb_acquire_fb()

◆ tfb_release_fb()

◆ tfb_set_window()

◆ tfb_set_center_window_size()

◆ tfb_iterate_over_fonts()

◆ tfb_set_current_font()

◆ tfb_dyn_load_font()

◆ tfb_dyn_unload_font()

◆ tfb_set_font_by_size()

◆ tfb_get_curr_font_width()

◆ tfb_get_curr_font_height()

◆ tfb_make_color()

◆ tfb_make_color_hsv()

◆ tfb_draw_pixel()

◆ tfb_draw_hline()

◆ tfb_draw_vline()

◆ tfb_draw_line()

◆ tfb_draw_rect()

◆ tfb_fill_rect()

◆ tfb_draw_circle()

◆ tfb_fill_circle()

◆ tfb_draw_char()

◆ tfb_draw_string()

◆ tfb_draw_xcenter_string()

◆ tfb_draw_char_scaled()

◆ tfb_draw_string_scaled()

◆ tfb_draw_xcenter_string_scaled()

◆ tfb_clear_screen()

◆ tfb_clear_win()

◆ tfb_screen_width()

◆ tfb_screen_height()

◆ tfb_win_width()

◆ tfb_win_height()

◆ tfb_flush_rect()

◆ tfb_flush_window()