### Shader Table Indexing Example Calculation

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12Raytracing/src/D3D12RaytracingProceduralGeometry/readme.md

Example calculation for indexing into the hit group shader table for a shadow ray hitting a second AABB geometry.

```plaintext
  1  // ~ RayContributionToHitGroupIndex                   - from TraceRay()
+ 2  // ~ MultiplierForGeometryContributionToHitGroupIndex - from TraceRay()
* 1  // ~ GeometryContributionToHitGroupIndex              - from runtime, 2nd geometry => ID:1
+ 2  // ~ InstanceContributionToHitGroupIndex              - from BLAS instance desc
```

--------------------------------

### Build Error: Cannot open include file 'windows.h'

Source: https://github.com/microsoft/directx-graphics-samples/wiki/Home

This error occurs when the project's target platform version does not match an installed SDK. Ensure the Target Platform Version in project properties points to an installed Windows 10 SDK.

```cpp
fatal error C1083: Cannot open include file: 'windows.h': No such file or directory
```

--------------------------------

### Initialize ResidencyManager with MaxLatency

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3DX12Residency/readme.md

Initializes the ResidencyManager, specifying the maximum latency to prevent the renderer from getting too far ahead of the library's worker thread. MaxLatency should be calculated based on buffered frames and command list submissions per frame.

```cpp
D3DX12Residency::ResidencyManager manager;
UINT numberOfBufferedFrames = 3;
UINT numberOfCommandListSubmissionsPerFrame = 1;
UINT maxLatency = numberOfBufferedFrames * numberOfCommandListSubmissionsPerFrame;

manager.Initialize(d3dDevice, maxLatency);
```

--------------------------------

### Get Wrapped GPU Pointer Simple

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Use this function to create a WRAPPED_GPU_POINTER for resources. The descriptor heap index points to the UAV for the resource, and GpuVA is the resource's GPU virtual address.

```cpp
UINT32 DescriptorHeapIndex, D3D12_GPU_VIRTUAL_ADDRESS GpuVA)
```

--------------------------------

### Conceptual AFR Diagram

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3DX12AffinityLayer/readme.md

Illustrates the round-robin frame rendering across multiple GPUs in an Alternate Frame Rendering (AFR) setup. GPU0 renders even frames, and GPU1 renders odd frames, aiming for theoretical double frame rates.

```text
   GPU0   |---Frame 0---|---Frame 2---|---Frame 4---|--- etc
   GPU1          |---Frame 1---|---Frame 3---|---Frame 5---|--- etc
```

--------------------------------

### Shader Record Creation for LOD Transitions

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12Raytracing/src/D3D12RaytracingRealTimeDenoisedAmbientOcclusion/readme.md

Illustrates the strategy for creating shader records to handle dynamic Level of Detail (LOD) transitions in raytracing. This approach accounts for ping-ponging between frames and different transition types (lower LOD, same LOD, higher LOD).

```cpp
// Dynamic geometry with multiple LODs is handled by creating shader records
// for all cases. Then, on geometry/instance updates, a BLAS instance updates
// its InstanceContributionToHitGroupIndex to point to the corresponding 
// shader records for that LOD.
// 
// The LOD selection can change from a frame to frame depending on distance
// to the camera. For simplicity, we assume the LOD difference from frame to frame 
// is no greater than 1. This can be false if camera moves fast, but in that case 
// temporal reprojection would fail for the most part anyway yielding diminishing returns.
// Consistency checks will prevent blending in from false geometry.
//
// Given multiple LODs and LOD delta being 1 at most, we create the records as follows:
// 2 * 3 Shader Records per LOD
// 2 - ping-pong frame to frame
// 3 - transition types
//   Transition from lower LOD in previous frame
//   Same LOD as previous frame
//   Transition from higher LOD in previous frame

```

--------------------------------

### Add Application to d3dconfig for Settings

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12StateObjectDatabase/readme.md

Add an executable to d3dconfig to apply specific settings. Ensure the correct number of dashes are used for the '--add' command.

```txt
d3dconfig.exe apps --add <exefilename>
```

--------------------------------

### Check if Raytracing Driver is Used

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Call this function to determine if the application is using the native DXR API or the compute-based path. This helps in deciding which method to use for getting wrapped pointers.

```cpp
bool ID3D12RaytracingFallbackDevice::UsingRaytracingDriver();
```

--------------------------------

### Enable Acceleration Structure Visualization

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Set this macro to 1 to visualize the acceleration structure. Ensure the Fallback Layer has a raytracing output and application shaders disable writing to it.

```c
#define ENABLE_ACCELERATION_STRUCTURE_VISUALIZATION 0
```

--------------------------------

### Get Wrapped Pointer from GPU Virtual Address

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Use this function when the native DXR API is in use (UsingRaytracingDriver() returns true). It retrieves a wrapped GPU pointer using the GPU virtual address.

