Skip to content

Commit 5a4c5e5

Browse files
oddhackoddhack
committed
Change log for February 25, 2015 Vulkan 1.0.4 spec update:
 * Bump API patch number from 3 to 4 for the first public update to the spec. Add patch number to the spec title (this will be done automatically from XML, later). * Fixes for numerous editorial issues. Regularize descriptions of variable-length array queries. Properly tag enumerants so they come out in the right font (many were mislabeled in usage tags in vk.xml, or not tagged). Spelling and markup corrections (public issue 4). * Fix typos and clearly separate description of different types of memory areas (public issue 5). * Use standards-compliant preprocessor guard symbols on headers (public issue 7). * Note that Github users can't currently set labels on issues, and recommend a fallback approach (public issue 15). * Use latexmath prefix on len= attributes (public issue 29). * Make flink:vkCmdUpdateBuffer pname:dataSize limit consistent (public issue 65). * Add VK_KHR_mirror_clamp_to_edge extension to core API branch, as an optional feature not introducing new commands or enums (internal issue 104). * Cleanup invariance language inherited from the GL specification to not refer to nonexistent (GL-specific) state (internal issue 111). * Modify the flink:vkCmdDrawIndexed pname:vertexOffset definition to not be the "base offset within the index buffer" but rather the "value added to the vertex index before indexing into the vertex buffer" (internal issue 118). * Fix drawing chapter in the "Programmable Primitive Shading" section where it described categories of drawing commands. It referenced flink:vkCmdDrawIndexed twice. Replace the second reference with flink:vkCmdDrawIndexedIndirect (internal issue 119). * Typo fixed in <<sparsememory-examples-advanced,Advanced Sparse Resources>> sparse memory example (internal issue 122). * Add flink:VkDisplayPlaneAlphaFlagsKHR to <require> section of VK_KHR_display extension (internal issue 125) * Add missing optional="false,true" to flink:vkGetImageSparseMemoryRequirements pname:pSparseMemoryRequirementCount parameter (internal issue 132) * Rename ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CREATE_INFO_EXT to ename:VK_STRUCTURE_TYPE_DEBUG_REPORT_CALLBACK_CREATE_INFO_EXT (internal issue 133) * Fix a handful of broken cross-references in the <<samplers,Samplers>> chapter (internal issue 134). * Fix "Input Attachement" GLSL example to use correct syntax (internal issue 135). * Update XML schema and documentation to accomodate recently added attributes for validity. Add some introductory material describing design choices and pointing to the public repository to file issues. * Put include of validity in the core spec extensions chapter on its own line, so that asciidoc is happy. * Fix vertexOffset language to specify that it's the value added to the vertex index before indexing into the vertex buffer, not the base offset within the index buffer. * Fix error in the description of flink:vkCmdNextSubpass.
1 parent 8555ed8 commit 5a4c5e5

52 files changed

