Add Location Component chapter (#292)

* Add Location Component chapter

* Apply tobias feedback

* Apply Alan feedback

Author: spencer-lunarg

README.adoc

@@ -180,6 +180,10 @@ The Vulkan Guide can be built as a single page using `asciidoctor guide.adoc`
 
 // include::{chapters}descriptor_dynamic_offset.adoc[]
 
+=== xref:{chapters}location_component_interface.adoc[Location and Component Interface]
+
+// include::{chapters}location_component_interface.adoc[]
+
 === xref:{chapters}push_constants.adoc[Push Constants]
 
 // include::{chapters}push_constants.adoc[]

chapters/images/location_example_16bit.svg

@@ -0,0 +1,154 @@
+// Copyright 205 The Khronos Group, Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+ifndef::chapters[:chapters:]
+ifndef::images[:images: images/]
+
+[[location-and-component-interface]]
+= Location and Component Interface
+
+This chapter is an overview of the link:https://docs.vulkan.org/spec/latest/chapters/interfaces.html#interfaces-iointerfaces-locations[Location and Component Assignment] chapter to help give examples, especially around some of the more extreme edge cases.
+
+The simplest way to think about a `Location` is that it is made up of four 32-bit `Component`s.
+This means a `vec4`/`float4`/`uvec4`/etc will fit perfectly in a single `Location`.
+Multiple variables can be packed into the same `Location` if their `Component`s do not overlap.
+
+Locations are used for both the `Input` and `Output` to interface between shaders stages when possible.
+
+== Advice for general users
+
+For most people, this chapter is much deeper into edge cases compared who developers generally use the `Location` interface. For those developers, the simple advise to take away is:
+
+1. Use less `Location` if possible.
+2. If you need many `Location`s, make sure you are link:https://docs.vulkan.org/spec/latest/chapters/interfaces.html#interfaces-iointerfaces-limits[under the limits].
+
+== Basic Example
+
+Here is a basic example:
+
+[source,glsl]
+----
+layout(location=0) in vec4 a;
+layout(location=1, component = 0) in vec2 b;
+layout(location=1, component = 2) in float c;
+----
+
+image::{images}location_example_basic.svg[location_example_basic]
+
+== 16-bit
+
+16-bit values always consume a full 32-bit `Component`. So a vector with 16-bit elements will consume the same resources as a vector with 32-bit elements; they are not tightly packed.
+
+[source,glsl]
+----
+layout(location=0) in f16vec3 a;
+----
+
+image::{images}location_example_16bit.svg[location_example_16bit]
+
+== Crossing Location Boundaries
+
+All 16-bit and 32-bit vectors must be inside a single `Location`, so the following is **not** allowed.
+The last two elements would consume `component = 4` and `component = 5`, which do not exist.
+
+[source,glsl]
+----
+layout(location=0, component = 2) in vec4 a;
+----
+
+image::{images}location_example_boundaries.svg[location_example_boundaries]
+
+== 64-bit
+
+64-bit are special as they can consume up to 2 `Location`, but they must only start at `Component` `0` or `2`.
+
+[source,glsl]
+----
+layout(location=0) in f64vec3 a;
+----
+
+image::{images}location_example_64bit.svg[location_example_64bit]
+
+== Interleaving Components
+
+The following attempt to have multiple variables alias the same component is link:https://godbolt.org/z/h61baYhT4[not allowed].
+
+[source,glsl]
+----
+layout(location=0) in vec2 in_a; // Components 0 and 1
+layout(location=0, component=1) in float in_f; // Invalid: overlaps component 1
+----
+
+The following modification would make it legal as multiple variable can share a `Location`, just not a `Component
+`
+[source,patch]
+----
+layout(location=0) in vec2 in_a;
+// Change in_f to use component 2 instead
+- layout(location=0, component=1) in float in_f;
++ layout(location=0, component=2) in float in_f;
+----
+
+== Array
+
+An element of an array will consume all every `Component` in a `Location` that it would consume as a non-arrayed value, with each subsequent element consuming the next available `Location`.
+
+For example:
+
+[source,glsl]
+----
+layout(location=0) in float a[3];
+----
+
+image::{images}location_example_array.svg[location_example_array]
+
+As seen, using a scalar or something such as a `vec2`/`float2` will leave many `Component` slots unused.
+
+It is **not** allowed to use any other `Component` in a `Location` that is being consumed by an array
+
+[source,glsl]
+----
+layout(location=0) in float a[3];
+layout(location=2, component=2) in float b;
+----
+
+`float b` is invalid because the array consumes all of `Location` 2.
+
+image::{images}location_example_array2.svg[location_example_array2]
+
+[NOTE]
+====
+Some shader stages, like geometry shaders, have an array around its interface matching, this array is disregarded for the above examples.
+====
+
+== Matrix
+
+A matrix is viewed as an array, which consume all 4 components.
+
+So something like
+
+[source,glsl]
+----
+layout(location = 0) in mat3x2 a;
+----
+
+From a `Location`/`Component` point-of-view looks like
+
+[source,glsl]
+----
+// N == 3
+// Arrays consume whole Location
+layout(location = 0) in vec2 a[3];
+----
+
+As stated above, arrays consume the whole `Location` so the following is **not** allowed.
+
+[source,glsl]
+----
+layout(location = 0) in mat3x2 a;
+layout(location = 2, component = 2) in float b;
+----
+
+`float b` is invalid because the implicit array of the matrix consumes all of `Location` 2.
+
+image::{images}location_example_matrix.svg[location_example_matrix]

chapters/images/location_example_64bit.svg

@@ -11,6 +11,8 @@ This chapter is an overview of the link:https://docs.vulkan.org/spec/latest/chap
 
 It is also important to remember that Vulkan is a tool that can be used in different ways. The following are examples for educational purposes of how vertex data **can** be laid out.
 
+For more information about `Location` and `Component`, see the xref:{chapters}location_component_interface.adoc[Location and Component Interface] chapter.
+
 == Binding and Locations
 
 A `binding` is tied to a position in the vertex buffer from which the vertex shader will start reading data out of during a `vkCmdDraw*` call. Changing the `bindings` does **not** require making any alterations to an app's vertex shader source code.