Add a Descriptor Array chapter (#317)

* Add a Descriptor Array chapter

* Update chapters/descriptor_arrays.adoc

Author: spencer-lunarg

README.adoc

@@ -190,6 +190,10 @@ The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc`
 
 // include::{chapters}vertex_input_data_processing.adoc[]
 
+=== xref:{chapters}descriptor_arrays.adoc[Descriptor Arrays]
+
+// include::{chapters}descriptor_arrays.adoc[]
+
 === xref:{chapters}descriptor_dynamic_offset.adoc[Descriptor Dynamic Offset]
 
 // include::{chapters}descriptor_dynamic_offset.adoc[]

antora/modules/ROOT/nav.adoc

@@ -43,6 +43,7 @@
 ** xref:{chapters}primitive_topology.adoc[]
 ** xref:{chapters}mapping_data_to_shaders.adoc[]
 *** xref:{chapters}vertex_input_data_processing.adoc[]
+*** xref:{chapters}descriptor_arrays.adoc[]
 *** xref:{chapters}descriptor_dynamic_offset.adoc[]
 *** xref:{chapters}location_component_interface.adoc[]
 *** xref:{chapters}push_constants.adoc[]

chapters/descriptor_arrays.adoc

@@ -0,0 +1,161 @@
+// Copyright 2025 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[descriptor-arrays]]
+= Descriptor Arrays
+
+This chapter is to help explain about how you can create an array of descriptors.
+
+== Bindings vs Arrays
+
+Inside a single descriptor set there can be multiple bindings. The main advantage of bindings is if you have different types of descriptors in the descriptor set (samplers, uniform buffers, etc).
+
+When you have multiple of the same descriptor type, you might want to use an array of descriptors instead.
+
+As a simple example, if we have 4 `VkBuffer` that we want to turn into 4 different Uniform Buffers, we could represent this as 4 different bindings in the descriptor set:
+
+[source,glsl]
+----
+layout(set = 0, binding = 0) uniform UBO0 {
+    uint data_0;
+};
+layout(set = 0, binding = 1) uniform UBO1 {
+    uint data_1;
+};
+layout(set = 0, binding = 2) uniform UBO2 {
+    uint data_2;
+};
+layout(set = 0, binding = 3) uniform UBO3 {
+    uint data_3;
+};
+----
+
+We could also represent this as an array of 4 descriptors:
+
+[source,glsl]
+----
+layout(set = 0, binding = 0) uniform UBO0 {
+    uint data;
+} buffers[4];
+----
+
+If you have the `runtimeDescriptorArray` feature found in xref:{chapters}extensions/VK_EXT_descriptor_indexing.adoc[VK_EXT_descriptor_indexing] you can also tell the shader the array size will be known at runtime
+
+[source,glsl]
+----
+layout(set = 0, binding = 0) uniform UBO0 {
+    uint data;
+} buffers[];
+----
+
+== Setting up a Descriptor Array
+
+Using the example of
+
+[source,glsl]
+----
+layout(set = 0, binding = 0) uniform UBO0 {
+    uint data;
+} buffers[4];
+----
+
+it is pretty easy to set up. You just need to set your `VkDescriptorSetLayoutBinding::descriptorCount` to `4`.
+
+When you update you have 2 options
+
+1. Use an array of 4 `VkDescriptorBufferInfo` (likely easier way)
+
+[source,c++]
+----
+VkDescriptorBufferInfo buffer_infos[4];
+buffer_infos[0] = {buffer_0, 0, VK_WHOLE_SIZE};
+buffer_infos[1] = {buffer_1, 0, VK_WHOLE_SIZE};
+buffer_infos[2] = {buffer_2, 0, VK_WHOLE_SIZE};
+buffer_infos[3] = {buffer_3, 0, VK_WHOLE_SIZE};
+
+VkWriteDescriptorSet writes;
+writes.dstBinding = 0;
+writes.dstArrayElement = 0;
+writes.descriptorCount = 4; // will consume 4 items in pBufferInfo
+writes.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
+writes.pBufferInfo = buffer_infos;
+----
+
+2. Use an array of 4 `VkWriteDescriptorSet`
+
+[source,c++]
+----
+VkWriteDescriptorSet writes[4];
+writes[0].dstArrayElement = 0; // points which descriptor in the array
+writes[0].descriptorCount = 1;
+writes[0].pBufferInfo = buffer_info_0;
+
+writes[1].dstArrayElement = 1;
+writes[1].descriptorCount = 1;
+writes[1].pBufferInfo = buffer_info_1;
+
+writes[2].dstArrayElement = 2;
+writes[2].descriptorCount = 1;
+writes[2].pBufferInfo = buffer_info_2;
+
+writes[3].dstArrayElement = 3;
+writes[3].descriptorCount = 1;
+writes[3].pBufferInfo = buffer_info_3;
+----
+
+== Consecutive Binding Updates
+
+When updating multiple bindings at once there is a concept of link:https://docs.vulkan.org/spec/latest/chapters/descriptorsets.html#descriptorsets-updates-consecutive[Consecutive Binding Updates in the Vulkan Spec].
+
+The follow is an example to help illustrate how it works. We will have 5 descriptors spread across for 3 different bindings. The shader code is expressed as:
+
+[source,glsl]
+----
+layout(set = 0, binding = 1) uniform sampler Samplers_A[2];
+
+layout(set = 0, binding = 2) uniform sampler Samplers_B;
+
+layout(set = 0, binding = 6) uniform sampler Samplers_C[2];
+----
+
+The API is expressed as:
+
+[source,c++]
+----
+VkDescriptorSetLayoutBinding sampler_a;
+sampler_a.binding = 1;
+sampler_a.descriptorCount = 2;
+
+VkDescriptorSetLayoutBinding sampler_b;
+sampler_b.binding = 2;
+sampler_b.descriptorCount = 1;
+
+VkDescriptorSetLayoutBinding sampler_c;
+sampler_c.binding = 6;
+sampler_c.descriptorCount = 2;
+----
+
+If we try to update the descriptors together, the `VkWriteDescriptorSet` will look like:
+
+[source,c++]
+----
+VkDescriptorImageInfo image_infos[5];
+
+VkWriteDescriptorSet writes;
+writes.dstBinding = 1;
+writes.dstArrayElement = 0;
+writes.descriptorCount = 5;
+writes.descriptorType = VK_DESCRIPTOR_TYPE_SAMPLER;
+writes.pImageInfo = image_infos;
+----
+
+Here the `VkWriteDescriptorSet::descriptorCount` is `5`. It will set the following:
+
+- `image_infos[0]` to binding 1, index 0
+- `image_infos[1]` to binding 1, index 1
+- `image_infos[2]` to binding 2, index 0
+- `image_infos[3]` to binding 6, index 0
+- `image_infos[4]` to binding 6, index 1

guide.adoc

@@ -185,6 +185,10 @@ include::{chapters}mapping_data_to_shaders.adoc[]
 
 include::{chapters}vertex_input_data_processing.adoc[]
 
+// === Descriptor Array
+
+include::{chapters}descriptor_arrays.adoc[]
+
 // === Descriptor Dynamic Offset
 
 include::{chapters}descriptor_dynamic_offset.adoc[]

lang/jp/README-jp.adoc

@@ -176,6 +176,10 @@ Vulkan Guide は、`asciidoctor guide.adoc` を使って1つのページとし
 
 // include::{chapters}vertex_input_data_processing.adoc[]
 
+=== xref:{chapters}descriptor_arrays.adoc[Descriptor Arrays]
+
+// include::{chapters}descriptor_arrays.adoc[]
+
 === xref:{chapters}descriptor_dynamic_offset.adoc[ディスクリプタ動的オフセット]
 
 // include::{chapters}descriptor_dynamic_offset.adoc[]

lang/jp/chapters/descriptor_arrays.adoc

@@ -0,0 +1,11 @@
+// Copyright 2025 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Required for both single-page and combined guide xrefs to work
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[descriptor-arrays]]
+= Descriptor Arrays
+
+すみません！まだまだ翻訳が必要！

lang/jp/guide.adoc

@@ -178,6 +178,10 @@ include::{chapters}mapping_data_to_shaders.adoc[]
 
 include::{chapters}vertex_input_data_processing.adoc[]
 
+// === Descriptor Array
+
+include::{chapters}descriptor_arrays.adoc[]
+
 // === Descriptor Dynamic Offset
 
 include::{chapters}descriptor_dynamic_offset.adoc[]

lang/kor/README-kor.adoc

@@ -191,6 +191,10 @@ Vulkan에서 사용하는 특수한 용어에 대한 혼란을 막기 위해 명
 
 // include::{chapters}vertex_input_data_processing.adoc[]
 
+=== xref:{chapters}descriptor_arrays.adoc[Descriptor Arrays]
+
+// include::{chapters}descriptor_arrays.adoc[]
+
 === xref:{chapters}descriptor_dynamic_offset.adoc[디스크립터 동적 오프셋]
 
 // include::{chapters}descriptor_dynamic_offset.adoc[]

lang/kor/chapters/descriptor_arrays.adoc

@@ -0,0 +1,11 @@
+// Copyright 2025 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+// Required for both single-page and combined guide xrefs to work
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[descriptor-arrays]]
+= Descriptor Arrays
+
+죄송합니다, 아직 번역이 필요합니다.

lang/kor/guide.adoc

@@ -181,6 +181,10 @@ include::{chapters}mapping_data_to_shaders.adoc[]
 
 include::{chapters}vertex_input_data_processing.adoc[]
 
+// === Descriptor Array
+
+include::{chapters}descriptor_arrays.adoc[]
+
 // === Descriptor Dynamic Offset
 
 include::{chapters}descriptor_dynamic_offset.adoc[]