FabGL
ESP32 Display Controller and Graphics Library
fabgl::SSD1306Controller Class Reference

Display driver for SSD1306 based OLED display, with I2C connection. More...

#include <SSD1306Controller.h>

Inheritance diagram for fabgl::SSD1306Controller:
Collaboration diagram for fabgl::SSD1306Controller:

Public Member Functions

bool available ()
 Checks the SSD1306 device availability. More...
 
void begin (I2C *i2c, int address=0x3C, gpio_num_t resetGPIO=GPIO_NUM_39)
 Initializes SSD1306 assigning I2C bus, reset pin and address. More...
 
void enableBackgroundPrimitiveExecution (bool value)
 Enables or disables drawings inside vertical retracing time. More...
 
void enableBackgroundPrimitiveTimeout (bool value)
 Enables or disables execution time limitation inside vertical retracing interrupt. More...
 
int getScreenHeight ()
 Determines the screen height in pixels. More...
 
int getScreenWidth ()
 Determines the screen width in pixels. More...
 
int getViewPortHeight ()
 Determines vertical size of the viewport. More...
 
int getViewPortWidth ()
 Determines horizontal size of the viewport. More...
 
bool isDoubleBuffered ()
 Determines whether DisplayController is on double buffered mode. More...
 
NativePixelFormat nativePixelFormat ()
 Represents the native pixel format used by this display. More...
 
void processPrimitives ()
 Draws immediately all primitives in the queue. More...
 
void refreshSprites ()
 Forces the sprites to be updated. More...
 
void removeSprites ()
 Empties the list of active sprites. More...
 
void resumeBackgroundPrimitiveExecution ()
 Resumes drawings after suspendBackgroundPrimitiveExecution(). More...
 
int screenCol ()
 Gets initial left column of the viewport. More...
 
int screenRow ()
 Gets initial top row of the viewport. More...
 
void setMouseCursor (Cursor *cursor)
 Sets mouse cursor and make it visible. More...
 
void setMouseCursor (CursorName cursorName)
 Sets mouse cursor from a set of predefined cursors. More...
 
void setMouseCursorPos (int X, int Y)
 Sets mouse cursor position. More...
 
void setResolution (char const *modeline, int viewPortWidth=-1, int viewPortHeight=-1, bool doubleBuffered=false)
 Sets SSD1306 resolution and viewport size. More...
 
void setScreenCol (int value)
 Set initial left column of the viewport. More...
 
void setScreenRow (int value)
 Set initial top row of the viewport. More...
 
template<typename T >
void setSprites (T *sprites, int count)
 Sets the list of active sprites. More...
 
void suspendBackgroundPrimitiveExecution ()
 Suspends drawings. More...
 

Detailed Description

Display driver for SSD1306 based OLED display, with I2C connection.

Example:

fabgl::I2C               I2C;
fabgl::SSD1306Controller SSD1306Controller;

