surfman

surfman is a low-level, cross-platform Rust library for managing surfaces, blocks of image data in GPU memory. Using this library, you can:

• Draw to a window (perhaps created with winit) on the CPU.

• Render to a window (created via winit or otherwise) with OpenGL.

• Render to an off-screen surface with OpenGL.

• Use a surface created on one thread as an OpenGL texture on another thread.

• Draw to a surface with a platform-specific GPU API like Metal.

surfman forms the low-level graphics infrastructure of the Servo project, where it allows for easy porting of the browser's WebGL and WebXR code to a variety of platforms.

What surfman is not

surfman is not a full-featured GPU rendering API. It doesn't attempt to abstract over rendering libraries like OpenGL, Metal, and Direct3D. For that, try gfx-rs.

surfman is also not a windowing solution. It can only render to a window that is already open and needs to be paired with a crate like winit to actually open the window.

Likewise, surfman is not a UI toolkit. For that, see GTK+ and many other libraries. It's possible to use surfman alongside any of these UI toolkits to efficiently integrate GPU rendering into an application, however.

Why surfman?

Most of this functionality can be achieved with other libraries, such as glutin and SDL. However, for several use cases you can achieve better performance and/or correctness with surfman. For example:

• On multi-GPU systems, games typically want to use the discrete GPU instead of the integrated GPU for better performance, while UI applications want the reverse for better energy consumption. However, most game-oriented OpenGL windowing libraries end up using the discrete GPU on Linux and macOS and the integrated GPU on Windows. On such systems, surfman explicitly allows you to choose which GPU you would like to render with.

• OpenGL's share context or share lists feature allows you to share textures across contexts. However, this often exposes driver bugs, and, even if it works, it causes most operations to take mutex locks. Efficient texture sharing requires the use of platform-specific APIs, which surfman abstracts over.

• The ANGLE implementation of OpenGL on Windows is not generally thread-safe, so attempts to render on background threads will generally segfault. surfman carefully works around all the safety issues so that the library is safe to use from any thread.

• Applications such as emulators and video players that draw to the CPU want to avoid copying pixels as much as possible. Classic APIs for transferring image data like glTexImage2D() and XPutImage() often cause the data to be copied several times. In contrast, surfman allows you to render to the screen with as few copies as feasible—sometimes even zero, depending on the platform.

Platform support

The library supports the following platforms:

• Windows, with OpenGL via the native WGL framework.

• Windows, with OpenGL via Google's ANGLE library.

• macOS, with OpenGL via the native CGL framework.

• macOS, with Metal.

• Linux/other Unix, with OpenGL on Wayland.

• Linux/other Unix, with OpenGL on X11 via GLX.

• Android P and up, with OpenGL.

• Generic CPU rendering of OpenGL via the OSMesa framework.

Future work

The following features may be added later:

• Support for Android Marshmallow, Nougat, and Oreo.

• Partial presentation, to allow the OS to composite only the region of the window that has changed.

• CPU rendering support on more platforms. (Right now, the CPU rendering features only work on macOS.)

• Vulkan support.

• Direct3D 11 support on Windows.

• YUV surfaces, for software video codecs.

• Support for running in a browser with WebAssembly.

License

surfman is licensed under the same terms as Rust itself.

surfman abides by the same code of conduct as Rust itself.