From faa2e4040629ccc7180b00d54d04cafa644023d2 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 25 Apr 2025 14:19:04 -0400
Subject: [PATCH] gpu: Warn about Direct3D 12 texture alignment requirements.
Fixes #12835.
---
include/SDL3/SDL_gpu.h | 6 ++++++
src/gpu/d3d12/SDL_gpu_d3d12.c | 11 ++++++++++-
2 files changed, 16 insertions(+), 1 deletion(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 6bcfd76276316..faefb8cfceef6 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -1347,6 +1347,12 @@ typedef struct SDL_GPUViewport
* SDL_DownloadFromGPUTexture are used as default values respectively and data
* is considered to be tightly packed.
*
+ * **WARNING**: Direct3D 12 requires texture data row pitch to be 256 byte
+ * aligned, and offsets to be aligned to 512 bytes. If they are not, SDL will
+ * make a temporary copy of the data that is properly aligned, but this adds
+ * overhead to the transfer process. Apps can avoid this by aligning their
+ * data appropriately, or using a different GPU backend than Direct3D 12.
+ *
* \since This struct is available since SDL 3.2.0.
*
* \sa SDL_UploadToGPUTexture
diff --git a/src/gpu/d3d12/SDL_gpu_d3d12.c b/src/gpu/d3d12/SDL_gpu_d3d12.c
index c869d64e06487..c06593874a7ab 100644
--- a/src/gpu/d3d12/SDL_gpu_d3d12.c
+++ b/src/gpu/d3d12/SDL_gpu_d3d12.c
@@ -5934,6 +5934,10 @@ static void D3D12_UploadToTexture(
D3D12_INTERNAL_ReleaseBuffer(
d3d12CommandBuffer->renderer,
temporaryBuffer);
+
+ if (d3d12CommandBuffer->renderer->debug_mode) {
+ SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "Texture upload row pitch not aligned to 256 bytes! This is suboptimal on D3D12!");
+ }
} else if (needsPlacementCopy) {
temporaryBuffer = D3D12_INTERNAL_CreateBuffer(
d3d12CommandBuffer->renderer,
@@ -5971,7 +5975,9 @@ static void D3D12_UploadToTexture(
d3d12CommandBuffer->renderer,
temporaryBuffer);
- SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "Texture upload offset not aligned to 512 bytes! This is suboptimal on D3D12!");
+ if (d3d12CommandBuffer->renderer->debug_mode) {
+ SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "Texture upload offset not aligned to 512 bytes! This is suboptimal on D3D12!");
+ }
} else {
sourceLocation.pResource = transferBufferContainer->activeBuffer->handle;
sourceLocation.PlacedFootprint.Offset = source->offset;
@@ -6242,6 +6248,9 @@ static void D3D12_DownloadFromTexture(
destinationLocation.pResource = textureDownload->temporaryBuffer->handle;
destinationLocation.PlacedFootprint.Offset = 0;
+ if (d3d12CommandBuffer->renderer->debug_mode) {
+ SDL_LogWarn(SDL_LOG_CATEGORY_GPU, "Texture pitch or offset not aligned properly! This is suboptimal on D3D12!");
+ }
} else {
destinationLocation.pResource = destinationBuffer->handle;
destinationLocation.PlacedFootprint.Offset = destination->offset;