[−][src]Module vulkano::swapchain

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 5 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 potentially unsafe. It is your responsibility to keep the window alive for at least as long as the surface exists. In many cases Surface may be able to do this for you, if you pass it ownership of your Window (or a reference-counting container for it).

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.hwnd(), Arc::clone(&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::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):

let ext = DeviceExtensions {
    khr_swapchain: true,
    .. DeviceExtensions::none()
};

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

let caps = surface.capabilities(device.physical_device())?;

// Use the current window size or some fixed resolution.
let dimensions = caps.current_extent.unwrap_or([640, 480]);

// Try to use double-buffering.
let buffers_count = match caps.max_image_count {
    None => max(2, caps.min_image_count),
    Some(limit) => min(max(2, caps.min_image_count), limit)
};

// Preserve the current surface transform.
let transform = caps.current_transform;

// Use the first available format.
let (format, color_space) = caps.supported_formats[0];

Then, call Swapchain::new().

// The created swapchain will be used as a color attachment for rendering.
let usage = ImageUsage {
    color_attachment: true,
    .. ImageUsage::none()
};

let sharing_mode = SharingMode::Exclusive(present_queue.family().id());

// Create the swapchain and its buffers.
let (swapchain, buffers) = Swapchain::new(
    // Create the swapchain in this `device`'s memory.
    device,
    // The surface where the images will be presented.
    surface,
    // How many buffers to use in the swapchain.
    buffers_count,
    // The format of the images.
    format,
    // The size of each image.
    dimensions,
    // How many layers each image has.
    1,
    // What the images are going to be used for.
    usage,
    // Describes which queues will interact with the swapchain.
    sharing_mode,
    // What transformation to use with the surface.
    surface_transform,
    // How to handle the alpha channel.
    composite_alpha,
    // How to present images.
    present_mode,
    // Clip the parts of the buffer which aren't visible.
    true,
    // No previous swapchain.
    None
)?;

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 retrieved all the images that belong to it (see previous section), you can draw on it. This is done in three steps:

use vulkano::swapchain;
use vulkano::sync::GpuFuture;
// let mut (swapchain, images) = Swapchain::new(...);
loop {
    let (image_num, acquire_future)
        = swapchain::acquire_next_image(swapchain.clone(), None).unwrap();

    // The command_buffer contains the draw commands that modify the framebuffer
    // constructed from images[image_num]
    acquire_future
        .then_execute(queue.clone(), command_buffer).unwrap()
        .then_swapchain_present(queue.clone(), swapchain.clone(), image_num)
        .then_signal_fence_and_flush().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_and_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.

PresentRegion

Represents a region on an image.

RectangleLayer

Represents a rectangular region on an image layer.

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 retrieving 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.

present_incremental

Same as swapchain::present, except it allows specifying a present region. Areas outside the present region may be ignored by Vulkan in order to optimize presentation.