frame.h File Reference

Header file for frame handling on OLED display. More...

#include <stdlib.h>
#include <string.h>
#include <avr/io.h>
#include <avr/pgmspace.h>
#include <util/delay.h>
#include "../oled.h"
#include "../font/font.h"
#include "../../common/numbers/datatypes.h"
#include "../../common/numbers/radix.h"
#include "../../common/drawing/elements.h"

Include dependency graph for frame.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	F_CPU   12000000UL
	System clock frequency definition.
#define	FRAME_WIDTH   OLED_COLUMN_SIZE
	Defines the width of the display frame in pixels.
#define	FRAME_HEIGHT   OLED_ROW_SIZE
	Defines the height of the display frame in pixels.
#define	FRAME_SPECIFIC_BACKGROUND
	Enables the use of a custom background stored in a framebuffer array in PROGMEM.
#define	FRAME_NUMBER_ENABLE_FLOATING_POINT
	Enables support for floating-point numbers in frame rendering.
#define	FRAME_NUMBER_PRECISION   2
	Sets the number of decimal places to display for floating-point numbers.

Typedefs
typedef enum FRAME_Number_Operation_t	FRAME_Number_Operation
	Alias for enum FRAME_Number_Operation_t representing numeric operation modes.

Enumerations
enum	FRAME_Number_Operation_t { FRAME_Number_Operation_Decimal = 0 , FRAME_Number_Operation_Signed , FRAME_Number_Operation_Unsigned }
	Specifies the numeric operation modes for number rendering. More...

Functions
void	frame_init (void)
	Initializes the frame system and OLED display.
void	frame_draw_char (const char character, DRAWING_Position position)
	Renders a single character on the OLED display at a specified position.
void	frame_draw_text (const char *text, DRAWING_Position position)
	Renders a text string on the OLED display at a specified position.
void	frame_draw_number (const void *number, unsigned char length, NUMBER_Type type, NUMBER_Radix radix, DRAWING_Position position)
	Renders a formatted number on the OLED display at a specified position.
void	frame_draw_number_uint (const unsigned int number, unsigned char length, NUMBER_Radix radix, DRAWING_Position position)
	Inline helper function to draw an unsigned integer number on the OLED display.
void	frame_draw_number_int (const int number, unsigned char length, NUMBER_Radix radix, DRAWING_Position position)
	Inline helper function to draw a signed integer number on the OLED display.
void	frame_draw_bar (DRAWING_Position position, DRAWING_Size size, unsigned char percent)
	Draws a horizontal progress bar on the OLED display.
void	frame_clear (void)
	Clears the entire display frame.

Detailed Description

Header file for frame handling on OLED display.

This file provides macro definitions and function prototypes for managing graphical frames on an OLED display. It defines default frame dimensions based on the OLED's column and row size, allows enabling a specific background, and supports different numeric display operations including decimal, signed, and unsigned number rendering. The interface depends on included font, OLED driver, number datatype, radix, and drawing element modules. Configuration macros control CPU frequency, frame size, background support, and numeric formatting options. The provided functions initialize the frame system, draw text and numbers at specified positions, draw progress bars, and clear the display frame.

Author

g.raf

Date

2025-09-03

Version

1.0 Release

Copyright

Copyright (c) 2025 g.raf Released under the GPLv3 License. (see LICENSE in repository)

Note

This file is part of a larger project and subject to the license specified in the repository. For updates and the complete revision history, see the GitHub repository.

See also

https://github.com/0x007e/oled "AVR ATmega GitHub Repository"

Macro Definition Documentation

F_CPU

#define F_CPU   12000000UL

System clock frequency definition.

This macro defines the operating frequency of the microcontroller's clock in Hertz. It is used by delay functions and timing calculations. The value should match the actual hardware clock frequency to ensure correct timing behavior in the software.

FRAME_HEIGHT

#define FRAME_HEIGHT   OLED_ROW_SIZE

Defines the height of the display frame in pixels.

This macro sets the vertical size (height) of the display frame used for rendering graphics or text. If not already defined, it defaults to the OLED display's row size (OLED_ROW_SIZE). This allows adjustment of frame height to match different OLED display dimensions at compile time.

Note

FRAME_HEIGHT should be set to correspond to the physical number of pixel rows of the OLED.

FRAME_NUMBER_ENABLE_FLOATING_POINT

