Expand description
Windowing system interoperability.
Screen presentation (fullscreen or window) of images requires two objects:
- Surface is an abstraction of a native screen or window, for graphics use. It hosts a chain of multiple images, which can be presented on a surface (“swapchain”).
Window
gfx-hal
does not provide any methods for creating a native window or screen.
This is handled exeternally, either by managing your own window or by using a
library such as winit, and providing
the raw window handle.
Surface
Once you have a window handle, you need to create a surface compatible with the instance of the graphics API you currently use.
PresentationSurface
A surface has an implicit swapchain in it.
The most interesting part of a swapchain are the contained presentable images/backbuffers. Presentable images are specialized images, which can be presented on the screen. They are 2D color images with optionally associated depth-stencil images.
The common steps for presentation of a frame are acquisition and presentation:
let mut render_semaphore = device.create_semaphore().unwrap();
let (frame, suboptimal) = surface.acquire_image(!0).unwrap();
// render the scene..
// `render_semaphore` will be signalled once rendering has been finished
present_queue.present(&mut surface, frame, Some(&mut render_semaphore));
Queues need to synchronize with the presentation engine, usually done via signalling a semaphore once a frame is available for rendering and waiting on a separate semaphore until scene rendering has finished.
Recreation
DOC TODO
Structs
Specifies how the alpha channel of the images should be handled during compositing.
An extent describes the size of a rectangle, such as
a window or texture. It is not used for referring to a
sub-rectangle; for that see command::Rect
.
An offset describes the position of a rectangle, such as a window or texture.
Error occurred caused surface to be lost.
Specifies the mode regulating how a swapchain presents frames.
Marker value returned if the swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.
Describes information about what a Surface
’s properties are.
Fetch this with Surface::capabilities.
Error occurred caused surface to be lost.
Contains all the data necessary to create a new Swapchain
:
color, depth, and number of images.
Enums
Error on acquiring the next image from a swapchain.
Error occurred during surface creation.
Error on acquiring the next image from a swapchain.
Error occurred during swapchain configuration.
Constants
Default image count for the swapchain.
Default image usage for the swapchain.
Traits
A surface trait that exposes the ability to present images on the associtated swap chain.
A Surface
abstracts the surface of a native window.
Type Definitions
Index of an image in the swapchain.