Skip to content

Commit 2656f45

Browse files
oddhackoddhack
committed
Change log for May 13, 2016 Vulkan 1.0.13 spec update:
 * Bump API patch number and header version number to 13 for this update. Github Issues: * Improve the description of ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the VK_KHR_surface extension (public issue 174). * Clarify use of etext:*_SIMULTANEOUS_USE_BIT for secondary command buffers (public issue 182). * Fix typos in VK_KHR_wayland_surface extension where code:wl_device was used instead of code:wl_display (public issue 193). * Replaced {apiname} with ``Vulkan'' in XML validity statements (public issue 199). * Fix dead links for WSI handle types (public issue 200). *** N.b. this needs to be done in WSI branches as well *** * Use "signaled" instead of "signalled" spelling everywhere (public issue 201). *** N.b. this needs to be done in WSI branches as well *** * Move readme.pdf target directory for XML schema documentation into the target generation directory, instead of leaving it checked into the spec source tree (public issue 203). *** N.b. need to add generated PDF to registry index/1.0 page * Fix duplicate 'which which' typo in description of elink:VkCommandPoolResetFlagBits (public issue 204). * Move the <<Programmable Primitive Shading>> section up one level, out of the <<drawing-primitive-topologies,Primitive Topologies>> section (public issue 209). Internal Issues: * Clarify in the <<pipelines-cache,Pipeline Cache>> section that implementations should not manage the size of pipeline cache (internal issue 192). * Deprecate the concept of device layers and associated commands (internal issue 255). * Remove ename:VK_INCOMPLETE from the list of possible result codes of flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR (internal issue 314). * Add missing std140/std430 rule: the base alignment of a member following a structure is a multiple of the structure's base alignment (internal issue 321). * Fixes naming of the single elink:VkColorSpaceKHR enum from ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR to ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in XML/header and the VK_KHR_swapchain and VK_KHR_surface extensions to match the style of the typename (space and color are two words, not one) (internal issue 322). * Make it clear that code:LocalInvocationID should only be applied to an input variable and normalize the language describing code:LocalInvocationID to the language for other compute shader variables in the <<interfaces-builtin-variables,Built-in Variables>> section, and add normative language (internal issue 323). * Clarify in the <<fundamentals-returncodes,Return Codes>> section that the result pointer may be modified for specific commands, even if a runtime error is returned (internal issue 324).
1 parent 648049f commit 2656f45

25 files changed

Lines changed: 311 additions & 152 deletions

‎ChangeLog.txt‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -580,3 +580,63 @@ Other Commits:
580580
* Replace the {apiname} macro with hardcoded "Vulkan", now that we've
581581
committed to that name.
582582
* Add the VK_AMD_rasterization_order extension to vk.xml.
583+
584+
-----------------------------------------------------
585+
586+
Change log for May 13, 2016 Vulkan 1.0.13 spec update:
587+
588+
* Bump API patch number and header version number to 13 for this
589+
update.
590+
591+
Github Issues:
592+
593+
* Improve the description of ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR in the
594+
VK_KHR_surface extension (public issue 174).
595+
* Clarify use of etext:*_SIMULTANEOUS_USE_BIT for secondary command
596+
buffers (public issue 182).
597+
* Fix typos in VK_KHR_wayland_surface extension where code:wl_device was
598+
used instead of code:wl_display (public issue 193).
599+
* Replaced {apiname} with ``Vulkan'' in XML validity statements (public
600+
issue 199).
601+
* Fix dead links for WSI handle types (public issue 200).
602+
* Use "signaled" instead of "signalled" spelling everywhere (public issue
603+
201).
604+
* Move readme.pdf target directory for XML schema documentation into the
605+
target generation directory, instead of leaving it checked into the spec
606+
source tree (public issue 203).
607+
* Fix duplicate 'which which' typo in description of
608+
elink:VkCommandPoolResetFlagBits (public issue 204).
609+
* Move the <<Programmable Primitive Shading>> section up one level, out of
610+
the <<drawing-primitive-topologies,Primitive Topologies>> section
611+
(public issue 209).
612+
613+
Internal Issues:
614+
615+
* Clarify in the <<pipelines-cache,Pipeline Cache>> section that
616+
implementations should not manage the size of pipeline cache (internal
617+
issue 192).
618+
* Deprecate the concept of device layers and associated commands (internal
619+
issue 255).
620+
* Remove ename:VK_INCOMPLETE from the list of possible result codes of
621+
flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR (internal issue 314).
622+
* Add missing std140/std430 rule: the base alignment of a member following
623+
a structure is a multiple of the structure's base alignment (internal
624+
issue 321).
625+
* Fixes naming of the single elink:VkColorSpaceKHR enum from
626+
ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR to
627+
ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in XML/header and the
628+
VK_KHR_swapchain and VK_KHR_surface extensions to match the style of the
629+
typename (space and color are two words, not one) (internal issue 322).
630+
* Make it clear that code:LocalInvocationID should only be applied to an
631+
input variable and normalize the language describing
632+
code:LocalInvocationID to the language for other compute shader
633+
variables in the <<interfaces-builtin-variables,Built-in Variables>>
634+
section, and add normative language (internal issue 323).
635+
* Clarify in the <<fundamentals-returncodes,Return Codes>> section that
636+
the result pointer may be modified for specific commands, even if a
637+
runtime error is returned (internal issue 324).
638+
639+
640+
641+
642+

