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 persistent 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 without layers#

To perform recording without using the provided layers you can build PVRCarbon directly into your application by copying the libraries into the /src/main/jniLibs/<ABI> directory and modifying the application to preload the libraries.

e.g.

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"

    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.

Note

To be able to correctly pass OpenGL ES calls from the PVRCarbon recorder libraries to the host PVRCarbon needs to know the location of the OpenGL ES libraries on the system. By default, PVRCarbon will attempt to locate them them however in some situations it may be necessary to explicitly set their location 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.

Note

To be able to correctly pass OpenGL ES calls from the PVRCarbon recorder libraries to the host implementation PVRCarbon needs to know the location of the OpenGL ES libraries on the system. By default, PVRCarbon will attempt to locate them however in some situations it may be necessary to explicitly set their location 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>