Vulkan#

Capturing Vulkan#

The PVRCarbon Recorder for Vulkan is a Vulkan layer. The PVRCarbon Recording layer consists of the VkLayer_PowerVR_carbon.json manifest file and VkLayer_PowerVR_carbon library.

Supported Platforms#

  • Android (Rooted/Unrooted)

  • Linux

  • Windows

Note

The remote recording functionality from the PVRCarbon GUI automatically configures Android devices for recording. Remote recording from the GUI should be preferred in most cases.

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#

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/graphics/validation-layer#enable-layers-outside-app.

Vulkan Layers on Android allow the PVRCarbon Recorder to be set up easily. The PVRCarbon Recorder layers simply need to be enabled using adb. On Vulkan the required PVRCarbon Recorder layer is libVkLayer_PowerVR_carbon.so.

Firstly, this layer needs to be copied onto the Android device. This layer is found in the PVRCarbon package in Recorder/Vk/Android/[DEVICE_CPU_ARCHITECTURE]/. Android searches for layers in a couple of different places:

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

    adb disable-verity
adb reboot
adb root
adb shell "setenforce 0"
adb shell "mkdir -p /data/local/debug/vulkan"
adb push libVkLayer_PowerVR_carbon.so /data/local/debug/vulkan/

  • 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 libVkLayer_PowerVR_carbon.so /data/local/tmp
adb shell "run-as <target_app_name>" cp /data/local/tmp/libVkLayer_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 debug 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 VK_LAYER_POWERVR_carbon"

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"

To enable the PVRCarbon Recorder layer globally:

# This attempts to load layers for all applications, including native executables
adb shell "setprop debug.vulkan.layers VK_LAYER_POWERVR_carbon"

Note

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

Recording on Android 9 and Earlier#

Vulkan Android Unrooted Setup#

On non-rooted devices, the layer has to be built into the .apk as follows:

  1. Copy the layer to the /src/main/jniLibs/<ABI> directory.

  2. The layer should be enabled at vkInstance creation.

PVRCarbon will start recording upon launch, unless configured to start at a different frame.

Vulkan Android Rooted Setup#

On rooted devices it is possible to use layers without building them into the .apk. This can be achieved as follows:

  • Install the layer by placing it into /data/local/debug/vulkan on the device. adb push libVkLayer_PowerVR_carbon.so /data/local/debug/vulkan

    Note

    When copying the layer, depending on the device, it may be necessary to set the ownership group and access permissions, as shown below.

    chown system:system libVkLayer_PowerVR_carbon.so
chmod 777 libVkLayer_PowerVR_carbon.so

  • Enable the layer globally for all applications. This will be cleared on reboot:

    adb shell
setprop debug.vulkan.layers VK_LAYER_POWERVR_carbon

PVRCarbon will start recording upon launch, unless configured to start at a different frame.

Linux Setup#

The PVRCarbon Recording layer is a Vulkan layer meaning that the Vulkan loader being used (often libvulkan.so) must support layers. Note that implementation provided Vulkan loaders very often do not support Vulkan layers out of the box. In this case a separate Vulkan loader should be used. The canonical Vulkan loader supporting Vulkan layers is Khronos’ Vulkan-Loader which can be obtained through any of the following:

The PVRCarbon Vulkan recording layer must be made visible to the Vulkan loader which can be achieved in one of the following ways:

  • Adding the path to the directory containing PVRCarbon’s VkLayer_PowerVR_carbon.json manifest file and VkLayer_PowerVR_carbon library to VK_LAYER_PATH:

    export VK_LAYER_PATH=<Path to directory containing VkLayer_PowerVR_carbon.json>:$VK_LAYER_PATH

  • By default Khronos’ Vulkan-Loader also searches for explicit layers (of which PVRCarbon is one) in /usr/share/vulkan/explicit_layer.d and /etc/vulkan/explicit_layer.d so PVRCarbon can also be made visible to the Vulkan-Loader in this manner.

Once the PVRCarbon Vulkan recording layer has been made visible to the Vulkan loader the layer can be enabled in one of the following ways:

  • Adding VK_LAYER_POWERVR_carbon to the VkInstanceCreateInfo::ppEnabledLayerNames when calling vkCreateInstance and updating VkInstanceCreateInfo::enabledLayerCount accordingly;

  • Adding VK_LAYER_POWERVR_carbon to the list of layers specified by the VK_INSTANCE_LAYERS environment variable: export VK_INSTANCE_LAYERS=VK_LAYER_POWERVR_carbon:$VK_INSTANCE_LAYERS

Windows Setup#

The PVRCarbon Recording layer is a Vulkan layer meaning that the Vulkan loader being used (often libvulkan.dll) must support layers. Note that implementation provided Vulkan loaders very often do not support Vulkan layers out of the box. In this case a separate Vulkan loader should be used. The canonical Vulkan loader supporting Vulkan layers is Khronos’ Vulkan-Loader which can be obtained through any of the following:

The PVRCarbon Vulkan recording layer must be made visible to the Vulkan loader which can be achieved in one of the following ways:

  • Adding the path to the directory containing PVRCarbon’s VkLayer_PowerVR_carbon.json manifest file and VkLayer_PowerVR_carbon library to VK_LAYER_PATH:

    set VK_LAYER_PATH=<Path to directory containing VkLayer_PowerVR_carbon.json>;%VK_LAYER_PATH%

  • Adding the path to PVRCarbon’s VkLayer_PowerVR_carbon.json manifest file as a new 32-bit DWORD value to one of the following Windows registry keys:

    • If using a 64-bit build of PVRCarbon: HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\ExplicitLayers

    • If using a 32-bit build of PVRCarbon on 64-bit Windows: HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Khronos\Vulkan\ExplicitLayers

Once the PVRCarbon Vulkan recording layer has been made visible to the Vulkan loader the layer can be enabled in one of the following ways:

  • Adding VK_LAYER_POWERVR_carbon to the VkInstanceCreateInfo::ppEnabledLayerNames when calling vkCreateInstance and updating VkInstanceCreateInfo::enabledLayerCount accordingly;

  • Adding VK_LAYER_POWERVR_carbon to the list of layers specified by the VK_INSTANCE_LAYERS environment variable: set VK_INSTANCE_LAYERS=VK_LAYER_POWERVR_carbon;%VK_INSTANCE_LAYERS% If using Visual Studio this variable can be set in Project->Properties->Debugging->Environment.