VulkanResourceState.h File Reference

donner::gpu::vulkan::VulkanResourceState - the tracked per-texture synchronization state the Vulkan backend derives its barriers from. More...

#include <vulkan/vulkan.h>
#include <cstdint>
#include <map>
#include <ostream>
#include <span>
#include "donner/gpu/Descriptors.h"

Include dependency graph for VulkanResourceState.h:

Classes
struct	donner::gpu::vulkan::TextureSyncState
	The synchronization state a texture is left in, as the backend's bookkeeping records it. More...
struct	donner::gpu::vulkan::ImageBarrierParams
	The six values an image barrier is built from, plus whether precision was available. More...
struct	donner::gpu::vulkan::SubpassDependencyParams
	The two halves of a render pass external subpass dependency. More...
class	donner::gpu::vulkan::TextureSyncStateTable
	Tracked state for a set of textures, under the discipline the backend records against. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Enumerations
enum class	donner::gpu::vulkan::TextureUsageKind : uint8_t {   Undefined ,   ColorAttachment ,   SampledRead ,   StorageWrite ,   TransferRead ,   TransferWrite }
	What a texture is being used for at one point of a recorded command stream. More...

Functions
std::ostream &	donner::gpu::vulkan::operator<< (std::ostream &os, TextureUsageKind value)
	Ostream output operator.
std::ostream &	donner::gpu::vulkan::operator<< (std::ostream &os, const TextureSyncState &value)
	Ostream output operator.
std::ostream &	donner::gpu::vulkan::operator<< (std::ostream &os, const ImageBarrierParams &value)
	Ostream output operator.
std::ostream &	donner::gpu::vulkan::operator<< (std::ostream &os, const SubpassDependencyParams &value)
	Ostream output operator.
ImageBarrierParams	donner::gpu::vulkan::ConservativeImageBarrier (VkImageLayout oldLayout, VkImageLayout newLayout)
	The maximal barrier: ALL_COMMANDS to ALL_COMMANDS with memory availability and visibility.
VkImageLayout	donner::gpu::vulkan::LayoutForUsage (TextureUsageKind usage)
	The image layout a usage requires.
TextureSyncState	donner::gpu::vulkan::StateAfterUsage (TextureUsageKind usage)
	The state a texture is left in once usage has executed against it.
ImageBarrierParams	donner::gpu::vulkan::TransitionFor (const TextureSyncState &current, TextureUsageKind usage)
	The barrier that takes a texture from current to usage.
SubpassDependencyParams	donner::gpu::vulkan::AttachmentEntryDependency (std::span< const TextureSyncState > attachmentStates)
	The external dependency into a render pass, ordering whatever touched the attachments before it against the pass's color output.
SubpassDependencyParams	donner::gpu::vulkan::AttachmentExitDependency (TextureUsage declaredUsage)
	The external dependency out of a render pass, ordering the pass's color output against whatever the attachment's declared usage says can consume it next.

Detailed Description

donner::gpu::vulkan::VulkanResourceState - the tracked per-texture synchronization state the Vulkan backend derives its barriers from.

Every barrier this backend records, and every render pass external dependency it declares, is derived here from one table so the two cannot disagree. A precise image barrier sitting behind a render pass dependency that still says ALL_COMMANDS buys nothing: the dependency is the edge that orders an attachment write against whatever reads it next, so both halves read from the same source of truth.

This is pure state machinery over Vulkan enums: it opens no device, calls no entry point, and records nothing. That keeps it testable on every platform the project builds on, rather than only where a Vulkan loader exists.

The tracked patterns are the ones the recorded command streams actually produce. Anything outside them resolves to ConservativeImageBarrier, which is the maximal ALL_COMMANDS/memory barrier this backend used everywhere before: unknown usage costs precision, never correctness.

Enumeration Type Documentation

TextureUsageKind

enum class donner::gpu::vulkan::TextureUsageKind : uint8_t

strong

What a texture is being used for at one point of a recorded command stream.

