.. _stdlib_vulkan_window:

===============================================================
Window — surface, swapchain, frame sync, and the present loop
===============================================================

.. das:module:: vulkan_window

Windowing and presentation: create a ``SurfaceKHR`` from a native window,
build and **recreate** a ``Swapchain`` (with its images, views, and
framebuffers), set up per-frame ``FrameSync`` primitives, and run the
acquire → record → submit → present loop via ``draw_frame``. Pair with
``create_graphics_pipeline_simple(..., dynamic_viewport = true)`` for
resize-friendly pipelines.



+++++++++
Constants
+++++++++

.. _global-vulkan_window-UINT64_MAX:

.. das:attribute:: UINT64_MAX = 0xffffffffffffffff

UINT64_MAX:uint64 const


++++++++++
Structures
++++++++++

.. _struct-vulkan_window-Swapchain:

.. das:attribute:: Swapchain

:Fields: * **handle** :  :ref:`SwapchainKHR <struct-vulkan_handles-SwapchainKHR>` - < the VkSwapchainKHR

         * **format** :  :ref:`VkFormat <enum-vulkan-VkFormat>` - < color format of the swapchain images

         * **color_space** :  :ref:`VkColorSpaceKHR <enum-vulkan-VkColorSpaceKHR>` - < color space the surface presents in

         * **width** : int - < current extent width, in pixels

         * **height** : int - < current extent height, in pixels

         * **images** : array< :ref:`VkImage <alias-VkImage>`> - < owned by the swapchain object itself; not destroyed here

         * **views** : array< :ref:`ImageView <struct-vulkan_handles-ImageView>`> - < created + owned here

         * **framebuffers** : array< :ref:`Framebuffer <struct-vulkan_handles-Framebuffer>`> - < created + owned here (after build_swapchain_framebuffers)

         * **readback_supported** : bool - < true if the images carry TRANSFER_SRC (host readback is possible)



.. _struct-vulkan_window-FrameSync:

.. das:attribute:: FrameSync

struct FrameSync


++++++++
Surfaces
++++++++

  *  :ref:`create_surface (instance: Instance; native_window: void?; native_display: void? = null) : SurfaceKHR <function-vulkan_window_create_surface_Instance_void_q__void_q_>`
  *  :ref:`queue_family_supports_present (phys: VkPhysicalDevice; queue_family: uint; surface: SurfaceKHR) : bool <function-vulkan_window_queue_family_supports_present_VkPhysicalDevice_uint_SurfaceKHR>`

.. _function-vulkan_window_create_surface_Instance_void_q__void_q_:

.. das:function:: create_surface(instance: Instance; native_window: void?; native_display: void? = null) : SurfaceKHR

def create_surface (instance: Instance; native_window: void?; native_display: void? = null) : SurfaceKHR

:Arguments: * **instance** :  :ref:`Instance <struct-vulkan_handles-Instance>`

            * **native_window** : void?

            * **native_display** : void?

.. _function-vulkan_window_queue_family_supports_present_VkPhysicalDevice_uint_SurfaceKHR:

.. das:function:: queue_family_supports_present(phys: VkPhysicalDevice; queue_family: uint; surface: SurfaceKHR) : bool

def queue_family_supports_present (phys: VkPhysicalDevice; queue_family: uint; surface: SurfaceKHR) : bool

:Arguments: * **phys** :  :ref:`VkPhysicalDevice <alias-VkPhysicalDevice>`

            * **queue_family** : uint

            * **surface** :  :ref:`SurfaceKHR <struct-vulkan_handles-SurfaceKHR>`


+++++++++
Swapchain
+++++++++

  *  :ref:`build_swapchain_framebuffers (device: Device; var sc: Swapchain; render_pass: RenderPass) <function-vulkan_window_build_swapchain_framebuffers_Device_Swapchain_RenderPass>`
  *  :ref:`create_swapchain (device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; width: int; height: int; preferred_format: VkFormat = vulkan::VkFormat.UNDEFINED) : Swapchain <function-vulkan_window_create_swapchain_Device_VkPhysicalDevice_SurfaceKHR_int_int_VkFormat>`
  *  :ref:`recreate_swapchain (var sc: Swapchain; device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; render_pass: RenderPass; width: int; height: int) <function-vulkan_window_recreate_swapchain_Swapchain_Device_VkPhysicalDevice_SurfaceKHR_RenderPass_int_int>`

.. _function-vulkan_window_build_swapchain_framebuffers_Device_Swapchain_RenderPass:

.. das:function:: build_swapchain_framebuffers(device: Device; sc: Swapchain; render_pass: RenderPass)

def build_swapchain_framebuffers (device: Device; var sc: Swapchain; render_pass: RenderPass)

:Arguments: * **device** :  :ref:`Device <struct-vulkan_handles-Device>`

            * **sc** :  :ref:`Swapchain <struct-vulkan_window-Swapchain>`

            * **render_pass** :  :ref:`RenderPass <struct-vulkan_handles-RenderPass>`

.. _function-vulkan_window_create_swapchain_Device_VkPhysicalDevice_SurfaceKHR_int_int_VkFormat:

.. das:function:: create_swapchain(device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; width: int; height: int; preferred_format: VkFormat = vulkan::VkFormat.UNDEFINED) : Swapchain

def create_swapchain (device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; width: int; height: int; preferred_format: VkFormat = vulkan::VkFormat.UNDEFINED) : Swapchain

