Extreme Performance

There’s yet another option besides the kernel modules or our userspace code: fbcp-ili9341, developed by Jukka Jylänki, takes extreme measures to maximize TFT frame rates and minimize latency. It’s the best choice for fast “twitch” gaming.

Some things to be aware of before trying this approach:

  • Any PiTFT-related kernel modules you may have previously installed need to be disabled, and SPI needs to be disabled as well. It’s probably easiest to begin with a fresh install of RetroPie or Raspbian!
  • Getting the very best performance requires lots of tweaking and trial-and-error! If you just want to get games up and running on a PiTFT, other options are simpler and may perform well enough. Remember, non-optimal doesn’t necessarily mean pessimal.
  • We’re not involved in the development of this third-party code. Any issues…like if something stops working with a new OS release…will need to be brought up with the developer.
  • Touch is not supported.

Setting Up

Complete instructions are provided on the project’s Github page. Here’s an abbreviated walkthrough for getting things up and running quickly:

Prior Pi experience is required. These directions assume you already have the Pi booting and on the network, and with ssh enabled (makes it easier to copy-and-paste the commands that follow). You’ll want some games on there for testing, and have configured the controls if using RetroPie.

To begin, let’s set the HDMI resolution to match the PiTFT. This makes games more “pixel perfect” on the small display.

Edit the file /boot/config.txt (this requires a “sudo” command) and add the following lines:

Download: file
hdmi_cvt=320 240 60 1 0 0 0

For the larger 480x320 PiTFT, replace the values 320 and 240 on the hdmi_cvt line with 480 and 320.

Some newer games might not look good at these coarse resolutions, or menus may appear large and unusable. What you can do is set the HDMI resolution to exactly twice the PiTFT resolution and the software will provide nice 2x2 area sampling…so that’s “640 480” for a 320x240 PiTFT or “960 640” for 480x320.

Reboot the system after making this change. If an HDMI monitor is connected, it’s possible that it won’t sync to these unusually low settings. That’s okay, we’ll do the rest through ssh…

If playing vector games (e.g. Battlezone, Vectrex games, etc.), things look vastly better if antialiasing is enabled. Edit the file /opt/retropie/configs/all/retroarch.cfg and change this line:

Download: file
video_smooth = "false"


Download: file
video_smooth = "true"

Download, Build, Test

If using a Raspberry Pi 3 or a late-model (v1.2) Pi 2 along with any of the 320x240 pixel PiTFT displays, enter the following commands:

Download: file
git clone https://github.com/juj/fbcp-ili9341.git
cd fbcp-ili9341
mkdir build
cd build
make -j

For any Pi 1 or Pi Zero variant, replace:

Download: file


Download: file

For early-model Pi 2 boards (pre-1.2), use:

Download: file

If using a 480x320 pixel PiTFT, replace the options:

Download: file


Download: file

Don’t forget the two periods at the end of the “cmake” line! If you get a “CMake Error:” message, that’s probably the reason.

You can then test the program with:

Download: file
sudo ./fbcp-ili9341

This should mirror the current contents of the HDMI display to the PiTFT. Press Control+C to exit, and we’ll continue with more setup…

Fine Tuning

The above commands should get you up and running with decent performance in most cases. If you’re seeing any graphic “glitches” on the display, or if you really want to fine-tune settings to their fullest, the project’s README explains every detail.

If working to improve the frame rate, you’ll want statistics enabled. These are overlaid on game graphics, so you’ll want to work everything out and then disable statistics afterward.

To enable statistics, on the cmake line, replace:

Download: file


Download: file

(Or 2 if you want a frame rate graph as well.)

After making changes with cmake, rebuild the software and retest:

Download: file
cmake [options] ..
make -j
sudo ./fbcp-ili9341

Test out your favorite games using various settings (with guidance from the README) to narrow in on the best performance, then build once more with statistics disabled.

Run on Startup

When everything looks good, let’s set up the system to run this automatically…

Edit the file /etc/rc.local (this requires a “sudo” command) and insert a line just above the final “exit 0”:

Download: file

(Change the path if the software is situated elsewhere.)

Reboot and the software should run automatically. It may take up to a minute before it starts and shows anything on the PiTFT. This thread in the software’s repository talks about ways to get it started quicker at boot-time with a little extra work.

This guide was first published on Mar 12, 2015. It was last updated on Mar 12, 2015. This page (Extreme Performance) was last updated on Apr 20, 2019.