Trait raw_window_handle::HasWindowHandle

source ·

pub trait HasWindowHandle {
    // Required method
    fn window_handle(&self) -> Result<WindowHandle<'_>, HandleError>;
}

Expand description

A handle to a window.

Objects that implement this trait should be able to return a WindowHandle for the window that they are associated with. This handle should last for the lifetime of the object, and should return an error if the application is inactive.

Implementors of this trait will be windowing systems, like winit and sdl2. These windowing systems should implement this trait on types that already implement HasRawWindowHandle. First, it should be made sure that the display type contains a unique Active ref-counted handle. To create a WindowHandle, the Active should be used to create an ActiveHandle that is then used to create a WindowHandle. Finally, the raw window handle should be retrieved from the type and used to create a WindowHandle.

Users of this trait will include graphics libraries, like wgpu and glutin. These APIs should be generic over a type that implements HasWindowHandle, and should use the WindowHandle type to access the window handle. The window handle should be acquired and held while the window is being used, in order to ensure that the window is not deleted while it is in use.

Safety

All pointers within the resulting WindowHandle must be valid and not dangling for the lifetime of the handle.

Note that this guarantee only applies to pointers, and not any window ID types in the handle. This includes Window IDs (XIDs) from X11 and the window ID for web platforms. There is no way for Rust to enforce any kind of invariant on these types, since:

For all three listed platforms, it is possible for safe code in the same process to delete the window.
For X11, it is possible for code in a different process to delete the window. In fact, it is possible for code on a different machine to delete the window.

It is also possible for the window to be replaced with another, valid-but-different window. User code should be aware of this possibility, and should be ready to soundly handle the possible error conditions that can arise from this.

In addition, the window handle must not be invalidated for the duration of the ActiveHandle token.

Note that these requirements are not enforced on HasWindowHandle, rather, they are enforced on the constructors of WindowHandle. This is because the HasWindowHandle trait is safe to implement.