Module vulkano::swapchain [] [src]

Link between Vulkan and a window and/or the screen.

Before you can draw on the screen or a window, you have to create two objects:

Creating a surface can be done with only an Instance object. However creating a swapchain requires a Device object.

Once you have a swapchain, you can retrieve Image objects from it and draw to them just like you would draw on any other image.

Surfaces

A surface is an object that represents a location where to render. It can be created from an instance and either a window handle (in a platform-specific way) or a monitor.

In order to use surfaces, you will have to enable the VK_KHR_surface extension on the instance. See the instance module for more information about how to enable extensions.

Creating a surface from a window

There are 6 extensions that each allow you to create a surface from a type of window:

For example if you want to create a surface from an Android surface, you will have to enable the VK_KHR_android_surface extension and use Surface::from_anativewindow. See the documentation of Surface for all the possible constructors.

Trying to use one of these functions without enabling the proper extension will result in an error.

Note that the Surface object is unsafe. It is your responsibility to keep the window alive for at least as long as the surface exists.

Example

use std::ptr;
use vulkano::instance::Instance;
use vulkano::instance::InstanceExtensions;
use vulkano::swapchain::Surface;

let instance = {
    let extensions = InstanceExtensions {
        khr_surface: true,
        khr_win32_surface: true,        // If you don't enable this, `from_hwnd` will fail.
        .. InstanceExtensions::none()
    };

     match Instance::new(None, &extensions, None) {
        Ok(i) => i,
        Err(err) => panic!("Couldn't build instance: {:?}", err)
    }
};

let window = build_window();        // Third-party function, not provided by vulkano
let _surface = unsafe {
    let hinstance: *const () = ptr::null();     // Windows-specific object
    Surface::from_hwnd(instance.clone(), hinstance, window).unwrap()
};

Creating a surface from a monitor

Currently no system provides the VK_KHR_display extension that contains this feature. This feature is still a work-in-progress in vulkano and will reside in the display module.

Swapchains

A surface represents a location on the screen and can be created from an instance. Once you have a surface, the next step is to create a swapchain. Creating a swapchain requires a device, and allocates the resources that will be used to display images on the screen.

A swapchain is composed of one or multiple images. Each image of the swapchain is presented in turn on the screen, one after another. More information below.

Swapchains have several properties:

You can query the supported values of all these properties with Surface::get_capabilities().

Creating a swapchain

In order to create a swapchain, you will first have to enable the VK_KHR_swapchain extension on the device (and not on the instance like VK_KHR_surface).

Then, you should query the capabilities of the surface with Surface::get_capabilities() and choose which values you are going to use. Then, call Swapchain::new.

TODO: add example here

Creating a swapchain not only returns the swapchain object, but also all the images that belong to it.

Acquiring and presenting images

Once you created a swapchain and retreived all the images that belong to it (see previous section), you can draw on it. This is done in three steps:

TODO: add example here loop { let index = swapchain::acquire_next_image(None).unwrap(); draw(images[index]); swapchain::present(queue, index).unwrap(); }

Recreating a swapchain

In some situations, the swapchain will become invalid by itself. This includes for example when the window is resized (as the images of the swapchain will no longer match the window's) or, on Android, when the application went to the background and goes back to the foreground.

In this situation, acquiring a swapchain image or presenting it will return an error. Rendering to an image of that swapchain will not produce any error, but may or may not work. To continue rendering, you will need to recreate the swapchain by creating a new swapchain and passing as last parameter the old swapchain.

TODO: suboptimal stuff

use vulkano::swapchain;
use vulkano::swapchain::AcquireError;
use vulkano::sync::GpuFuture;

// let mut swapchain = Swapchain::new(...);
let mut recreate_swapchain = false;

loop {
    if recreate_swapchain {
        swapchain = swapchain.0.recreate_with_dimension([1024, 768]).unwrap();
        recreate_swapchain = false;
    }

    let (ref swapchain, ref _images) = swapchain;

    let (index, acq_future) = match swapchain::acquire_next_image(swapchain.clone(), None) {
        Ok(r) => r,
        Err(AcquireError::OutOfDate) => { recreate_swapchain = true; continue; },
        Err(err) => panic!("{:?}", err)
    };

    // ...

    let final_future = acq_future
        // .then_execute(...)
        .then_swapchain_present(queue.clone(), swapchain.clone(), index)
        .then_signal_fence();

    final_future.flush().unwrap();      // TODO: PresentError?
}

Modules

display

Allows you to create surfaces that fill a whole display, outside of the windowing system.

Structs

AcquiredImage
Capabilities

The capabilities of a surface when used by a physical device.

PresentFuture

Represents a swapchain image being presented on the screen.

SupportedCompositeAlpha

List of supported composite alpha modes.

SupportedCompositeAlphaIter

Enumeration of the CompositeAlpha that are supported.

SupportedPresentModes

List of PresentModes that are supported.

SupportedPresentModesIter

Enumeration of the PresentModes that are supported.

SupportedSurfaceTransforms

List of supported composite alpha modes.

SupportedSurfaceTransformsIter

Enumeration of the SurfaceTransform that are supported.

Surface

Represents a surface on the screen.

Swapchain

Contains the swapping system and the images that can be shown on a surface.

SwapchainAcquireFuture

Represents the moment when the GPU will have access to a swapchain image.

Enums

AcquireError

Error that can happen when calling acquire_next_image.

CapabilitiesError

Error that can happen when retreiving a surface's capabilities.

ColorSpace

How the presentation engine should interpret the data.

CompositeAlpha

How the alpha values of the pixels of the window are treated.

PresentMode

The way presenting a swapchain is accomplished.

SurfaceCreationError

Error that can happen when creating a debug callback.

SurfaceTransform

A transformation to apply to the image before showing it on the screen.

SwapchainCreationError

Error that can happen when creation a swapchain.

Functions

acquire_next_image

Tries to take ownership of an image in order to draw on it.

acquire_next_image_raw

Unsafe variant of acquire_next_image.

present

Presents an image on the screen.