‎doc/specs/vulkan/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ ECHO:=echo
4343
# XHTMLDIR - 'xhtml' target
4444
# PDFDIR - 'pdf' target
4545
# CHECKDIR - 'allchecks' target
46-
OUTDIR :=../../../out/1.0
46+
OUTDIR := ../../../out/1.0
4747
HTMLDIR := $(OUTDIR)/html
4848
XHTMLDIR := $(OUTDIR)/xhtml
4949
PDFDIR := $(OUTDIR)/pdf
@@ -125,7 +125,7 @@ INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpo
125125
COMMONDOCS := $(CHAPTERS) $(INCLUDES)
126126
# A generated included file with the spec version, date, and git commit
127127
SPECVERSION = specversion.txt
128-
SPECREVISION = 1.0.12
128+
SPECREVISION = 1.0.13
129129
SPECREMARK =
130130

131131
# Spec targets

‎doc/specs/vulkan/appendices/glossary.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ Explicitly-Enabled Layer::
245245
list in flink:vkCreateInstance or flink:vkCreateDevice.
246246

247247
Event::
248-
A synchronization primitive that is signalled when execution of previous
248+
A synchronization primitive that is signaled when execution of previous
249249
commands complete through a specified set of pipeline stages. Events can
250250
be waited on by the device and polled by the host. Represented by a
251251
sname:VkEvent object.

‎doc/specs/vulkan/buildRelease‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,7 @@ git checkout master
3333

3434
echo "**** AUTOGENERATING HEADERS AND SPEC INCLUDE FILES ****"
3535
cd $xml
36-
make clobber
37-
make full_install
36+
make OUTDIR=$outdir clobber full_install
3837

3938
echo "**** CLEANING SPEC ****"
4039
cd $spec

‎doc/specs/vulkan/chapters/cmdbuffers.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ command buffers allocated from the command pool back to the command pool.
136136
All command buffers that have been allocated from the command pool are put
137137
in the initial state.
138138

139-
pname:flags is a bitmask controlling the operation. Bits which which can: be
139+
pname:flags is a bitmask controlling the operation. Bits which can: be
140140
set include:
141141

142142
include::../enums/VkCommandPoolResetFlagBits.txt[]
@@ -336,7 +336,8 @@ fname:vkCmdExecuteCommands) until the final time that primary buffer's
336336
submission to a queue completes. If, after the primary buffer completes, the
337337
secondary command buffer is recorded to execute on a different primary
338338
buffer, the first primary buffer mustnot: be resubmitted until after it is
339-
reset with flink:vkResetCommandBuffer.
339+
reset with flink:vkResetCommandBuffer unless the secondary command buffer
340+
was recorded with ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT.
340341

341342
If ename:VK_COMMAND_BUFFER_USAGE_SIMULTANEOUS_USE_BIT is not set on a
342343
secondary command buffer, that command buffer mustnot: be used more than
@@ -428,7 +429,7 @@ Each call to fname:vkQueueSubmit submits zero or more _batches_ of work to
428429
the queue for execution. pname:submitCount is used to specify the number of
429430
batches to submit. Each batch includes zero or more semaphores to wait upon,
430431
and a corresponding set of stages that will wait for the semaphore to be
431-
signalled before executing any work, followed by a number of command buffers
432+
signaled before executing any work, followed by a number of command buffers
432433
that will be executed, and finally, zero or more semaphores that will be
433434
signaled after command buffer execution completes. Each batch is represented
434435
as an instance of the slink:VkSubmitInfo structure stored in an array, the

