Add a query to determine logical identifiers for descriptors

* This is a consideration for any cases where binding numbers are relevant -
  primarily D3D11 and GL - where the offset into an arbitrary (and possibly
  fake) descriptor storage is not helpful but knowing the register binding
  definitely is.
* If someone wants to look at the raw descriptor contents without respect to a
  particular shader access they can use this query to determine a more useful
  'name' for any given descriptor. On D3D11 and GL this gives the register
  number, on Vulkan it gives the binding number (and array element). On D3D12 it
  just repeats the offset effectively.

renderdoc/api/replay/common_pipestate.h

@@ -849,6 +849,111 @@ does not necessarily guarantee that the descriptor was accessed on the GPU durin
 
 DECLARE_REFLECTION_STRUCT(DescriptorAccess);
 
+DOCUMENT(R"(In many cases there may be a logical location or fixed binding point for a particular
+descriptor which is not conveyed with a simple byte offset into a descriptor store.
+This is particularly true for any descriptor stores that are not equivalent to a buffer of bytes
+but actually have an API structure - for example D3D11 and GL with fixed binding points, or Vulkan
+with descriptor sets.
+
+In some cases on APIs with explicit descriptor storage this may convey information about virtualised
+descriptors that are not explicitly backed with real storage.
+
+This structure describes such a location queried for a given descriptor.
+
+For example on D3D11 this would give the register number of the binding, and on GL it would give the
+unit index. Both cases would be able to query the type and shader stage visibility of descriptors
+that are not accessed or even bound.
+
+On Vulkan this would give the set, binding, and visibility. In most cases this information will be
+available for all descriptors but in some cases the type of descriptor may not be available if it
+is unused and has not been initialised.
+
+On D3D12 this would only give the index into the heap, as no other information is available purely
+by the descriptor itself.
+
+.. note::
+
+  This information may not be fully present on all APIs so the returned structures may be empty or
+  partially filled out, depending on what information is relevant per API.
+)");
+struct DescriptorLogicalLocation
+{
+  DOCUMENT("");
+  DescriptorLogicalLocation() = default;
+  DescriptorLogicalLocation(const DescriptorLogicalLocation &) = default;
+  DescriptorLogicalLocation &operator=(const DescriptorLogicalLocation &) = default;
+
+  bool operator==(const DescriptorLogicalLocation &o) const
+  {
+    return fixedBindNumber == o.fixedBindNumber && stageMask == o.stageMask &&
+           category == o.category && logicalBindName == o.logicalBindName;
+  }
+  bool operator<(const DescriptorLogicalLocation &o) const
+  {
+    // note there are two different conflicting sorts that would be sensible here:
+    // stage > category > fixed bind would work best for D3D11/GL
+    // fixed bind first works better for Vulkan/D3D12.
+    //
+    // We assume users will access or sort D3D11/GL descriptors directly by binds if needed so are
+    // less likely to rely on this sort behaviour.
+    if(fixedBindNumber != o.fixedBindNumber)
+      return fixedBindNumber < o.fixedBindNumber;
+    if(stageMask != o.stageMask)
+      return stageMask < o.stageMask;
+    if(category != o.category)
+      return category < o.category;
+    if(logicalBindName != o.logicalBindName)
+      return logicalBindName < o.logicalBindName;
+    return false;
+  }
+
+  DOCUMENT(R"(The set of shader stages that this descriptor is intrinsically available to. This is
+primarily relevant for D3D11 with its fixed per-stage register binding points.
+
+Note this *only* shows if a descriptor itself can only ever be accessed by some shader stages by
+definition, not if a descriptor is generally available but happened to only be accessed by one or
+more stage. That information is available directly in the :class:`DescriptorAccess` itself.
+
+:type: ShaderStageMask
+)");
+  ShaderStageMask stageMask = ShaderStageMask::All;
+
+  DOCUMENT(R"(The general category of a descriptor stored. This may not be available for
+uninitialised descriptors on all APIs.
+
+:type: DescriptorCategory
+)");
+  DescriptorCategory category = DescriptorCategory::Unknown;
+
+  DOCUMENT(R"(The fixed binding number for this descriptor. The interpretation of this is
+API-specific and it is provided purely for informational purposes and has no bearing on how data
+is accessed or described.
+
+Generally speaking sorting by this number will give a reasonable ordering by binding if it exists.
+
+.. note::
+  Because this number is API-specific, there is no guarantee that it will be unique across all
+  descriptors. It should be used only within contexts that can interpret it API-specifically, or
+  else for purely informational/non-semantic purposes like sorting.
+
+:type: int
+)");
+  uint32_t fixedBindNumber = 0;
+
+  DOCUMENT(R"(The logical binding name, as suitable for displaying to a user when displaying
+the contents of a descriptor queried directly from a heap.
+
+Depending on the API, this name may be identical or less specific than the one obtained from
+shader reflection. Generally speaking it's preferred to use any information from shader reflection
+first, and fall back to this name if no reflection information is available in the context.
+
+:type: str
+)");
+  rdcinflexiblestr logicalBindName;
+};
+
+DECLARE_REFLECTION_STRUCT(DescriptorLogicalLocation);
+
 DOCUMENT("Information about a single constant buffer binding.");
 struct BoundCBuffer
 {

renderdoc/api/replay/renderdoc_replay.h

@@ -595,6 +595,16 @@ Multiple ranges within the store can be queried at once, and are returned in a c
 )");
   virtual rdcarray<DescriptorAccess> GetDescriptorAccess() = 0;
 
+  DOCUMENT(R"(Retrieve the logical locations for descriptors in a given descriptor store.
+
+:param ResourceId descriptorStore: The descriptor store to be queried from.
+:param List[DescriptorRange] ranges: The descriptor ranges to query.
+:return: The descriptor logical locations.
+:rtype: List[DescriptorLogicalLocation]
+)");
+  virtual rdcarray<DescriptorLogicalLocation> GetDescriptorLocations(
+      ResourceId descriptorStore, const rdcarray<DescriptorRange> &ranges) = 0;
+
   DOCUMENT(R"(Retrieve the list of possible disassembly targets for :meth:`DisassembleShader`. The
 values are implementation dependent but will always include a default target first which is the
 native disassembly of the shader. Further options may be available for additional diassembly views

renderdoc/api/replay/replay_enums.h

@@ -4771,7 +4771,7 @@ DOCUMENT(R"(A set of flags for ``ShaderStage`` stages
 
   A shorthand version with flags set for all stages together.
 )");
-enum class ShaderStageMask : uint32_t
+enum class ShaderStageMask : uint16_t
 {
   Unknown = 0,
   Vertex = 1 << uint32_t(ShaderStage::Vertex),