feat: support OpenGL EGL and GLX contexts by ciscorn · Pull Request #230 · maplibre/maplibre-native-rs

ciscorn · 2026-06-07T12:34:12Z

Resolves #229.

Linux OpenGL rendering used GLX, which requires X11/Xvfb. This PR adds an EGL context so headless OpenGL works without an X server (beneficial for container environments), and makes EGL the default OpenGL context on Linux.

Feature changes

opengl: OpenGL backend. The Linux default is now EGL (surfaceless, no X server needed)
glx: use the GLX (X11) context on Linux (the previous default)

CI matrix

Linux OpenGL jobs split into egl (no xvfb) and glx (xvfb).

Blocker

fix(core): make headless OpenGL display singletons thread-safe maplibre-native#4332

AI assistance

Claude was used for investigating MLN and coding assistance.

Copilot

Pull request overview

This PR adds explicit OpenGL context selection on Linux (EGL vs GLX) so headless OpenGL rendering works without an X server by default, and updates build/CI wiring to match MapLibre Native’s MLN_WITH_* options. It also introduces a temporary serialization workaround in the C++ bridge to avoid crashes when creating/destroying headless OpenGL renderers concurrently.

Changes:

Add egl, glx, and x11 Cargo features and map them in build.rs to the corresponding MapLibre Native build/link configuration.
Make EGL the default Linux OpenGL context (surfaceless) and split CI into separate egl (no Xvfb) and glx (Xvfb) jobs.
Serialize OpenGL headless display create/teardown in the bridge (map_renderer.h) via a global mutex until the upstream fix lands.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`src/cpp/map_renderer.h`	Adds an OpenGL-only global mutex + forced backend activation to serialize headless display init/teardown.
`README.md`	Documents new Linux OpenGL context/windowing feature flags and updated dependency instructions.
`justfile`	Updates Linux dependency installation to support `egl` vs `glx` backends (and Xvfb only for GLX).
`examples/slint/Cargo.toml`	Exposes the new `egl/glx/x11` feature passthroughs for the Slint example.
`Cargo.toml`	Defines new `egl/glx/x11` features and their relationships to `opengl`.
`build.rs`	Adds feature-derived OpenGL context selection and adjusts CMake/link flags; emits feature-combination warnings.
`.github/workflows/ci.yml`	Splits Linux OpenGL CI into `egl` and `glx` variants, running GLX under Xvfb.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

CommanderStorm

I think this needs another quick round, or at least a lot more clarity in the approach 😉

CommanderStorm · 2026-06-07T12:38:19Z

+- `egl`: use EGL context (default)
+- `glx`: use a GLX context. Implies `x11`
+- `x11`: build with X11 support


needs much more docs what this is and when to use which.

I am for example not sure if we should have an x11 feature or just an glx feature..

I dropped the egl and x11 feature flags and kept only glx, by not covering the relatively niche EGL + X11 case for now. The docs are simplified accordingly.

CommanderStorm · 2026-06-07T12:41:42Z

 - `vulkan` (default on Linux/Windows): `cargo build --features vulkan`
- `opengl` (cross-platform): `cargo build --features opengl`
 - `metal` (default on macOS/iOS): `cargo build --features metal`
+- `opengl` (Linux/Windows): `cargo build --features opengl`


Since our dependencys no longer install anything for this, should it remain a feature?
We should remove dead features..

It looks dead but it's needed as the platform selector.

I actually thought the same and considered opengl-egl / opengl-glx features, but stopped because we still need to select Windows + OpenGL.

CommanderStorm · 2026-06-07T12:48:47Z

+// TODO: Remove this mutex once the upstream fix is released and `MLN_REVISION` is
+// bumped: https://github.com/maplibre/maplibre-native/pull/4332
+#if MLN_RENDER_BACKEND_OPENGL
+inline std::mutex& headlessDisplayMutex() {
+    static std::mutex mutex;
+    return mutex;
+}
+#endif
+


If there is a PR out already, I would like to have the fix only in one place unless you have a reason to need this right now.
If that is the case, I am fine with merging.

Having a fix in one place is just a lot less work overall that we are 90% sure to forget 😉

Agreed. But without it, concurrent renderers crash on both EGL and GLX, and maplibre/maplibre-native#4332 will probably take a while to be merged ~~and released~~.

So I'm a bit unsure, but I think adding the mutex to MLN-rs too is not so harmful for now.

will probably take a while to be merged and released

Sounds like a solvable issue. Core is not bound to any of the other release cycles ^^
CC @louwers

