Skip to content

android: build the GL stack a guest needs to reach the shim (GLX + kopper, EGL/GBM, GLES2) - #41

Open
joshuatam wants to merge 5 commits into
gamenativefrom
feat/kopper-gl-stack
Open

joshuatam wants to merge 5 commits into
gamenativefrom
feat/kopper-gl-stack

Conversation

@joshuatam

@joshuatam joshuatam commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

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/:

commit what
877b0b9c android/mesa-gl/build-mesa-gl.sh — Mesa zink with GLX + DRI3, one monolithic libGL.so.1.2.0
6c89b6da package-gamescope.sh stages it into lib/gl/
8b083d8a the same stage also builds EGL + GBM, so Xwayland's glamor has a usable EGL
3738bbe9 and a real libGLESv2, which is the path glamor actually runs on

Why GL needed its own stack at all

The container image's libGL is Mesa 24.3's libgl-xlib: zink renders on a
headless Vulkan instance and the frame is copied into the X server with
XShmPutImage. No VkSurfaceKHR is ever created, so the ICD shim sees no
swapchain — 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=disabled
gives 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 rides
the same ring, the same gate and the same release notes as a Vulkan guest.

It is staged in lib/gl/, not lib/: both Mesa stages emit libgallium-26.2.6.so
and one would overwrite the other. The launcher puts lib/gl first on
LD_LIBRARY_PATH, so a GL guest resolves this libGL and this libgallium while
gamescope 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 libGL was not enough, and the reason is in Mesa, not in our
build: src/egl/main/eglcurrent.h gates EGL_OPENGL_API on
#if HAVE_OPENGL && !DETECT_OS_ANDROID — "OpenGL is not a valid/supported API on
Android"
. So in Xwayland eglBindAPI(EGL_OPENGL_API) returns EGL_BAD_PARAMETER,
the display advertises EGL_CLIENT_APIS="OpenGL_ES" only, and no config carries
EGL_OPENGL_BIT. try_big_gl_api can never succeed; try_gles_api is the only
path — which is also how Android Xwayland is normally configured.

Measured inside the server, one pass over every request glamor might make:

EGL_CLIENT_APIS=[OpenGL_ES ]
config[0..2] RENDERABLE_TYPE=0x0044   ES1=0 ES2=1 ES3=1 GL=0
eglBindAPI(OpenGL)=0 err=BAD_PARAMETER
GL 3.1 core → BAD_ATTRIBUTE · 3.3 core → BAD_ATTRIBUTE
GL 2.1 compat → BAD_MATCH   · 1.0 compat / no attribs → BAD_ALLOC
GLES2 / GLES3 → SUCCESS

BAD_ATTRIBUTE on the profile mask is the tell: it is emitted only when
api != 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 a
glvnd EGL vendor library — and this stage is glvnd=disabled, so there is none.
glGetString returned NULL, glamor stopped at "your GL is broken", fell back to
software, and every GL client then read DRI3 not available. Staging this stage's
own libGLESv2 (88 304 B, NEEDs only libgallium + libc) fixed it:
glGetString reports zink Vulkan 1.4(Turnip Adreno (TM) 740) and glamor
initialises on GLES2.

Verified

Retroid Pocket Nova (Adreno 740, 120 Hz panel), SteamWorld Dig 2 under gamescope,
payload built from this branch:

Xwayland      glGetString = zink Vulkan 1.4(Turnip Adreno (TM) 740)
              glamor initialised on GLES2, no "DRI3 not available"
Dig2.exe      maps gamescope/lib/gl/libGL.so.1.2.0 + libgallium-26.2.6.so
gn-vkshim     ICD loaded pid=Dig2.exe
              proxy swapchain create: 3 images for asked=3 ceiling=8
              present mode: declared=fifo source=guest cap=60 acquire=60 generate=0
screen        game content at 60.0 fps, HUD "LIMITED BY: FPS CAP"

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

  • One 2D title at a 60 cap on one device. Tear, pacing under load, and a 3D GL
    title are unmeasured.
  • MESA_GLX_FORCE_DIRECT=1 is set by the launcher (app-side) so a GLX client does
    not fall back to indirect rendering; that change is in the app repo, not here.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant