SSD1306 OLED display driver  1.5.0
This library is developed to control SSD1306/SSD1331 RGB i2c/spi OLED displays and spi PCD8544 LED display
Classes | Macros | Functions
LCD direct graphics functions for all display types

LCD direct graphics functions for all display types: color and monochrome. More...

Classes

struct  SAppMenu
 

Macros

#define ssd1306_drawCanvas(x, y, w, h, buf)   ssd1306_drawBuffer(x, y, w, h, buf)
 

Functions

void ssd1306_setPos (uint8_t x, uint8_t y)
 
void ssd1306_fillScreen (uint8_t fill_Data)
 
void ssd1306_clearScreen (void)
 
void ssd1306_negativeMode (void)
 
void ssd1306_positiveMode (void)
 
uint8_t ssd1306_printFixed (uint8_t xpos, uint8_t y, const char *ch, EFontStyle style)
 
uint8_t ssd1306_printFixed2x (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style) __attribute__((deprecated))
 
uint8_t ssd1306_printFixedN (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style, uint8_t factor)
 
uint8_t ssd1306_charF6x8 (uint8_t x, uint8_t y, const char ch[], EFontStyle style=STYLE_NORMAL) __attribute__((deprecated))
 
uint8_t ssd1306_charF12x16 (uint8_t xpos, uint8_t y, const char ch[], EFontStyle style) __attribute__((deprecated))
 
uint8_t ssd1306_charF6x8_eol (uint8_t left, uint8_t y, const char ch[], EFontStyle style, uint8_t right) __attribute__((deprecated))
 
void ssd1306_setFixedFont (const uint8_t *progmemFont)
 
void ssd1306_setFont6x8 (const uint8_t *progmemFont) __attribute__((deprecated))
 
void ssd1306_putPixel (uint8_t x, uint8_t y)
 
void ssd1306_putPixels (uint8_t x, uint8_t y, uint8_t pixels)
 
void ssd1306_drawRect (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2)
 
void ssd1306_drawLine (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2)
 
void ssd1306_drawHLine (uint8_t x1, uint8_t y1, uint8_t x2)
 
void ssd1306_drawVLine (uint8_t x1, uint8_t y1, uint8_t y2)
 
void ssd1306_drawBuffer (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *buf)
 
void ssd1306_drawBitmap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *buf)
 
void gfx_drawMonoBitmap (lcdint_t x, lcdint_t y, lcduint_t w, lcduint_t h, const uint8_t *buf)
 
void ssd1306_clearBlock (uint8_t x, uint8_t y, uint8_t w, uint8_t h)
 
void ssd1306_drawSpriteEx (uint8_t x, uint8_t y, uint8_t w, const uint8_t *sprite)
 
void ssd1306_drawSprite (SPRITE *sprite)
 
void ssd1306_eraseSprite (SPRITE *sprite)
 
void ssd1306_eraseTrace (SPRITE *sprite)
 
SPRITE ssd1306_createSprite (uint8_t x, uint8_t y, uint8_t w, const uint8_t *data)
 
void ssd1306_replaceSprite (SPRITE *sprite, const uint8_t *data)
 
void ssd1306_createMenu (SAppMenu *menu, const char **items, uint8_t count)
 
void ssd1306_showMenu (SAppMenu *menu)
 
void ssd1306_updateMenu (SAppMenu *menu)
 
uint8_t ssd1306_menuSelection (SAppMenu *menu)
 
void ssd1306_menuDown (SAppMenu *menu)
 
void ssd1306_menuUp (SAppMenu *menu)
 

Detailed Description

LCD direct graphics functions for all display types: color and monochrome.

LCD Direct graphics functions applicable for all display types. These functions will work both for monochrome and 8-bit/16-bit color OLED displays. You need remember, that for RGB oled displays these functions work only in vertical addressing mode. If you're going to combine NanoEngine capabilities with these fucntions, don't forget to switch addressing mode via ssd1331_setMode(), ssd1351_setMode() and etc. This function draws directly in GDRAM and do not use any pre-buffering.