:Arguments: * **device** :  :ref:`Device <struct-vulkan_handles-Device>`

            * **phys** :  :ref:`VkPhysicalDevice <alias-VkPhysicalDevice>`

            * **surface** :  :ref:`SurfaceKHR <struct-vulkan_handles-SurfaceKHR>`

            * **width** : int

            * **height** : int

            * **preferred_format** :  :ref:`VkFormat <enum-vulkan-VkFormat>`

.. _function-vulkan_window_recreate_swapchain_Swapchain_Device_VkPhysicalDevice_SurfaceKHR_RenderPass_int_int:

.. das:function:: recreate_swapchain(sc: Swapchain; device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; render_pass: RenderPass; width: int; height: int)

def recreate_swapchain (var sc: Swapchain; device: Device; phys: VkPhysicalDevice; surface: SurfaceKHR; render_pass: RenderPass; width: int; height: int)

:Arguments: * **sc** :  :ref:`Swapchain <struct-vulkan_window-Swapchain>`

            * **device** :  :ref:`Device <struct-vulkan_handles-Device>`

            * **phys** :  :ref:`VkPhysicalDevice <alias-VkPhysicalDevice>`

            * **surface** :  :ref:`SurfaceKHR <struct-vulkan_handles-SurfaceKHR>`

            * **render_pass** :  :ref:`RenderPass <struct-vulkan_handles-RenderPass>`

            * **width** : int

            * **height** : int


++++++++++
Frame sync
++++++++++

  *  :ref:`create_frame_sync (device: Device) : FrameSync <function-vulkan_window_create_frame_sync_Device>`

.. _function-vulkan_window_create_frame_sync_Device:

.. das:function:: create_frame_sync(device: Device) : FrameSync

def create_frame_sync (device: Device) : FrameSync

:Arguments: * **device** :  :ref:`Device <struct-vulkan_handles-Device>`


++++++++++
Frame loop
++++++++++

  *  :ref:`draw_frame (device: Device; queue: VkQueue; sc: Swapchain; render_pass: RenderPass; pool: CommandPool; sync: FrameSync; clear: VkClearValue; dynamic_viewport: bool = false; blk: block\<(cmd:CommandBuffer):void\>) : bool <function-vulkan_window_draw_frame_Device_VkQueue_Swapchain_RenderPass_CommandPool_FrameSync_VkClearValue_bool_block_ls_cmd_c_CommandBuffer_c_void_gr_>`
  *  :ref:`present_frame (device: Device; queue: VkQueue; sc: Swapchain; pool: CommandPool; sync: FrameSync; blk: block\<(cmd:CommandBuffer;target:VkImage;image_index:uint):void\>) : bool <function-vulkan_window_present_frame_Device_VkQueue_Swapchain_CommandPool_FrameSync_block_ls_cmd_c_CommandBuffer;target_c_VkImage;image_index_c_uint_c_void_gr_>`

.. _function-vulkan_window_draw_frame_Device_VkQueue_Swapchain_RenderPass_CommandPool_FrameSync_VkClearValue_bool_block_ls_cmd_c_CommandBuffer_c_void_gr_:

.. das:function:: draw_frame(device: Device; queue: VkQueue; sc: Swapchain; render_pass: RenderPass; pool: CommandPool; sync: FrameSync; clear: VkClearValue; dynamic_viewport: bool = false; blk: block<(cmd:CommandBuffer):void>) : bool

def draw_frame (device: Device; queue: VkQueue; sc: Swapchain; render_pass: RenderPass; pool: CommandPool; sync: FrameSync; clear: VkClearValue; dynamic_viewport: bool = false; blk: block<(cmd:CommandBuffer):void>) : bool

:Arguments: * **device** :  :ref:`Device <struct-vulkan_handles-Device>`

            * **queue** :  :ref:`VkQueue <alias-VkQueue>`

            * **sc** :  :ref:`Swapchain <struct-vulkan_window-Swapchain>`

            * **render_pass** :  :ref:`RenderPass <struct-vulkan_handles-RenderPass>`

            * **pool** :  :ref:`CommandPool <struct-vulkan_handles-CommandPool>`

            * **sync** :  :ref:`FrameSync <struct-vulkan_window-FrameSync>`

            * **clear** :  :ref:`VkClearValue <handle-vulkan-VkClearValue>`

            * **dynamic_viewport** : bool

            * **blk** : block<(cmd: :ref:`CommandBuffer <struct-vulkan_handles-CommandBuffer>`):void>

.. _function-vulkan_window_present_frame_Device_VkQueue_Swapchain_CommandPool_FrameSync_block_ls_cmd_c_CommandBuffer;target_c_VkImage;image_index_c_uint_c_void_gr_:

.. das:function:: present_frame(device: Device; queue: VkQueue; sc: Swapchain; pool: CommandPool; sync: FrameSync; blk: block<(cmd:CommandBuffer;target:VkImage;image_index:uint):void>) : bool

def present_frame (device: Device; queue: VkQueue; sc: Swapchain; pool: CommandPool; sync: FrameSync; blk: block<(cmd:CommandBuffer;target:VkImage;image_index:uint):void>) : bool

:Arguments: * **device** :  :ref:`Device <struct-vulkan_handles-Device>`

            * **queue** :  :ref:`VkQueue <alias-VkQueue>`

            * **sc** :  :ref:`Swapchain <struct-vulkan_window-Swapchain>`

            * **pool** :  :ref:`CommandPool <struct-vulkan_handles-CommandPool>`

            * **sync** :  :ref:`FrameSync <struct-vulkan_window-FrameSync>`

            * **blk** : block<(cmd: :ref:`CommandBuffer <struct-vulkan_handles-CommandBuffer>`;target: :ref:`VkImage <alias-VkImage>`;image_index:uint):void>