Ui::Monitor::Buffer Namespace Reference

Detailed Description

Reading the elements of a raw buffer as floats: what the bytes are, how many components an element has, and where the elements are. Nothing of this travels with a GPU buffer, the user says it.

The gather pass of the buffer view: a compute shader copies the elements a view reads, wherever they are in the buffer, one after the other into a staging buffer, and that alone is read back. What it reads back is the size of the elements, not of the bytes between them.

In an overview it also measures every element of the window: the extent of each component and how many are not finite, at the head of the staging buffer.

This holds what the CPU computes for it, and the same arithmetic as the shader, which the tests check it against.

Classes
struct	GatherParams
	The uniforms of the gather shader, as std140 lays them out. More...
class	GatherPass
struct	GatherPlan
	What a gather pass reads and where its result goes. More...
struct	GatherRange
	What the header of a staging buffer says of the elements measured. More...
struct	Layout
struct	Sampling
	Which elements of a buffer a view reads. More...

Enumerations
enum class	ElementType : int {   Float , Half , Int , UInt ,   UNorm8 , UInt8 }
enum class	Fallback : uint8_t {   None , NoCompute , NotStorage , TooLarge ,   Failed }
	Why a buffer is read back as one range instead of through the gather pass.

Functions
constexpr int	componentBytes (ElementType t) noexcept
constexpr int	components (const Layout &l) noexcept
constexpr int64_t	elementBytes (const Layout &l) noexcept
	Bytes one element covers.
constexpr int64_t	strideOf (const Layout &l) noexcept
constexpr int64_t	elementCount (const Layout &l, int64_t bytes) noexcept
	Whole elements in bytes bytes, the first at the layout's offset.
constexpr Sampling	sampleElements (int64_t available, int64_t first, int64_t max_elements, int64_t element_bytes, int64_t cap_bytes, bool overview) noexcept
constexpr int64_t	contiguousFit (int64_t stride, int64_t element_bytes, int64_t misalign, int64_t cap_bytes) noexcept
constexpr bool	integral (ElementType t) noexcept
	Whether the values are integers, to print them as such.
float	halfToFloat (uint16_t h) noexcept
	IEEE 754 binary16 to binary32, subnormals, infinities and NaN included.
float	readComponent (ElementType t, const unsigned char *p) noexcept
	One component at p, which needs no alignment.
int64_t	decode (const Layout &l, std::span< const unsigned char > bytes, std::span< float > out) noexcept
constexpr int64_t	gatherReadable (int64_t buffer_bytes) noexcept
constexpr GatherPlan	planGather (const Layout &l, int64_t origin, int64_t buffer_bytes, const Sampling &s, bool reduce, int64_t max_bind, int max_groups_per_dim) noexcept
constexpr uint32_t	gatherBytesAt (std::span< const uint32_t > words, uint32_t b, uint32_t n) noexcept
constexpr uint32_t	gatherWord (const GatherParams &g, std::span< const uint32_t > words, uint32_t w) noexcept
	The word w of the elements the shader writes. The shader's gathered.
constexpr uint32_t	orderedFloat (float f) noexcept
	A float as an unsigned integer in the same order, for atomic min and max.
constexpr float	unorderedFloat (uint32_t u) noexcept
GatherRange	readGatherHeader (std::span< const uint32_t > header, int components) noexcept

Variables
constexpr int64_t	max_readback_bytes = int64_t(16) << 20
	Bytes one readback holds at most, whatever the layout and the controls.
constexpr int64_t	max_view_elements = int64_t(1) << 20
	Elements a view reads at most.
constexpr int	gather_header_words = 16
constexpr int64_t	gather_header_bytes = gather_header_words * 4
constexpr int	gather_local_size = 256
constexpr int64_t	gather_max_groups = 4096
constexpr int64_t	gather_max_reduce
	Elements one pass can measure: an invocation's index never wraps.
constexpr int64_t	gather_bind_alignment = 256

Enumeration Type Documentation

ElementType

enum class Ui::Monitor::Buffer::ElementType : int

strong

Enumerator
UNorm8	0 to 255 read as 0 to 1

Function Documentation

contiguousFit()

constexpr int64_t Ui::Monitor::Buffer::contiguousFit ( int64_t  stride, int64_t  element_bytes, int64_t  misalign, int64_t  cap_bytes  )

constexprnoexcept

Elements, stride bytes apart, that one contiguous read of at most cap_bytes holds when it starts on a 4-byte boundary misalign bytes before the first and ends on one too.

decode()

int64_t Ui::Monitor::Buffer::decode ( const Layout &  l, std::span< const unsigned char >  bytes, std::span< float >  out  )

inlinenoexcept

The elements of bytes, the first at the layout's offset, into out: the components of each element one after the other. Decodes as many elements as both hold, and returns how many.

gatherBytesAt()

constexpr uint32_t Ui::Monitor::Buffer::gatherBytesAt ( std::span< const uint32_t >  words, uint32_t  b, uint32_t  n  )

constexprnoexcept

The n bytes (1 to 4) at byte b of words, little endian; a word past the end reads as 0. The shader's bytesAt.

gatherReadable()

constexpr int64_t Ui::Monitor::Buffer::gatherReadable ( int64_t  buffer_bytes )

constexprnoexcept

Bytes of a buffer of buffer_bytes the shader can read: it reads words, and the bytes of a last word cut short are past the end of its array

planGather()

constexpr GatherPlan Ui::Monitor::Buffer::planGather ( const Layout &  l, int64_t  origin, int64_t  buffer_bytes, const Sampling &  s, bool  reduce, int64_t  max_bind, int  max_groups_per_dim  )

constexprnoexcept

The gather pass of the sampled elements s of a buffer of buffer_bytes bytes, element 0 at byte origin. With reduce, it also measures every element of the window. Not valid when the range it reads is larger than max_bind bytes, past the 32 bit offsets of the shader or past what the shader can read of the buffer.

sampleElements()

constexpr Sampling Ui::Monitor::Buffer::sampleElements ( int64_t  available, int64_t  first, int64_t  max_elements, int64_t  element_bytes, int64_t  cap_bytes, bool  overview  )

constexprnoexcept

The elements to read of available, from first: as many as max_elements and cap_bytes allow. With overview, a window holding more than that is read at an even step over its whole length instead of from its start.

Variable Documentation

gather_bind_alignment

constexpr int64_t Ui::Monitor::Buffer::gather_bind_alignment = 256

inlineconstexpr

Alignment of the start of the bound range: the largest storage buffer offset alignment of the backends

gather_header_words

constexpr int Ui::Monitor::Buffer::gather_header_words = 16

inlineconstexpr

Words before the elements in the staging buffer: the minimum of each component, their maximum, then the count of values not finite

gather_max_groups

constexpr int64_t Ui::Monitor::Buffer::gather_max_groups = 4096

inlineconstexpr

Workgroups of a dispatch at most: each invocation goes over as many words and elements as it takes

gather_max_reduce

constexpr int64_t Ui::Monitor::Buffer::gather_max_reduce

inlineconstexpr

Initial value:

= int64_t(std::numeric_limits<uint32_t>::max())
      - gather_max_groups * gather_local_size

Elements one pass can measure: an invocation's index never wraps.