‎doc/specs/vulkan/chapters/devsandqueues.txt‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -330,11 +330,9 @@ include::../structs/VkDeviceCreateInfo.txt[]
330330
requested to be created along with the logical device. Refer to the
331331
<<devsandqueues-queue-creation,Queue Creation>> section below for
332332
further details.
333-
* pname:enabledLayerCount is the number of device layers to enable.
334-
* pname:ppEnabledLayerNames is a pointer to an array of
335-
pname:enabledLayerCount null-terminated UTF-8 strings containing the
336-
names of layers to enable for the created device. See the
337-
<<extended-functionality-layers,Layers>> section for further details.
333+
* pname:enabledLayerCount is deprecated and ignored.
334+
* pname:ppEnabledLayerNames is deprecated and ignored. See
335+
<<extended-functionality-device-layer-deprecation,Device Layer Deprecation>>.
338336
* pname:enabledExtensionCount is the number of device extensions to
339337
enable.
340338
* pname:ppEnabledExtensionNames is a pointer to an array of

‎doc/specs/vulkan/chapters/drawing.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,7 @@ The order of vertices in such a primitive is significant during
340340
<<shaders-fragment,fragment shading>>.
341341

342342

343-
=== Programmable Primitive Shading
343+
== Programmable Primitive Shading
344344

345345
Once primitives are assembled, they proceed to the vertex shading stage of
346346
the pipeline. If the draw includes multiple instances, then the set of

‎doc/specs/vulkan/chapters/extensions.txt‎

Lines changed: 98 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,23 @@
77
Additional functionality may: be provided by layers or extensions. A layer
88
cannot: add or modify Vulkan commands, while an extension may: do so.
99

10-
There are two kinds of layers and extensions, instance and device. Instance
11-
layers and extensions are general purpose and do not depend on a specific
12-
device. Device layers and extensions operate on specific devices, and
13-
require a valid sname:VkDevice to be used. Instance extensions usually
14-
affect the operation of the API as a whole, whereas device layers and
15-
extensions tend to be hardware-specific. Examples of these might be:
16-
17-
* Whole API validation is an example of a good instance layer.
10+
The set of layers to enable is specified when creating an instance, and those
11+
layers are able to intercept any Vulkan command dispatched to that instance
12+
or any of its child objects.
13+
14+
Extensions can operate at either the instance or device scope. Enabled instance
15+
extensions are able to affect the operation of the instance and any of its
16+
child objects, while device extensions may: only be available on a subset of
17+
physical devices, must be individually enabled per-device, and only affect the
18+
operation of the devices where they are enabled.
19+
20+
Examples of these might be:
21+
22+
* Whole API validation is an example of a layer.
1823
* Debug capabilities might make a good instance extension.
1924
* A layer that provides hardware-specific performance telemetry and
20-
analysis could be a device layer.
25+
analysis could be a layer that is only active for devices created from
26+
compatible physical devices.
2127
* Functions to allow an application to use additional hardware features
2228
beyond the core would be a good candidate for a device extension.
2329

@@ -32,7 +38,7 @@ allowed ranges. Instead, a validation layer would do those checks and flag
3238
issues. This avoids a performance penalty during production use of the
3339
application because those layers would not be enabled in production.
3440

35-
To query the available instance layers, call:
41+
To query the available layers, call:
3642

3743
include::../protos/vkEnumerateInstanceLayerProperties.txt[]
3844

@@ -43,48 +49,25 @@ include::../protos/vkEnumerateInstanceLayerProperties.txt[]
4349

4450
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
4551

