Skip to content
Permalink
Browse files

Change log for March 24, 2017 Vulkan 1.0.45 spec update:

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

Github Issues:

  * Defined the lifetime of the memory pointed to by
    slink:VkDisplayPropertiesKHR::pname:displayName to be equal to that of
    its associated display handle (public issue 460).
  * Correct several cases where the sparse memory feature name
    pname:residencyNonResidentStrict was written as
    pname:sparseResidencyNonResidentStrict (public issue 475).

Internal Issues:

  * Fix ptext:pNext member of slink:VkPhysicalDeviceGroupPropertiesKHX to be
    a non-const pointer. Properties structures return values, so the chain
    should be non-const.
  * Clarify definition of memory aliasing to consistently use the terms
    "linear" and "non-linear" when referring to resources, and define what
    those terms mean.
  * Modified XML schema and implicit validity scripts to generate language
    for all ptext:pNext values in a ptext:pNext chain instead of just the
    top level struct, and made `noautovalidity` functional for ptext:sType
    and ptext:pNext (internal issue 535).
  * Add more detail for BT2020 and scRGB color spaces in
    `VK_EXT_swapchain_colorspace` extension (internal issue 632).
  * Add naming rules for Extension Structure Names (structures added to the
    ptext:pNext chain of a base structure) to the style guide (internal
    issue 706).
  * Define the glossary term "ptext:pNext chain", and use it consistently in
    the spec (internal issue 744).

New Extensions:
  • Loading branch information...
oddhack committed Mar 25, 2017
1 parent 43f1fd5 commit e8cbffbd2548d26915f7a52bbff1204d7407fd09
Showing with 746 additions and 390 deletions.
  1. +35 −0 ChangeLog.txt
  2. +1 −1 doc/specs/vulkan/Makefile
  3. +13 −0 doc/specs/vulkan/README.adoc
  4. +19 −100 doc/specs/vulkan/appendices/VK_EXT_swapchain_colorspace.txt
  5. +8 −6 doc/specs/vulkan/appendices/VK_KHR_get_physical_device_properties2.txt
  6. +11 −0 doc/specs/vulkan/appendices/glossary.txt
  7. +19 −20 doc/specs/vulkan/chapters/VK_EXT_debug_report.txt
  8. +2 −2 doc/specs/vulkan/chapters/VK_EXT_display_control/display_control.txt
  9. +4 −4 doc/specs/vulkan/chapters/VK_EXT_display_control/fence_events.txt
  10. +2 −1 doc/specs/vulkan/chapters/VK_EXT_display_surface_counter/surface_capabilities.txt
  11. +2 −1 doc/specs/vulkan/chapters/VK_EXT_validation_flags.txt
  12. +1 −1 doc/specs/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt
  13. +2 −0 doc/specs/vulkan/chapters/VK_KHR_display/display.txt
  14. +211 −15 doc/specs/vulkan/chapters/VK_KHR_surface/wsi.txt
  15. +4 −4 doc/specs/vulkan/chapters/VK_NV_clip_space_w_scaling/vertexpostproc.txt
  16. +12 −13 doc/specs/vulkan/chapters/cmdbuffers.txt
  17. +12 −5 doc/specs/vulkan/chapters/descriptorsets.txt
  18. +1 −1 doc/specs/vulkan/chapters/devsandqueues.txt
  19. +28 −34 doc/specs/vulkan/chapters/features.txt
  20. +4 −3 doc/specs/vulkan/chapters/fragops.txt
  21. +4 −2 doc/specs/vulkan/chapters/fundamentals.txt
  22. +2 −1 doc/specs/vulkan/chapters/fxvertex.txt
  23. +1 −1 doc/specs/vulkan/chapters/initialization.txt
  24. +28 −12 doc/specs/vulkan/chapters/memory.txt
  25. +2 −3 doc/specs/vulkan/chapters/pipelines.txt
  26. +6 −6 doc/specs/vulkan/chapters/primsrast.txt
  27. +10 −2 doc/specs/vulkan/chapters/queries.txt
  28. +24 −6 doc/specs/vulkan/chapters/renderpass.txt
  29. +33 −45 doc/specs/vulkan/chapters/resources.txt
  30. +24 −3 doc/specs/vulkan/chapters/samplers.txt
  31. +17 −6 doc/specs/vulkan/chapters/sparsemem.txt
  32. +12 −4 doc/specs/vulkan/chapters/synchronization.txt
  33. +10 −9 doc/specs/vulkan/chapters/textures.txt
  34. +14 −14 doc/specs/vulkan/chapters/vertexpostproc.txt
  35. +2 −1 doc/specs/vulkan/config/extDependency.py
  36. +2 −1 doc/specs/vulkan/config/extDependency.sh
  37. +9 −2 doc/specs/vulkan/registry.txt
  38. +4 −0 doc/specs/vulkan/style/extensions.txt
  39. +43 −0 doc/specs/vulkan/style/naming.txt
  40. +4 −0 doc/specs/vulkan/style/writing.txt
  41. +2 −0 doc/specs/vulkan/styleguide.txt
  42. +28 −18 src/spec/validitygenerator.py
  43. +51 −41 src/spec/vk.xml
  44. +23 −2 src/vulkan/vulkan.h
