Skip to content
Permalink
Browse files

Change log for March 17, 2017 Vulkan 1.0.44 spec update:

  * Bump API patch number and header version number to 44 for this update.

Github Issues:

  * Fix description of <<features-extentperimagetype, Allowed Extent Values
    Based On Image Type>> (public issue 290).
  * Better specify VK_DEVICE_LOST behavior around flink:vkQueueSubmit,
    flink:vkWaitForFences, and flink:vkGetFenceStatus (public issue 423).
  * Clarify definition of flink:vkGetQueryPoolResults::pname:queryCount
    (public issue 441).
  * Simplify and clean up normative language. Remove shall and replace
    recommend and variants with should wherever possible (public issue 448).
  * Fix all dangling internal cross-references in the 1.0-extensions
    specification, and add scripts/checkXrefs to find these in the future
    (public issue 456).
  * Reverse order of ChangeLog.txt entries so the most recent version is
    documented first (public issue 463)
  * Removes "become invalid" which clashes with invalid state for command
    buffers. (public issue 467)
  * Disallowed pending state in spec text for vkResetCommandBuffer, matching
    valid usage (public issue 468)
  * Removes sentence describing invalid state "like initial state". (public
    issue 469)
  * Disallows begin command buffer from resetting command buffers in the
    "recording" state. (public issue 470)
  * Removes mention of state from description of
    VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT (public issue 471)
  * Removed extra valid usage statement in VkSubmitInfo (public issue 472)

Internal Issues:

  * Clarify description of the pname:imageLayout member of
    sname:VkDescriptorImageInfo.
  * Fix typos where etext:VK_VIEW_TYPE* was used instead of
    etext:VK_IMAGE_VIEW_TYPE.
  * Removed the <<VK_KHR_display>> and <<VK_KHR_display_swapchain>> example
    code from the specification and noted it has been moved to the Vulkan
    SDK cube demo (internal issue 179).
  * Reorder VkExternalMemoryHandleTypeFlagBitsNV description (internal issue
    480).
  * Clarify than an implementation is
    <<fundamentals-validusage-flags,permitted to return 'undefined' bit
    flags>> in a bitfield (internal issue 640).
  * Break Valid Usage statements describing unrelated parameters into
    separate statements, and add a style guide entry to follow this approach
    (internal issue 685).
  * Move valid usage statement for slink:VkImageCreateInfo from spec body to
    the explicit valid usage block (internal issue 693).
  * Fix typos in the descriptions of slink:VkDisplaySurfaceCreateInfoKHR,
    flink:vkCreateDisplayModeKHR, and
    flink:vkGetDisplayPlaneSupportedDisplaysKHR in the <<display,Presenting
    Directly to Display Devices>> section (internal issue 698, 704, 716).
  * Clarified that mandatory depth/stencil formats are only a requirement
    for 2D images (internal issue 719).
  * Clarify that variables decorated with DeviceIndex/ViewIndex must be in
    the Input storage class (internal issue 733).
  * Work around generator script problem with removal of Unicode literals
    from Python 3.0-3.2 using `future` package (internal issue 737).
  * Remove nonexistent structure type enums from vk.xml (internal issue
    738).
  * Fix validextensionstructs attributes for structures in the pname:pNext
    chain for VkPresentInfoKHR, fixing implicit valid usage statements for
    those structures (internal issue 740).

New Extensions:
  • Loading branch information...