Lines changed: 514 additions & 356 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎doc/specs/vulkan/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ INCLUDES := $(wildcard protos/*.txt structs/*.txt flags/*.txt enums/*.txt funcpo
126126
COMMONDOCS := $(CHAPTERS) $(INCLUDES)
127127
# A generate included file with the spec version, date, and git commit
128128
SPECVERSION = specversion.txt
129-
SPECREVISION = 1.0
129+
SPECREVISION = 1.0.4
130130
SPECREMARK =
131131

132132
# Spec targets

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
== VK_KHR_sampler_mirror_clamp_to_edge
2+
3+
*Name String*:: VK_KHR_sampler_mirror_clamp_to_edge
4+
*Extension Type*:: Device extension
5+
*Registered Extension Number*:: 15
6+
*Status*:: Final
7+
*Last Modified Date*:: 16/02/2016
8+
*Revision*:: 1
9+
*Dependencies*::
10+
- This extension is written against version 1.0. of the {apiname} API.
11+
*Contributors*::
12+
- Tobias Hector, Imagination Technologies
13+
*Contacts*::
14+
- Tobias Hector (tobias.hector@imgtec.com)
15+
16+
VK_KHR_sampler_mirror_clamp_to_edge extends the set of sampler address modes to
17+
include an additional mode (ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE)
18+
that effectively uses a texture map twice as large as the original image in
19+
which the additional half of the new image is a mirror image of the original
20+
image.
21+
22+
This new mode relaxes the need to generate images whose opposite edges
23+
match by using the original image to generate a matching "mirror image".
24+
This mode allows the texture to be mirrored only once in the negative
25+
s, t, and r directions.
26+
27+
=== New Enum Constants
28+
29+
* Extending ename:VkSamplerAddressMode:
30+
** ename:VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE
31+
32+
=== Example
33+
34+
Creating a sampler with the new address mode in each dimension
35+
36+
37+
[source,{basebackend@docbook:C++:cpp}]
38+
----------------------------------------
39+
VkSamplerCreateInfo createInfo =
40+
{
41+
VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO // sType
42+
// Other members set to application-desired values
43+
};
44+
45+
createInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
46+
createInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
47+
createInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE;
48+
49+
VkSampler sampler;
50+
VkResult result = vkCreateSampler(
51+
device,
52+
&createInfo,
53+
&sampler);
54+
----------------------------------------
55+
56+
=== Version History
57+
58+
* Revision 1, 2016-02-16 (Tobias Hector)
59+
- Initial draft

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ use of any other state value is not affected by the change):_
7676
* _Pixel storage state_
7777

7878
*Corollary 1* _Fragment generation is invariant with respect to the state
79-
values marked with * in Rule 2._
79+
values listed in Rule 2._
8080

8181
*Rule 3* _The arithmetic of each per-fragment operation is invariant except
8282
with respect to parameters that directly control it._

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,13 +203,15 @@ include::../protos/vkResetCommandBuffer.txt[]
203203
can: be in any state, and is put in the initial state.
204204
* pname:flags is of type elink:VkCommandBufferResetFlags:
205205
+
206+
--
206207
include::../enums/VkCommandBufferResetFlagBits.txt[]
207-
+
208+
208209
If pname:flags includes ename:VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT,
209210
then most or all memory resources currently owned by the command buffer
210211
should: be returned to the parent command pool. If this flag is not set,
211212
then the command buffer may: hold onto memory resources and reuse them when
212213
recording commands.
214+
--
213215

214216
include::../validity/protos/vkResetCommandBuffer.txt[]
215217

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -503,7 +503,7 @@ attachment index in addition to descriptor set and binding numbers.
503503
.GLSL example
504504
[source,{basebackend@docbook:c:glsl}]
505505
---------------------------------------------------
506-
layout (input_attachment_index=i, set=m, binding=n) uniform subpass myInputAttachment;
506+
layout (input_attachment_index=i, set=m, binding=n) uniform subpassInput myInputAttachment;
507507
---------------------------------------------------
508508

509509
.SPIR-V example

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

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,20 @@ include::../protos/vkEnumeratePhysicalDevices.txt[]
2323

2424
* pname:instance is a handle to a {apiname} instance previously created
2525
with fname:vkCreateInstance.
26-
* If pname:pPhysicalDevices is `NULL`, the number of physical devices
27-
available is returned in pname:pPhysicalDeviceCount. If
28-
pname:pPhysicalDevices is not `NULL`,
29-
* pname:pPhysicalDeviceCount must: point to a variable set by the user to
30-
the size of the array pointed to by pname:pPhysicalDevices, and is
31-
overwritten with the number of physical devices actually written to
32-
pname:pPhysicalDevices.
26+
* pname:pPhysicalDeviceCount is a pointer to an integer related to the
27+
number of physical devices available or queried, as described below.
28+
* pname:pPhysicalDevices is either `NULL` or a pointer to an
29+
array of sname:VkPhysicalDevice structures.
30+
31+
If pname:pPhysicalDevices is `NULL`, then the number of physical devices
32+
available is returned in pname:pPhysicalDeviceCount. Otherwise,
33+
pname:pPhysicalDeviceCount must: point to a variable set by the user to
34+
the number of elements in the pname:pPhysicalDevices array, and on
35+
return the variable is overwritten with the number of structures actually
36+
written to pname:pPhysicalDevices. If the value of
37+
pname:pPhysicalDeviceCount is less than the number of physical devices
38+
available, at most pname:pPhysicalDeviceCount structures will be
39+
written.
3340

3441
include::../validity/protos/vkEnumeratePhysicalDevices.txt[]
3542

@@ -142,7 +149,7 @@ include::../protos/vkGetPhysicalDeviceQueueFamilyProperties.txt[]
142149
* pname:pQueueFamilyPropertyCount is a pointer to an integer related to
143150
the number of queue families available or queried, as described below.
144151
* pname:pQueueFamilyProperties is either `NULL` or a pointer to an array
145-
of sname:VkQueueFamilyProperties structures.
152+
of slink:VkQueueFamilyProperties structures.
146153

147154
If pname:pQueueFamilyProperties is `NULL`, then the number of queue families
148155
available is returned in pname:pQueueFamilyPropertyCount. Otherwise,

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -427,7 +427,8 @@ include::../protos/vkCmdDrawIndexed.txt[]
427427
* pname:indexCount is the number of vertices to draw.
428428
* pname:instanceCount is the number of instances to draw.
429429
* pname:firstIndex is the base index within the index buffer.
430-
* pname:vertexOffset is the base offset within the index buffer.
430+
* pname:vertexOffset is the value added to the vertex index before indexing
431+
into the vertex buffer.
431432
* pname:firstInstance is the instance ID of the first instance to draw.
432433

433434
When the command is executed, primitives are assembled using the current

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

Lines changed: 44 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,10 @@ To query the available instance layers, call:
3636

3737
include::../protos/vkEnumerateInstanceLayerProperties.txt[]
3838

39-
* pname:pPropertyCount is the number of layer properties that can be
40-
returned in pname:pProperties.
41-
* pname:pProperties is an array of slink:VkLayerProperties structures in
42-
which properties of instance layers available on this implementation are
43-
returned.
39+
* pname:pPropertyCount is a pointer to an integer related to the number of
40+
layer properties available or queried, as described below.
41+
* pname:pProperties is either `NULL` or a pointer to an array of
42+
slink:VkLayerProperties structures.
4443

4544
include::../validity/protos/vkEnumerateInstanceLayerProperties.txt[]
4645

@@ -53,29 +52,29 @@ To query the layers available to a given physical device, call:
5352
include::../protos/vkEnumerateDeviceLayerProperties.txt[]
5453

5554
* pname:physicalDevice is the physical device that will be queried.
56-
* pname:pPropertyCount is the number of layer properties that can be
57-
returned in pname:pProperties.
58-
* pname:pProperties is an array of slink:VkLayerProperties structures in
59-
which properties of layers available on pname:physicalDevice are
60-
returned.
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.
6159

6260
include::../validity/protos/vkEnumerateDeviceLayerProperties.txt[]
6361

6462
To enable a device layer, the name of the layer should be added to the
6563
pname:ppEnabledLayerNames member of slink:VkDeviceCreateInfo when creating
6664
a slink:VkDevice.
6765

68-
Both commands will return an array of sname:VkLayerProperties of the
69-
respective instance or device layers present. Calling
70-
fname:vkEnumerateInstanceLayerProperties or
71-
fname:vkEnumerateDeviceLayerProperties with pname:pProperties set to `NULL`
72-
will return the number of supported layers in the basetype:uint32_t variable
73-
pointed to by pname:pPropertyCount. If pname:pProperties is not set to
74-
`NULL`, the query will fill the array and update pname:pPropertyCount to
75-
indicate the number of sname:VkLayerProperties filled in. If
76-
pname:pPropertyCount is smaller than the number of layers available,
77-
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
78-
indicate that not all the available properties were returned.
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 the value of 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 properties were
77+
returned.
7978

8079
The definition of sname:VkLayerProperties is:
8180

@@ -123,14 +122,14 @@ include::../protos/vkEnumerateInstanceExtensionProperties.txt[]
123122

124123
* pname:pLayerName is either `NULL` or the name of a instance layer to
125124
retrieve extensions from.
126-
* pname:pPropertyCount is the number of extension properties that can be
127-
returned in pname:pProperties.
128-
* pname:pProperties is an array of slink:VkExtensionProperties structures
129-
in which properties of instance extensions available on this
130-
implementation are returned.
131-
132-
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[] Any
133-
instance extensions provided by the {apiname} implementation or by
125+
* pname:pPropertyCount is a pointer to an integer related to the number of
126+
extension properties available or queried, as described below.
127+
* pname:pProperties is either `NULL` or a pointer to an array of
128+
slink:VkExtensionProperties structures.
129+
130+
include::../validity/protos/vkEnumerateInstanceExtensionProperties.txt[]
131+
132+
Any instance extensions provided by the {apiname} implementation or by
134133
implicitly enabled layers, but not by explicitly enabled layers, are
135134
returned when pname:pLayerName parameter is `NULL`. When pname:pLayerName is
136135
the name of a layer, the instance extensions provided by that layer are
@@ -147,11 +146,10 @@ include::../protos/vkEnumerateDeviceExtensionProperties.txt[]
147146
* pname:physicalDevice is the physical device that will be queried.
148147
* pname:pLayerName is either `NULL` or the name of a device layer to
149148
retrieve extensions from.
150-
* pname:pPropertyCount is the number of extension properties that can be
151-
returned in pname:pProperties.
152-
* pname:pProperties is an array of slink:VkExtensionProperties structures
153-
in which properties of extensions available on pname:physicalDevice are
154-
returned.
149+
* pname:pPropertyCount is a pointer to an integer related to the number of
150+
extension properties available or queried, as described below.
151+
* pname:pProperties is either `NULL` or a pointer to an array of
152+
slink:VkExtensionProperties structures.
155153

156154
include::../validity/protos/vkEnumerateDeviceExtensionProperties.txt[]
157155

@@ -165,21 +163,18 @@ To enable a device layer, the name of the layer should be added to the
165163
pname:ppEnabledExtensionNames member of slink:VkDeviceCreateInfo when
166164
creating a slink:VkDevice.
167165

168-
Both commands return an array of sname:VkExtensionProperties
169-
for any extensions implemented by the given pname:pLayerName.
170-
Set pname:pLayerName to `NULL` to query for extensions not part of any
171-
layer. Calling fname:vkEnumerateInstanceExtensionProperties or
172-
fname:vkEnumerateDeviceExtensionProperties with pname:pProperties set to
173-
`NULL` will return the count of extensions for the given layer in the
174-
basetype:uint32_t variable pointed to by pname:pPropertyCount. With
175-
pname:pProperties pointing to an array of sname:VkExtensionProperties,
176-
fname:vkEnumerateInstanceExtensionProperties
177-
and fname:vkEnumerateDeviceExtensionProperties will fill the array and
178-
update the count to indicate the number of sname:VkExtensionProperties
179-
filled in. If the provided count is smaller than the number of extensions
180-
available, ename:VK_INCOMPLETE will be returned
181-
instead of ename:VK_SUCCESS to indicate that not all the
182-
available properties were returned.
166+
For both flink:vkEnumerateInstanceExtensionProperties and
167+
flink:vkEnumerateDeviceExtensionProperties, if pname:pProperties is `NULL`,
168+
then the number of extensions properties available is returned in
169+
pname:pPropertyCount. Otherwise, pname:pPropertyCount must: point to a
170+
variable set by the user to the number of elements in the pname:pProperties
171+
array, and on return the variable is overwritten with the number of
172+
structures actually written to pname:pProperties. If the value of
173+
pname:pPropertyCount is less than the number of extension properties
174+
available, at most pname:pPropertyCount structures will be written. If
175+
pname:pPropertyCount is smaller than the number of extensions available,
176+
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS, to
177+
indicate that not all the available properties were returned.
183178

184179
The definition of sname:VkExtensionProperties is:
185180

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -979,7 +979,7 @@ different equations in the spec).
979979
subpixel precision that floating-point viewport bounds are interpreted
980980
at is given by this limit.
981981
* [[features-limits-minMemoryMapAlignment]] pname:minMemoryMapAlignment is
982-
the minimum required alignment, in bytes, of host-visible memory
982+
the minimum required alignment, in bytes, of host visible memory
983983
allocations within the host address space. When mapping a memory
984984
allocation with flink:vkMapMemory, subtracting pname:offset bytes from
985985
the returned pointer will always produce an integer multiple of this

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

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,16 @@ advertise one or more heaps, representing different areas of memory. Memory
4242
heaps are either device local or host local, but are always visible to the
4343
device. Further detail about memory heaps is exposed via memory types
4444
available on that heap. Examples of memory areas that may: be available on
45-
an implementation include _device local_ (memory that is physically
46-
connected to the device), _device local, host visible_ (device local memory
47-
that is visible to the host) and _host local, host visible_ (memory that is
48-
local to the host and visible to the device and host). On other
49-
architectures, there may: only be a single heap that can: be used for any
50-
purpose.
45+
an implementation include:
46+
47+
* _device local_ is memory that is physically connected to the device.
48+
* _device local, host visible_ is device local memory that is visible to
49+
the host.
50+
* _host local, host visible_ is memory that is local to the host and
51+
visible to the device and host.
52+
53+
On other architectures, there may: only be a single heap that can: be used
54+
for any purpose.
5155

5256
A {apiname} application controls a set of devices through the submission of
5357
command buffers which have recorded device commands issued via {apiname}
@@ -73,8 +77,9 @@ the responsibility of the application.
7377
{apiname} queues provide an interface to the execution engines of a device.
7478
Commands are recorded into command buffers ahead of execution time.
7579
These command buffers are then submitted to queues for execution. Command
76-
buffers submitted to a single queue play back the commands in the order
77-
they were recorded, both within and across command buffer boundaries.
80+
buffers submitted to a single queue are played back in the order they were
81+
submitted, and commands within each buffer are played back in the order they
82+
were recorded.
7883
Work performed by those commands respects the ordering guarantees provided
7984
by explicit and implicit dependencies, as described below. Work submitted
8085
to separate queues may: execute in any relative order unless otherwise
@@ -206,7 +211,7 @@ There are two classes of handles, dispatchable and non-dispatchable.
206211
_Dispatchable_ handle types are a pointer to an opaque type. This pointer
207212
may: be used by layers as part of intercepting API commands, and thus each
208213
API command takes a dispatchable type as its first parameter. Each object of
209-
a dispatchable type has a unique handle value.
214+
a dispatchable type must: have a unique handle value during its lifetime.
210215

211216
_Non-dispatchable_ handle types are a 64-bit integer type whose meaning is
212217
implementation-dependent, and may: encode object information directly in the
@@ -301,7 +306,7 @@ reset, then it can: be used as if it never used the freed object. An
301306
exception to this is when there is a parent/child relationship between
302307
objects. In this case, the application mustnot: destroy a parent object
303308
before its children, except when the parent is explicitly defined to free
304-
its children when it is destroyed (i.e. for pool objects, as defined below).
309+
its children when it is destroyed (e.g. for pool objects, as defined below).
305310

306311
sname:VkCommandPool objects are parents of sname:VkCommandBuffer objects.
307312
sname:VkDescriptorPool objects are parents of sname:VkDescriptorSet objects.
@@ -520,19 +525,19 @@ by the command, and all fundamental types accessed through the pointer (e.g.
520525
as elements of an array or as members of a structure) satisfy the alignment
521526
requirements of the host processor.
522527

523-
Any parameter that is an enumerant must: be a valid value for that enumerant
524-
type. A value is valid for an enumerant if:
528+
Any parameter of an enumerated type must: be a valid enumerant for that
529+
type. A enumerant is valid if:
525530

526-
* The value is defined as part of the enumerant type.
527-
* The value is not one of the special values defined for an enumerant
528-
type, which are suffixed with etext:_BEGIN_RANGE, etext:_END_RANGE,
529-
etext:_RANGE_SIZE or etext:_MAX_ENUM.
531+
* The enumerant is defined as part of the enumerated type.
532+
* The enumerant is not one of the special values defined for the
533+
enumerated type, which are suffixed with etext:_BEGIN_RANGE,
534+
etext:_END_RANGE, etext:_RANGE_SIZE or etext:_MAX_ENUM.
530535

531536
Any parameter that is a flag value must: be a valid combination of bit
532537
flags. A valid combination is either zero or the bitwise OR of valid bit
533538
flags. A bit flag is valid if:
534539

535-
* The value is defined as part of the bits type, where the bits type is
540+
* The flag is defined as part of the bits type, where the bits type is
536541
obtained by taking the flag type and replacing the trailing etext:Flags
537542
with etext:FlagBits. For example, a flag value of type
538543
elink:VkColorComponentFlags must: contain only values selected from the

0 commit comments

Comments
 (0)