surfman

In surfman, pixel buffers are managed through two primary abstractions: Surface and SurfaceTexture.

Surface

A Surface represents a hardware buffer of pixels. It can be rendered to via the CPU or GPU and is used for either displaying in a native widget or being bound to a texture.

There are two types of surfaces:

• Generic Surfaces: Can be bound to a texture for reading, but cannot be displayed in a widget directly.
• Widget Surfaces: Can be displayed in a widget, but cannot be bound to a texture.

Key constraints:

• Surfaces are tied to a specific Context. You cannot render to a surface from a different context than the one used to create it.
• Manual Destruction Required: You must call destroy_surface() to clean up a surface. If the surface is dropped without being explicitly destroyed, the application will panic.

SurfaceTexture

A SurfaceTexture is an OpenGL texture that wraps a Surface.

Key constraints:

• Read-only: Reading from the associated OpenGL texture reads from the underlying surface. Writing to this texture (e.g., binding it to a framebuffer and rendering to it) is undefined behavior.
• Context Flexibility: While the Surface is tied to a specific context, a SurfaceTexture can be used in a different context, provided that context shares the same adapter and connection.
• Manual Destruction Required: You must call destroy_surface_texture() to clean up. Failure to do so will result in a panic.

A Surface is a hardware pixel buffer that can be rendered to via CPU or GPU. Surfaces are categorized into two types:

1. Generic Surfaces: Can be bound to a texture for reading by other contexts but cannot be displayed directly in a native widget.
2. Widget Surfaces: Can be displayed in a native widget but cannot be bound to a texture.

Key Lifecycle and Access Rules:

• Rendering: A Surface can only be rendered to by the specific Context used to create it.
• Reading: While rendering is restricted to the owning context, a generic Surface can be read from by any context (on any thread) if it is wrapped in a SurfaceTexture.
• Memory Management: Both Surface and SurfaceTexture must be explicitly destroyed using destroy_surface() and destroy_surface_texture() respectively. Failing to call these methods will result in a panic during drop.
• Double Buffering: Depending on the platform, surfaces may be internally double-buffered. For widget surfaces, you must call present_surface() to make changes visible in the associated widget.

When creating or managing a surface, you must specify its SurfaceAccess level. This determines whether the CPU has direct memory access to the surface's pixel data.

• GPUOnly: The surface is accessible by the GPU only. This is the recommended setting for better performance as it allows the GPU to use texture swizzling. Calling lock_surface_data() on a GPUOnly surface will return a SurfaceDataInaccessible error.
• GPUCPU: The surface data is accessible by both the GPU and the CPU.
• GPUCPUWriteCombined: The surface is accessible by both, with optimizations for sequential writes (filling every byte in a range). This is optimized for writing, not reading. Note that while this doesn't affect correctness on x86, failing to follow sequential write patterns can cause severe performance penalties.

use surfman::SurfaceAccess;

// Example of choosing access levels
let access = SurfaceAccess::GPUOnly; // Recommended for performance
let access = SurfaceAccess::GPUCPU; // Use if CPU needs to read/write pixels
let access = SurfaceAccess::GPUCPUWriteCombined; // Use for optimized sequential CPU writes

In surfman, a Context represents an OpenGL rendering context that allows you to issue rendering commands to a Surface. A Context is local to a single thread and device.

To create a context, you must first create a ContextDescriptor (often referred to as a "config" or "pixel format") using the Device. The ContextDescriptor contains the specific attributes required by the underlying API for that device.

Key Lifecycle Rules:

• Surface Attachment: A new context has no attached surface. You must use bind_surface_to_context to attach a surface before rendering commands will have any effect.
• Ownership: A context takes ownership of the surfaces attached to it. To perform non-rendering operations on a surface (like presenting it to a window), you must first detach it using unbind_surface_from_context.
• Thread Locality: Contexts are local to a single thread. Use make_context_current to make a context active for the current thread.
• Destruction: Contexts must be explicitly destroyed using destroy_context(); failing to do so will cause a panic.
• Sharing: You can create a context that shares resources with another by passing an existing context to the share_with parameter in create_context.

// Conceptual workflow:
let descriptor = device.create_context_descriptor(&attributes)?;
let mut context = device.create_context(&descriptor, None)?;
device.make_context_current(&mut context)?;

device.bind_surface_to_context(&mut context, surface)?;
// ... perform rendering ...
device.present_bound_surface(&mut context)?;

device.unbind_surface_from_context(&mut context)?;
device.destroy_context(&mut context)?;

The following types are exported by the surfman crate for managing GPU resources and platform surfaces.

pub use crate::context::{ContextAttributeFlags, ContextAttributes, ContextID};
pub use crate::error::{Error, WindowingApiError};
pub use crate::info::{GLApi, GLVersion};
pub use crate::surface::{SurfaceAccess, SurfaceID, SurfaceInfo, SurfaceType, SystemSurfaceInfo};
pub use default::connection::Connection;
pub use default::context::{Context, ContextDescriptor};
pub use default::device::{Adapter, Device};
pub use default::surface::{NativeWidget, Surface, SurfaceTexture};

// macOS specific system types
#[cfg(target_os = "macos")]
pub use base::io_surface::connection::Connection as SystemConnection;
#[cfg(target_os = "macos")]
pub use base::io_surface::device::{Adapter as SystemAdapter, Device as SystemDevice};
#[cfg(target_os = "macos")]
pub use base::io_surface::surface::Surface as SystemSurface;