void setup() {
  // SDA = gpio-4, SCL = gpio-15
  I2C.begin(GPIO_NUM_4, GPIO_NUM_15);

  // default OLED address is 0x3C
  SSD1306Controller.begin(&I2C);
  SSD1306Controller.setResolution(OLED_128x64);

  Canvas cv(&SSD1306Controller);
  cv.drawText(0, 0, "Hello World!");
Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x32/SimpleTerminalOut/SimpleTerminalOut.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/NetworkTerminal/NetworkTerminal.ino, and SSD1306_OLED/128x64/SimpleTerminalOut/SimpleTerminalOut.ino.

Member Function Documentation

◆ available()

bool fabgl::SSD1306Controller::available ( )
inline

◆ begin()

void fabgl::SSD1306Controller::begin ( I2C i2c,
int  address = 0x3C,
gpio_num_t  resetGPIO = GPIO_NUM_39 
)

Initializes SSD1306 assigning I2C bus, reset pin and address.

Parameters
i2cI2C pointer
addressDevice address. Default is 0x3C.
resetGPIOReset pin (use GPIO_NUM_39 to disable). Default if disabled.
Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x32/SimpleTerminalOut/SimpleTerminalOut.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/NetworkTerminal/NetworkTerminal.ino, and SSD1306_OLED/128x64/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ enableBackgroundPrimitiveExecution()

void fabgl::DisplayController::enableBackgroundPrimitiveExecution ( bool  value)
inherited

Enables or disables drawings inside vertical retracing time.

Primitives are processed in background (for example in vertical retracing for VGA or in a separated task for SPI/I2C displays). This method can disable (or reenable) this behavior, making drawing instantaneous. Flickering may occur when drawings are executed out of retracing time.
When background executing is disabled the queue is emptied executing all pending primitives. Some displays (SPI/I2C) may be not updated at all when enableBackgroundPrimitiveExecution is False.

Parameters
valueWhen true drawings are done on background, when false drawings are executed instantly.

◆ enableBackgroundPrimitiveTimeout()

void fabgl::DisplayController::enableBackgroundPrimitiveTimeout ( bool  value)
inlineinherited

Enables or disables execution time limitation inside vertical retracing interrupt.

Disabling interrupt execution timeout may generate flickering but speedup drawing operations.

Parameters
valueTrue enables timeout (default), False disables timeout

◆ getScreenHeight()

int fabgl::SSD1306Controller::getScreenHeight ( )
inlinevirtual

Determines the screen height in pixels.

Returns
Screen height in pixels.

Implements fabgl::DisplayController.

Examples:
SSD1306_OLED/128x32/SimpleTerminalOut/SimpleTerminalOut.ino, and SSD1306_OLED/128x64/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getScreenWidth()

int fabgl::SSD1306Controller::getScreenWidth ( )
inlinevirtual

Determines the screen width in pixels.

Returns
Screen width in pixels.

Implements fabgl::DisplayController.

Examples:
SSD1306_OLED/128x32/SimpleTerminalOut/SimpleTerminalOut.ino, and SSD1306_OLED/128x64/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ getViewPortHeight()

int fabgl::SSD1306Controller::getViewPortHeight ( )
inlinevirtual

Determines vertical size of the viewport.

Returns
Vertical size of the viewport.

Implements fabgl::DisplayController.

Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, and SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino.

◆ getViewPortWidth()

int fabgl::SSD1306Controller::getViewPortWidth ( )
inlinevirtual

Determines horizontal size of the viewport.

Returns
Horizontal size of the viewport.

Implements fabgl::DisplayController.

Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, and SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino.

◆ isDoubleBuffered()

bool fabgl::DisplayController::isDoubleBuffered ( )
inlineinherited

Determines whether DisplayController is on double buffered mode.

Returns
True if DisplayController is on double buffered mode.

◆ nativePixelFormat()

NativePixelFormat fabgl::SSD1306Controller::nativePixelFormat ( )
inlinevirtual

Represents the native pixel format used by this display.

Returns
Display native pixel format

Implements fabgl::DisplayController.

◆ processPrimitives()

void IRAM_ATTR fabgl::DisplayController::processPrimitives ( )
inherited

Draws immediately all primitives in the queue.

Draws all primitives before they are processed in the vertical sync interrupt.
May generate flickering because don't care of vertical sync.

◆ refreshSprites()

void fabgl::DisplayController::refreshSprites ( )
inherited

Forces the sprites to be updated.

Screen is automatically updated whenever a primitive is painted (look at Canvas).
When a sprite updates its image or its position (or any other property) it is required to force a refresh using this method.
DisplayController.refreshSprites() is required also when using the double buffered mode, to paint sprites.

Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, VGA/CollisionDetection/CollisionDetection.ino, and VGA/SpaceInvaders/SpaceInvaders.ino.

◆ removeSprites()

void fabgl::DisplayController::removeSprites ( )
inlineinherited

Empties the list of active sprites.

Call this method when you don't need active sprites anymore.

Examples:
VGA/SpaceInvaders/SpaceInvaders.ino.

◆ resumeBackgroundPrimitiveExecution()

void fabgl::SSD1306Controller::resumeBackgroundPrimitiveExecution ( )
virtual

Resumes drawings after suspendBackgroundPrimitiveExecution().

Resumes drawings enabling vertical sync interrupt.

Implements fabgl::DisplayController.

◆ screenCol()

int fabgl::SSD1306Controller::screenCol ( )
inline

Gets initial left column of the viewport.

Returns
First column displayed

◆ screenRow()

int fabgl::SSD1306Controller::screenRow ( )
inline

Gets initial top row of the viewport.

Returns
First row displayed

◆ setMouseCursor() [1/2]

void fabgl::DisplayController::setMouseCursor ( Cursor cursor)
inherited

Sets mouse cursor and make it visible.

Parameters
cursorCursor to use when mouse pointer need to be painted. nullptr = disable mouse pointer.
Examples:
VGA/MouseOnScreen/MouseOnScreen.ino.

◆ setMouseCursor() [2/2]

void fabgl::DisplayController::setMouseCursor ( CursorName  cursorName)
inherited

Sets mouse cursor from a set of predefined cursors.

Parameters
cursorNameName (enum) of predefined cursor.

Example:

VGAController.setMouseCursor(CursorName::CursorPointerShadowed);

◆ setMouseCursorPos()

void fabgl::DisplayController::setMouseCursorPos ( int  X,
int  Y 
)
inherited

Sets mouse cursor position.

Parameters
XMouse cursor horizontal position.
YMouse cursor vertical position.

◆ setResolution()

void fabgl::SSD1306Controller::setResolution ( char const *  modeline,
int  viewPortWidth = -1,
int  viewPortHeight = -1,
bool  doubleBuffered = false 
)

Sets SSD1306 resolution and viewport size.

Viewport size can be larger than display size. You can pan the view using SSD1306Controller.setScreenCol() and SSD1306Controller.setScreenRow().

Parameters
modelineNative display reoslution. Possible values: OLED_128x64 and OLED_128x32.
viewPortWidthVirtual viewport width. Should be larger or equal to display native width.
viewPortHeightVirtual viewport height. Should be larger or equal to display native height.
doubleBufferedif True allocates another viewport of the same size to use as back buffer.
Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x32/SimpleTerminalOut/SimpleTerminalOut.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/NetworkTerminal/NetworkTerminal.ino, and SSD1306_OLED/128x64/SimpleTerminalOut/SimpleTerminalOut.ino.

◆ setScreenCol()

void fabgl::SSD1306Controller::setScreenCol ( int  value)

Set initial left column of the viewport.

Use this method only when viewport is larger than display size.

Parameters
valueFirst column to display

◆ setScreenRow()

void fabgl::SSD1306Controller::setScreenRow ( int  value)

Set initial top row of the viewport.

Use this method only when viewport is larger than display size.

Parameters
valueFirst row to display

◆ setSprites()

template<typename T >
void fabgl::DisplayController::setSprites ( T *  sprites,
int  count 
)
inlineinherited

Sets the list of active sprites.

A sprite is an image that keeps background unchanged.
There is no limit to the number of active sprites, but flickering and slow refresh happens when a lot of sprites (or large sprites) are visible.
To empty the list of active sprites call DisplayController.removeSprites().

Parameters
spritesThe list of sprites to make currently active.
countNumber of sprites in the list.

Example:

// define a sprite with user data (velX and velY)
struct MySprite : Sprite {
  int  velX;
  int  velY;
};

static MySprite sprites[10];

VGAController.setSprites(sprites, 10);
Examples:
SSD1306_OLED/128x32/CollisionDetection/CollisionDetection.ino, SSD1306_OLED/128x64/CollisionDetection/CollisionDetection.ino, VGA/CollisionDetection/CollisionDetection.ino, and VGA/SpaceInvaders/SpaceInvaders.ino.

◆ suspendBackgroundPrimitiveExecution()

void fabgl::SSD1306Controller::suspendBackgroundPrimitiveExecution ( )
virtual

Suspends drawings.

Suspends drawings disabling vertical sync interrupt.
After call to suspendBackgroundPrimitiveExecution() adding new primitives may cause a deadlock.
To avoid it a call to "processPrimitives()" should be performed very often.
This method maintains a counter so can be nested.

Implements fabgl::DisplayController.


The documentation for this class was generated from the following files: