U8g2 is a graphics library developed at [olikraus/u8g2](https://github.com/olikraus/u8g2) with support for many different displays. It is the successor of [U8glib](https://github.com/olikraus/u8glib) which is not developed any further. Please see [How to port U8g code](https://github.com/olikraus/u8g2/wiki/u8gvsu8g2) for generic porting instructions.
This integration uses full "RAM" memory buffer without picture loop and calls u8g2's `begin()` internally when creating a display object. It is based on [v2.23.18](https://github.com/olikraus/U8g2_Arduino/releases/tag/2.23.18).
The Lua bindings for this library closely follow u8g2's object oriented C++ API. Based on the u8g2 class, you create an object for your display type. The communication interface has to be initialized up front, refer to the examples below on how to do this.
This object provides all of u8g2's methods to control the display. Refer to [graphics_test.lua](../../lua_examples/u8g2/graphics_test.lua) to get an impression how this is achieved with Lua code. Visit the [u8g2 homepage](https://github.com/olikraus/u8g2) for technical details.
Alternatively, you can define them as `U8G2_DISPLAY_TABLE_I2C_EXTRA` and `U8G2_DISPLAY_TABLE_SPI_EXTRA` in an external file to avoid changing the source tree. Include the extra file on the `make` command line:
```
make EXTRA_CCFLAGS='-include $(TOP_DIR)/my_extras.h'
Enable the desired entries for I²C and SPI displays in u8g2's sub-menu (run `make menuconfig`).
### Fonts selection
U8g2 comes with a wide range of fonts for small displays. Fonts can be supplied as strings or compiled into the firmware image to decrease the RAM footprint. If compiled into the firmware they become available as `u8g2.<font_name>` in Lua.
The procedure is different for ESP8266 and ESP32 platforms.
Alternatively, you can define this as `U8G2_FONT_TABLE_EXTRA` in an external file to avoid changing the source tree. Include the extra file on the `make` command line:
```
make EXTRA_CCFLAGS='-include $(TOP_DIR)/my_extras.h'
XBM bitmaps are supplied as strings to `drawXBM()` in contrast to the source code based inclusion of XBMs in upstream u8g2 library. This off-loads all data handling from the u8g2 module to generic methods for binary files. See [graphics_test.lua](../../lua_examples/u8g2/graphics_test.lua).
Conversion of XBM bitmaps can be performed online with [Online-Utility's Image Converter](http://www.online-utility.org/image_converter.jsp): Convert from XBM to MONO format and upload the binary result.
Each display type can be initialized to provide the framebuffer contents in run-length encoded format to a Lua callback. This mode is enabled when a callback function is specified for the setup function. Hardware display and framebuffer callback can be operated in parallel. If the callback function is the only parameter then no signals for a hardware display are generated, leaving a virtual display.
The callback function can be used to process the framebuffer line by line. It's called with either `nil` as parameter to indicate the start of a new frame or with a string containing a line of the framebuffer with run-length encoding. First byte in the string specifies how many pairs of (x, len) follow, while each pair defines the start (leftmost x-coordinate) and length of a sequence of lit pixels. All other pixels in the line are dark.
XBM bitmaps are supplied as strings to `drawXBM()`. This off-loads all data handling from the u8g2 module to generic methods for binary files. See [graphics_test.lua](../../lua_examples/u8g2/graphics_test.lua).
In contrast to the source code based inclusion of XBMs in upstream u8g2 library, it's required to provide precompiled binary files. This can be performed online with [Online-Utility's Image Converter](http://www.online-utility.org/image_converter.jsp): Convert from XBM to MONO format and upload the binary result.
## u8g2.disp:getAscent()
Returns the reference height of the glyphs above the baseline (ascent).
See [u8g2 getAscent()](https://github.com/olikraus/u8g2/wiki/u8g2reference#getascent).
## u8g2.disp:getDescent()
Returns the reference height of the glyphs below the baseline (descent).
See [u8g2 getDescent()](https://github.com/olikraus/u8g2/wiki/u8g2reference#getdescent).
## u8g2.disp:getStrWidth()
Return the pixel width of string.
See [u8g2 getStrWidth()](https://github.com/olikraus/u8g2/wiki/u8g2reference#getstrwidth).
## u8g2.disp:getUTF8Width()
Return the pixel width of an UTF-8 encoded string.
See [u8g2 getUTF8Width()](https://github.com/olikraus/u8g2/wiki/u8g2reference#getutf8width).
## u8g2.disp:sendBuffer()
Send the content of the memory frame buffer to the display.
See [u8g2 sendBuffer()](https://github.com/olikraus/u8g2/wiki/u8g2reference#sendbuffer).
## u8g2.disp:setBitmapMode()
Define bitmap background color mode.
See [u8g2 setBitmapMode()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setbitmapmode).
## u8g2.disp:setContrast()
Set the contrast or brightness.
See [u8g2 setContrast()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setconstrast).
## u8g2.disp:setDisplayRotation()
Changes the display rotation.
See [u8g2 setDisplayRotation()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setdisplayrotation).
## u8g2.disp:setDrawColor()
Defines the bit value (color index) for all drawing functions.
See [u8g2 setDrawColor()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setdrawcolor).
## u8g2.disp:setFlipMode()
Set flip (180 degree rotation) mode.
See [u8g2 setFlipMode()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setflipmode).
## u8g2.disp:setFont()
Define a u8g2 font for the glyph and string drawing functions. They can be supplied as strings or compiled into the firmware image. They are available as `u8g2.<font_name>` in Lua.
See [u8g2 setFont()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfont).
## u8g2.disp:setFontDirection()
Set the drawing direction of all strings or glyphs.
See [u8g2 setFontDirection()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontdirection).
## u8g2.disp:setFontMode()
Define font background color mode.
See [u8g2 setFontMode()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontmode).
## u8g2.disp:setFontPosBaseline()
Change the reference position for the glyph and string draw functions to "baseline".
See [u8g2 setFontPosBaseline()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontposbaseline).
## u8g2.disp:setFontPosBottom()
Change the reference position for the glyph and string draw functions to "bottom".
See [u8g2 setFontPosBottom()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontposbottom).
## u8g2.disp:setFontPosTop()
Change the reference position for the glyph and string draw functions to "top".
See [u8g2 setFontPosTop()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontpostop).
## u8g2.disp:setFontPosCenter()
Change the reference position for the glyph and string draw functions to "center".
See [u8g2 setFontPosCenter()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontposcenter).
## u8g2.disp:setFontRefHeightAll()
Set ascent and descent calculation mode to "highest and lowest glyph".
See [u8g2 setFontRefHeightAll()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontrefheightall).
## u8g2.disp:setFontRefHeightExtendedText()
Set ascent and descent calculation mode to "highest of [A1(], lowest of [g(]".
See [u8g2 setFontRefHeightExtendedText()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontrefheightextendedtext).
## u8g2.disp:setFontRefHeightText()
Set ascent and descent calculation mode to "highest of [A1], lowest of [g]".
See [u8g2 setFontRefHeightText()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setfontrefheighttext).
## u8g2.disp:setPowerSave()
Activate or disable power save mode of the display.
See [u8g2 setPowerSave()](https://github.com/olikraus/u8g2/wiki/u8g2reference#setpowersave).