oddhack committed Mar 18, 2017
1 parent 3e4bee3 commit 43f1fd5550cac5547cf3421ad0783f46a6e64aa2
Showing with 2,390 additions and 2,294 deletions.
  1. +1 −0 .gitattributes
  2. +1,695 −1,624 ChangeLog.txt
  3. +1 −1 doc/specs/vulkan/Makefile
  4. +3 −3 doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt
  5. +1 −1 doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt
  6. +1 −1 doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt
  7. +32 −182 doc/specs/vulkan/appendices/VK_KHR_display.txt
  8. +23 −74 doc/specs/vulkan/appendices/VK_KHR_display_swapchain.txt
  9. +7 −6 doc/specs/vulkan/appendices/VK_KHR_surface.txt
  10. +9 −8 doc/specs/vulkan/appendices/VK_KHR_swapchain.txt
  11. +1 −1 doc/specs/vulkan/appendices/VK_KHR_wayland_surface.txt
  12. +1 −1 doc/specs/vulkan/appendices/VK_KHX_external_memory_fd.txt
  13. +11 −2 doc/specs/vulkan/appendices/VK_KHX_external_memory_win32.txt
  14. +1 −1 doc/specs/vulkan/appendices/VK_KHX_external_semaphore_fd.txt
  15. +2 −2 doc/specs/vulkan/appendices/VK_KHX_external_semaphore_win32.txt
  16. +3 −3 doc/specs/vulkan/appendices/VK_NVX_device_generated_commands.txt
  17. +11 −2 doc/specs/vulkan/appendices/VK_NV_external_memory_win32.txt
  18. +3 −0 doc/specs/vulkan/appendices/boilerplate.txt
  19. +1 −1 doc/specs/vulkan/appendices/glossary.txt
  20. +1 −1 doc/specs/vulkan/appendices/invariance.txt
  21. +4 −8 doc/specs/vulkan/chapters/VK_EXT_debug_marker.txt
  22. +9 −0 doc/specs/vulkan/chapters/VK_EXT_debug_report.txt
  23. +4 −0 doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/queries.txt
  24. +26 −10 doc/specs/vulkan/chapters/VK_KHR_display/display.txt
  25. +11 −4 doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt
  26. +9 −1 doc/specs/vulkan/chapters/VK_KHR_swapchain/wsi.txt
  27. +2 −2 doc/specs/vulkan/chapters/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt
  28. +1 −1 doc/specs/vulkan/chapters/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt
  29. +4 −4 doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generatedcommands.txt
  30. +7 −7 doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/generation.txt
  31. +5 −5 doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/indirectcommands.txt
  32. +15 −16 doc/specs/vulkan/chapters/VK_NVX_device_generated_commands/objecttable.txt
  33. +34 −22 doc/specs/vulkan/chapters/VK_NV_external_memory_win32/import_memory_win32.txt
  34. +1 −2 doc/specs/vulkan/chapters/clears.txt
  35. +33 −24 doc/specs/vulkan/chapters/cmdbuffers.txt
  36. +19 −32 doc/specs/vulkan/chapters/copies.txt
  37. +19 −19 doc/specs/vulkan/chapters/descriptorsets.txt
  38. +5 −4 doc/specs/vulkan/chapters/devsandqueues.txt
  39. +1 −1 doc/specs/vulkan/chapters/dispatch.txt
  40. +6 −6 doc/specs/vulkan/chapters/drawing.txt
  41. +5 −6 doc/specs/vulkan/chapters/extensions.txt
  42. +67 −21 doc/specs/vulkan/chapters/features.txt
  43. +2 −2 doc/specs/vulkan/chapters/fragops.txt
  44. +6 −2 doc/specs/vulkan/chapters/fundamentals.txt
  45. +8 −1 doc/specs/vulkan/chapters/interfaces.txt
  46. +7 −5 doc/specs/vulkan/chapters/introduction.txt
  47. +9 −9 doc/specs/vulkan/chapters/memory.txt
  48. +2 −2 doc/specs/vulkan/chapters/pipelines.txt
  49. +6 −0 doc/specs/vulkan/chapters/queries.txt
  50. +2 −3 doc/specs/vulkan/chapters/renderpass.txt
  51. +64 −40 doc/specs/vulkan/chapters/resources.txt
  52. +1 −0 doc/specs/vulkan/chapters/sparsemem.txt
  53. +29 −9 doc/specs/vulkan/chapters/synchronization.txt
  54. +0 −4 doc/specs/vulkan/config/vulkan-macros.rb
  55. +2 −38 doc/specs/vulkan/config/vulkan-macros/extension.rb
  56. +21 −0 doc/specs/vulkan/scripts/checkXrefs
  57. +5 −1 doc/specs/vulkan/style/extensions.txt
  58. +33 −15 doc/specs/vulkan/style/markup.txt
  59. +2 −3 doc/specs/vulkan/style/naming.txt
  60. +73 −28 doc/specs/vulkan/style/writing.txt
  61. +3 −4 doc/specs/vulkan/styleguide.txt
  62. +5 −4 src/spec/generator.py
  63. +13 −10 src/spec/vk.xml
  64. +2 −5 src/vulkan/vulkan.h
