Module window

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

CompositeAlphaMode

Specifies how the alpha channel of the images should be handled during compositing.

Extent2D

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.

Offset2D

An offset describes the position of a rectangle, such as a window or texture.

OutOfDate

Error occurred caused surface to be lost.

PresentMode

Specifies the mode regulating how a swapchain presents frames.

Suboptimal

Marker value returned if the swapchain no longer matches the surface properties exactly, but can still be used to present to the surface successfully.

SurfaceCapabilities

Describes information about what a Surface’s properties are. Fetch this with Surface::capabilities.

SurfaceLost

Error occurred caused surface to be lost.

SwapchainConfig

Contains all the data necessary to create a new Swapchain: color, depth, and number of images.

Enums

AcquireError

Error on acquiring the next image from a swapchain.

InitError

Error occurred during surface creation.

PresentError

Error on acquiring the next image from a swapchain.

SwapchainError

Error occurred during swapchain configuration.

Constants

DEFAULT_IMAGE_COUNT

Default image count for the swapchain.

DEFAULT_USAGE

Default image usage for the swapchain.

Traits

PresentationSurface

A surface trait that exposes the ability to present images on the associtated swap chain.

Surface

A Surface abstracts the surface of a native window.

Type Aliases

SwapImageIndex

Index of an image in the swapchain.