Macro Definition Documentation

◆ ssd1306_drawCanvas

#define ssd1306_drawCanvas (   x,
  y,
  w,
  h,
  buf 
)    ssd1306_drawBuffer(x, y, w, h, buf)

Draws bitmap, located in SRAM, on the display Each byte represents 8 vertical pixels.

// Draw small rectangle 3x8 at position 10,8
uint8_t buffer[3] = { 0xFF, 0x81, 0xFF };
ssd1306_drawBuffer(10, 1, 3, 8, buffer);
Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
w- width of bitmap in pixels
h- height of bitmap in pixels (must be divided by 8)
buf- pointer to data, located in SRAM: each byte represents 8 vertical pixels.

Definition at line 402 of file ssd1306.h.

Function Documentation

◆ gfx_drawMonoBitmap()

void gfx_drawMonoBitmap ( lcdint_t  x,
lcdint_t  y,
lcduint_t  w,
lcduint_t  h,
const uint8_t *  buf 
)

Draws bitmap, located in Flash, on the display

Parameters
x- horizontal position in pixels
y- vertical position in pixels
w- width of bitmap in pixels
h- height of bitmap in pixels (must be divided by 8)
buf- pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 661 of file ssd1306_generic.c.

◆ ssd1306_charF12x16()

uint8_t ssd1306_charF12x16 ( uint8_t  xpos,
uint8_t  y,
const char  ch[],
EFontStyle  style 
)

Prints text to screen using double size font 12x16.

Parameters
xpos- horizontal position in pixels
y- vertical position in blocks (pixels/8)
ch- NULL-terminated string to print
style- font style (EFontStyle).
Returns
number of chars in string

Definition at line 403 of file ssd1306_generic.c.

◆ ssd1306_charF6x8()

uint8_t ssd1306_charF6x8 ( uint8_t  x,
uint8_t  y,
const char  ch[],
EFontStyle  style = STYLE_NORMAL 
)

Prints text to screen using font 6x8.

Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
ch- NULL-terminated string to print
style- font style (EFontStyle), normal by default.
Returns
number of chars in string

Definition at line 357 of file ssd1306_generic.c.

◆ ssd1306_charF6x8_eol()

uint8_t ssd1306_charF6x8_eol ( uint8_t  left,
uint8_t  y,
const char  ch[],
EFontStyle  style,
uint8_t  right 
)

Prints text to screen using set font. If real text ends before right boundary, the remaining part on the display will be erased till right boundary.

Parameters
left- horizontal position in pixels
y- vertical position in blocks (pixels/8)
ch- NULL-terminated string to print
style- font style (EFontStyle), normal by default.
right- right boundary of the text to output
Returns
number of chars in string

Definition at line 478 of file ssd1306_generic.c.

◆ ssd1306_clearBlock()

void ssd1306_clearBlock ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h 
)

Fills block with black pixels

Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
w- width of block in pixels
h- height of block in pixels (must be divided by 8)
Note
usually this method is used to erase bitmap on the screen.

Definition at line 718 of file ssd1306_generic.c.

◆ ssd1306_clearScreen()

void ssd1306_clearScreen ( void  )

Fills screen with zero-byte

Definition at line 75 of file ssd1306_generic.c.

◆ ssd1306_createMenu()

void ssd1306_createMenu ( SAppMenu menu,
const char **  items,
uint8_t  count 
)

Creates menu object with the provided list of menu items. List of menu items (strings) must exist all until menu object is no longer needed. Selection is set to the first item by default.

Parameters
menu- Pointer to SAppMenu structure
items- array of null-termintated strings (located in SRAM)
count- count of menu items in the array

Definition at line 41 of file ssd1306_menu.c.

◆ ssd1306_createSprite()

SPRITE ssd1306_createSprite ( uint8_t  x,
uint8_t  y,
uint8_t  w,
const uint8_t *  data 
)

Creates sprite object. Sprite height is fixed to 8 pixels