@@ -5,5 +5,6 @@ doc/specs/vulkan/makeExt text eol=lf
doc/specs/vulkan/makeKHR text eol=lf
doc/specs/vulkan/sandboxCopy text eol=lf
doc/specs/vulkan/config/optimize-pdf text eol=lf
doc/specs/vulkan/scripts/checkXrefs text eol=lf

*.sh text eol=lf

Large diffs are not rendered by default.

@@ -86,7 +86,7 @@ VERBOSE =
# $(EXTENSIONS))
# ADOCOPTS options for asciidoc->HTML5 output
NOTEOPTS = -a editing-notes -a implementation-guide
SPECREVISION = 1.0.43
SPECREVISION = 1.0.44
# Spell out RFC2822 format as not all date commands support -R
SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`)

@@ -91,9 +91,9 @@ reduce overdraw by appropriately ordering the input primitives?

*RESOLVED*: While the relaxed rasterization order might somewhat limit the
effectiveness of such content optimizations, most of the benefits of it are
expected to be retained even when the relaxed rasterization order is used so
applications are still recommended to apply these optimizations even if they
intend to use the extension.
expected to be retained even when the relaxed rasterization order is used,
so applications should: still apply these optimizations even if they intend
to use the extension.

3) Are there any guarantees about the primitive rasterization order when
using the new relaxed mode?
@@ -28,7 +28,7 @@
This is extension defines a vertical blanking period counter associated with
display surfaces.
It provides a mechanism to query support for such a counter from a
slink:VkSurface object.
slink:VkSurfaceKHR object.

=== New Enum Constants

@@ -108,7 +108,7 @@ flink:vkCreateSwapchainKHR will create a swapchain using that color space.

Vulkan requires that all implementations support the sRGB OETF and EOTF when
using an SRGB pixel format.
Other transfer functions, such as SMPTE 170M, must not: be performed by the
Other transfer functions, such as SMPTE 170M, must: not be performed by the
implementation, but can: be performed by the application shader.

=== New Enum Constants
@@ -13,9 +13,9 @@
*Status*::
Draft.
*Last Modified Date*::
2015-12-18
2017-03-13
*Revision*::
21
23
*IP Status*::
No known IP claims.
*Dependencies*::
@@ -199,19 +199,18 @@ be implemented as two side-by-side displays using the same display engine
(and sometimes cabling) resources as two physically separate display
devices.

*PROPOSED RESOLUTION*: Tiled displays will appear as a single display object
in this API.
*RESOLVED*: Tiled displays will appear as a single display object in this
API.

14) Should the raw EDID data be included in the display information?

*PROPOSED RESOLUTION*: None.
Unclear whether this is a good idea.
Provides a path for forward-compatibility as new EDID extensions are
introduced, but may be complicated by the outcome of issue 13.
*RESOLVED*: No.
A future extension could be added which reports the EDID if necessary.
This may be complicated by the outcome of issue 13.

15) Should min and max scaling factor capabilities of overlays be exposed?

*PROPOSED RESOLUTION*: Yes.
*RESOLVED*: Yes.
This is exposed indirectly by allowing applications to query the min/max
position and extent of the source and destination regions from which image
contents are fetched by the display engine when using a particular mode and
@@ -220,197 +219,41 @@ overlay pair.
16) Should devices be able to expose planes that can be moved between
displays? If so, how?

*PROPOSED RESOLUTION*: None.
*RESOLVED*: Yes.
Applications can determine which displays a given plane supports using
vkGetDisplayPlaneSupportedDisplaysKHR.

17) Should there be a way to destroy display modes? If so, does it support
destroying "`built in`" modes?

*PROPOSED RESOLUTION*: None.
*RESOLVED*: Not in this extension.
A future extension could add this functionality.

18) What should the lifetime of display and built-in display mode objects
be?

*PROPOSED RESOLUTION*: The lifetime of the instance.
*RESOLVED*: The lifetime of the instance.
These objects can not be destroyed.
A future extension may be added to expose a way to destroy these objects
and/or support display hotplug.

19) Should persistent mode for smart panels be enabled/disabled at swap
chain creation time, or on a per-present basis.

*PROPOSED RESOLUTION*: On a per-present basis.
*RESOLVED*: On a per-present basis.

=== Examples

**Example 1**

Enumerating displays, display modes, and planes, and creating a VkSurfaceKHR

[source,c++]
----------------------------------------
extern VkBool32 ModeMatchesMyCriteria(const VkDisplayModePropertiesKHR *m);
extern VkInstance instance;
extern VkPhysicalDevice physDevice;
extern VkSurfaceKHR surface;

uint32_t displayCount, planeCount, i, j, k;
VkDisplayPropertiesKHR* pDisplayProps;
VkDisplayPlanePropertiesKHR* pPlaneProps;
VkDisplayModeKHR myMode = VK_NULL_HANDLE;
VkDisplayKHR myDisplay = VK_NULL_HANDLE;
uint32_t bestPlane = UINT32_MAX;
VkDisplayPlaneAlphaFlagBitsKHR alphaMode = 0;
PFN_vkGetPhysicalDeviceDisplayPropertiesKHR pfnGetPhysicalDeviceDisplayPropertiesKHR;
PFN_vkGetPhysicalDeviceDisplayPlanePropertiesKHR pfnGetPhysicalDeviceDisplayPlanePropertiesKHR;
PFN_vkGetDisplayModePropertiesKHR pfnGetDisplayModePropertiesKHR;
PFN_vkGetDisplayPlaneCapabilitiesKHR pfnGetDisplayPlaneCapabilitiesKHR;
PFN_vkGetDisplayPlaneSupportedDisplaysKHR pfnGetDisplayPlaneSupportedDisplaysKHR;
PFN_vkCreateDisplayPlaneSurfaceKHR pfnCreateDisplayPlaneSurfaceKHR;

pfnGetPhysicalDeviceDisplayPropertiesKHR =
(PFN_vkGetPhysicalDeviceDisplayPropertiesKHR)
vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceDisplayPropertiesKHR");
pfnGetPhysicalDeviceDisplayPlanePropertiesKHR =
(PFN_vkGetPhysicalDeviceDisplayPlanePropertiesKHR)
vkGetInstanceProcAddr(instance, "vkGetPhysicalDeviceDisplayPlanePropertiesKHR");
pfnGetDisplayModePropertiesKHR =
(PFN_vkGetDisplayModePropertiesKHR)
vkGetInstanceProcAddr(instance, "vkGetDisplayModePropertiesKHR");
pfnGetDisplayPlaneCapabilitiesKHR =
(PFN_vkGetDisplayPlaneCapabilitiesKHR)
vkGetInstanceProcAddr(instance, "vkGetDisplayPlaneCapabilitiesKHR");
pfnGetDisplayPlaneSupportedDisplaysKHR =
(PFN_vkGetDisplayPlaneSupportedDisplaysKHR)
vkGetInstanceProcAddr(instance, "vkGetDisplayPlaneSupportedDisplaysKHR");
pfnCreateDisplayPlaneSurfaceKHR =
(PFN_vkCreateDisplayPlaneSurfaceKHR)
vkGetInstanceProcAddr(instance, "vkCreateDisplayPlaneSurfaceKHR");

// Get a list of displays on a physical device
displayCount = 0;
pfnGetPhysicalDeviceDisplayPropertiesKHR(physDevice, &displayCount, NULL);

pDisplayProps = (VkDisplayPropertiesKHR*)malloc(sizeof(VkDisplayPropertiesKHR) * displayCount);
pfnGetPhysicalDeviceDisplayPropertiesKHR(physDevice, &displayCount, pDisplayProps);

// Get a list of display planes on a physical device
planeCount = 0;
pfnGetPhysicalDeviceDisplayPlanePropertiesKHR(physDevice, &planeCount, NULL);
pPlaneProps = (VkDisplayPlanePropertiesKHR*)malloc(sizeof(VkDisplayPlanePropertiesKHR) * planeCount);
pfnGetPhysicalDeviceDisplayPlanePropertiesKHR(physDevice, &planeCount, pPlaneProps);

// Get the list of pModes each display supports
for (i = 0; i < displayCount; ++i)
{
VkDisplayKHR display = pDisplayProps[i].display;
VkDisplayModePropertiesKHR* pModes;
uint32_t modeCount;

vkGetDisplayModePropertiesKHR(physDevice, display, &modeCount, NULL);

pModes = (VkDisplayModePropertiesKHR*)malloc(sizeof(VkDisplayModePropertiesKHR) * modeCount);
vkGetDisplayModePropertiesKHR(physDevice, display, &modeCount, pModes);

myMode = VK_NULL_HANDLE;
for (j = 0; j < modeCount; ++j)
{
const VkDisplayModePropertiesKHR* mode = &pModes[i];

if (ModeMatchesMyCriteria(mode))
{
myMode = mode->displayMode;
break;
}
}

free(pModes);

// If there are no usable pModes found then check the next display.
if (myMode == VK_NULL_HANDLE)
continue;

// Find a plane that matches these criteria, in order of preference:
// -Is compatible with the chosen display + mode.
// -Is not currently bound to another display.
// -Supports per-pixel alpha, if possible.
for (j = 0; j < planeCount; ++j)
{
uint32_t supportedCount = 0;
VkDisplayKHR* pSupportedDisplays;
VkDisplayPlaneCapabilitiesKHR planeCaps;
// See if the plane is compatible with the current display.
pfnGetDisplayPlaneSupportedDisplaysKHR(physDevice, j, &supportedCount, NULL);

// Plane does not support any displays. This might happen on a card
// that has a fixed mapping between planes and connectors when no
// displays are currently attached to this plane's connector, for
// example.
if (supportedCount == 0)
continue;

pSupportedDisplays = (VkDisplayKHR*)malloc(sizeof(VkDisplayKHR) * supportedCount);
pfnGetDisplayPlaneSupportedDisplaysKHR(physDevice, j, &supportedCount, pSupportedDisplays);

for (k = 0; k < supportedCount; ++k)
if (pSupportedDisplays[k] == display) {
// If no supported plane has yet been found, this is
// currently the best available plane.
if (bestPlane == UINT32_MAX)
bestPlane = j;
break;
}

// If the plane cannot be used with the chosen display, keep looking.
// Each display must have at least one compatible plane.
if (k == supportedCount)
continue;

// If the plane passed the above test and is currently bound to the
// desired display, or is not in use, it is the best plane found so
// far.
if ((pPlaneProps[j].currentDisplay == VK_NULL_HANDLE) &&
(pPlaneProps[j].currentDisplay == display))
bestPlane = j;
else
continue;

pfnGetDisplayPlaneCapabilitiesKHR(physDevice, myMode, j, &planeCaps);

// Prefer a plane that supports per-pixel alpha.
if (planeCaps.supportedAlpha & VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR)
{
// This is the perfect plane for the given criteria. Use it.
bestPlane = j;
alphaMode = VK_DISPLAY_PLANE_ALPHA_PER_PIXEL_BIT_KHR;
break;
}
}
}

free(pDisplayProps);

if (myDisplay == VK_NULL_HANDLE || myMode == VK_NULL_HANDLE) {
// No suitable display + mode could be found. Abort.
abort();
} else {
// Success. Create a VkSurfaceKHR object for this plane.
const VkDisplaySurfaceCreateInfoKHR createInfo =
{
VK_STRUCTURE_TYPE_DISPLAY_SURFACE_CREATE_INFO_KHR, // sType
NULL, // pNext
0, // flags
myMode, // displayMode
bestPlane, // planeIndex
pPlaneProps[bestPlane].currentStackIndex, // planeStackIndex
VK_SURFACE_TRANSFORM_IDENTITY_KHR, // transform
1.0f, // globalAlpha
alphaMode, // alphaMode
...
}

pfnCreateDisplayPlaneSurfaceKHR(instance, &createInfo, NULL, &surface);
}
----------------------------------------
[NOTE]
.Note
====
The example code for the +VK_KHR_display+ and +VK_KHR_display_swapchain+
extensions was removed from the appendix after revision 1.0.43.
The display enumeration example code was ported to the cube demo that is
shipped with the official Khronos SDK, and is being kept up-to-date in that
location (see:
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c).
====

=== Version History

@@ -542,3 +385,10 @@ Enumerating displays, display modes, and planes, and creating a VkSurfaceKHR
* Revision 22, 2015-12-18 (James Jones)
- Added missing "planeIndex" parameter to
vkGetDisplayPlaneSupportedDisplaysKHR()

* Revision 23, 2017-03-13 (James Jones)
- Closed all remaining issues.
The specification and implementations have been shipping with the
proposed resolutions for some time now.
- Removed the sample code and noted it has been integrated into the
official Vulkan SDK cube demo.

0 comments on commit 43f1fd5

Please sign in to comment.
You can’t perform that action at this time.