OpenGL ES#

Capturing OpenGL ES#

The PVRCarbon Recorder for OpenGL ES consists of two components:

  • An OpenGL ES layer libGlLayer_PowerVR_carbon.so for Android 10 (API level 29) and higher

  • A set of libraries:

    • libEGL

    • libGLESv2

    • libPVRCarbon

Supported Platforms#

  • Android

  • Linux

  • Windows

Android Setup#

Note

Depending on your adb version, the adb shell commands shown here may or may not need quotation marks around the arguments.

Recording on Android 10 Onwards#

Recording on Android can be done directly on device, or alternatively can be performed remotely via the PVRCarbon GUI.

This section will go through the process of recording directly on a device. The instructions presented here are based on the following document: https://developer.android.com/ndk/guides/rootless-debug-gles#enable-layers

OpenGL ES layers on Android allow the PVRCarbon Recorder to be set up easily. The PVRCarbon Recorder layers simply need to be enabled using adb. On OpenGL ES, the required PVRCarbon Recorder layer is libGlLayer_PowerVR_carbon.so.

Firstly, this layer needs to be copied onto the Android device. This layer is found in the PVRCarbon package in Recorder/GLES/Android/[DEVICE_CPU_ARCHITECTURE]/. Android searches for layers in the following locations:

  • /data/local/debug/gles - copying layers into this location requires root access. Layers can be copied using the following commands in adb:

    adb root