@@ -8,6 +8,41 @@ public issues.

-----------------------------------------------------

Change log for March 24, 2017 Vulkan 1.0.45 spec update:

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

Github Issues:

* Defined the lifetime of the memory pointed to by
slink:VkDisplayPropertiesKHR::pname:displayName to be equal to that of
its associated display handle (public issue 460).
* Correct several cases where the sparse memory feature name
pname:residencyNonResidentStrict was written as
pname:sparseResidencyNonResidentStrict (public issue 475).

Internal Issues:

* Fix ptext:pNext member of slink:VkPhysicalDeviceGroupPropertiesKHX to be
a non-const pointer. Properties structures return values, so the chain
should be non-const.
* Clarify definition of memory aliasing to consistently use the terms
"linear" and "non-linear" when referring to resources, and define what
those terms mean.
* Modified XML schema and implicit validity scripts to generate language
for all ptext:pNext values in a ptext:pNext chain instead of just the
top level struct, and made `noautovalidity` functional for ptext:sType
and ptext:pNext (internal issue 535).
* Add more detail for BT2020 and scRGB color spaces in
`VK_EXT_swapchain_colorspace` extension (internal issue 632).
* Add naming rules for Extension Structure Names (structures added to the
ptext:pNext chain of a base structure) to the style guide (internal
issue 706).
* Define the glossary term "ptext:pNext chain", and use it consistently in
the spec (internal issue 744).

-----------------------------------------------------

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

@@ -731,6 +731,8 @@ gem install --pre asciidoctor-pdf
[[ruby-enum-downgrade]]
==== Ruby Gem Versioning Errors

*ruby-enum*

As of 2017-03-06, there appears to be a problem with the ruby-enum version
0.7.1 gem which breaks the PDF build. Make sure you are using ruby-enum
0.7.0, as follows:
@@ -743,9 +745,20 @@ https://github.com/gjtorikian/mathematical/issues/69 for a report of this
problem.


*prawn*

As of 2017-03-20, there are incompatibilities between asciidoctor-pdf and
certain versions of prawn and prawn-templates affecting the PDF build. Make
sure to update to prawn 2.2.1 and prawn-templates 0.0.5. See

https://github.com/KhronosGroup/Vulkan-Docs/issues/476


[[history]]
== Revision History

* 2017-03-20 - Add description of prawn versioning problem and how to fix
it.
* 2017-03-06 - Add description of ruby-enum versioning problem and how to
fix it.
* 2017-02-13 - Move some comments here from ../../../README.md. Tweak
@@ -8,7 +8,7 @@
*Registered Extension Number*::
105
*Last Modified Date*::
2017-01-13
2017-03-15
*Revision*::
1
*IP Status*::
@@ -21,107 +21,13 @@
*Contacts*::
- Courtney Goeltzenleuchter, Google

