From 91cffbec09fae46d4bb0952a0066fcf7cf32e68c Mon Sep 17 00:00:00 2001
From: Sergio Pedri <sergio0694@live.com>
Date: Sat, 1 Jul 2023 21:44:25 +0200
Subject: [PATCH] Add docs on COM interfaces over AllocationServices

---
 .../Graphics/Interop/AllocationServices.cs    | 52 ++++++++++++++++++-
 1 file changed, 50 insertions(+), 2 deletions(-)

diff --git a/src/ComputeSharp/Graphics/Interop/AllocationServices.cs b/src/ComputeSharp/Graphics/Interop/AllocationServices.cs
index 4e1d3b6f0..a926644c5 100644
--- a/src/ComputeSharp/Graphics/Interop/AllocationServices.cs
+++ b/src/ComputeSharp/Graphics/Interop/AllocationServices.cs
@@ -9,7 +9,55 @@ namespace ComputeSharp.Interop;
 /// <summary>
 /// Provides methods to configure the global allocator factory instance that will be used by all <see cref="GraphicsDevice"/> objects.
 /// </summary>
-public static unsafe class AllocationServices
+/// <remarks>
+/// <para>
+/// By default, all resources will be created as committed resources. The <see cref="AllocationServices"/> APIs make it possible to change
+/// this behavior, and instead use a pluggable memory allocator implementing any desired custom logic to manage how resources are created.
+/// </para>
+/// <para>
+/// Memory allocators are created through a factory object that can be configured via <see cref="ConfigureAllocatorFactory"/>. This object
+/// needs to implement the <c>ID3D12MemoryAllocatorFactory</c> COM interface, which has the following definition:
+/// <code>
+/// [uuid(CC1E74A7-786D-40F4-8AE2-F8B7A255587E)]
+/// interface ID3D12MemoryAllocatorFactory : IUnknown
+/// {
+///     HRESULT CreateAllocator(
+///         [in] const ID3D12Device* device,
+///         [in] const IDXGIAdapter* adapter,
+///         [out] ID3D12MemoryAllocator allocator);
+/// };
+/// </code>
+/// </para>
+/// <para>
+/// This is a simple, possibly stateless factory, responsible for creating per-device memory allocators. Those use the following interface:
+/// <code>
+/// [uuid(2D5E55D2-9244-431F-868E-0D90AAB6E575)]
+/// interface ID3D12MemoryAllocator : IUnknown
+/// {
+///     HRESULT AllocateResource(
+///         [in] const D3D12_RESOURCE_DESC* resourceDescription,
+///         const D3D12_HEAP_TYPE heapType,
+///         const D3D12_RESOURCE_STATES resourceState,
+///         const BOOL clearAllocation,
+///         [out] ID3D12Allocation** allocation);
+/// };
+/// </code>
+/// </para>
+/// <para>
+/// Finally, each returned allocation object wraps a given native resource, and uses the following interface:
+/// <code>
+/// [uuid(D42D5782-2DE7-4539-A817-482E3AA01E2E)]
+/// interface ID3D12Allocation : IUnknown
+/// {
+///     HRESULT GetD3D12Resource([out] ID3D12Resource** resource);
+/// };
+/// </code>
+/// </para>
+/// <para>
+/// The implementation of these types can be done in any language, as long as the COM interfaces defined above are correctly supported.
+/// </para>
+/// </remarks>
+public static class AllocationServices
 {
     /// <summary>
     /// Configures the global <c>ID3D12MemoryAllocatorFactory</c> instance to use for the current process.
@@ -20,7 +68,7 @@ public static unsafe class AllocationServices
     /// <remarks>
     /// The allocatory factory can only be configured once, and before any <see cref="GraphicsDevice"/> instance has been created.
     /// </remarks>
-    public static void ConfigureAllocatorFactory(ICustomQueryInterface allocatorFactory)
+    public static unsafe void ConfigureAllocatorFactory(ICustomQueryInterface allocatorFactory)
     {
         default(ArgumentNullException).ThrowIfNull(allocatorFactory);