Parameters
x- horizontal position in pixels
y- vertical position in pixels
w- width of sprite in pixels
data- pointer to data, located in Flash: each byte represents 8 vertical pixels.
Returns
SPRITE structure

Definition at line 831 of file ssd1306_generic.c.

◆ ssd1306_drawBitmap()

void ssd1306_drawBitmap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t *  buf 
)

Draws bitmap, located in Flash, on the display

Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
w- width of bitmap in pixels
h- height of bitmap in pixels (must be divided by 8)
buf- pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 643 of file ssd1306_generic.c.

◆ ssd1306_drawBuffer()

void ssd1306_drawBuffer ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t *  buf 
)

Draws bitmap, located in SRAM, on the display Each byte represents 8 vertical pixels.

// Draw small rectangle 3x8 at position 10,8
uint8_t buffer[3] = { 0xFF, 0x81, 0xFF };
ssd1306_drawBuffer(10, 1, 3, 8, buffer);
Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
w- width of bitmap in pixels
h- height of bitmap in pixels (must be divided by 8)
buf- pointer to data, located in SRAM: each byte represents 8 vertical pixels.

Definition at line 628 of file ssd1306_generic.c.

◆ ssd1306_drawHLine()

void ssd1306_drawHLine ( uint8_t  x1,
uint8_t  y1,
uint8_t  x2 
)

Draws horizontal line

Parameters
x1- left boundary in pixels
y1- position Y in pixels
x2- right boundary in pixels

Definition at line 586 of file ssd1306_generic.c.

◆ ssd1306_drawLine()

void ssd1306_drawLine ( uint8_t  x1,
uint8_t  y1,
uint8_t  x2,
uint8_t  y2 
)

Draws line

Parameters
x1- x position in pixels of start point
y1- y position in pixels of start point
x2- x position in pixels of end point
y2- y position in pixels of end point
Warning
Remember that this function draws line directly in GDRAM of oled controller. Since there is no way to detect pixels already being displayed, some pixels can be overwritten by black color. If you use RGB oled, based on ssd1331 controller, use ssd1331_drawLine() function.

Definition at line 541 of file ssd1306_generic.c.

◆ ssd1306_drawRect()

void ssd1306_drawRect ( uint8_t  x1,
uint8_t  y1,
uint8_t  x2,
uint8_t  y2 
)

Draws rectangle

Parameters
x1- left boundary in pixel units
y1- top boundary in pixel units
x2- right boundary in pixel units
y2- bottom boundary int pixel units

Definition at line 620 of file ssd1306_generic.c.

◆ ssd1306_drawSprite()

void ssd1306_drawSprite ( SPRITE sprite)

Draws sprite on the display. Position can be changed by updating x and y fields of SPRITE structure.

Parameters
sprite- pointer to SPRITE structure

Definition at line 746 of file ssd1306_generic.c.

◆ ssd1306_drawSpriteEx()

void ssd1306_drawSpriteEx ( uint8_t  x,
uint8_t  y,
uint8_t  w,
const uint8_t *  sprite 
)

Draws bitmap, located in Flash, on the display. This sprite must have wx8 size

Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)
w- width in pixels
sprite- pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 734 of file ssd1306_generic.c.

◆ ssd1306_drawVLine()

void ssd1306_drawVLine ( uint8_t  x1,
uint8_t  y1,
uint8_t  y2 
)

Draws vertical line

Parameters
x1- position X in pixels
y1- top boundary in pixels
y2- bottom boundary in pixels

Definition at line 596 of file ssd1306_generic.c.

◆ ssd1306_eraseSprite()

void ssd1306_eraseSprite ( SPRITE sprite)

Clears sprite from the display leaving black rectangle.

Parameters
sprite- pointer to SPRITE structure

Definition at line 772 of file ssd1306_generic.c.

◆ ssd1306_eraseTrace()

void ssd1306_eraseTrace ( SPRITE sprite)

Clears some sprite parts in old position on the display.

Parameters
sprite- pointer to SPRITE structure

Definition at line 794 of file ssd1306_generic.c.

◆ ssd1306_fillScreen()