This extension defines enums for elink:VkColorSpaceKHR that correspond to
the following color spaces::

[[VK_EXT_swapchain_colorspace-table]]
.Color Spaces and Attributes
[options="header"]
|====
| Name | Red Primary | Green Primary | Blue Primary | White-point | OETF
| DCI-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Gamma 2.6
| Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB
| BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | SMPTE 170M
| sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB
| scRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | scRGB
| BT2020 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | SMPTE 170M
| AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Gamma 2.2
|====

For Opto-Electrical Transfer Function (OETF), unless otherwise specified,
the values of [eq]#L# and [eq]#E# are defined as:

[eq]#L# - luminance of image [eq]#0 {leq} L {leq} 1# for conventional
colorimetry

[eq]#E# - corresponding electrical signal (value stored in memory)

=== sRGB OETF

[latexmath]
+++++++++++++++++++
\begin{aligned}
E & =
\begin{cases}
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0031308 \leq L \leq 1 \\
12.92 \times L & \text{for}\ 0 \leq L < 0.0031308
\end{cases}
\end{aligned}
+++++++++++++++++++

=== scRGB OETF

[latexmath]
+++++++++++++++++++
\begin{aligned}
E & =
\begin{cases}
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0031308 \leq L \leq 7.5913 \\
12.92 \times L & \text{for}\ 0 \leq L < 0.0031308 \\
-E \times -L & \text{for}\ L < 0
\end{cases}
\end{aligned}
+++++++++++++++++++

[eq]#L# - luminance of image is within [eq]#[-0.6038, 7.5913]#.

[eq]#E# can be negative and/or > 1.
That is how scRGB specifies colors outside the standard sRGB gamut.

=== SMPTE 170M OETF

[latexmath]
+++++++++++++++++++
\begin{aligned}
E & =
\begin{cases}
1.099 \times L^0.45 - 0.099 & \text{for}\ 0.018 \leq L \leq 1 \\
4.5 \times L & \text{for}\ 0 \leq L < 0.018
\end{cases}
\end{aligned}
+++++++++++++++++++

=== Display Gamma 2.2 OETF

latexmath:[$E = L^{1 \over 2.2}$]

=== Display Gamma 2.6 OETF

latexmath:[$E = L^{1 \over 2.6}$]

An implementation supporting this extension indicates support for these
color spaces via slink:VkSurfaceFormatKHR structures returned from
flink:vkGetPhysicalDeviceSurfaceFormatsKHR.

Specifying the supported surface color space when calling
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
implementation, but can: be performed by the application shader.

=== New Enum Constants

* Extending elink:VkColorSpaceKHR:
** ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT - supports the Display-P3
color space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT - supports the Display-P3
color space and applies the sRGB OETF.
** ename:VK_COLOR_SPACE_SCRGB_LINEAR_EXT - supports the scRGB color space
and applies a linear OETF.
** ename:VK_COLOR_SPACE_SCRGB_NONLINEAR_EXT - supports the scRGB color
space and applies the scRGB OETF.
color space and applies an sRGB-like OETF.
** ename:VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT - supports the extended
sRGB color space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT - supports the DCI-P3 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT - supports the DCI-P3 color
@@ -132,12 +38,19 @@ implementation, but can: be performed by the application shader.
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT - supports the BT2020 color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_BT2020_NONLINEAR_EXT - supports the BT2020 color
space and applies the SMPTE 170M OETF.
** ename:VK_COLOR_SPACE_HDR10_ST2084_EXT - supports HDR10 (BT2020 color
space and applies the SMPTE ST2084 Perceptual Quantizer (PQ) OETF).
** ename:VK_COLOR_SPACE_DOLBYVISION_EXT - supports Dolby Vision (BT2020
color space, proprietary encoding, and applies the SMPTE ST2084 OETF).
** ename:VK_COLOR_SPACE_HDR10_HLG_EXT - supports HDR10 (BT2020 color space
and applies the Hybrid Log Gamma (HLG) OETF).
** ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT - supports the AdobeRGB color
space and applies a linear OETF.
** ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT - supports the AdobeRGB
color space and applies the Gamma 2.2 OETF.
** ename:VK_COLOR_SPACE_PASS_THROUGH_EXT - color components used "as is".
Intended to allow application to supply data for color spaces not
described here.

