vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_win32_surface

Description

Name

VK_KHR_win32_surface - instance extension

VK_KHR_win32_surface

Name String
VK_KHR_win32_surface
Extension Type
Instance extension
Registered Extension Number
10
Revision
6
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_surface
Contact

Other Extension Metadata

Last Modified Date
2017-04-24
IP Status
No known IP claims.
Contributors
  • Patrick Doane, Blizzard
  • Faith Ekstrand, Intel
  • Ian Elliott, LunarG
  • Courtney Goeltzenleuchter, LunarG
  • Jesse Hall, Google
  • James Jones, NVIDIA
  • Antoine Labour, Google
  • Jon Leech, Khronos
  • David Mao, AMD
  • Norbert Nopper, Freescale
  • Alon Or-bach, Samsung
  • Daniel Rakos, AMD
  • Graham Sellers, AMD
  • Ray Smith, ARM
  • Jeff Vigil, Qualcomm
  • Chia-I Wu, LunarG

Description

The VK_KHR_win32_surface extension is an instance extension. It provides a mechanism to create a SurfaceKHR object (defined by the VK_KHR_surface extension) that refers to a Win32 HWND, as well as a query to determine support for rendering to the windows desktop.

New Commands

New Structures

New Bitmasks

New Enum Constants

Issues

1) Does Win32 need a way to query for compatibility between a particular physical device and a specific screen? Compatibility between a physical device and a window generally only depends on what screen the window is on. However, there is not an obvious way to identify a screen without already having a window on the screen.

RESOLVED: No. While it may be useful, there is not a clear way to do this on Win32. However, a method was added to query support for presenting to the windows desktop as a whole.

2) If a native window object (HWND) is used by one graphics API, and then is later used by a different graphics API (one of which is Vulkan), can these uses interfere with each other?

RESOLVED: Yes.

Uses of a window object by multiple graphics APIs results in undefined behavior. Such behavior may succeed when using one Vulkan implementation but fail when using a different Vulkan implementation. Potential failures include:

  • Creating then destroying a flip presentation model DXGI swapchain on a window object can prevent createSwapchainKHR from succeeding on the same window object.
  • Creating then destroying a SwapchainKHR on a window object can prevent creation of a bitblt model DXGI swapchain on the same window object.
  • Creating then destroying a SwapchainKHR on a window object can effectively SetPixelFormat to a different format than the format chosen by an OpenGL application.
  • Creating then destroying a SwapchainKHR on a window object on one PhysicalDevice can prevent createSwapchainKHR from succeeding on the same window object, but on a different PhysicalDevice that is associated with a different Vulkan ICD.

In all cases the problem can be worked around by creating a new window object.

Technical details include:

  • Creating a DXGI swapchain over a window object can alter the object for the remainder of its lifetime. The alteration persists even after the DXGI swapchain has been destroyed. This alteration can make it impossible for a conformant Vulkan implementation to create a SwapchainKHR over the same window object. Mention of this alteration can be found in the remarks section of the MSDN documentation for DXGI_SWAP_EFFECT.
  • Calling GDI’s SetPixelFormat (needed by OpenGL’s WGL layer) on a window object alters the object for the remainder of its lifetime. The MSDN documentation for SetPixelFormat explains that a window object’s pixel format can be set only one time.
  • Creating a SwapchainKHR over a window object can alter the object for its remaining lifetime. Either of the above alterations may occur as a side effect of createSwapchainKHR.

Version History

  • Revision 1, 2015-09-23 (Jesse Hall)

    • Initial draft, based on the previous contents of VK_EXT_KHR_swapchain (later renamed VK_EXT_KHR_surface).
  • Revision 2, 2015-10-02 (James Jones)

    • Added presentation support query for win32 desktops.
  • Revision 3, 2015-10-26 (Ian Elliott)

    • Renamed from VK_EXT_KHR_win32_surface to VK_KHR_win32_surface.
  • Revision 4, 2015-11-03 (Daniel Rakos)

    • Added allocation callbacks to vkCreateWin32SurfaceKHR.
  • Revision 5, 2015-11-28 (Daniel Rakos)

    • Updated the surface create function to take a pCreateInfo structure.
  • Revision 6, 2017-04-24 (Jeff Juliano)

    • Add issue 2 addressing reuse of a native window object in a different Graphics API, or by a different Vulkan ICD.