#define FRAME_NUMBER_ENABLE_FLOATING_POINT

Enables support for floating-point numbers in frame rendering.

Defining this macro enables the display and formatting of numbers with fractional parts within the frame output functions.

Note

Enabling floating-point number support increases program memory usage due to added formatting and processing code. This tradeoff should be considered when working with memory-constrained embedded systems. If memory usage is critical and decimal precision is not required, refrain from defining this macro.

FRAME_NUMBER_PRECISION

#define FRAME_NUMBER_PRECISION   2

Sets the number of decimal places to display for floating-point numbers.

This macro defines the precision used when rendering decimal (floating-point) numbers on the display. It specifies how many digits should appear after the decimal point. The default value is 2 decimal places if not explicitly defined.

Note

Increasing the precision allows for more detailed numbers, but may increase program memory usage and processing time.

FRAME_SPECIFIC_BACKGROUND

#define FRAME_SPECIFIC_BACKGROUND

Enables the use of a custom background stored in a framebuffer array in PROGMEM.

When this macro is defined, a specific background image stored in PROGMEM (frame_background in frame.c) is drawn to the OLED display. The background serves as a persistent image or pattern that is constantly used as a base layer, and during data output or screen updates, the display content is continuously reconciled against this background to maintain visual consistency.

The custom background can be created or edited using the tool available at https://0x007e.github.io/oled/, allowing flexible design of frame backgrounds.

Note

Defining this macro activates background drawing and reconciliation with display content and reserves PROGMEM space.

FRAME_WIDTH

#define FRAME_WIDTH   OLED_COLUMN_SIZE

Defines the width of the display frame in pixels.

This macro sets the horizontal size (width) of the display frame used for rendering graphics or text. If not already defined, it defaults to the OLED display's column size (OLED_COLUMN_SIZE). This allows flexibility for different display sizes by adjusting the macro at compile time.

Note

FRAME_WIDTH is typically configured to match the physical dimensions of the OLED display.

Typedef Documentation

FRAME_Number_Operation

typedef enum FRAME_Number_Operation_t FRAME_Number_Operation

Alias for enum FRAME_Number_Operation_t representing numeric operation modes.

Enumeration Type Documentation

FRAME_Number_Operation_t

enum FRAME_Number_Operation_t

Specifies the numeric operation modes for number rendering.

This enumeration defines how numbers should be interpreted and processed when rendering formatted output on the display. It distinguishes between decimal operations (typically for floating-point numbers), signed operations, and unsigned operations.

Enumerator
FRAME_Number_Operation_Decimal	Decimal operation mode for floating-point numbers
FRAME_Number_Operation_Signed	Signed operation mode
FRAME_Number_Operation_Unsigned	Unsigned operation mode

Function Documentation

frame_clear()

void frame_clear

(

void

)

Clears the entire display frame.

This function resets the OLED display content to a blank state by calling oled_clear(). If the compile-time macro FRAME_SPECIFIC_BACKGROUND is defined, it additionally redraws the predefined background image stored in frame_background to maintain the visual context. Without FRAME_SPECIFIC_BACKGROUND, the screen is simply cleared to black.

The function's linkage depends on the background setting:

• Inline when no specific background is used, suggesting compiler optimization for small size.
• Normal function otherwise due to potentially larger code size from background redraw.

Here is the call graph for this function:

Here is the caller graph for this function:

frame_draw_bar()

void frame_draw_bar	(	DRAWING_Position	position,
		DRAWING_Size	size,
		unsigned char	percent )

Draws a horizontal progress bar on the OLED display.

This function renders a progress bar at the specified position with the given size, visually representing the completion percentage as a filled section of the bar. The filled area of the bar corresponds to the percentage value (0-100%), calculated as a width increment. The unfilled remainder of the bar is cleared to maintain visual clarity.

Parameters

position	The starting coordinates (x, y) of the progress bar on the display.
size	The width and height dimensions of the progress bar.
percent	The completion percentage to display (0 to 100).

Note

If the percentage exceeds 100, the bar is considered fully filled. The function internally handles clearing and filling the appropriate regions.

frame_draw_char()

void frame_draw_char	(	const char	character,
		DRAWING_Position	position )

Renders a single character on the OLED display at a specified position.