=== Issues

@@ -157,8 +70,14 @@ function for a colorspace?
*RESOLVED*: Extension indicates that implementation must: not do the OETF
encoding if it is not sRGB.
That responsibility falls to the application shaders.
Any other native OETF / EOTF functions supported by an implementation can be
described by separate extension.

=== Version History

* Revision 1, 2016-12-27 (Courtney Goeltzenleuchter)
- Initial version

* Revision 2, 2017-01-19 (Courtney Goeltzenleuchter)
- Add pass through and multiple options for BT2020.
- Clean up some issues with equations not displaying properly.
@@ -29,14 +29,16 @@
This extension provides new entry points to query device features, device
properties, and format properties in a way that can be easily extended by
other extensions, without introducing any further entry points.
The Vulkan 1.0 feature/limit/formatproperty structures do not include an
sType/pNext, this extension wraps them in new structures with sType/pNext so
an application can query a chain of feature/limit/formatproperty structures
by constructing the chain and letting the implementation fill them in.
The Vulkan 1.0 feature/limit/formatproperty structures do not include
ptext:sType/ptext:pNext members.
This extension wraps them in new structures with ptext:sType/ptext:pNext
members, so an application can query a chain of feature/limit/formatproperty
structures by constructing the chain and letting the implementation fill
them in.
A new command is added for each ftext:vkGetPhysicalDevice* command in core
Vulkan 1.0.
The new feature structure (and a chain of extensions) can also be passed in
to device creation to enable features.
The new feature structure (and a chain of extension structures) can also be
passed in to device creation to enable features.

This extension also allows applications to use the physical-device
components of device extensions before flink:vkCreateDevice is called.
@@ -606,6 +606,13 @@ Invocation Group::
execute the same control flow path in order for control flow to be
considered dynamically uniform.

[[glossary-linear-resource]]
Linear Resource::
A resource is _linear_ if it is a slink:VkBuffer, or a slink:VkImage
created with ename:VK_IMAGE_TILING_LINEAR.
A resource is _non-linear_ if it is a slink:VkImage created with
ename:VK_IMAGE_TILING_OPTIMAL.

Local Workgroup::
A collection of compute shader invocations invoked by a single dispatch
command, which share shared memory and can synchronize with each other.
@@ -742,6 +749,10 @@ Pipeline Stage::
A logically independent execution unit that performs some of the
operations defined by an action command.

pname:pNext Chain::
A set of structures <<fundamentals-validusage-pNext,chained together>>
through their ptext:pNext members.

Point Sampling (Rasterization)::
A rule that determines whether a fragment sample location is covered by
a polygon primitive by testing whether the sample location is in the
@@ -61,27 +61,26 @@ include::../api/structs/VkDebugReportCallbackCreateInfoEXT.txt[]
// refBegin VkDebugReportFlagBitsEXT Bitmask specifying events which cause a debug report callback
include::../api/enums/VkDebugReportFlagBitsEXT.txt[]

