Hardware Acceleration
Relevant source files
The following files were used as context for generating this wiki page:
Hardware acceleration in the Termux-Desktops project refers to the offloading of graphical rendering tasks from the CPU to the Graphics Processing Unit (GPU). This is achieved through various translation layers, open-source drivers, and specialized renderers that bridge the gap between Android's Bionic-based environment and standard Linux graphical APIs like OpenGL and Vulkan.
The project supports hardware acceleration across different environments, including Proot, Chroot, and Native Termux. Depending on the hardware (primarily Qualcomm Adreno or ARM Mali GPUs), users can utilize different driver stacks such as VirGL, Zink, Turnip, or Freedreno to achieve significant performance improvements in desktop environments and 3D applications.
Sources: Documentation/HardwareAcceleration.md:1-10, Documentation/terminology.md:43-130, README.md:100-115
Key Technologies and Drivers
Hardware acceleration relies on several key components that translate standard Linux graphics calls into formats compatible with Android hardware.
Driver Comparison
| Component | Type | Description | Compatibility |
|---|---|---|---|
| VirGL | Virtual Renderer | A renderer that works with most GPUs but generally offers lower performance. | Most GPUs |
| Zink | Gallium Driver | Translates OpenGL calls to run on top of Vulkan drivers. | Vulkan-capable GPUs |
| Turnip | Vulkan Driver | Open-source Vulkan driver for Qualcomm Adreno GPUs. | Adreno 610+ |
| Freedreno | OpenGL Driver | Open-source OpenGL driver for Adreno GPUs; runs directly on OpenGL. | Adreno 610+ |
| LLVMpipe | Software Rasterizer | Uses the CPU for rendering; represents the baseline/worst performance. | All |
| Sources: Documentation/terminology.md:83-130, Documentation/HardwareAcceleration.md:16-40 |
Architecture Overview
The following diagram illustrates the relationship between the various graphics APIs and the underlying hardware drivers used in the project.
The diagram shows how high-level applications interface with hardware through various drivers. For example, Zink acts as a bridge between OpenGL apps and the Turnip Vulkan driver.
Sources: Documentation/terminology.md:83-130, Documentation/HardwareAcceleration.md:16-35
Implementation by Environment
Proot and Chroot Environments
In Proot or Chroot, hardware acceleration typically requires a bridge between the isolated environment and the Android host.
- Package Installation: Required packages include
mesa-zink,virglrenderer-mesa-zink,vulkan-loader-android, andvirglrenderer-android. - Server Initialization: A graphical server must be started in the Termux host before launching the distro.
- Vulkan (ZINK): Initialized using
virgl_test_serverwith EGL and GLES flags. - OpenGL (VIRGL): Initialized using
virgl_test_server_android.
- Vulkan (ZINK): Initialized using
- Client Execution: Within the distro, applications are launched with environment variables like
GALLIUM_DRIVER=virpipeorMESA_LOADER_DRIVER_OVERRIDE=zink.
Sources: Documentation/HardwareAcceleration.md:16-40, Documentation/chroot/ubuntu_chroot.md:144-150
Native Termux
Native Termux provides a more direct path to the GPU. For Adreno devices, users can install mesa-vulkan-icd-freedreno-dri3 to enable Turnip. Experimental Freedreno support is also available, allowing direct OpenGL rendering by building Mesa with gallium-drivers=freedreno.
Sources: Documentation/HardwareAcceleration.md:164-180, Documentation/native/termux_native.md:140-150
Performance Benchmarks
Performance varies significantly based on the driver stack used. The project cites glmark2 scores on a Snapdragon 870 (Adreno 650) to demonstrate these differences.
GLMARK2 Performance Table (Debian Proot)
| Driver | Score (Higher is Better) | GPU Info Detected |
|---|---|---|
| LLVMPIPE | ~93 | llvmpipe |
| VIRGL | ~75 | virgl (Adreno) |
| TURNIP | ~198 | virgl (Turnip Adreno) |
| ZINK | Error | zink (Adreno) |
Sources: Documentation/HardwareAcceleration.md:46-80
Rendering Flow: Zink + Turnip
The combination of Zink and Turnip is often cited as providing the best hardware acceleration for Adreno devices.
This sequence demonstrates the translation process where OpenGL commands are converted to Vulkan calls to leverage the high-performance Turnip driver.
Sources: Documentation/terminology.md:83-100, Documentation/HardwareAcceleration.md:35-42
Setup and Configuration
Environment Variables
Key variables used to toggle acceleration modes:
GALLIUM_DRIVER=virpipe: Routes rendering through the VirGL pipe.GALLIUM_DRIVER=zink: Forces the use of Zink for OpenGL to Vulkan translation.MESA_LOADER_DRIVER_OVERRIDE=zink: Overrides the default loader to use Zink.TU_DEBUG=noconform: Used with Turnip to bypass certain conformance checks for performance.
Sources: Documentation/HardwareAcceleration.md:35-42, Documentation/HardwareAcceleration.md:130-140
Troubleshooting
- Black Screens (Arch/XFCE): Often caused by the compositor. Disabling the compositor in "Window Manager Tweaks" is a common fix.
- Input Lag/Keys: Games not registering WASD keys can be fixed by enabling "Prefer scancodes" in Termux:X11 preferences.
- Mali Compatibility: ARM Mali GPUs may experience compatibility issues with VirGL due to OEM driver limitations, sometimes requiring Mesa recompilation.
Sources: Documentation/HardwareAcceleration.md:145-160, Documentation/HardwareAcceleration.md:214-222, Documentation/terminology.md:105-115
Summary
Hardware acceleration is a critical component for achieving a usable desktop experience in Termux. By leveraging the Turnip + Zink stack on Adreno devices or VirGL on a broader range of hardware, the project enables high-performance 3D rendering and smooth GUI interactions that would otherwise be impossible using software-based rendering like LLVMpipe.
Sources: Documentation/HardwareAcceleration.md:1-10, Documentation/terminology.md:120-130