search

bitluni / ESP32Lib

http://bitluni.net/esp32-vga/
457 stars 79 forks source link

readme

bitluni's ESP32Lib

ESP32Lib is a collection features for the ESP32 including highest performance VGA graphics (sprites, 3D), sound and game controllers packed in an Arduino library. Check out https://youtube.com/bitlunislab for project updates

If you found it useful please consider supporting my work on

Patreon https://patreon.com/bitluni Paypal https://paypal.me/bitluni

Acknowledgements

Great thanks to Martin Laclaustra for Version 0.4.0 that was refactored by in the development branch unifing even more features for this library. Thanks to Ivan Grokhotkov & Jeroen Domburg (aka Sprite_tm) for their great work on I2S revealing some nitty-gritty details and quirks of the ESP32. Special thanks to Fabrizio Di Vittorio for the inpiration to look deeper into 8Bit modes enabling higher resolutions. He developed the FabGL library simultaneously.

License

bitluni 2019 Creative Commons Attribution ShareAlike 4.0 https://creativecommons.org/licenses/by-sa/4.0/

If you need another license, please feel free to contact me

Documentation

Installation

This library only supports the ESP32. I be able to install the ESP32 features in the board manager you need to add an additional Boards Manager URL in the Preferences (File -> Preferences)

https://dl.espressif.com/dl/package_esp32_index.json

The ESP32Lib can be found in the Library Manager (Sketch -> Include Library -> Manage Libaries) To be able to use the library featues the main header needs to included in the sketch

#include <ESP32Lib.h>

VGA Features

ESP32Lib implements VGA output over I²S.
The highest possible resolution with this library is 800x600. Many common resolutions like 320x240 are preconfigured und can be used without any effort. Two color depths are available. 14Bit R5G5B4 and 3Bit(8 color) R1G1B1 for convenience and memory savings.

To simplify things you can find boards specially designed to work with this library in my shop: https://www.tindie.com/stores/bitluni/ Any purchase supports the further development. Thanks!

Predefined Pin Configurations

A simplified way to configure the pins for shields from my tindie store is using the default predefined configurations VGAv01, VGABlackEdition, VGAWhiteEdition, PicoVGA like this:

vga.init(vga.MODE320x200, vga.VGABlackEdition);

Pin configuration

An VGA cable can be used to connect to the ESP32 The connector pins can be found here: https://en.wikipedia.org/wiki/VGA_connector The 3Bit modes are very easy to set up. You can connect the Ground, Red, Green, Blue, hSync and vSync to output pins of the ESP32.

3Bit color setup

The 14Bit mode require a resistor ladder to be set up for each color (DAC) as shown here

14Bit color setup

There are limitation on which the VGA output an DACs can work:

I/O GPIO pads are 0-19, 21-23, 25-27, 32-39 Input/Output GPIOs are 0-19, 21-23, 25-27, 32-33. GPIO pads 34-39 are input-only.

Beware of pin 0. It selects the boot mode. It's not suitable for color channels and might cause problems as sync signals as well.

Pin 5 is often tied to the LED but can be used as hSync if you don't need the LED. I²C is on 21 (SDA), 22(SCL) DACs are 25, 26 ins 1(TX), 3(RX) sould only be used if really don't need to communicate anymore.

Here is an overview for your convenience: (0), 2, 4, (5), 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 27, 32, 33

Usage

There are 4 diffent VGA Drivers VGA3Bit, VGA3BitI, VGA14Bit and VGA14BitI. VGA3Bit, VGA14Bit are the high performance drivers that don't need any CPU time to serve the VGA. However the VGA3Bit driver takes twice the memory compared to VGA3BitI. The high performace drivers work the best with the WiFi features. The other driver might cause errors. WiFi should connect first before VGA3BitI and VGA14BitI is initialized. The I drivers are using an interrupt to feed the pixels to the I²S. This feature can be used for realtime outputs (Check the VGANoFramebuffer example). An instance of the driver has to be created. The optional parameter (only for 14 bit versions) is the I²S bus to be used. If no parameter is given 1 is used by default to keep I²S0 free for audio output.

VGA14Bit vga(1);

Creating the instance does nothing until the init method is called once. The driver will initialize with one frame buffer by default (that's the memory where the pixels are stored). Showing animated using only one frame buffer will cause flickering since the frame will be displayed while it is redrawn. To have smooth animations double buffering is recommended. A second - the back buffer - is used to paint the graphics in the back ground. When the rendering is finished the front and back buffer are flipped. The disadvantage of the second buffer is the doubled memory requirements. 320x240 will no longer work (320x200 will). Double buffering is enabled using

vga.setFrameBufferCount(2);

before the init method is called (not calling it will result in a single buffer init)

vga.init(vga.MODE320x200, redPins, greenPins, bluePins, hsyncPin, vsyncPin);

The R, G and B pins are passed as arrays for the 14Bit driver and as single integers for the 3Bit version. Please try the examples The following modes are predefined:

These native modes require a too high pixel clock but can be used as a base to create a custom resolution. Please check out the VGACustomResolution example:

2D features

The vga instance implements several drawing methods that can be seen in the VGA2DFeatures example. A complete list will be available in an API documentation soon...

Converting 3D Meshes

The Utilities folder provides a convenient StlConverter that you can use directly from the browser. No worries, your files are not uploaded. Make sure your STL is low poly. The 3D example use a model with < 5000 triangles.

Converting Sprites and Images

The Utilities folder provides a convenient SpriteEditor that you can use directly from the browser. No worries, your files are not uploaded. The correct pixel format for VGA14Bit and VGA3Bit is R5G5B4A2 (that will be improved in future). You can import PNG files to use transparency. Each sprite has the origin in the center by default. You can modify it by changing the x/y values of the first point definition. Clicking on the image creates additional points that can be used for other purpouses like hit boxes etc.