20 unstable releases (7 breaking)
|0.8.1||Oct 31, 2023|
|0.7.2||Aug 3, 2023|
|0.7.1||Jun 19, 2023|
|0.6.0||Feb 23, 2023|
|0.1.2||Nov 19, 2019|
#35 in Graphics APIs
3,318 downloads per month
Used in 9 crates (2 directly)
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
winitor 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.
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.
surfman is not a UI toolkit. For that, see GTK+ and many other libraries. It's possible
surfman alongside any of these UI toolkits to efficiently integrate GPU rendering into an
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
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,
surfmanexplicitly 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
The ANGLE implementation of OpenGL on Windows is not generally thread-safe, so attempts to render on background threads will generally segfault.
surfmancarefully 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
XPutImage()often cause the data to be copied several times. In contrast,
surfmanallows you to render to the screen with as few copies as feasible—sometimes even zero, depending on the platform.
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.
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.)
Direct3D 11 support on Windows.
YUV surfaces, for software video codecs.
Support for running in a browser with WebAssembly.
surfman is licensed under the same terms as Rust itself.
surfman abides by the same code of conduct as Rust itself.
Cross-platform GPU device and surface management.
You can use this crate to multithread a graphics application so that rendering happens on multiple threads, sharing textures among them in the most efficient manner. It may also be useful as a lightweight framework for just initializing rendering in native applications. This is in contrast to crates like SDL, GLFW, winit, and Glutin, all of which have a broader focus in that they manage windowing and the event loop as well.