Texture transfer & mipmaps

Inspect the relationship#

Step from a disk file to a sampled material, compare backend staging rules, and inspect prefiltered detail.

Try these experiments#

1. Step through all seven lifecycle stages and read the state explanation after each step.
2. Scrub to a stage, press Play, and follow the transfer. Pause to inspect one owner boundary.
3. Change mip level and compare texel dimensions, meaningful row bytes, and staging row bytes.
4. Switch the backend. The lifecycle stays recognizable, while the displayed DX12 pitch and Vulkan tightly packed copy model differ.

What the illustration calculates#

The base checker is 128 × 128 RGBA8. Each mip halves its dimensions. At small levels the prefiltered image approaches the average rather than preserving detail that cannot be represented. DX12 rows are padded to the required upload RowPitch alignment. The Vulkan illustration uses a tightly packed VkBufferImageCopy case, not a universal native image-memory layout. Production resource copies use actual backend requirements. DX12 GetCopyableFootprints handles subresources and format layout. Vulkan copy descriptions use texel/block rules and explicit buffer offsets. Neither staging form is the same as a compressed PNG file.

Connect the stages to ownership#

AssetStore owns source identity and decode state. UploadManager owns staging and pending destinations. GraphicsDevice records copies, transitions, and completion. A material retains a stable handle and uses a fallback descriptor until a safe boundary publishes the ready resource.

// Destination texture: copied on this direct queue.
D3D12_RESOURCE_BARRIER b{};
b.Type = D3D12_RESOURCE_BARRIER_TYPE_TRANSITION;
b.Transition.pResource = texture;
b.Transition.StateBefore = D3D12_RESOURCE_STATE_COPY_DEST;
b.Transition.StateAfter = D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE;
b.Transition.Subresource = D3D12_RESOURCE_BARRIER_ALL_SUBRESOURCES;
list->ResourceBarrier(1, &b);

// Same-family copy → fragment sampling; one mip, one layer.
VkImageMemoryBarrier2 b{VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2};
b.srcStageMask = VK_PIPELINE_STAGE_2_TRANSFER_BIT;
b.srcAccessMask = VK_ACCESS_2_TRANSFER_WRITE_BIT;
b.dstStageMask = VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT;
b.dstAccessMask = VK_ACCESS_2_SHADER_SAMPLED_READ_BIT;
b.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
b.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
b.srcQueueFamilyIndex = b.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
b.image = image;
b.subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
VkDependencyInfo d{VK_STRUCTURE_TYPE_DEPENDENCY_INFO};
d.imageMemoryBarrierCount = 1;
d.pImageMemoryBarriers = &b;
vkCmdPipelineBarrier2(commandBuffer, &d);

What readiness means#

Creating a GPU allocation is not sufficient. Its copy must be ordered before use, its usage/layout must permit sampling, its descriptor must be populated and bound, and its lifetime must cover all readers. Staging can retire after the copy completes; the sampled texture continues living while materials and in-flight frames reference it.

What to inspect when it is wrong#

Striped rows suggest a stride/pitch error. Washed-out color suggests encoded/linear confusion. Flicker after loading suggests a binding/lifetime issue. Missing fine detail can be a deliberate streaming fallback rather than failed import. Read assets and complete DX12 texture loading. The latter contains the actual WIC decode and native copy implementation.