46-
To enable a instance layer, the name of the layer should be added to the
47-
pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
48-
a sname:VkInstance.
49-
50-
To query the layers available to a given physical device, call:
51-
52-
include::../protos/vkEnumerateDeviceLayerProperties.txt[]
53-
54-
* pname:physicalDevice is the physical device that will be queried.
55-
* pname:pPropertyCount is a pointer to an integer related to the number of
56-
layer properties available or queried, as described below.
57-
* pname:pProperties is either `NULL` or a pointer to an array of
58-
slink:VkLayerProperties structures.
59-
60-
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
61-
62-
To enable a device layer, the name of the layer should be added to the
63-
pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo when creating
64-
a sname:VkDevice.
65-
66-
For both flink:vkEnumerateInstanceLayerProperties and
67-
flink:vkEnumerateDeviceLayerProperties, if pname:pProperties is `NULL`, then
68-
the number of layer properties available is returned in pname:pPropertyCount.
69-
Otherwise, pname:pPropertyCount must: point to a variable set by the user to
70-
the number of elements in the pname:pProperties array, and on return the
71-
variable is overwritten with the number of structures actually written to
72-
pname:pProperties. If pname:pPropertyCount is less than the
73-
number of layer properties available, at most pname:pPropertyCount
74-
structures will be written. If pname:pPropertyCount is smaller than the
75-
number of layers available, ename:VK_INCOMPLETE will be returned instead of
76-
ename:VK_SUCCESS, to indicate that not all the available layer properties
77-
were returned.
52+
If pname:pProperties is `NULL`, then the number of layer properties available
53+
is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
54+
point to a variable set by the user to the number of elements in the
55+
pname:pProperties array, and on return the variable is overwritten with the
56+
number of structures actually written to pname:pProperties. If
57+
pname:pPropertyCount is less than the number of layer properties available, at
58+
most pname:pPropertyCount structures will be written. If pname:pPropertyCount
59+
is smaller than the number of layers available, ename:VK_INCOMPLETE will be
60+
returned instead of ename:VK_SUCCESS, to indicate that not all the available
61+
layer properties were returned.
7862

7963
The sname:VkLayerProperties structure is defined as:
8064

8165
include::../structs/VkLayerProperties.txt[]
8266

8367
* pname:layerName is a null-terminated UTF-8 string specifying the name of
8468
the layer. Use this name in the pname:ppEnabledLayerNames array passed
85-
in the slink:VkInstanceCreateInfo and slink:VkDeviceCreateInfo
86-
structures passed to flink:vkCreateInstance and flink:vkCreateDevice,
87-
respectively, to enable this layer for an instance or device.
69+
in the slink:VkInstanceCreateInfo structure to enable this layer for an
70+
instance.
8871
* pname:specVersion is the Vulkan version the layer was written to,
8972
encoded as described in the <<fundamentals-versionnum,API Version
9073
Numbers and Semantics>> section.
@@ -95,16 +78,82 @@ include::../structs/VkLayerProperties.txt[]
9578

9679
include::../validity/structs/VkLayerProperties.txt[]
9780

81+
To enable a layer, the name of the layer should be added to the
82+
pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo when creating
83+
a sname:VkInstance.
84+
9885
Loader implementations may: provide mechanisms outside the Vulkan API for
9986
enabling specific layers. Layers enabled through such a mechanism are
10087
_implicitly enabled_, while layers enabled by including the layer name in
101-
the pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo are
88+
the pname:ppEnabledLayerNames member of slink:VkInstanceCreateInfo are
10289
_explicitly enabled_. Except where otherwise specified, implicitly enabled
10390
and explicitly enabled layers differ only in the way they are enabled.
10491
Explicitly enabling a layer that is implicitly enabled has no additional
10592
effect.
10693

10794