Write-only storage textures are the only writable binding the runtime declares, so a storage usage is unambiguously a write and needs no read/write fallback. If a writable storage BUFFER binding kind ever enters the runtime, this enum and the table below must gain the host-visibility edge that goes with it, because every buffer this backend allocates is host-mapped and a kernel write to one would otherwise be invisible to the mapping.

Enumerator
Undefined	Never used; contents undefined.
ColorAttachment	Written as a render pass color attachment.
SampledRead	Read through a sampled-texture binding.
StorageWrite	Written through a write-only storage-texture binding.
TransferRead	Read as the source of a copy.
TransferWrite	Written as the destination of a copy or an upload.

Function Documentation

AttachmentEntryDependency()

SubpassDependencyParams donner::gpu::vulkan::AttachmentEntryDependency ( std::span< const TextureSyncState > attachmentStates )

nodiscard

The external dependency into a render pass, ordering whatever touched the attachments before it against the pass's color output.

One edge covers every attachment, so the source scope is the union across all of them: a pass that loads one attachment a compute dispatch wrote and clears another must still wait for that write, and taking any single attachment's prior state would lose it. A pass with no attachments, or one whose attachment reached its layout through a path the model does not describe, falls back to the maximal edge.

Parameters

attachmentStates

State each attachment texture is tracked in, in any order.

AttachmentExitDependency()

SubpassDependencyParams donner::gpu::vulkan::AttachmentExitDependency ( TextureUsage declaredUsage )

nodiscard

The external dependency out of a render pass, ordering the pass's color output against whatever the attachment's declared usage says can consume it next.

The consumer is read from the texture's declared usage set rather than by scanning ahead: a texture declared Sampled gets the shader-read edge, one declared CopySrc the transfer-read edge, and one declaring several gets their union. A usage set naming no tracked consumer falls back to the maximal edge.

Parameters

declaredUsage

Usage flags the attachment texture was created with.

ConservativeImageBarrier()

ImageBarrierParams donner::gpu::vulkan::ConservativeImageBarrier ( VkImageLayout oldLayout, VkImageLayout newLayout )

nodiscard

The maximal barrier: ALL_COMMANDS to ALL_COMMANDS with memory availability and visibility.

The fallback for any usage pair the table does not name. VK_ACCESS_MEMORY_* is valid with any pipeline stage, so this is always legal, and it orders strictly more than any precise barrier would - which is why an unrecognised pattern degrades to it rather than to nothing.

Parameters

oldLayout	Layout the image is in.
newLayout	Layout the image moves to.

LayoutForUsage()

VkImageLayout donner::gpu::vulkan::LayoutForUsage ( TextureUsageKind usage )

nodiscard

The image layout a usage requires.

Parameters

usage

Usage the texture is put to.

operator<<() [1/4]

std::ostream & donner::gpu::vulkan::operator<<	(	std::ostream &	os,
		const ImageBarrierParams &	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

operator<<() [2/4]

std::ostream & donner::gpu::vulkan::operator<<	(	std::ostream &	os,
		const SubpassDependencyParams &	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

operator<<() [3/4]

std::ostream & donner::gpu::vulkan::operator<<	(	std::ostream &	os,
		const TextureSyncState &	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

operator<<() [4/4]

std::ostream & donner::gpu::vulkan::operator<<	(	std::ostream &	os,
		TextureUsageKind	value )

Ostream output operator.

Parameters

os	Output stream.
value	Value to output.

StateAfterUsage()

TextureSyncState donner::gpu::vulkan::StateAfterUsage ( TextureUsageKind usage )

nodiscard

The state a texture is left in once usage has executed against it.

Parameters

usage

Usage the texture is put to.

TransitionFor()

ImageBarrierParams donner::gpu::vulkan::TransitionFor ( const TextureSyncState & current, TextureUsageKind usage )

nodiscard

The barrier that takes a texture from current to usage.

The source scope comes from what last touched the image and the destination scope from what is about to, so the tracked patterns - attachment write to sampled read, storage write to sampled read, transfer write to shader read, and their transfer counterparts - name the stages and accesses actually involved instead of every stage and every access.

Parameters

current	State the texture is tracked in.
usage	Usage the texture is about to be put to.