Add RT acceleration structure abstraction with size queries and resource allocation

Introduce the foundational types for ray tracing acceleration structures:
abstract `AccelerationStructure` base class, geometry/instance descriptors,
BLAS/TLAS build-request structs with size queries, the
`AccelerationStructureBuildFlags` bitmask (using
`LLVM_DECLARE_ENUM_AS_BITMASK` since `TextureUsage` already uses the
intrusive `LLVM_MARK_AS_BITMASK_ENUM`; `TextureUsage` also gains its
previously-missing `LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE()`), and AS
resource allocation across DX12, Vulkan, and Metal. Recording build
commands lands in a follow-up commit on top of the ComputeEncoder
abstraction.

Vulkan device creation switches to a single `vkGetPhysicalDeviceFeatures2`
call covering every extension feature struct we care about (atomic-int64,
mesh-shader, acceleration-structure, BDA on 1.1): each struct is chained
into `pNext` before the query, and post-query we verify the gating bool
and clear the sub-features we don't enable (capture-replay,
indirect-build, multiview, etc.).

Drive-by: rather than letting `vkCreateDevice` reject the device with a
generic `VK_ERROR_FEATURE_NOT_PRESENT`, the code now returns a
descriptive `llvm::Error` naming the extension and the bool that came
back zero — pinpointing the case where a driver advertises an extension
but reports its base feature as `VK_FALSE`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarijnS95

include/API/AccelerationStructure.h

@@ -0,0 +1,193 @@
+//===- AccelerationStructure.h - RT Acceleration Structure Types ----------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef OFFLOADTEST_API_ACCELERATIONSTRUCTURE_H
+#define OFFLOADTEST_API_ACCELERATIONSTRUCTURE_H
+
+#include "API/API.h"
+#include "API/Buffer.h"
+#include "API/Resources.h"
+
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/BitmaskEnum.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/Support/Error.h"
+
+#include <cstdint>
+
+namespace offloadtest {
+LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE();
+
+enum AccelerationStructureBuildFlags : uint32_t {
+  BuildFlagNone = 0,
+  AllowUpdate = 1 << 0,
+  PreferFastTrace = 1 << 1,
+  PreferFastBuild = 1 << 2,
+  // NOTE: keep LargestValue in LLVM_DECLARE_ENUM_AS_BITMASK at the end of this
+  // header in sync when adding new flags.
+};
+
+struct AccelerationStructureSizes {
+  uint64_t ResultDataMaxSizeInBytes = 0;
+  uint64_t ScratchDataSizeInBytes = 0;
+  uint64_t UpdateScratchDataSizeInBytes = 0;
+};
+
+struct TriangleGeometryDesc {
+  Buffer *VertexBuffer = nullptr;
+  uint64_t VertexBufferOffset = 0;
+  uint32_t VertexCount = 0;
+  uint32_t VertexStride = 0;
+  Format VertexFormat = Format::RGB32Float;
+  Buffer *IndexBuffer = nullptr;
+  uint64_t IndexBufferOffset = 0;
+  uint32_t IndexCount = 0;
+  IndexFormat IdxFormat = IndexFormat::Uint32;
+  bool Opaque = true;
+};
+
+struct AABBGeometryDesc {
+  Buffer *AABBBuffer = nullptr;
+  uint64_t AABBBufferOffset = 0;
+  uint32_t AABBCount = 0;
+  uint32_t AABBStride = 24;
+  bool Opaque = true;
+};
+
+class AccelerationStructure;
+
+struct AccelerationStructureInstance {
+  float Transform[3][4] = {{1, 0, 0, 0}, {0, 1, 0, 0}, {0, 0, 1, 0}};
+  uint32_t InstanceID = 0;
+  uint8_t InstanceMask = 0xFF;
+  AccelerationStructure *BLAS = nullptr;
+};
+
+struct BLASBuildRequest {
+  llvm::SmallVector<TriangleGeometryDesc> Triangles;
+  llvm::SmallVector<AABBGeometryDesc> AABBs;
+  AccelerationStructureBuildFlags Flags = BuildFlagNone;
+  AccelerationStructureSizes Sizes;
+};
+
+struct TLASBuildRequest {
+  llvm::SmallVector<AccelerationStructureInstance> Instances;
+  AccelerationStructureBuildFlags Flags = BuildFlagNone;
+  AccelerationStructureSizes Sizes;
+};
+
+inline llvm::Error validateTriangleGeometryDesc(const TriangleGeometryDesc &D) {
+  if (!D.VertexBuffer)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: VertexBuffer is null.");
+  if (!isPositionCompatible(D.VertexFormat))
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: VertexFormat '%s' is not position-compatible.",
+        getFormatName(D.VertexFormat).data());
+  if (D.VertexStride < getFormatSizeInBytes(D.VertexFormat))
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: VertexStride (%u) must be >= format size (%u).",
+        D.VertexStride, getFormatSizeInBytes(D.VertexFormat));
+  if (D.VertexCount == 0)
+    return llvm::createStringError(std::errc::invalid_argument,
+                                   "TriangleGeometryDesc: VertexCount is 0.");
+  if (D.IndexBuffer && D.IndexCount == 0)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: IndexBuffer is set but IndexCount is 0.");
+  if (!D.IndexBuffer && D.IndexCount != 0)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: IndexCount is set but IndexBuffer is null.");
+  if (D.IndexBuffer && D.IndexCount % 3 != 0)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: IndexCount (%u) must be a multiple of 3.",
+        D.IndexCount);
+  if (!D.IndexBuffer && D.VertexCount % 3 != 0)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TriangleGeometryDesc: VertexCount (%u) must be a multiple of 3 when "
+        "no index buffer is provided.",
+        D.VertexCount);
+  return llvm::Error::success();
+}
+
+inline llvm::Error validateAABBGeometryDesc(const AABBGeometryDesc &D) {
+  if (!D.AABBBuffer)
+    return llvm::createStringError(std::errc::invalid_argument,
+                                   "AABBGeometryDesc: AABBBuffer is null.");
+  if (D.AABBCount == 0)
+    return llvm::createStringError(std::errc::invalid_argument,
+                                   "AABBGeometryDesc: AABBCount is 0.");
+  if (D.AABBStride < 24)
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "AABBGeometryDesc: AABBStride (%u) must be >= 24.", D.AABBStride);
+  return llvm::Error::success();
+}
+
+inline llvm::Error validateBLASBuildRequest(const BLASBuildRequest &Req) {
+  if (Req.Triangles.empty() && Req.AABBs.empty())
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "BLASBuildRequest: Must have at least one geometry descriptor.");
+  // Vulkan and Metal forbid mixing triangle and AABB geometry in a single BLAS;
+  // D3D12 technically permits it but is uncommon. Reject for portability.
+  if (!Req.Triangles.empty() && !Req.AABBs.empty())
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "BLASBuildRequest: Cannot mix triangle and AABB geometry in a "
+        "single BLAS.");
+  for (const auto &T : Req.Triangles)
+    if (auto Err = validateTriangleGeometryDesc(T))
+      return Err;
+  for (const auto &A : Req.AABBs)
+    if (auto Err = validateAABBGeometryDesc(A))
+      return Err;
+  return llvm::Error::success();
+}
+
+inline llvm::Error validateTLASBuildRequest(const TLASBuildRequest &Req) {
+  if (Req.Instances.empty())
+    return llvm::createStringError(
+        std::errc::invalid_argument,
+        "TLASBuildRequest: Must have at least one instance.");
+  for (size_t I = 0; I < Req.Instances.size(); ++I)
+    if (!Req.Instances[I].BLAS)
+      return llvm::createStringError(
+          std::errc::invalid_argument,
+          "TLASBuildRequest: Instance %zu has a null BLAS pointer.", I);
+  return llvm::Error::success();
+}
+
+class AccelerationStructure {
+  GPUAPI API;
+
+public:
+  virtual ~AccelerationStructure();
+  AccelerationStructure(const AccelerationStructure &) = delete;
+  AccelerationStructure &operator=(const AccelerationStructure &) = delete;
+
+  GPUAPI getAPI() const { return API; }
+
+protected:
+  explicit AccelerationStructure(GPUAPI API) : API(API) {}
+};
+
+} // namespace offloadtest
+
+namespace llvm {
+LLVM_DECLARE_ENUM_AS_BITMASK(::offloadtest::AccelerationStructureBuildFlags,
+                             ::offloadtest::PreferFastBuild);
+} // namespace llvm
+
+#endif // OFFLOADTEST_API_ACCELERATIONSTRUCTURE_H