CommanderStorm

but before merging, lets see what bart has to say regarding the mutex. seems solvable

CommanderStorm · 2026-06-07T17:25:05Z

also, ci is red a bit

CommanderStorm · 2026-06-07T23:24:58Z

I don't think my review above changed..

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

ciscorn · 2026-06-08T00:32:25Z

Thank you for reviewing! I'll wait for maplibre/maplibre-native#4332.

# Conflicts: # .github/workflows/ci.yml # Cargo.toml # build.rs # examples/slint/Cargo.toml # justfile

ciscorn · 2026-06-19T06:51:45Z

I'd like to merge now to avoid further heavy conflicts. I'll file a tracking issue to drop the duplicate thread-safety, blocked on maplibre/maplibre-native#4332.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

feat: support OpenGL EGL and GLX contexts

d3e4a3f

Copilot AI review requested due to automatic review settings June 7, 2026 12:34

Copilot started reviewing on behalf of ciscorn June 7, 2026 12:34 View session

Copilot AI reviewed Jun 7, 2026

View reviewed changes

Comment thread build.rs Outdated

Comment thread README.md Outdated

ciscorn marked this pull request as draft June 7, 2026 12:46

CommanderStorm reviewed Jun 7, 2026

View reviewed changes

ciscorn added 4 commits June 7, 2026 22:26

adjust OpenGL CI

dd40cb7

refactor OpenGL platform/context selectors

d6daed6

fix justfile

5ce0c57

simplify OpenGL features to opengl + glx

63c4e13

CommanderStorm approved these changes Jun 7, 2026

View reviewed changes

ciscorn requested a review from CommanderStorm June 7, 2026 23:23

GraphicsApi

aea28b9

CommanderStorm approved these changes Jun 7, 2026

View reviewed changes

ciscorn requested a review from Copilot June 7, 2026 23:26

Copilot started reviewing on behalf of ciscorn June 7, 2026 23:26 View session

Copilot AI reviewed Jun 7, 2026

View reviewed changes

Comment thread src/cpp/map_renderer.h Outdated

Comment thread build.rs Outdated

fix(clippy): extract checkout_maplibre_native from build_local

f39202a

ciscorn marked this pull request as ready for review June 7, 2026 23:37

ciscorn marked this pull request as draft June 8, 2026 00:32

ciscorn added 3 commits June 8, 2026 09:41

s/MLN_REVISION/MLN_COMMIT/g

a351b70

Drop libglu1-mesa-dev dependency

f94ec4b

Merge remote-tracking branch 'upstream/main' into opengl-glx-egl

1b49489

# Conflicts: # .github/workflows/ci.yml # Cargo.toml # build.rs # examples/slint/Cargo.toml # justfile

ciscorn marked this pull request as ready for review June 19, 2026 06:51

ciscorn requested a review from Copilot June 19, 2026 07:01

Copilot started reviewing on behalf of ciscorn June 19, 2026 07:02 View session

Copilot AI reviewed Jun 19, 2026

View reviewed changes

Comment thread build.rs Outdated

Comment thread justfile Outdated

Address Copilot review

05d6405

ciscorn enabled auto-merge (squash) June 19, 2026 07:40

ciscorn mentioned this pull request Jun 19, 2026

Remove the headless OpenGL display mutex workaround #245

Open

ciscorn merged commit 624c6aa into maplibre:main Jun 19, 2026
18 checks passed

ciscorn deleted the opengl-glx-egl branch June 19, 2026 08:36

CommanderStorm mentioned this pull request Jun 19, 2026

chore: release #236

Merged

Uh oh!

Conversation

ciscorn commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Feature changes

CI matrix

Blocker

AI assistance

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

CommanderStorm left a comment

Choose a reason for hiding this comment

Uh oh!

CommanderStorm Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

ciscorn Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CommanderStorm Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

ciscorn Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

CommanderStorm Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

ciscorn Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CommanderStorm Jun 7, 2026

Choose a reason for hiding this comment

Uh oh!

CommanderStorm left a comment

Choose a reason for hiding this comment

Uh oh!

CommanderStorm commented Jun 7, 2026

Uh oh!

CommanderStorm commented Jun 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

ciscorn commented Jun 8, 2026

Uh oh!

ciscorn commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ciscorn commented Jun 7, 2026 •

edited

Loading

ciscorn Jun 7, 2026 •

edited

Loading

ciscorn Jun 7, 2026 •

edited

Loading

ciscorn commented Jun 19, 2026 •

edited

Loading