Replicant doesn't rely on the dedicated graphics processor (GPU) for accelerated graphics rendering. Instead it uses the CPU with a technique known as software rendering. Software rendering is the reason why Replicant devices appear slow at times and is responsible for a lot of crashes that can happen during usage.

At the beginning of Replicant, using the GPU required non-free software on all of the supported devices. As of today free-software replacements exist for some (but not all) the GPUs used in Replicant compatible devices, but the drivers are not ready yet for Replicant.

These drivers implement a subset of the OpenGL ES (GLES) API, and don't support Vulkan, which is now the default for the latest Android versions. They still need to be integrated in Replicant in a way that doesn't make things worse. For instance, due to their incomplete implementation of GLES, it may be needed to configure Replicant to use software rendering for specific apps or system components.

There are more details on the various options we are considering in the GraphicsResearch and GraphicsReplicant9 wiki pages.

Software renderers

Until version 6.0 0003, Replicant used libagl. libagl is fast, but caused several issues due to lack of GLES 2.0 support.

As of Replicant 6.0 0004 rc1, llvmpipe is used as the default software renderer. llvmpipe has a more complete GLES implementation than libagl (see #705), so more apps work with it, like Firefox-based browsers or more recent WebViews (see #1780). Unfortunately, llvmpipe is too slow for certain system components, which may also be true for some apps. Furthermore, certain apps still crash with llvmpipe, although less frequently. Usually the screen stays black if an app does not work with llvmpipe.

To cater for these issues, Replicant 6.0 0004 includes a mechanism to choose between llvmpipe and ligagl, on a per process basis. Such mechanism is actually used on the Replicant 6.0 0004 images to force some system components (bootanimation, SurfaceFlinger and system_server) to use libagl.

Methods to choose the software renderer


The script should be shipped in Replicant 6.0 0004 RC2.

If you run a Replicant version that is before 6.0 0004 RC2, you will need to install the scripts.

To do that, from your PC, clone the user-scripts repository:

git clone -b replicant-6.0

For the next steps, ADB needs to be set up and running as root. Connect the device to your PC. The scripts are in the networking/modem folder. Run the setup script from that folder to push the scripts to the device:

cd vendor_replicant-scripts
cd display/renderer/

Then disconnect the device. Make sure root access for apps is enabled.


Open a terminal emulator. If the terminal is not running as root, you can gain root by running:


To switch everything back to libagl, run the following command: faster

It will then switch to libagl and reboot.

To switch back use llvmpipe by default, run the following command: compatible

It will then switch back to llvmpipe by default and reboot.

Directly from the command line

If you don't want to install any scripts, you can use the following command line to switch back and forth between llvmpipe and libagl:

adb shell "grep -q "ro.libagl=1" /system/build.prop && sed "s/ro.libagl=1/ro.libagl=0/" -i /system/build.prop || sed "s/ro.libagl=0/ro.libagl=1/" -i /system/build.prop" 

Then, you will need to reboot the device. To switch back to previous renderer, you can run the above command again and reboot the device again.

This method works on both Replicant 6.0 0003 and 0004. Do note that: on 0003 you will start with libagl by default, whereas on 0004 the default is llvmpipe.

Choosing the software renderer for a specific app

  1. Find out the app ID. Example: org.gnu.icecat
  2. Force the app to always use libagl by creating empty file named libGLES_android on it's data directory (e.g. /data/data/org.gnu.icecat/). Example command:
    adb shell touch /data/data/org.gnu.icecat/libGLES_android

    To force llvmpipe instead, use a file named libGLES_mesa.
  3. Restart the app. For instance: kill it and open again.
  4. Get back to the default renderer by removing the file. Example command:
    adb shell rm /data/data/org.gnu.icecat/libGLES_android

This method only works for Replicant 6.0 0004.

Choosing the software renderer for a system component

The following method only works for Replicant 6.0 0004.

System components usually lack a directory in the data partition. Thus, another method must be used to switch their software renderer.

  1. Find out the process name. This can be done by getting the process pid with ps or pidof and then looking at /proc/<pid>/cmdline.
    For instance for surfaceflinger:
    root@i9300:/ $ pidof surfaceflinger
    root@i9300:/ $ cat /proc/1984/cmdline ; echo                                  

    Here the process name is /system/bin/surfaceflinger.
    Or for system_server:
    root@i9300:/ $ pidof system_server
    root@i9300:/ $ cat /proc/2362/cmdline ; echo                                  

    Here the process name is system_server.
  2. Force the component to always use libagl by creating an empty file at /system/etc/libGLES_android/<process_name>.
    For surfaceflinger:
    adb shell mkdir -p /system/etc/libGLES_android/system/bin
    adb shell touch /system/etc/libGLES_android/system/bin/surfaceflinger

    Or for system_server:
    adb shell mkdir -p /system/etc/libGLES_android/
    adb shell touch /system/etc/libGLES_android/system_server

    To force llvmpipe instead, create the file under /system/etc/libGLES_mesa/.
  3. Reboot your device, or restart the specific system component individually (if possible).
  4. Get back to the default renderer by removing the file.
    For surfaceflinger:
    adb shell rm /system/etc/libGLES_android/system/bin/surfaceflinger

    For system_server:
    adb shell rm /system/etc/libGLES_android/system_server

Known issues with libagl

  • Selecting the third option besides photo and video (Panorama mode) will crash the Camera app.
  • Video playback in the browser does not work. (issue #1533)
  • Screenshots do not work. (see Screenshots for a workaround)
  • Selecting wallpapers from storage does not work.
  • Screen content is sometimes shortly visible before unlocking. (issue #1275, happens with llvmpipe as well)
  • Previews of the windows in the tasks switcher are missing.
  • Switching between apps, apps and the launcher or different views inside an app is sometimes slow and the device may seem unresponsive.
  • There are issues with using folders with the Trebuchet launcher. (issue #1790, happens with llvmpipe as well)

Apps from F-Droid that do not work with libagl

Known issues with llvmpipe

  • Too slow to use in SurfaceFlinger (screen compositor).
  • If SurfaceFlinger uses llvmpipe, Gallery and Orbot render some GUI elements are visible while the main screen is black. The GUI of Simple File Manager works as long as no image is viewed in fullscreen.

See also

There is a page about GraphicsResearch that gathers information to improve graphics support.

Updated by Denis 'GNUtoo' Carikli over 1 year ago ยท 46 revisions

Also available in: PDF HTML TXT