Revamped API Proposal

[mrobinson]

In the interest of simplifying the surfman and preparing for adding support for interoperability with wgpu and for cross-process surface handles, I would like to propose version 2 of the API:

Connection

pub enum Connection {
    Android(...),
    Angle(...),
    Cgl(...),
    Ohos(...),
    SurfacelessMesa(...),
    Wayland(...),
    Wgl(...),
    X11(...),
}

Adapter

pub enum Adapter {
    Android(...),
    Angle(...),
    Cgl(...),
    Egl(...),
    Ohos(...),
    Wgl(...),
}

Surface

pub enum Surface {
    Window(WindowSurface),
    Buffer(BufferSurface),
}

pub enum BufferSurface {
    Android(...),
    Direct3d(...),
    IoSurface(...)
    Ohos(...),
    Pbuffer(...),
}

pub enum WindowSurface {
    Android(...),
    AppKit(...)
    Ohos(...),
    Wayland(...),
    Win32(...),
    X11(...),
}

Notes:

• Only WindowSurface would implement present meaning it's not possible to call present on a buffer surface (this causes an error today).
• Mutability concerns would be handled by a mutable getter for the currently bound surface:

  if let Some(Surface::Window(window_surface)) = cnnection.bound_surface_mut() {
      window_surface.present(&device);
  }

• Multi is eliminated. Instead a factory returns the most appropriate context given what is enabled at compile-time and what is currently running (when choosing between X11 and Wayland).
• This opens up the possibility of other kinds of offscreen buffers such as GBM, which will be necessary for cross-process rendering and integration with wgpu.
• The idea is that BufferSurface will provide a fallible method to get a shareable handle to be used for cross-process surfaces.

[jdm]

this makes sense! Where do platform-specific extensions like

surfman/src/angle/surface.rs

Line 422 in 9eaf3fc

/// Given a D3D11 texture, create a surface texture that wraps that texture. This method is unsafe

fit into this new model?

[mrobinson]

I think there are a couple things we could do here.

1. For some APIs such as create_surface_from_texture used on ANGLE, I think it will make sense to have some kind of external handle API for buffer sharing (with wgpu and to send across the process) boundary. In those cases the handle could also be used to import. Image:

 pub enum BufferHandle {
      IoSurface(...),
      DmaBuf(...),
      Android(...),
      Ohos(...),
      D3DTexture(...),
}

// create_surface_from_texture
let surface = device.import_buffer_handle(&context, handle);

2. For other APIs such as ANGLE's create_surface_texture_from_texture and the CGL/IOSurface specific APIs, the internal device could expose special APIs:

if let Device::ANGLE(device) = device {
    let texture = device.texture_for_sampling(...);
}