95+
[[extended-functionality-device-layer-deprecation]]
96+
=== Device Layer Deprecation
97+
98+
Previous versions of this specification distinguished between instance and
99+
device layers. Instance layers were only able to intercept commands that
100+
operate on sname:VkInstance and sname:VkPhysicalDevice, except they were not
101+
able to intercept flink:vkCreateDevice. Device layers were enabled for
102+
individual devices when they were created, and could only intercept commands
103+
operating on that device or its child objects.
104+
105+
Device-only layers are now deprecated, and this specification no longer
106+
distinguishes between instance and device layers. Layers are enabled during
107+
instance creation, and are able to intercept all commands operating on that
108+
instance or any of its child objects. At the time of deprecation there were no
109+
known device-only layers and no compelling reason to create one.
110+
111+
In order to maintain compatibility with implementations released prior to
112+
device-layer deprecation, applications should: still enumerate and enable
113+
device layers. The behavior of fname:vkEnumerateDeviceLayerProperties and
114+
valid usage of the pname:ppEnabledLayerNames member of sname:VkDeviceCreateInfo
115+
maximizes compatibility with applications written to work with the previous
116+
requirements.
117+
118+
Device layers can: be enumerated by calling:
119+
120+
include::../protos/vkEnumerateDeviceLayerProperties.txt[]
121+
122+
* pname:pPropertyCount is a pointer to an integer related to the number of
123+
layer properties available or queried.
124+
* pname:pProperties is either `NULL` or a pointer to an array of
125+
slink:VkLayerProperties structures.
126+
127+
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
128+
129+
If pname:pProperties is `NULL`, then the number of layer properties available
130+
is returned in pname:pPropertyCount. Otherwise, pname:pPropertyCount must:
131+
point to a variable set by the user to the number of elements in the
132+
pname:pProperties array, and on return the variable is overwritten with the
133+
number of structures actually written to pname:pProperties. If
134+
pname:pPropertyCount is less than the number of layer properties available, at
135+
most pname:pPropertyCount structures will be written. If pname:pPropertyCount
136+
is smaller than the number of layers available, ename:VK_INCOMPLETE will be
137+
returned instead of ename:VK_SUCCESS, to indicate that not all the available
138+
layer properties were returned.
139+
140+
The list of layers enumerated by fname:vkEnumerateDeviceLayerProperties must:
141+
be exactly the sequence of layers enabled for the instance. The members of
142+
sname:VkLayerProperties for each enumerated layer must: be the same as the
143+
properties when the layer was enumerated by
144+
fname:vkEnumerateInstanceLayerProperties.
145+
146+
The pname:ppEnabledLayerNames and pname:enabledLayerCount members of
147+
sname:VkDeviceCreateInfo are deprecated and their values must: be ignored by
148+
implementations. However, for compatibility, only an empty list of layers or a
149+
list that exactly matches the sequence enabled at instance creation time are
150+
valid, and validation layers should: issue diagnostics for other cases.
151+
152+
Regardless of the enabled layer list provided in sname:VkDeviceCreateInfo, the
153+
sequence of layers active for a device will be exactly the sequence of layers
154+
enabled when the parent instance was created.
155+
156+
108157
[[extended-functionality-extensions]]
109158
== Extensions
110159

@@ -123,7 +172,7 @@ To query the available instance extensions, call:
123172
include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
124173

125174
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
126-
UTF-8 string naming the instance layer to retrieve extensions from.
175+
UTF-8 string naming the layer to retrieve extensions from.
127176
* pname:pPropertyCount is a pointer to an integer related to the number of
128177
extension properties available or queried, as described below.
129178
* pname:pProperties is either `NULL` or a pointer to an array of
@@ -136,7 +185,7 @@ implementation or by implicitly enabled layers are returned.
136185
When pname:pLayerName is the name of a layer, the instance extensions
137186
provided by that layer are returned.
138187

139-
To enable a instance extension, the name of the extension should be added to
188+
To enable an instance extension, the name of the extension should be added to
140189
the pname:ppEnabledExtensionNames member of slink:VkInstanceCreateInfo when
141190
creating a sname:VkInstance.
142191

@@ -146,7 +195,7 @@ include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
146195

147196
* pname:physicalDevice is the physical device that will be queried.
148197
* pname:pLayerName is either `NULL` or a pointer to a null-terminated
149-
UTF-8 string naming the device layer to retrieve extensions from.
198+
UTF-8 string naming the layer to retrieve extensions from.
150199
* pname:pPropertyCount is a pointer to an integer related to the number of
151200
extension properties available or queried, as described below.
152201
* pname:pProperties is either `NULL` or a pointer to an array of
@@ -159,10 +208,6 @@ implementation or by implicitly enabled layers are returned.
159208
When pname:pLayerName is the name of a layer, the device extensions
160209
provided by that layer are returned.
161210

162-
To enable a device layer, the name of the layer should be added to the
163-
pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when
164-
creating a sname:VkDevice.
165-
166211
For both flink:vkEnumerateInstanceExtensionProperties and
167212
flink:vkEnumerateDeviceExtensionProperties, if pname:pProperties is `NULL`,
168213
then the number of extensions properties available is returned in

‎doc/specs/vulkan/chapters/fundamentals.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -691,7 +691,7 @@ include::../enums/VkResult.txt[]
691691
A requested format is not supported on this device.
692692

693693
If a command returns a run time error, it will leave any result pointers
694-
unmodified.
694+
unmodified, unless other behavior is explicitly defined in the specification.
695695

696696
Out of memory errors do not damage any currently existing Vulkan objects.
697697
Objects that have already been successfully created can: still be used by

0 commit comments

Comments
 (0)