request_adapter requires specific configuration to succeed with webgl feature enabled

[ltxitai]

Description
When enabling webgl feature and running on wasm target, Instance::request_adapter requires one of the following to be true, otherwise it will fail with no informative error:

1. Either: only backends: wgpu::Backends::GL should be used when creating the instance (see Only GL Backend on WASM is allowed when webgl feature is enabled #3847 )
2. Or: a compatible_surface must be provided when calling request_adapter (e.g. created from an OffscreenCanvas etc.).

Note the documentation of request_adapter doesn't specify compatible_surface may be required in some cases, and the documentation of backends doesn't imply that choosing more than just GL may cause no adapter to be provided.

Repro steps
Run the following in wasm with the webgl feature - the expect will fail.
Running without the webgl feature - it works.
Creating a Surface and passing it in the compatible_surface would also make it work, which is very surprising.
Using wgpu::Backends::GL for backends would also make it work, which is strange - I would not have expected lowering restrictions to make it work.

let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
  backends: wgpu::Backends::all(),
  flags: wgpu::InstanceFlags::empty(),
  dx12_shader_compiler: wgpu::Dx12Compiler::default(),
  gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
});

let adapter = instance
  .request_adapter(&wgpu::RequestAdapterOptions {
      power_preference: wgpu::PowerPreference::HighPerformance,
      force_fallback_adapter: false,
      compatible_surface: None,
  })
  .await
  .expect("Failed to create wgpu::Adapter");

Expected vs observed behavior
Expected adapter to be available, or for it to be clearly documented in either Instance::new or Instance::request_adapter that compatible_surface may be required in some cases, or that allowing more backends may unintuitively cause adapter to be unavailable.
Observed: fails every time, unless using one of the workarounds described above.

Extra materials
N/A

Platform
Tried with wgpu 0.18 and 0.19.1 - same observed behavior.
Tried with Chrome 120.0.6099.234 and Firefox 120.0.1 - same observed behavior.
Running on MacOS 13.6.1

[ltxitai]

Sorry, seems like the important step is actually to call instance.create_surface, regardless of whether it is later passed to request_adapter. Which is even more strange.

[ltxitai]

After some more testing - it seems one must create_surface from the same Instance one wishes to create an adapter, and the surface must remain alive during the call to request_adapter, although it may be immediately dropped afterwards.
Possibly I should close this issue and open a new one to reduce confusion?

[cwfitzgerald]

I actually didn't realize this wasn't properly documented! Yes, the webgl surface requirement absolutely should be documented.