See Also

Win32SurfaceCreateFlagsKHR, Win32SurfaceCreateInfoKHR, createWin32SurfaceKHR, getPhysicalDeviceWin32PresentationSupportKHR

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Synopsis

Documentation

createWin32SurfaceKHR Source #

Arguments

:: forall io. MonadIO io 
=> Instance

instance is the instance to associate the surface with.

-> Win32SurfaceCreateInfoKHR

pCreateInfo is a pointer to a Win32SurfaceCreateInfoKHR structure containing parameters affecting the creation of the surface object.

-> ("allocator" ::: Maybe AllocationCallbacks)

pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

-> io SurfaceKHR 

vkCreateWin32SurfaceKHR - Create a VkSurfaceKHR object for an Win32 native window

Valid Usage (Implicit)

  • instance must be a valid Instance handle

Return Codes

Success
Failure

See Also

VK_KHR_win32_surface, AllocationCallbacks, Instance, SurfaceKHR, Win32SurfaceCreateInfoKHR

getPhysicalDeviceWin32PresentationSupportKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

physicalDevice is the physical device.

physicalDevice must be a valid PhysicalDevice handle

-> ("queueFamilyIndex" ::: Word32)

queueFamilyIndex is the queue family index.

queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by getPhysicalDeviceQueueFamilyProperties for the given physicalDevice

-> io Bool 

vkGetPhysicalDeviceWin32PresentationSupportKHR - Query queue family support for presentation on a Win32 display

Description

This platform-specific function can be called prior to creating a surface.

Valid Usage (Implicit)

See Also

VK_KHR_win32_surface, PhysicalDevice

data Win32SurfaceCreateInfoKHR Source #

VkWin32SurfaceCreateInfoKHR - Structure specifying parameters of a newly created Win32 surface object

Valid Usage (Implicit)

See Also

VK_KHR_win32_surface, StructureType, Win32SurfaceCreateFlagsKHR, createWin32SurfaceKHR

Constructors

Win32SurfaceCreateInfoKHR 

Fields

Instances

Instances details
Storable Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Show Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Eq Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

FromCStruct Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

ToCStruct Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Zero Win32SurfaceCreateInfoKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

newtype Win32SurfaceCreateFlagsKHR Source #

VkWin32SurfaceCreateFlagsKHR - Reserved for future use

Description

Win32SurfaceCreateFlagsKHR is a bitmask type for setting a mask, but is currently reserved for future use.

See Also

VK_KHR_win32_surface, Win32SurfaceCreateInfoKHR

Instances

Instances details
Storable Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Bits Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Methods

(.&.) :: Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR #

(.|.) :: Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR #

xor :: Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR #

complement :: Win32SurfaceCreateFlagsKHR -> Win32SurfaceCreateFlagsKHR #

shift :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

rotate :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

zeroBits :: Win32SurfaceCreateFlagsKHR #

bit :: Int -> Win32SurfaceCreateFlagsKHR #

setBit :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

clearBit :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

complementBit :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

testBit :: Win32SurfaceCreateFlagsKHR -> Int -> Bool #

bitSizeMaybe :: Win32SurfaceCreateFlagsKHR -> Maybe Int #

bitSize :: Win32SurfaceCreateFlagsKHR -> Int #

isSigned :: Win32SurfaceCreateFlagsKHR -> Bool #

shiftL :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

unsafeShiftL :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

shiftR :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

unsafeShiftR :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

rotateL :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

rotateR :: Win32SurfaceCreateFlagsKHR -> Int -> Win32SurfaceCreateFlagsKHR #

popCount :: Win32SurfaceCreateFlagsKHR -> Int #

FiniteBits Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Read Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Show Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Eq Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Ord Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

Zero Win32SurfaceCreateFlagsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_win32_surface

pattern KHR_WIN32_SURFACE_SPEC_VERSION :: forall a. Integral a => a Source #

type KHR_WIN32_SURFACE_EXTENSION_NAME = "VK_KHR_win32_surface" Source #

pattern KHR_WIN32_SURFACE_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #

type HINSTANCE = Ptr () Source #

type HWND = Ptr () Source #

newtype SurfaceKHR Source #

Constructors

SurfaceKHR Word64 

Instances

Instances details
Storable SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Show SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Eq SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Ord SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

HasObjectType SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

IsHandle SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Zero SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles