Skip to content

Commit

Permalink
Change log for March 17, 2017 Vulkan 1.0.44 spec update:
Browse files Browse the repository at this point in the history 
  * 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
oddhack committed Mar 18, 2017
1 parent 3e4bee3 commit 43f1fd5
Show file tree
Hide file tree
Showing 64 changed files with 2,390 additions and 2,294 deletions.
1 change: 1 addition & 0 deletions .gitattributes
View file
Expand Up @@ -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
3,319 changes: 1,695 additions & 1,624 deletions ChangeLog.txt
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion doc/specs/vulkan/Makefile
View file
Expand Up @@ -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"`)

Expand Down
6 changes: 3 additions & 3 deletions doc/specs/vulkan/appendices/VK_AMD_rasterization_order.txt
View file
Expand Up @@ -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?
Expand Down
2 changes: 1 addition & 1 deletion doc/specs/vulkan/appendices/VK_EXT_display_surface_counter.txt
View file
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt
View file
Expand Up @@ -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
Expand Down
214 changes: 32 additions & 182 deletions doc/specs/vulkan/appendices/VK_KHR_display.txt
View file
Expand Up @@ -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*::
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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.