* ename:VK_DEBUG_REPORT_ERROR_BIT_EXT indicates an error that may cause
undefined results, including an application crash.
* ename:VK_DEBUG_REPORT_WARNING_BIT_EXT indicates use of Vulkan that may
expose an app bug.
Such cases may not be immediately harmful, such as a fragment shader
outputting to a location with no attachment.
Other cases may point to behavior that is almost certainly bad when
unintended such as using an image whose memory has not been filled.
In general if you see a warning but you know that the behavior is
intended/desired, then simply ignore the warning.
* ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a
potentially non-optimal use of Vulkan.
E.g. using flink:vkCmdClearColorImage when a RenderPass load_op would
have worked.
* ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT indicates an informational
message such as resource details that may be handy when debugging an
application.
* ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates diagnostic information
from the loader and layers.
** ename:VK_DEBUG_REPORT_ERROR_BIT_EXT indicates an error that may cause
undefined results, including an application crash.
** ename:VK_DEBUG_REPORT_WARNING_BIT_EXT indicates use of Vulkan that may
expose an app bug.
Such cases may not be immediately harmful, such as a fragment shader
outputting to a location with no attachment.
Other cases may point to behavior that is almost certainly bad when
unintended such as using an image whose memory has not been filled.
In general if you see a warning but you know that the behavior is
intended/desired, then simply ignore the warning.
** ename:VK_DEBUG_REPORT_PERFORMANCE_WARNING_BIT_EXT indicates a
potentially non-optimal use of Vulkan.
E.g. using flink:vkCmdClearColorImage when a RenderPass load_op would
have worked.
** ename:VK_DEBUG_REPORT_INFORMATION_BIT_EXT indicates an informational
message such as resource details that may be handy when debugging an
application.
** ename:VK_DEBUG_REPORT_DEBUG_BIT_EXT indicates diagnostic information
from the loader and layers.
--
+
* pname:pfnCallback is the application callback function to call.
* pname:pUserData is user data to be passed to the callback.

@@ -27,14 +27,14 @@ include::../../api/structs/VkDisplayPowerInfoEXT.txt[]
--
// refBegin VkDisplayPowerStateEXT Possible power states for a VkDisplay
include::../../api/enums/VkDisplayPowerStateEXT.txt[]
--
+

** ename:VK_DISPLAY_POWER_STATE_OFF_EXT means the display is powered down.
** ename:VK_DISPLAY_POWER_STATE_SUSPEND_EXT means the display is in a low
power mode, but may: be able to transition back to
ename:VK_DISPLAY_POWER_STATE_ON_EXT more quickly than if it were in
ename:VK_DISPLAY_POWER_STATE_OFF_EXT.
This state may: be the same as ename:VK_DISPLAY_POWER_STATE_OFF_EXT.
** ename:VK_DISPLAY_POWER_STATE_ON_EXT is powered on.
--

include::../../validity/structs/VkDisplayPowerInfoEXT.txt[]
@@ -36,12 +36,12 @@ include::../../api/structs/VkDeviceEventInfoEXT.txt[]
--
// refBegin VkDeviceEventTypeEXT Events that can occur on a device object
include::../../api/enums/VkDeviceEventTypeEXT.txt[]
--
+

** ename:VK_DEVICE_EVENT_TYPE_DISPLAY_HOTPLUG_EXT occurs when a display is
plugged into or unplugged from the specified device.
Applications can: use this notification to determine when they need to
re-enumerate the available displays on a device.
--

include::../../validity/structs/VkDeviceEventInfoEXT.txt[]

@@ -78,10 +78,10 @@ include::../../api/structs/VkDisplayEventInfoEXT.txt[]
--
// refBegin VkDisplayEventTypeEXT Events that can occur on a display object
include::../../api/enums/VkDisplayEventTypeEXT.txt[]
--
+

** ename:VK_DISPLAY_EVENT_TYPE_FIRST_PIXEL_OUT_EXT occurs when the first
pixel of the next display refresh cycle leaves the display engine for
the display.
--

include::../../validity/structs/VkDisplayEventInfoEXT.txt[]
@@ -15,7 +15,8 @@ include::../../api/protos/vkGetPhysicalDeviceSurfaceCapabilities2EXT.txt[]

fname:vkGetPhysicalDeviceSurfaceCapabilities2EXT behaves similarly to
flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to return
extended information via chained output structures.
extended information by adding extension structures to its pname:pNext
chain.

include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2EXT.txt[]

@@ -17,7 +17,8 @@ include::../api/structs/VkValidationFlagsEXT.txt[]
--
// refBegin VkValidationCheckEXT Specify validation checks to disable
include::../api/enums/VkValidationCheckEXT.txt[]
--

** ename:VK_VALIDATION_CHECK_ALL_EXT disables all validation checks.
--

include::../validity/structs/VkValidationFlagsEXT.txt[]

0 comments on commit e8cbffb

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