```cpp
WRAPPED_GPU_POINTER ID3D12RaytracingFallbackDevice::GetWrappedPointerFromGpuVA(D3D12_GPU_VIRTUAL_ADDRESS gpuVA);
```

--------------------------------

### Root Signatures for Raytracing

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Root signatures for raytracing must be created using the fallback device's serialization and creation interfaces to allow the Fallback Layer to inject necessary bindings.

```APIDOC
## Root Signature Serialization and Creation

### Description
Root signatures used for raytracing must be created through the fallback device's interfaces to ensure proper injection of internal bindings.

### Interfaces
- `ID3D12RaytracingFallbackDevice::D3D12SerializeRootSignature`
- `ID3D12RaytracingFallbackDevice::D3D12SerializeVersionedRootSignature`
- `ID3D12RaytracingFallbackDevice::CreateRootSignature`

### Note
These interfaces are identical to their native D3D12 equivalents, but the Serialize calls require a device object.
```

--------------------------------

### Serialize and Create Root Signature for Raytracing

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Root signatures for raytracing must be created through these fallback device interfaces to allow the Fallback Layer to inject necessary bindings. These are similar to native D3D12 equivalents but require a device object for serialization.

```cpp
ID3D12RaytracingFallbackDevice::D3D12SerializeRootSignature
```

```cpp
ID3D12RaytracingFallbackDevice::D3D12SerializeVersionedRootSignature
```

```cpp
ID3D12RaytracingFallbackDevice::CreateRootSignature
```

--------------------------------

### Get Ray in AABB Primitive Local Space

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12Raytracing/src/D3D12RaytracingProceduralGeometry/readme.md

Transforms an object-space ray into the AABB primitive's local space using provided transformation matrices. This is a prerequisite for performing ray-primitive intersection tests.

```hlsl
// Get ray in AABB's local space.
Ray GetRayInAABBPrimitiveLocalSpace()
{
    PrimitiveInstancePerFrameBuffer attr = g_AABBPrimitiveAttributes[l_aabbCB.instanceIndex];
    
    // Retrieve a ray origin position and direction in bottom level AS space 
    // and transform them into the AABB primitive's local space.
    Ray ray;
    ray.origin = mul(float4(ObjectRayOrigin(), 1), attr.bottomLevelASToLocalSpace).xyz;
    ray.direction = mul(ObjectRayDirection(), (float3x3) attr.bottomLevelASToLocalSpace);
    return ray;
}
```

--------------------------------

### Get Wrapped Pointer from Descriptor Heap Index

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Use this function when the native DXR API is not in use (UsingRaytracingDriver() returns false). It retrieves a wrapped GPU pointer using a descriptor heap index and an optional offset.

```cpp
WRAPPED_GPU_POINTER ID3D12RaytracingFallbackDevice::GetWrappedPointerFromDescriptorHeapIndex(UINT32 DescriptorHeapIndex, UINT32 OffsetInBytes = 0);
```

--------------------------------

### Set State Object Database File Path

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12StateObjectDatabase/readme.md

Specify the output file path for the State Object Database. All applications matching d3dconfig settings will write to this database.

```txt
d3dconfig.exe device pso-db-path=<filepath>.sodb
```

--------------------------------

### Set Descriptor Heaps for Raytracing

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

When building raytracing acceleration structures or dispatching rays, you must bind a descriptor heap using this command list method, not the standard ID3D12GraphicsCommandList::SetDescriptorHeaps.

```cpp
ID3D12RaytracingFallbackCommandList::SetDescriptorHeaps
```

--------------------------------

### Enable State Object Database Collection

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12StateObjectDatabase/readme.md

Enable the collection of Pipeline State Objects and State Objects into the specified database. Settings are applied at device creation, so restart the application if necessary. This can be set to 'false' to temporarily stop collection.

```txt
d3dconfig.exe device enable-pso-db=true
```

--------------------------------

### Execute Command Lists with Residency Sets

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3DX12Residency/readme.md

Executes command lists while ensuring that all required heaps/committed resources are resident. This function takes the command queue, command lists, and corresponding residency sets as input.

```cpp
D3DX12Residency::ResidencyManager manager;
ID3D12CommandQueue* commandQueue;
ID3D12CommandList* commandLists[...];
D3DX12Residency::ResidencySet residencySets[...];
UINT numCommandLists = ...;

manager.ExecuteCommandLists(commandQueue, commandLists, residencySets, numCommandLists);
```

--------------------------------

### Create Global Root Signature from DXIL Library

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12Raytracing/src/D3D12RaytracingLibrarySubobjects/readme.md

Utilize the CreateRootSignature API to create a global root signature directly from the DXIL library bytecode. This is applicable when a unique global root signature is defined within the HLSL library.