adb disable-verity
adb reboot
adb root
adb shell "setenforce 0"
adb shell "mkdir -p /data/local/debug/gles"
adb push libGlLayer_PowerVR_carbon.so /data/local/debug/gles/`

  • In the target application’s base directory. It is important to note that the target application must be debuggable or adb must have root access. You can copy a layer using the following commands in adb:

    adb push libGlLayer_PowerVR_carbon.so /data/local/tmp
adb shell "run-as <target_app_name> cp /data/local/tmp/libGlLayer_PowerVR_carbon.so ."

You can either enable the layer on an individual app (settings) or globally (setprop). Global properties are cleared when the device is rebooted while app settings are not.

There are certain conditions that have to be met before Android’s security policies will allow external layers to be loaded. One of the following conditions must be true:

  • The target application’s manifest file includes the following meta-data element (only applies to apps that target Android 11 (API level 30) or higher):

    <meta-data android:name="com.android.graphics.injectLayers.enable" android:value="true" />

    You should use this option to debug/record your own application.

  • The target app is debuggable. This option gives you more debug information, but might negatively affect the performance of your app;

  • The target app is run on a userdebug build of the operating system which grants root access.

Once the layer is on the device and the target application is ready, the layer can be enabled. To enable the PVRCarbon Recorder layer on a per-app basis:

# Enable layers
adb shell "settings put global enable_gpu_debug_layers 1"

# Specify application which is going to be recorded
adb shell "settings put global gpu_debug_app <target_app_name>"

# Specify the layer that should be enabled
adb shell "settings put global gpu_debug_layers_gles libGlLayer_PowerVR_carbon.so"

Layers enabled on a per-app basis are persistant across reboots, so need to be disabled manually:

# Delete the global setting that enables layers
adb shell "settings delete global enable_gpu_debug_layers"

# Delete the global setting that selects target application
adb shell "settings delete global gpu_debug_app"

# Delete the global setting that specifies layer list
adb shell "settings delete global gpu_debug_layers_gles"

To enable the PVRCarbon Recorder layer globally:

# This attempts to load layers for all applications, including native executables
adb shell "setprop debug.gles.layers libGlLayer_PowerVR_carbon.so"

Note

Remember that globally-enabled layers are disabled after a reboot.

Recording on Android 9 and Earlier#

OpenGL ES Rooted Android Setup#

On rooted devices, PVRCarbon can be installed as a driver. This can be achieved as follows:

  • Copy the contents of the <PVRCarbon Package>/Recorder/GLES/Android directory to /data/local/tmp/ on your device. Once copied, make PVRCarbonInstaller.sh executable with:

    chmod 755 /data/local/tmp/PVRCarbonInstaller.sh

  • Install PVRCarbon by running PVRCarbonInstaller.sh as root.

    cd /data/local/tmp
./PVRCarbonInstaller.sh

PVRCarbon can be uninstalled by running this again as root a second time.

Note

To start recording on a rooted device using OpenGL ES libraries, the Android property pvrcbn.enable will need to be enabled. This will tell PVRCarbon that it needs to start recording. This can also be set in the pvrcarbon.json configuration file. See the Configuration Options section for how to do this.

Note

Before rebooting the device use setprop pvrcbn.enable 0, otherwise the rooted device cannot be booted up.

OpenGL ES Unrooted Android Setup#

To use PVRCarbon directly on an Android device, it must be built into your application’s .apk by copying it to the /src/main/jniLibs/<ABI> directory. The application will need to be modified to preload the libraries.

package com.powervr.OGLES2Water
import android.app.NativeActivity

public class OGLES2Water extends NativeActivity
{
    @Override
    protected void onCreate (Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
    }

    static
    {
        try
        {
            System.loadLibrary("PVRCarbon");
            System.loadLibrary("EGL");
            System.loadLibrary("GLESv2");
        }
        catch( UnsatisfiedLinkError e )
        {
            System.err.println("Failed to preload PVRCarbon.\n" + e);
        }
    }
}

Linux Setup#

  1. Copy PVRCarbon’s libEGL.so, libEGL.so.1, libGLESv2.so, libGLESv2.so.2, and libPVRCarbon.so to any directory and add the path to LD_LIBRARY_PATH.

    export LD_LIBRARY_PATH=<Path to directory containing PVRCarbon recording libraries>:$LD_LIBRARY_PATH

    In rare cases, LD_LIBRARY_PATH may not work as expected. In these cases it may be possible to use LD_PRELOAD to preload the PVRCarbon recording libraries before any other library is loaded by the application.

    export LD_PRELOAD="<Path to directory containing PVRCarbon recording libraries>/libEGL.so:<Path to directory containing PVRCarbon recording libraries>/libGLESv2.so:<Path to directory containing PVRCarbon recording libraries>/libPVRCarbon.so:$LD_PRELOAD"

    Note

    Using LD_LIBRARY_PATH should always be preferred if possible. LD_PRELOAD should be used as a last resort and may well cause unexpected behaviour.

  2. PVRCarbon’s OpenGL ES recording library names mirror the canonical names used by implementation/platforms for their own OpenGL ES library names so will be used instead of the host libraries. To be able to correctly pass down OpenGL ES calls from the PVRCarbon recorder libraries to the host PVRCarbon needs to know the location of the OpenGL ES graphics libraries on the system. By default, PVRCarbon will attempt to locate them itself however this process isn’t infallible and it may be necessary to explicitly set these paths using PVRCARBON_host_library_egl and PVRCARBON_host_library_glesv2.

    export PVRCARBON_host_library_egl=<Path to the host libEGL.so library>
export PVRCARBON_host_library_glesv2=<Path to the host libGLESv2.so library>

Windows Setup#

  1. Copy PVRCarbon’s libEGL.dll, libGLESv2.dll, and PVRCarbon.dll to the executable directory. Alternatively, copy to any directory and add this path to the head of PATH.

    set PATH=<Path to directory containing PVRCarbon's recording libraries>:%PATH%

  2. PVRCarbon’s OpenGL ES recording library names mirror the canonical names used by implementation/platforms for their own OpenGL ES library names so will be used instead of the host libraries.

    To be able to correctly pass down OpenGL ES calls from the PVRCarbon recorder libraries to the host implementation PVRCarbon needs to know the location of the OpenGL ES graphics libraries on the system. By default, PVRCarbon will attempt to locate them itself however this process isn’t infallible and it may be necessary to explicitly set these paths using PVRCARBON_host_library_egl and PVRCARBON_host_library_glesv2.

    set PVRCARBON_host_library_egl=<Path to the host libEGL.dll library>
set PVRCARBON_host_library_glesv2=<Path to the host libGLESv2.dll library>