Files | Functions
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)