gl: add GlClientApi option to override automatic API selection

On desktop Linux (Mesa), EGL reports both OpenGL and OpenGL ES as
available client APIs. wgpu-hal automatically prefers desktop OpenGL,
which prevents GLES-only features (e.g. EXTERNAL_TEXTURE /
GL_OES_EGL_image_external_essl3) from being advertised by the adapter.

Add a `GlClientApi` enum and a `client_api` field to `GlBackendOptions`
so callers can explicitly request `OpenGlEs` (or `OpenGl`) instead of
relying on the auto-detection heuristic.

Author: cmeissl

wgpu-hal/src/gles/egl.rs

@@ -395,6 +395,7 @@ impl Inner {
         flags: wgt::InstanceFlags,
         egl: Arc<EglInstance>,
         display: khronos_egl::Display,
+        client_api: wgt::GlClientApi,
         force_gles_minor_version: wgt::Gles3MinorVersion,
     ) -> Result<Self, crate::InstanceError> {
         let version = initialize_display(&egl, display)
@@ -456,6 +457,14 @@ impl Inner {
             false
         };
 
+        let use_opengl = match client_api {
+            wgt::GlClientApi::Auto | wgt::GlClientApi::OpenGl => supports_opengl,
+            wgt::GlClientApi::OpenGlEs => {
+                log::debug!("GlClientApi::OpenGlEs: skipping desktop OpenGL, forcing GLES");
+                false
+            }
+        };
+
         let mut khr_context_flags = 0;
         let supports_khr_context = display_extensions.contains("EGL_KHR_create_context");
 
@@ -466,7 +475,7 @@ impl Inner {
         gl_context_attributes.push(3);
         gl_context_attributes.push(khronos_egl::CONTEXT_MINOR_VERSION);
         gl_context_attributes.push(3);
-        if supports_opengl && force_gles_minor_version != wgt::Gles3MinorVersion::Automatic {
+        if use_opengl && force_gles_minor_version != wgt::Gles3MinorVersion::Automatic {
             log::warn!("Ignoring specified GLES minor version as OpenGL is used");
         }
         gles_context_attributes.push(khronos_egl::CONTEXT_MAJOR_VERSION);
@@ -582,7 +591,7 @@ impl Inner {
                 }
             };
 
-            let result = if supports_opengl {
+            let result = if use_opengl {
                 create_context(khronos_egl::OPENGL_API, &gl_context_attributes).or_else(
                     |gl_error| {
                         log::debug!("Failed to create desktop OpenGL context: {gl_error}, falling back to OpenGL ES");
@@ -899,6 +908,7 @@ impl crate::Instance for Instance {
             desc.flags,
             egl,
             display,
+            desc.backend_options.gl.client_api,
             desc.backend_options.gl.gles_minor_version,
         )?;
 

wgpu-types/src/backend.rs

@@ -248,6 +248,14 @@ impl BackendOptions {
 /// Part of [`BackendOptions`].
 #[derive(Clone, Debug, Default)]
 pub struct GlBackendOptions {
+    /// Which EGL client API to use when creating the context.
+    ///
+    /// Defaults to [`GlClientApi::Auto`], which prefers desktop OpenGL when
+    /// the EGL display advertises it and falls back to OpenGL ES otherwise.
+    /// Set to [`GlClientApi::OpenGlEs`] to force OpenGL ES even on machines
+    /// that also support desktop OpenGL (required for GLES-only features such
+    /// as `EXTERNAL_TEXTURE`).
+    pub client_api: GlClientApi,
     /// Which OpenGL ES 3 minor version to request, if using OpenGL ES.
     pub gles_minor_version: Gles3MinorVersion,
     /// Behavior of OpenGL fences. Affects how `on_completed_work_done` and `device.poll` behave.
@@ -277,6 +285,7 @@ impl GlBackendOptions {
         let gles_minor_version = Gles3MinorVersion::from_env().unwrap_or_default();
         let debug_fns = GlDebugFns::from_env().unwrap_or_default();
         Self {
+            client_api: GlClientApi::Auto,
             gles_minor_version,
             fence_behavior: GlFenceBehavior::Normal,
             debug_fns,
@@ -292,6 +301,7 @@ impl GlBackendOptions {
         let fence_behavior = self.fence_behavior.with_env();
         let debug_fns = self.debug_fns.with_env();
         Self {
+            client_api: self.client_api,
             gles_minor_version,
             fence_behavior,
             debug_fns,
@@ -1018,3 +1028,21 @@ impl GlFenceBehavior {
         }
     }
 }
+
+/// Selects which EGL client API is used when creating the OpenGL context.
+///
+/// Used in [`GlBackendOptions::client_api`].
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum GlClientApi {
+    /// Prefer desktop OpenGL when the EGL display advertises it; fall back to
+    /// OpenGL ES otherwise. This is the default behaviour.
+    #[default]
+    Auto,
+    /// Always request a desktop OpenGL context.
+    ///
+    /// Falls back to OpenGL ES if the EGL display does not support desktop GL.
+    OpenGl,
+    /// Always request an OpenGL ES context, even when desktop OpenGL is
+    /// available.
+    OpenGlEs,
+}

wgpu/src/lib.rs

@@ -138,9 +138,9 @@ pub use wgt::{
     DownlevelLimits, Dx12BackendOptions, Dx12Compiler, Dx12SwapchainKind,
     Dx12UseFrameLatencyWaitableObject, DxcShaderModel, DynamicOffset, ExperimentalFeatures,
     Extent3d, ExternalTextureFormat, ExternalTextureTransferFunction, Face, Features, FeaturesWGPU,
-    FeaturesWebGPU, FilterMode, ForceShaderModelToken, FrontFace, GlBackendOptions, GlDebugFns,
-    GlFenceBehavior, Gles3MinorVersion, HalCounters, ImageSubresourceRange, IndexFormat,
-    InstanceDescriptor, InstanceFlags, InternalCounters, Limits, LoadOpDontCare,
+    FeaturesWebGPU, FilterMode, ForceShaderModelToken, FrontFace, GlBackendOptions, GlClientApi,
+    GlDebugFns, GlFenceBehavior, Gles3MinorVersion, HalCounters, ImageSubresourceRange,
+    IndexFormat, InstanceDescriptor, InstanceFlags, InternalCounters, Limits, LoadOpDontCare,
     MemoryBudgetThresholds, MemoryHints, MipmapFilterMode, MultisampleState, NoopBackendOptions,
     Origin2d, Origin3d, PassthroughShaderEntryPoint, PipelineStatisticsTypes, PollError,
     PollStatus, PolygonMode, PowerPreference, PredefinedColorSpace, PresentMode,