Display contents from Flash memory

Display functions enabling flash memory contents. More...

Files
file	display.h

Functions
int8_t	sb_display_drawBitmapFromFlash (uint8_t pageStart, uint8_t colStart, uint8_t pageCount, uint8_t colCount, const __flash uint8_t *contents)
	Draw a bitmap from the flash memory onto the OLED display. More...
int8_t	sb_display_fillScreenFromFlash (const __flash uint8_t *contents)
	Draw the contents of the flash to the entire OLED display screen. More...
int8_t	sb_display_showStringFromFlash (uint8_t pageNum, uint8_t colStart, const __flash char *str)
	Print a \0 terminated text string from flash on the OLED display using a 8×8 pixel font. More...
int8_t	sb_display_showStringWideFromFlash (uint8_t pageNum, uint8_t colStart, const __flash char *str)
	Print a \0 terminated text string from flash with a (slightly) wider 8×8 pixel font onto the OLED display. More...
int8_t	sb_display_showStringSmallFromFlash (uint8_t pageNum, uint8_t colStart, const __flash char *str)
	Print a \0 terminated text string from flash on the OLED display using a small 6×4 pixel font. More...

Detailed Description

Display functions enabling flash memory contents.

For microcontroller-based software development, memory usage is a crucial part. The SRAM on the Atmega 328PB (the processor of the Xplained Mini / SPiCboard v3) is extremly tight compared to PCs – its 2 KB are the limiting factor for using the 128×64 pixel monochrome OLED display: Just the contents of a single screen (128×64 bits) would consume half of the available SRAM!

But since most data is constant, this can be stored and read from the flash program memory (with 32 KB on this microprocessor it is sixteen times the SRAM).

Due to the different address space, it is not possible to access the data in flash in the same way you access SRAM contents – a special instruction is required to read from this memory: the ldm instruction (instead of ld).

This will be done automatically by the compiler when using the Named-Address-Space keyword __flash in the variable declaration.

In case you have quite an old compiler not supporting this feature, you have to use the Program Space Utilities from the AVR LibC and not only tag the variables with the PROGMEM keywords but although use the pgm_read_byte function to access them.

The following functions use the same parameters (besides the flash keyword) as their counter parts and their function name is appended by FromFlash

Function Documentation

sb_display_drawBitmapFromFlash()

int8_t sb_display_drawBitmapFromFlash	(	uint8_t	pageStart,
		uint8_t	colStart,
		uint8_t	pageCount,
		uint8_t	colCount,
		const __flash uint8_t *	contents
	)

Draw a bitmap from the flash memory onto the OLED display.

Almost the same function as sb_display_drawBitmap(), but the contents are read from the flash (program memory) - so no SRAM is wasted.

See also

sb_display_drawBitmap

Parameters

pageStart	first page to set the top vertical position
colStart	first column to set the left horizontal position
pageCount	number of pages to set the bottom position
colCount	number of columns to define the right border
contents	array (pageCount * colCount elements) pointing to a bitmap stored in the flash memory (using either __flash namespace or PROGMEM macro)

Return values

0	success
<0	on I²C error (see sb_display_enable() return codes)

sb_display_fillScreenFromFlash()

int8_t sb_display_fillScreenFromFlash

(

const __flash uint8_t *

contents

)

Draw the contents of the flash to the entire OLED display screen.

Almost same function as sb_display_fillScreen(), but the contents are read from the flash (program memory) - so no SRAM is wasted.

The function call is identical to

sb_display_drawBitmapFromFlash(0, 0, 8, 128, contents);

Parameters

contents

pointer to a 8*128 item array in flash memory (using either __flash namespace or PROGMEM macro)

Return values

0	success
<0	on I²C error (see sb_display_enable() return codes)

sb_display_showStringFromFlash()

int8_t sb_display_showStringFromFlash	(	uint8_t	pageNum,
		uint8_t	colStart,
		const __flash char *	str
	)

Print a \0 terminated text string from flash on the OLED display using a 8×8 pixel font.

Almost same function as sb_display_showString(), but the string is read from the flash (program memory) - so no SRAM is wasted.

The Fonts Table contains a detailed list of the available characters

It is possible to define an inline flash string using the PSTR macro from the Program Space Utilities:

static const __flash str[] = "Ipsum";
 sb_display_showString(0, 0, "Lorem");
 sb_display_showStringFromFlash(1, 0, str);
 sb_display_showStringFromFlash(2, 0, PSTR("dolor"));

This will display Lorem , Ipsum and dolor on the subsequent lines, but only the first string will consume SRAM during runtime. The second and third call are different ways for reading from flash memory.

Warning

The font will be stored on the flash which will consume about 2300 bytes (but there is no additional overhead in case you are already using the sb_display_showString() ).

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string in flash memory

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_showStringSmallFromFlash()

int8_t sb_display_showStringSmallFromFlash	(	uint8_t	pageNum,
		uint8_t	colStart,
		const __flash char *	str
	)

Print a \0 terminated text string from flash on the OLED display using a small 6×4 pixel font.

Almost same function as sb_display_showStringSmall(), but the string is read from the flash (program memory) - so no SRAM is wasted.

The Fonts Table contains a detailed list of the available characters

Warning

This font will consume about 700 bytes (but no additional overhead for using sb_display_showStringSmall() ).

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string from flash

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (

See also

sb_display_enable() return codes)

sb_display_showStringWideFromFlash()

int8_t sb_display_showStringWideFromFlash	(	uint8_t	pageNum,
		uint8_t	colStart,
		const __flash char *	str
	)

Print a \0 terminated text string from flash with a (slightly) wider 8×8 pixel font onto the OLED display.

Almost same function as sb_display_showStringWide(), but the string is read from the flash (program memory) - so no SRAM is wasted.

The Fonts Table contains a detailed list of the available characters.

Warning

This font will consume about 2300 bytes, too (but no additional overhead for using sb_display_showStringWide() ).

Parameters

pageNum	page number (0-7) for vertical positioning the output
colStart	first column to set the horizontal position of the output
str	0-terminated string in flash memory

Return values

>=0	length of printed string (can be less than strlen(str) )
<0	on I²C error (see sb_display_enable() return codes)