void ssd1306_fillScreen ( uint8_t  fill_Data)

Fills screen with pattern byte

Definition at line 60 of file ssd1306_generic.c.

◆ ssd1306_menuDown()

void ssd1306_menuDown ( SAppMenu menu)

Moves selection pointer down by 1 item. If there are no items below, it will set selection pointer to the first item. Use ssd1306_updateMenu() to refresh menu state on the display.

Parameters
menu- Pointer to SAppMenu structure

Definition at line 112 of file ssd1306_menu.c.

◆ ssd1306_menuSelection()

uint8_t ssd1306_menuSelection ( SAppMenu menu)

Returns currently selected menu item. First item has zero-index.

Parameters
menu- Pointer to SAppMenu structure

Definition at line 107 of file ssd1306_menu.c.

◆ ssd1306_menuUp()

void ssd1306_menuUp ( SAppMenu menu)

Moves selection pointer up by 1 item. If selected item is the first one, then selection pointer will set to the last item in menu list. Use ssd1306_updateMenu() to refresh menu state on the display.

Parameters
menu- Pointer to SAppMenu structure

Definition at line 124 of file ssd1306_menu.c.

◆ ssd1306_negativeMode()

void ssd1306_negativeMode ( void  )

All drawing functions start to work in negative mode. Old picture on the display remains unchanged.

Definition at line 873 of file ssd1306_generic.c.

◆ ssd1306_positiveMode()

void ssd1306_positiveMode ( void  )

All drawing functions start to work in positive (default) mode. Old picture on the display remains unchanged.

Definition at line 878 of file ssd1306_generic.c.

◆ ssd1306_printFixed()

uint8_t ssd1306_printFixed ( uint8_t  xpos,
uint8_t  y,
const char *  ch,
EFontStyle  style 
)

Prints text to screen using fixed font.

Parameters
xpos- horizontal position in pixels
y- vertical position in pixels
ch- NULL-terminated string to print
style- font style (EFontStyle), normal by default.
Returns
number of chars in string
See also
ssd1306_setFixedFont
Warning
ssd1306_printFixed() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed() will output text starting at [10,16] position.
Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~396 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Definition at line 109 of file ssd1306_generic.c.

◆ ssd1306_printFixed2x()

uint8_t ssd1306_printFixed2x ( uint8_t  xpos,
uint8_t  y,
const char  ch[],
EFontStyle  style 
)

Prints text to screen using double size fixed font.

Parameters
xpos- horizontal position in pixels
y- vertical position in pixels
ch- NULL-terminated string to print
style- font style (EFontStyle), normal by default.
Returns
number of chars in string
See also
ssd1306_setFixedFont
Warning
ssd1306_printFixed2x() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed2x() will output text starting at [10,16] position.
Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~474 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Definition at line 183 of file ssd1306_generic.c.

◆ ssd1306_printFixedN()

uint8_t ssd1306_printFixedN ( uint8_t  xpos,
uint8_t  y,
const char  ch[],
EFontStyle  style,
uint8_t  factor 
)

Prints text to screen using size fixed font, scaled by factor value.
Factor value 0 gives regular font size (6x8 for example)
Factor value 1 gives double font size (12x16 if 6x8 font is used)
Factor value 2 gives fourth font size (24x32 if 6x8 font is used)
Factor value 3 gives eighth font size (48x64 if 6x8 font is used)

Parameters
xpos- horizontal position in pixels
y- vertical position in pixels
ch- NULL-terminated string to print
style- font style (EFontStyle), normal by default.
factor- 0, 1, 2, 3.
Returns
number of chars in string
See also
ssd1306_setFixedFont
Warning
ssd1306_printFixed2x() can output chars at fixed y positions: 0, 8, 16, 24, 32, etc. If you specify [10,18], ssd1306_printFixed2x() will output text starting at [10,16] position.
Be careful with you flash space! Do not mix too many different functions in single sketch. ssd1306_printFixedN() uses much flash: ~474 bytes, ssd1306_printFixed() needs 388 bytes. Placing both of these functions to your sketch will consume almost 1KiB.

