Repository navigation
Conversation
The container image ships Mesa 24.3's classic libGL: the glx/xlib frontend on winsys/sw/xlib, presenting with XShmPutImage. A GL guest therefore renders through zink on a headless Vulkan instance and copies the result into the X server, so its frames never create a Vulkan surface of their own -- the ICD shim sees no swapchain, applies no acquire cap, generates nothing and never gets a release note. That is why every GL title on this stack is paced by gamescope's limiter alone. Kopper is zink's own WSI: it presents through GLX/DRI3, so the client creates a VkSurfaceKHR from its X window, and the shim already serves that (VK_KHR_xcb_surface). A GL guest then rides the same ring, the same gate and the same release notes as a Vulkan guest. So build one, from the same pinned upstream source the glamor stage uses (android/mesa-glamor/fetch-mesa.sh: Mesa 26.2.6 with its patches) and the same cross file, with platforms=x11, glx=dri and opengl=true; glamor's `-Dglx=disabled -Dopengl=false -Dplatforms=` is the opposite of what a GL client needs. glvnd and shared-glapi are off so the result is one libGL.so.1, the shape the container image already has. Measured on the build: libGL.so.1.2.0 is 765 KB with LIBGL_KOPPER_DISABLE present (the option a 24.3 library does not even contain), no XShmPutImage, and libgallium-26.2.6.so carries zink and the xcb surface path. The cross file's pkg_config_libdir lists only the overlay, which carries libdrm, libglvnd and zlib -- x11, xcb, xshmfence and the DRI protocol packages live in the termux prefix, so this build appends it, overlay first. C only, so the -I ordering hazard that keeps the prefix out of the glamor build does not apply. Not wired into the payload yet: nothing copies this stage, and it has not been run on a device. The version coupling is the thing to settle first -- the imagefs has Mesa 24.3's libglapi.so.0, and glapi is inside this libGL instead, so the stack has to travel as a set.
A GL guest loads libGL.so.1 through wine's opengl32. The container image's own library is Mesa 24.3's glx/xlib build, which presents with XShmPutImage: the frames are copied into the X server and never create a Vulkan surface, so the shim sees no swapchain, applies no acquire cap, generates nothing and never gets a release note. The mesa-gl stage is the same Mesa 26.2.6 source as the glamor stage built with -Dplatforms=x11 -Dglx=dri -Dopengl=true, so a GL guest presents through GLX/DRI3 (kopper) and rides the same ring and the same gate as a Vulkan guest. Staged in lib/gl rather than lib/: both stages emit libgallium-26.2.6.so and one would overwrite the other. The launcher puts lib/gl ahead of lib/ on LD_LIBRARY_PATH, so a GL guest resolves this libGL and this libgallium while gamescope and Xwayland keep the glamor stage's copies. Both are the same Mesa version, so no process can end up with two gallium APIs. libGL keeps its lib/dri pointer in lib/gl/dri because it needs the x11-platform module. glvnd is disabled and glapi is built in, so the imagefs's Mesa 24.3 libglapi.so.0 is untouched.
The GLX stack alone does not get a GL guest onto the shim: Xwayland's glamor is
EGL-on-GBM, and with the glamor stage's EGL the server never got glamor.
Xwayland logged "Failed to make EGL context current with GL" and "with GLES2",
disabled glamor, fell back to software, and then every GL client reported "DRI3
not available" and stayed off the shim -- so the kopper libGL we ship was dead on
arrival.
That EGL is libglvnd's dispatch stub, and it was built for the termux prefix: its
compiled-in vendor dirs are /data/data/com.termux/files/usr/{etc,share}/glvnd/
egl_vendor.d, which do not exist on device, so no vendor loads at all (the client
extension list is empty) unless something sets __EGL_VENDOR_LIBRARY_DIRS. The
launcher does set it, which is enough for glvnd to find 50_mesa.json, but the
indirection is what failed and it is removable: this stage is glvnd=disabled, so
its libEGL is the implementation.
One stage now serves both sides of the socket -- the guest's GLX client and the
server's EGL-on-GBM -- which is also why both galliums stay in lib/gl together:
same tree, same version, same soname.
-Dgles2=enabled comes with egl; the staged libGLESv2 is not shipped to the
payload, which keeps the prefix's copy in front of everything else.
…here Mesa refuses EGL_OPENGL_API on Android: src/egl/main/eglcurrent.h gates it on `#if HAVE_OPENGL && !DETECT_OS_ANDROID` with the comment "OpenGL is not a valid/supported API on Android". So eglBindAPI(EGL_OPENGL_API) returns EGL_BAD_PARAMETER, the display advertises EGL_CLIENT_APIS="OpenGL_ES" only, and no config carries EGL_OPENGL_BIT. Measured on device, in one pass: GL 3.1 core -> EGL_BAD_ATTRIBUTE (the profile mask is rejected because the bound API was still ES), 2.1 -> EGL_BAD_MATCH, 1.0 -> EGL_BAD_ALLOC, GLES2/GLES3 -> SUCCESS. glamor's try_big_gl_api can never succeed, so try_gles_api is the only path -- which is also how Android Xwayland is normally configured. That path was handed libglvnd's dispatch stub from the termux prefix: its entry points resolve through libGLdispatch, whose vendor is registered by a glvnd EGL vendor library, and this stage is glvnd=disabled. glGetString returned NULL and glamor stopped at "your GL is broken", fell back to software, and every GL client then read "DRI3 not available" and stayed off the shim. Staging this stage's own libGLESv2 fixes it: glGetString reports "zink Vulkan 1.4(Turnip Adreno (TM) 740)", glamor initialises on GLES2, DRI3 appears, and a GL title (GLX + the kopper libGL) creates a swapchain through the shim for the first time -- SteamWorld Dig 2, 3 images for asked=3, declared=fifo, cap 60, acquire 60, 60.0 fps.
This was referenced Nov 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
The GL stack a guest needs to reach the shim, built from this tree and staged into
the payload. Four commits, all under
android/:877b0b9candroid/mesa-gl/build-mesa-gl.sh— Mesa zink with GLX + DRI3, one monolithiclibGL.so.1.2.06c89b6dapackage-gamescope.shstages it intolib/gl/8b083d8a3738bbe9libGLESv2, which is the path glamor actually runs onWhy GL needed its own stack at all
The container image's
libGLis Mesa 24.3'slibgl-xlib: zink renders on aheadless Vulkan instance and the frame is copied into the X server with
XShmPutImage. NoVkSurfaceKHRis ever created, so the ICD shim sees noswapchain — no acquire cap, no generation, no release note. A GL title was outside
the whole present path.
-Dplatforms=x11 -Dglx=dri -Dopengl=true -Dgallium-drivers=zink -Dglvnd=disabledgives the kopper frontend instead: the GLX client creates its surface from its X
window (
VK_KHR_xcb_surface, which the shim already serves), so a GL guest ridesthe same ring, the same gate and the same release notes as a Vulkan guest.
It is staged in
lib/gl/, notlib/: both Mesa stages emitlibgallium-26.2.6.soand one would overwrite the other. The launcher puts
lib/glfirst onLD_LIBRARY_PATH, so a GL guest resolves thislibGLand thislibgalliumwhilegamescope and Xwayland keep the glamor stage's copies. Same Mesa version in both,
so no process can end up with two gallium APIs.
The server half: glamor cannot use desktop GL here
Shipping the kopper
libGLwas not enough, and the reason is in Mesa, not in ourbuild:
src/egl/main/eglcurrent.hgatesEGL_OPENGL_APIon#if HAVE_OPENGL && !DETECT_OS_ANDROID— "OpenGL is not a valid/supported API onAndroid". So in Xwayland
eglBindAPI(EGL_OPENGL_API)returnsEGL_BAD_PARAMETER,the display advertises
EGL_CLIENT_APIS="OpenGL_ES"only, and no config carriesEGL_OPENGL_BIT.try_big_gl_apican never succeed;try_gles_apiis the onlypath — which is also how Android Xwayland is normally configured.
Measured inside the server, one pass over every request glamor might make:
BAD_ATTRIBUTEon the profile mask is the tell: it is emitted only whenapi != EGL_OPENGL_API, i.e. the thread was still bound to ES.The GLES2 path was then handed libglvnd's dispatch stub from the termux prefix.
Its entry points resolve through
libGLdispatch, whose vendor is registered by aglvnd EGL vendor library — and this stage is
glvnd=disabled, so there is none.glGetStringreturned NULL, glamor stopped at "your GL is broken", fell back tosoftware, and every GL client then read
DRI3 not available. Staging this stage'sown
libGLESv2(88 304 B, NEEDs onlylibgallium+libc) fixed it:glGetStringreportszink Vulkan 1.4(Turnip Adreno (TM) 740)and glamorinitialises on GLES2.
Verified
Retroid Pocket Nova (Adreno 740, 120 Hz panel), SteamWorld Dig 2 under gamescope,
payload built from this branch:
First time a GL title has created a swapchain through the shim.
Companion: GameNative/xserver#5 — the same build needs a server-side GLX
extension for a kopper client to bind to, and that is what the other PR turns on.
Neither half alone moves a GL title onto the shim.
Not verified
title are unmeasured.
MESA_GLX_FORCE_DIRECT=1is set by the launcher (app-side) so a GLX client doesnot fall back to indirect rendering; that change is in the app repo, not here.