This function draws a character bitmap starting at the coordinates specified by position. It determines which display pages are affected based on the font height and divides the character rendering across multiple OLED memory pages if necessary. For each column of the character, the corresponding font data is fetched from the font table and optionally combined with a predefined background buffer (if enabled). Bit shifting is applied to align the character correctly on display pages that do not align with the character boundaries. The final pixel data for each column is sent to the OLED driver via the oled_column function.

Parameters

character	The ASCII character to be drawn.
position	The starting position (x, y) on the display for the character.

Here is the call graph for this function:

Here is the caller graph for this function:

frame_draw_number()

void frame_draw_number	(	const void *	number,
		unsigned char	length,
		NUMBER_Type	type,
		NUMBER_Radix	radix,
		DRAWING_Position	position )

Renders a formatted number on the OLED display at a specified position.

This function receives a pointer to a number as any supported type (unsigned, signed, float, or double), converts it to a string representation according to the specified number type and radix (base), and draws the result as text at the given display position. The output can be padded with leading spaces (decimal) or zeros (other bases) to fit the desired field length. Supports decimal, hexadecimal, and other numeric bases, as well as fixed precision for floating-point numbers if FRAME_NUMBER_ENABLE_FLOATING_POINT is defined. Internally utilizes font rendering to display the formatted string.

Parameters

number	Pointer to the value to display (type selected via the type argument).
length	Minimum output width in characters (for padding).
type	The type of the number (unsigned/signed int/long, or float/double if enabled).
radix	Number base for formatting (e.g., decimal, hexadecimal).
position	Display coordinates (x, y) for the output string.

Note

Floating point support increases code size and should be enabled only when required.

Here is the call graph for this function:

Here is the caller graph for this function:

frame_draw_number_int()

void frame_draw_number_int ( const int number, unsigned char length, NUMBER_Radix radix, DRAWING_Position position )

inline

Inline helper function to draw a signed integer number on the OLED display.

This function is a simple wrapper around the generic frame_draw_number function, specifically for signed integers. It passes the address of the given number, the desired output length, radix, and position to the main number drawing function, specifying the type as signed int.

Note

Declared as inline to suggest compiler optimization by embedding the function code directly at the call site, minimizing function call overhead.

Parameters

number	The signed integer value to draw.
length	The minimum number of characters to display (with padding if necessary).
radix	The numeric base (e.g., decimal, hexadecimal) for displaying the number.
position	The screen coordinates (x, y) where the number will be rendered.

Here is the call graph for this function:

frame_draw_number_uint()

void frame_draw_number_uint ( const unsigned int number, unsigned char length, NUMBER_Radix radix, DRAWING_Position position )

inline

Inline helper function to draw an unsigned integer number on the OLED display.

This function wraps the more general frame_draw_number function, providing a convenient interface specifically for unsigned integers. It forwards the number pointer, length, radix, and drawing position to the main number rendering function with the appropriate type parameter.

Note

Declared as inline to suggest the compiler to optimize by embedding the function code at the call site, reducing function call overhead.

Parameters

number	The unsigned integer value to draw.
length	The minimum number of characters to display (padding as needed).
radix	The numeric base (e.g., decimal, hexadecimal) for number display.
position	The coordinates (x, y) on the display where the number will be rendered.

Here is the call graph for this function:

frame_draw_text()

void frame_draw_text	(	const char *	text,
		DRAWING_Position	position )

Renders a text string on the OLED display at a specified position.

This function draws the given null-terminated string starting at the coordinates specified by position. It calculates affected display pages based on the character height and handles multi-page rendering for characters that span page boundaries. For each character in the string, the corresponding font bitmap is fetched and individual bytes are combined with the optional background pattern (if enabled) to preserve display background beneath the text. Bit-shifting is applied to properly align the character pixels vertically on partial pages. The function outputs the composed columns of pixel data to the OLED display using the lower-level oled_column function.

Parameters

text	Pointer to the null-terminated string to be drawn.
position	The starting position (x, y) on the display for the text.

Here is the call graph for this function:

Here is the caller graph for this function:

frame_init()

void frame_init

(

void

)

Initializes the frame system and OLED display.

This function initializes the OLED display by calling the OLED driver initialization function (oled_init()) and then clears the display frame to prepare it for new content using frame_clear(). It should be called once during system startup before any text or graphics are drawn.

Note

This setup ensures the OLED hardware is ready and the display memory is cleared to a known state.

Here is the call graph for this function: