ferroui-vulkan 0.3.0

The Vulkan platform contracts of FerroUI: the instance, the device, the graphics context, the swap chain render target of a surface and the import of external objects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

use crate::{IVulkanPlatformGraphicsContext, IVulkanRenderTarget};
use ferroui_base::platform::surfaces::IPlatformRenderSurface;
use ferroui_base::PixelSize;
use std::any::TypeId;
use std::rc::Rc;
use std::sync::Arc;

/// A surface that is presented to through a `VkSurfaceKHR` and a swap chain.
///
/// A render surface announces that it is one through
/// `try_get_surface_kind(TypeId::of::<dyn IVulkanKhrSurfacePlatformSurface>())`,
/// which returns an `Rc<dyn IVulkanKhrSurfacePlatformSurface>`; see
/// [`try_get_vulkan_khr_surface`].
pub trait IVulkanKhrSurfacePlatformSurface: IPlatformRenderSurface {
    /// The scaling from logical units to device pixels.
    fn scaling(&self) -> f64;

    /// The size of the surface in device pixels.
    fn size(&self) -> PixelSize;

    /// Creates the `VkSurfaceKHR` of the surface for the instance of
    /// `context`.
    ///
    /// # Panics
    /// Panics when the window system refuses the surface.
    fn create_surface(&self, context: &dyn IVulkanPlatformGraphicsContext) -> u64;

    /// Releases the surface.
    fn dispose(&self);
}

/// The render surface viewed as a surface with a `VkSurfaceKHR`, when it is
/// one.
pub fn try_get_vulkan_khr_surface(
    surface: &dyn IPlatformRenderSurface,
) -> Option<Rc<dyn IVulkanKhrSurfacePlatformSurface>> {
    surface
        .try_get_surface_kind(TypeId::of::<dyn IVulkanKhrSurfacePlatformSurface>())?
        .downcast_ref::<Rc<dyn IVulkanKhrSurfacePlatformSurface>>()
        .cloned()
}

/// A platform render surface that provides its own [`IVulkanRenderTarget`],
/// e.g. an offscreen image-based target that doesn't involve a swapchain.
///
/// A render surface announces that it is one through
/// `try_get_surface_kind(TypeId::of::<dyn IVulkanRenderTargetPlatformSurface>())`,
/// which returns an `Rc<dyn IVulkanRenderTargetPlatformSurface>`; see
/// [`try_get_vulkan_render_target_surface`].
///
/// This API is private to the framework and its backends.
pub trait IVulkanRenderTargetPlatformSurface: IPlatformRenderSurface {
    /// Creates the render target of the surface for `context`.
    fn create_render_target(&self, context: &Rc<dyn IVulkanPlatformGraphicsContext>) -> Rc<dyn IVulkanRenderTarget>;
}

/// The render surface viewed as a surface with its own Vulkan render
/// target, when it is one.
pub fn try_get_vulkan_render_target_surface(
    surface: &dyn IPlatformRenderSurface,
) -> Option<Rc<dyn IVulkanRenderTargetPlatformSurface>> {
    surface
        .try_get_surface_kind(TypeId::of::<dyn IVulkanRenderTargetPlatformSurface>())?
        .downcast_ref::<Rc<dyn IVulkanRenderTargetPlatformSurface>>()
        .cloned()
}

/// Lets a context present to surfaces that are not Vulkan surfaces
/// themselves (the window of a platform).
///
/// A platform registers the factory among the platform features of its
/// options ([`VulkanPlatformSpecificOptions`](crate::VulkanPlatformSpecificOptions)),
/// from where every context of the platform graphics takes it; a context
/// announces it through its optional features as an `Arc<dyn
/// IVulkanKhrSurfacePlatformSurfaceFactory>` (`try_get_shared`).
pub trait IVulkanKhrSurfacePlatformSurfaceFactory: Send + Sync {
    /// Whether the context can present to the surface.
    fn can_render_to_surface(
        &self,
        context: &dyn IVulkanPlatformGraphicsContext,
        surface: &Arc<dyn IPlatformRenderSurface>,
    ) -> bool;

    /// Creates the Vulkan view of the surface.
    fn create_surface(
        &self,
        context: &dyn IVulkanPlatformGraphicsContext,
        surface: &Arc<dyn IPlatformRenderSurface>,
    ) -> Rc<dyn IVulkanKhrSurfacePlatformSurface>;
}