IrLayout.h File Reference

Host-shareable memory layout engine for donner::gpu::shader types. More...

#include <cstdint>
#include <ostream>
#include <vector>
#include "donner/gpu/shader/IrType.h"
#include "donner/gpu/shader/ShaderResult.h"

Include dependency graph for IrLayout.h:

Classes
struct	donner::gpu::shader::TypeLayout
	Alignment and size of a host-shareable type. More...
struct	donner::gpu::shader::StructMemberLayout
	Layout of one struct member. More...
struct	donner::gpu::shader::StructLayout
	Layout of a struct type: overall alignment/size plus per-member offsets in declaration order. More...
struct	donner::gpu::shader::ArrayStrideInfo
	Element stride of an array in an address space, plus whether uniform rules padded it. 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::shader::AddressSpace : uint8_t {   Uniform ,   Storage }
	Address space a host-shareable layout is computed for. More...

Functions
std::ostream &	donner::gpu::shader::operator<< (std::ostream &os, AddressSpace value)
	Ostream output operator, e.g.
ShaderResult< TypeLayout >	donner::gpu::shader::ComputeTypeLayout (const IrType &type, AddressSpace addressSpace)
	Computes alignment and size of type in addressSpace per the WGSL layout rules.
ShaderResult< uint32_t >	donner::gpu::shader::ComputeArrayStride (const IrType &arrayType, AddressSpace addressSpace)
	Computes the element stride of a sized or runtime array in addressSpace: roundUp(AlignOf(element), SizeOf(element)), rounded up to a multiple of 16 in the uniform address space.
ShaderResult< ArrayStrideInfo >	donner::gpu::shader::ComputeArrayStrideInfo (const IrType &arrayType, AddressSpace addressSpace)
	Like ComputeArrayStride, additionally reporting whether the uniform 16-byte rule raised the natural stride - the flag packet 5's emitters consult to decide whether a padded element wrapper is required.
ShaderResult< StructLayout >	donner::gpu::shader::ComputeStructLayout (const IrType &structType, AddressSpace addressSpace)
	Computes the full member layout of a struct type in addressSpace: member offsets rounded to member alignment (16-rounded for nested structs/arrays in uniform), struct alignment = max member alignment, struct size rounded up to the struct alignment.

Detailed Description

Host-shareable memory layout engine for donner::gpu::shader types.

Implements the WGSL specification's memory layout rules: scalar align/size 4/4, vec2 8/8, vec3 16/12, vec4 16/16, mat4x4f 16/64, array stride roundUp(AlignOf(elem), SizeOf(elem)), struct member offsets rounded to member alignment, struct alignment = max member alignment, struct size rounded up to the struct alignment. In the uniform address space, arrays round their element stride up to a multiple of 16, and members whose type is a struct or array round their alignment up to 16.

The C++ mirror structs the GPU runtime uploads (e.g. the Geode encoder's Uniforms/Band/ InstanceTransform) must byte-match these computed layouts; the shader tests anchor that.

Enumeration Type Documentation

AddressSpace

enum class donner::gpu::shader::AddressSpace : uint8_t

strong

Address space a host-shareable layout is computed for.

Enumerator
Uniform	Uniform buffers; extra 16-byte rounding rules apply.
Storage	(Read-only) storage buffers; base layout rules.

Function Documentation

ComputeArrayStride()

ShaderResult< uint32_t > donner::gpu::shader::ComputeArrayStride	(	const IrType &	arrayType,
		AddressSpace	addressSpace )

Computes the element stride of a sized or runtime array in addressSpace: roundUp(AlignOf(element), SizeOf(element)), rounded up to a multiple of 16 in the uniform address space.

The uniform rounding is a deliberate policy choice: WGSL validation would reject a uniform array whose natural stride is not a multiple of 16 (there is no stride attribute), so this engine defines the layout as the rounded stride and ComputeArrayStrideInfo reports when rounding occurred. Emitters must materialize padded element wrappers in that case (see ArrayStrideInfo).

Parameters

arrayType	Sized or runtime array type.
addressSpace	Address space the stride is computed for.

ComputeArrayStrideInfo()

ShaderResult< ArrayStrideInfo > donner::gpu::shader::ComputeArrayStrideInfo	(	const IrType &	arrayType,
		AddressSpace	addressSpace )

Like ComputeArrayStride, additionally reporting whether the uniform 16-byte rule raised the natural stride - the flag packet 5's emitters consult to decide whether a padded element wrapper is required.

Parameters

arrayType	Sized or runtime array type.
addressSpace	Address space the stride is computed for.

ComputeStructLayout()

ShaderResult< StructLayout > donner::gpu::shader::ComputeStructLayout	(	const IrType &	structType,
		AddressSpace	addressSpace )

Computes the full member layout of a struct type in addressSpace: member offsets rounded to member alignment (16-rounded for nested structs/arrays in uniform), struct alignment = max member alignment, struct size rounded up to the struct alignment.

Parameters

structType	Struct type to lay out.
addressSpace	Address space the layout is computed for.

ComputeTypeLayout()

ShaderResult< TypeLayout > donner::gpu::shader::ComputeTypeLayout	(	const IrType &	type,
		AddressSpace	addressSpace )

Computes alignment and size of type in addressSpace per the WGSL layout rules.

Fails closed for types with no host-shareable layout: bool (and vectors of bool), textures, samplers, and runtime arrays (which have a stride but no fixed size; use ComputeArrayStride).

Parameters

type	Type to lay out.
addressSpace	Address space the layout is computed for.

operator<<()

std::ostream & donner::gpu::shader::operator<<	(	std::ostream &	os,
		AddressSpace	value )

Ostream output operator, e.g.

uniform.

Parameters

os	Output stream.
value	Value to output.