Definition at line 264 of file ssd1306_generic.c.

◆ ssd1306_putPixel()

void ssd1306_putPixel ( uint8_t  x,
uint8_t  y 
)

Put single pixel on the LCD.

Warning
Please, take into account that there is no way to read data from ssd1306, thus since each byte contains 8 pixels, all other pixels in the same byte will be cleared on the display. Use ssd1306_putPixels() instead. If you need to have buffered output, please, refer to NanoCanvas.
Parameters
x- horizontal position in pixels
y- vertical position in pixels

Definition at line 507 of file ssd1306_generic.c.

◆ ssd1306_putPixels()

void ssd1306_putPixels ( uint8_t  x,
uint8_t  y,
uint8_t  pixels 
)

Puts eight vertical pixels on the LCD at once.

// Draw 8 vertical pixels, starting at [10,16] position
ssd1306_putPixels(10,2,0xFF);
// Draw 4 vertical pixels, starting at [32,28] position
ssd1306_putPixels(32,3,0x0F);
Parameters
x- horizontal position in pixels
y- vertical position pixels. Should be multiply of 8.
pixels- bit-pixels to draw on display

Definition at line 514 of file ssd1306_generic.c.

◆ ssd1306_replaceSprite()

void ssd1306_replaceSprite ( SPRITE sprite,
const uint8_t *  data 
)

Replaces image of the sprite with different data. The width must be the same as the width of original sprite image

Parameters
sprite- pointer to SPRITE structure
data- pointer to data, located in Flash: each byte represents 8 vertical pixels.

Definition at line 836 of file ssd1306_generic.c.

◆ ssd1306_setFixedFont()

void ssd1306_setFixedFont ( const uint8_t *  progmemFont)

Function allows to set another fixed font for the library. By default, the font supports only first 128 - 32 ascii chars. First 32 chars of ascii table are non-printable, and removed from the font table to reduce flash memory consumption. Default font doesn't support russian characters. Using this function you can implement your own fonts. First font char must be started with <space> image. Font data should be in the following format: | 0x00 | 0xWW | 0xHH | 0xAA | FONT DATA |, where 0xWW - width in pixels, 0xHH - height in pixels, 0xAA - ascii offset (0x20).
For fixed font 6x8 each char is presented by 6 bytes:
COL0, COL1, COL2, COL3, COL4, COL5.
For fixed font 4x16 each char is presented by 4x16/8 = 8 bytes:
ROW0: COL0, COL1, COL2, COL3,
ROW1: COL0, COL1, COL2, COL3

Parameters
progmemFont- font to setup located in Flash area

Definition at line 493 of file ssd1306_generic.c.

◆ ssd1306_setFont6x8()

void ssd1306_setFont6x8 ( const uint8_t *  progmemFont)

Function allows to set another font for the library. By default, the font supports only first 128 - 32 ascii chars. First 32 chars of ascii table are non-printable, and removed from the font table to reduce flash memory consumption. Default font doesn't support russian characters. Using this function you can implement your own fonts. First font char must be started with <space> image.

Parameters
progmemFont- font to setup located in Flash area

Definition at line 502 of file ssd1306_generic.c.

◆ ssd1306_setPos()

void ssd1306_setPos ( uint8_t  x,
uint8_t  y 
)

Set position in terms of display.

Parameters
x- horizontal position in pixels
y- vertical position in blocks (pixels/8)

◆ ssd1306_showMenu()

void ssd1306_showMenu ( SAppMenu menu)

Shows menu items on the display. If menu items cannot fit the display, the function provides scrolling.

Parameters
menu- Pointer to SAppMenu structure

Definition at line 77 of file ssd1306_menu.c.

◆ ssd1306_updateMenu()

void ssd1306_updateMenu ( SAppMenu menu)

Updates menu items on the display. That is if selection is changed, the function will update only those areas, affected by the change.

Parameters
menu- Pointer to SAppMenu structure

Definition at line 88 of file ssd1306_menu.c.