include/API/Device.h

@@ -15,6 +15,7 @@
 #include "Config.h"
 
 #include "API/API.h"
+#include "API/AccelerationStructure.h"
 #include "API/Buffer.h"
 #include "API/Capabilities.h"
 #include "API/CommandBuffer.h"
@@ -226,6 +227,21 @@ class Device {
   virtual llvm::Expected<std::unique_ptr<CommandBuffer>>
   createCommandBuffer() = 0;
 
+  virtual llvm::Expected<BLASBuildRequest> createBLASBuildRequest(
+      llvm::ArrayRef<TriangleGeometryDesc> Triangles,
+      llvm::ArrayRef<AABBGeometryDesc> AABBs,
+      AccelerationStructureBuildFlags Flags = BuildFlagNone) = 0;
+
+  virtual llvm::Expected<TLASBuildRequest> createTLASBuildRequest(
+      llvm::ArrayRef<AccelerationStructureInstance> Instances,
+      AccelerationStructureBuildFlags Flags = BuildFlagNone) = 0;
+
+  virtual llvm::Expected<std::unique_ptr<AccelerationStructure>>
+  createAccelerationStructure(const BLASBuildRequest &Request) = 0;
+
+  virtual llvm::Expected<std::unique_ptr<AccelerationStructure>>
+  createAccelerationStructure(const TLASBuildRequest &Request) = 0;
+
   virtual ~Device() = 0;
 
   llvm::StringRef getDescription() const { return Description; }

include/API/Texture.h

@@ -26,6 +26,7 @@
 #include <variant>
 
 namespace offloadtest {
+LLVM_ENABLE_BITMASK_ENUMS_IN_NAMESPACE();
 
 enum TextureUsage : uint32_t {
   Sampled = 1 << 0,

lib/API/DX/DXResources.h

@@ -84,6 +84,16 @@ inline D3D12_RESOURCE_FLAGS getDXResourceFlags(TextureUsage Usage) {
   return Flags;
 }
 
+inline DXGI_FORMAT getDXGIIndexFormat(IndexFormat Fmt) {
+  switch (Fmt) {
+  case IndexFormat::Uint16:
+    return DXGI_FORMAT_R16_UINT;
+  case IndexFormat::Uint32:
+    return DXGI_FORMAT_R32_UINT;
+  }
+  llvm_unreachable("All IndexFormat cases handled");
+}
+
 } // namespace offloadtest
 
 #endif // OFFLOADTEST_API_DXRESOURCES_H