Module gfx_hal::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.
• [Swapchain][Swapchain] is a chain of multiple images, which can be presented on a surface.

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 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(&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.
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.
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.
CreationError	Error occurred during swapchain creation.
InitError	Error occurred during surface creation.
PresentError	Error on acquiring the next image from a swapchain.

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 Definitions

SwapImageIndex

Index of an image in the swapchain.