```cpp
// A unique global root signature is defined in hlsl library g_pRaytracing. For such scenario we can create 
  // compute root signature can directly from the library bytecode, using CreateRootSignature API. 
  ThrowIfFailed(device->CreateRootSignature(1, g_pRaytracing, ARRAYSIZE(g_pRaytracing), IID_PPV_ARGS(&m_raytracingGlobalRootSignature)));
```

--------------------------------

### Runtime Error: DXGI_ERROR_UNSUPPORTED

Source: https://github.com/microsoft/directx-graphics-samples/wiki/Home

This error indicates that the GPU does not support DirectX 12. Samples can often be run with the WARP software rasterizer by adding '/warp' to the command line arguments in project debugging properties.

```cpp
ThrowIfFailed
```

```cpp
0x887A0004 (DXGI_ERROR_UNSUPPORTED)
```

```cpp
D3D12CreateDevice
```

```cpp
/warp
```

--------------------------------

### Distinguishing DXR API Path and Compute Path

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Use `UsingRaytracingDriver()` to determine whether to use `GetWrappedPointerFromDescriptorHeapIndex` or `GetWrappedPointerFromGpuVA`.

```APIDOC
## UsingRaytracingDriver

### Description
Checks if the system is using the raytracing driver.

### Method
```cpp
bool ID3D12RaytracingFallbackDevice::UsingRaytracingDriver();
```

## GetWrappedPointerFromDescriptorHeapIndex

### Description
Gets a wrapped pointer using a descriptor heap index. This is used when `UsingRaytracingDriver()` returns false.

### Method
```cpp
WRAPPED_GPU_POINTER ID3D12RaytracingFallbackDevice::GetWrappedPointerFromDescriptorHeapIndex(UINT32 DescriptorHeapIndex, UINT32 OffsetInBytes = 0);
```

### Pre-condition
`UsingRaytracingDriver()` must be false.

## GetWrappedPointerFromGpuVA

### Description
Gets a wrapped pointer using a GPU virtual address. This is used when `UsingRaytracingDriver()` returns true.

### Method
```cpp
WRAPPED_GPU_POINTER ID3D12RaytracingFallbackDevice::GetWrappedPointerFromGpuVA(D3D12_GPU_VIRTUAL_ADDRESS gpuVA);
```

### Pre-condition
`UsingRaytracingDriver()` must be true.
```

--------------------------------

### Track a ManagedObject with ResidencyManager

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3DX12Residency/readme.md

Begins tracking a ManagedObject with the ResidencyManager. This is a high-level step for enabling the library to manage the underlying heap or committed resource.

```cpp
D3DX12Residency::ResidencyManager manager;
D3DX12Residency::ManagedObject managedObject(...);

manager.BeginTrackingObject(managedObject);
```

--------------------------------

### D3D12 Raytracing Instance Desc for Fallback Layer

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

When generating instance descriptors on the CPU for the Fallback Layer, use this mirror class instead of D3D12_RAYTRACING_INSTANCE_DESC to ensure type safety for the Acceleration Structure member.

```cpp
D3D12_RAYTRACING_FALLBACK_INSTANCE_DESC
```

--------------------------------

### Binding Acceleration Structures

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Libraries/D3D12RaytracingFallback/developerguide.md

Acceleration structures must be bound using `ID3D12RaytracingFallbackDevice::SetTopLevelAccelerationStructure`, which uses a `SetComputeShaderResourceView`-style binding.

```APIDOC
## SetTopLevelAccelerationStructure

### Description
Binds the top-level acceleration structure for raytracing. This uses a `SetComputeShaderResourceView`-style binding.

### Method
```cpp
void ID3D12RaytracingFallbackDevice::SetTopLevelAccelerationStructure(const D3D12_CPU_DESCRIPTOR_HANDLE* pTopLevelAccelerationStructure);
```

### Limitations
This method does not support `SetComputeRootDescriptorTable`-style bindings or local root signatures.
```

--------------------------------

### Initialize Shadow Ray Payload

Source: https://github.com/microsoft/directx-graphics-samples/blob/master/Samples/Desktop/D3D12Raytracing/src/D3D12RaytracingProceduralGeometry/readme.md

Initialize the shadow ray payload with a true value, as hit shaders are skipped. The miss shader will set this to false if no geometry is hit.

```hlsl
// Initialize shadow ray payload.
// Set the initial value to true since closest and any hit shaders are skipped. 
// Shadow miss shader, if called, will set it to false.
ShadowRayPayload shadowPayload = { true };
TraceRay(g_scene,
    RAY_FLAG_CULL_BACK_FACING_TRIANGLES
    | RAY_FLAG_ACCEPT_FIRST_HIT_AND_END_SEARCH
    | RAY_FLAG_FORCE_OPAQUE             // ~skip any hit shaders
    | RAY_FLAG_SKIP_CLOSEST_HIT_SHADER, // ~skip closest hit shaders,
    ...

```