xiiMeshBufferResourceDescriptor Struct Reference

Descriptor for creating an xiiMeshBufferResource, containing all necessary information and data to initialize a mesh buffer resource, including vertex stream layout, vertex and index data, meshlet data, and resource usage flags. More...

#include <MeshBufferResource.h>

Public Member Functions
xiiArrayPtr< xiiUInt8 >	GetVertexData ()
	Returns the vertex data for this mesh buffer resource descriptor, used to access the raw vertex data that will be uploaded to the GPU for rendering this mesh. The returned array pointer contains the vertex data in a tightly packed format based on the vertex stream layout and formats specified in this descriptor, and can be used for direct memory copying to GPU buffers or for CPU-side processing of the vertex data before uploading it to the GPU.
xiiArrayPtr< const xiiUInt8 >	GetVertexData () const
	Returns the vertex data for this mesh buffer resource descriptor, used to access the raw vertex data that will be uploaded to the GPU for rendering this mesh. The returned array pointer contains the vertex data in a tightly packed format based on the vertex stream layout and formats specified in this descriptor, and can be used for direct memory copying to GPU buffers or for CPU-side processing of the vertex data before uploading it to the GPU.
xiiArrayPtr< xiiUInt8 >	GetIndexData ()
	Returns the index data for this mesh buffer resource descriptor, used to access the raw index data that will be uploaded to the GPU for rendering this mesh. The returned array pointer contains the index data in a tightly packed format based on the index format specified in this descriptor, and can be used for direct memory copying to GPU buffers or for CPU-side processing of the index data before uploading it to the GPU.
xiiArrayPtr< const xiiUInt8 >	GetIndexData () const
	Returns the index data for this mesh buffer resource descriptor, used to access the raw index data that will be uploaded to the GPU for rendering this mesh. The returned array pointer contains the index data in a tightly packed format based on the index format specified in this descriptor, and can be used for direct memory copying to GPU buffers or for CPU-side processing of the index data before uploading it to the GPU.
xiiUInt32	GetVertexCount () const
	Returns the vertex count for this mesh buffer resource descriptor, used to identify the number of vertices in this mesh and to calculate the required memory size for the vertex data based on the vertex stream layout and formats specified in this descriptor. The vertex count is typically determined by the number of unique vertices in the geometry data used to create this mesh buffer resource descriptor.
xiiUInt32	GetIndexCount () const
	Returns the index count for this mesh buffer resource descriptor, used to identify the number of indices in this mesh and to calculate the required memory size for the index data based on the index format specified in this descriptor. The index count is typically determined by the number of primitives (triangles, lines, etc.) in the geometry data used to create this mesh buffer resource descriptor, multiplied by the number of vertices per primitive (e.g., 3 for triangles).
xiiUInt32	GetPrimitiveCount () const
	Returns the primitive count for this mesh buffer resource descriptor, used to identify the number of primitives (triangles, lines, etc.) in this mesh and to calculate the required memory size for the index data based on the index format specified in this descriptor. The primitive count is typically determined by the number of primitives in the geometry data used to create this mesh buffer resource descriptor.
xiiUInt32	GetVertexDataSize () const
	Returns the vertex data size for this mesh buffer resource descriptor, used to identify the total memory size of the vertex data for this mesh based on the vertex count and the vertex stream layout and formats specified in this descriptor. The vertex data size is typically calculated as the vertex count multiplied by the vertex stride, where the vertex stride is determined by the sum of the sizes of all vertex streams in the vertex layout, taking into account any padding or alignment requirements based on the formats of the vertex streams.
xiiUInt32	GetIndexDataSize () const
	Returns the index data size for this mesh buffer resource descriptor, used to identify the total memory size of the index data for this mesh based on the index count and the index format specified in this descriptor. The index data size is typically calculated as the index count multiplied by the index stride, where the index stride is determined by the size of the index format (e.g., 2 bytes for 16-bit indices, 4 bytes for 32-bit indices).
xiiUInt32	GetVertexStride () const
	Returns the vertex stride for this mesh buffer resource descriptor, used to identify the byte stride between vertices in the vertex data based on the vertex stream layout and formats specified in this descriptor. The vertex stride is typically calculated as the sum of the sizes of all vertex streams in the vertex layout, taking into account any padding or alignment requirements based on the formats of the vertex streams.
const xiiBoundingBoxSphere &	GetBounds () const
	Returns the bounding box sphere for this mesh buffer resource descriptor, used to identify the spatial bounds of this mesh for frustum culling, collision detection, and other spatial queries during rendering. The bounding box sphere is typically calculated based on the vertex positions in the geometry data used to create this mesh buffer resource descriptor, and can be used for efficient culling and intersection tests during rendering.
	xiiMeshBufferResourceDescriptor ()
	Default constructor.
void	Clear ()
	Clears all data from this descriptor, resetting it to an empty state.
void	AddStream (xiiEnum< xiiMeshVertexSemantic > semantic, xiiEnum< xiiMeshVertexStreamFormat > format, xiiUInt16 uiOffset, xiiUInt16 uiStride)
void	AddCommonStreams ()
	Adds a set of common vertex streams (position, normal, tangent, texcoord0, texcoord1, color0, bone indices, bone weights) to this mesh buffer resource descriptor with standard formats and offsets for use with the provided geometry.
void	AllocateStreams (xiiUInt32 uiVertexCount, xiiUInt32 uiPrimitiveCount, bool bUse32BitIndices=true)
void	AllocateStreamsFromGeometry (const xiiGeometry &geometry, xiiEnum< xiiGALPrimitiveTopology > topology, bool bBuildMeshlets=true)
void	SetVertexData (xiiArrayPtr< const xiiUInt8 > pData, xiiUInt32 uiVertexCount, xiiUInt32 uiVertexStride)
void	SetIndexData (xiiArrayPtr< const xiiUInt8 > pData, xiiUInt32 uiIndexCount, xiiEnum< xiiGALValueType > indexType)
xiiResult	BuildMeshlets (xiiUInt32 uiMaxVertices=64U, xiiUInt32 uiMaxPrimitives=124U)
xiiResult	BuildMeshlets (xiiArrayPtr< const xiiMeshletBuildRange > ranges, xiiUInt32 uiMaxVertices=64U, xiiUInt32 uiMaxPrimitives=124U)
void	ComputeBounds ()
	Computes the bounding box sphere for this mesh buffer resource descriptor based on the vertex positions in the vertex data and the vertex stream layout specified in this descriptor. The bounding box sphere is typically calculated by iterating through the vertex positions in the vertex data, applying any necessary transformations based on the vertex stream layout, and computing the minimum enclosing sphere that contains all the vertex positions. This bounding box sphere can then be used for efficient frustum culling, collision detection, and other spatial queries during rendering.
void	SetBounds (const xiiBoundingBoxSphere &bounds)
xiiResult	Serialize (xiiStreamWriter &inout_stream) const
xiiResult	Deserialize (xiiStreamReader &inout_stream)

Public Attributes
xiiEnum< xiiGALPrimitiveTopology >	m_Topology = xiiGALPrimitiveTopology::TriangleList
	The primitive topology for this mesh, used to identify how the primitives in this mesh are defined and rendered (e.g., triangle list, triangle strip, line list, etc.) and may influence how the vertex and index data is organized in memory for optimal rendering performance.
xiiEnum< xiiGALValueType >	m_IndexType = xiiGALValueType::UInt32
	The data format of the index data for this mesh, used to identify how the index data is organized and interpreted by the renderer (e.g., 16-bit unsigned integer or 32-bit unsigned integer) and to calculate the expected index data size based on the index count and index stride for this descriptor.
xiiEnum< xiiGALResourceUsage >	m_ResourceUsage = xiiGALResourceUsage::Immutable
	The resource usage pattern for this mesh buffer resource, used to identify how the vertex and index data will be used and updated during rendering (e.g., immutable, dynamic, staging, etc.) and to optimize the memory allocation and access patterns for the GPU based on the expected usage of this mesh.
bool	m_bKeepCpuMeshData = false
	Whether to keep a copy of the vertex and index data in CPU memory after uploading it to the GPU, which can be useful for CPU-side processing, collision detection, or other operations that require access to the mesh data on the CPU, but may increase memory usage. If true, a copy of the vertex and index data will be retained in CPU memory after uploading it to the GPU. If false, the vertex and index data will be released from CPU memory after uploading it to the GPU to reduce memory usage.
bool	m_bAllowGpuDrivenDraw = true
	Whether to allow GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering for this mesh, which can improve rendering performance by reducing draw calls and enabling more efficient culling, but may require additional GPU resources and may not be supported on all hardware. If true, this mesh buffer resource can be used with GPU-driven rendering techniques if the hardware supports it. If false, this mesh buffer resource will not be used with GPU-driven rendering techniques and will fall back to traditional vertex and index buffer rendering.
bool	m_bAllowCpuFallback = true
	Whether to allow CPU-based rendering fallback for this mesh, which can be useful for compatibility with older hardware or for debugging purposes, but may reduce rendering performance compared to GPU-driven rendering techniques. If true, this mesh buffer resource can be rendered using CPU-based rendering techniques if GPU-driven rendering is not available or not allowed. If false, this mesh buffer resource will not be rendered using CPU-based rendering techniques and may require GPU-driven rendering techniques to be enabled for rendering.
xiiDynamicArray< xiiMeshVertexStream >	m_VertexStreams
	The vertex stream layout for this mesh, used to identify the semantic meaning, data format, byte offset, and stride for each vertex stream in the vertex data, which is essential for correctly interpreting the vertex data and for configuring the vertex input layout for rendering this mesh.
xiiDynamicArray< xiiUInt8 >	m_VertexData
	The raw vertex data for this mesh, formatted according to the vertex stream layout specified in m_VertexStreams. This data is typically tightly packed based on the vertex stream layout, with each vertex's data organized according to the specified offsets and strides for each vertex stream. This vertex data will be uploaded to the GPU for rendering this mesh, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the mesh data on the CPU.
xiiDynamicArray< xiiUInt8 >	m_IndexData
	The raw index data for this mesh, formatted according to the index format specified in m_IndexType. This data is typically tightly packed based on the index format, with each index represented as either a 16-bit unsigned integer or a 32-bit unsigned integer depending on the index format specified in m_IndexType. This index data will be uploaded to the GPU for rendering this mesh, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the mesh data on the CPU.
xiiDynamicArray< xiiMeshlet, xiiAlignedAllocatorWrapper >	m_Meshlets
	The meshlet data for this mesh, used for GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering to enable more efficient culling and draw call batching. Each meshlet contains information about the primitives and vertices it contains, as well as its bounding sphere and normal cone for culling purposes. The meshlet data will be uploaded to the GPU for use in rendering this mesh with GPU-driven techniques, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the meshlet data on the CPU.
xiiDynamicArray< xiiUInt32 >	m_MeshletVertexRemap
	The vertex remapping data for the meshlets in this mesh, used to remap the vertex indices for each meshlet to a compact set of unique vertices that are referenced by the primitives in that meshlet. This data is essential for GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering, where each meshlet may reference a different subset of vertices for optimal culling and rendering performance. The vertex remapping data will be uploaded to the GPU for use in rendering this mesh with GPU-driven techniques, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the vertex remapping data on the CPU.
xiiDynamicArray< xiiUInt8 >	m_MeshletPrimitiveIndices
	The primitive index data for the meshlets in this mesh, used to identify the primitives (triangles, lines, etc.) that belong to each meshlet for rendering and culling purposes in GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering. This data is essential for GPU-driven rendering techniques, where each meshlet may reference a different subset of primitives for optimal culling and rendering performance. The primitive index data will be uploaded to the GPU for use in rendering this mesh with GPU-driven techniques, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the primitive index data on the CPU.
xiiDynamicArray< xiiUInt32 >	m_MeshletMaterialIndices
	The material index data for the meshlets in this mesh, used to identify the material that should be applied to each meshlet during rendering in GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering. This data is essential for GPU-driven rendering techniques, where each meshlet may reference a different material for optimal rendering performance. The material index data will be uploaded to the GPU for use in rendering this mesh with GPU-driven techniques, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the material index data on the CPU.
xiiDynamicArray< xiiMeshDrawCommand >	m_DrawCommands
	The draw command data for this mesh, used for GPU-driven rendering techniques such as mesh shaders or compute shader-based rendering to specify the number of thread groups to dispatch for rendering this mesh. Each draw command contains information about the thread group counts in the X, Y, and Z dimensions, which are essential for configuring the dispatch parameters for rendering this mesh with GPU-driven techniques. The draw command data will be uploaded to the GPU for use in rendering this mesh with GPU-driven techniques, and can also be retained in CPU memory if m_bKeepCpuMeshData is true for CPU-side processing or other operations that require access to the draw command data on the CPU.

Detailed Description

Descriptor for creating an xiiMeshBufferResource, containing all necessary information and data to initialize a mesh buffer resource, including vertex stream layout, vertex and index data, meshlet data, and resource usage flags.

Member Function Documentation

AddStream()

void xiiMeshBufferResourceDescriptor::AddStream	(	xiiEnum< xiiMeshVertexSemantic >	semantic,
		xiiEnum< xiiMeshVertexStreamFormat >	format,
		xiiUInt16	uiOffset,
		xiiUInt16	uiStride )

Adds a vertex stream to this mesh buffer resource descriptor with the specified semantic, format, byte offset, and stride.

Parameters

semantic	The semantic meaning of the vertex stream, used to identify how the renderer should interpret the data in this stream.
format	The data format of the vertex stream, used to identify the type and layout of the vertex data for correct interpretation by the renderer.
uiOffset	The byte offset of this vertex stream from the start of the vertex, used to calculate the memory address of this stream's data for each vertex.
uiStride	The byte stride between vertices for this vertex stream, used to calculate the memory address of this stream's data for each vertex when vertices are tightly packed or interleaved.

AllocateStreams()

void xiiMeshBufferResourceDescriptor::AllocateStreams	(	xiiUInt32	uiVertexCount,
		xiiUInt32	uiPrimitiveCount,
		bool	bUse32BitIndices = true )

Allocates memory for the vertex and index data in this mesh buffer resource descriptor based on the specified vertex count, primitive count, and index format.

Parameters

uiVertexCount	The number of vertices in the mesh, used to calculate the required memory size for the vertex data based on the vertex stream layout and formats.
uiPrimitiveCount	The number of primitives in the mesh, used to calculate the required memory size for the index data based on the index format.
bUse32BitIndices	Whether to use 32-bit unsigned integers for the index data, which allows for more than 65535 vertices but increases memory usage. If false, 16-bit unsigned integers will be used, which limits the maximum vertex count to 65535 but reduces memory usage.

AllocateStreamsFromGeometry()

void xiiMeshBufferResourceDescriptor::AllocateStreamsFromGeometry	(	const xiiGeometry &	geometry,
		xiiEnum< xiiGALPrimitiveTopology >	topology,
		bool	bBuildMeshlets = true )

Allocates memory for the vertex and index data in this mesh buffer resource descriptor based on the provided geometry, including vertex count, primitive count, and index format inferred from the geometry data.

Parameters

geometry	The geometry data used to determine the vertex count, primitive count, and index format for allocating the vertex and index streams in this mesh buffer resource descriptor. The vertex count is typically determined by the number of unique vertices in the geometry, while the primitive count is determined by the number of primitives (triangles, lines, etc.) in the geometry. The index format is determined based on whether the vertex count exceeds 65535, which would require 32-bit indices instead of 16-bit indices.
topology	The primitive topology of the geometry, used to determine how the primitives are defined and rendered (e.g., triangle list, triangle strip, line list, etc.) and may influence how the vertex and index data is organized in memory for optimal rendering performance.
bBuildMeshlets	Whether to build meshlets for this geometry, which can improve rendering performance by allowing for more efficient culling and draw call batching, but may increase memory usage and build time. If true, meshlets will be built based on the geometry data and included in this mesh buffer resource descriptor. If false, no meshlets will be built and the mesh will be rendered using traditional vertex and index buffers without meshlet-based culling or batching optimizations.

BuildMeshlets() [1/2]

xiiResult xiiMeshBufferResourceDescriptor::BuildMeshlets	(	xiiArrayPtr< const xiiMeshletBuildRange >	ranges,
		xiiUInt32	uiMaxVertices = 64U,
		xiiUInt32	uiMaxPrimitives = 124U )

Builds independent clusters for the supplied ranges, preserving material, section and LOD metadata. Reads vertices once and reuses scratch storage between ranges. Invalid topology, layout, indices, positions or ranges return failure and clear all generated meshlet data. Source geometry is unchanged. An empty range list succeeds with empty output. Limits are clamped to the native meshlet limits.

BuildMeshlets() [2/2]

xiiResult xiiMeshBufferResourceDescriptor::BuildMeshlets	(	xiiUInt32	uiMaxVertices = 64U,
		xiiUInt32	uiMaxPrimitives = 124U )

Builds meshlets for this mesh buffer resource descriptor based on the vertex and index data, vertex stream layout, and specified maximum vertices and primitives per meshlet. Meshlets are small clusters of geometry that can be efficiently culled and rendered by modern GPU pipelines, improving rendering performance by reducing draw calls and enabling more efficient culling. The meshlet building process typically involves clustering the geometry into meshlets based on spatial locality and other heuristics, and generating the necessary data for each meshlet such as vertex remapping, primitive indices, and material indices.

Parameters

uiMaxVertices

The maximum number of unique vertices allowed in each meshlet, used to control the size of the meshlets and to ensure that the vertex remapping data for each meshlet can fit within the specified limits for efficient GPU processing. A common value for this parameter is 64, which allows for efficient GPU processing while still providing good culling granularity.

uiMaxPrimitives

The maximum number of primitives (triangles, lines, etc.) allowed in each meshlet, used to control the size of the meshlets and to ensure that the primitive index data for each meshlet can fit within the specified limits for efficient GPU processing. A common value for this parameter is 124, which allows for efficient GPU processing while still providing good culling granularity. The specific values for these parameters may need to be adjusted based on the target hardware capabilities and the complexity of the geometry being processed to achieve optimal rendering performance.

SetBounds()

void xiiMeshBufferResourceDescriptor::SetBounds

(

const xiiBoundingBoxSphere &

bounds

)

Sets the bounding box sphere for this mesh buffer resource descriptor, allowing for manual specification of the spatial bounds of this mesh. This can be useful in cases where the bounding box sphere has been precomputed or optimized based on specific requirements, or when the vertex data is not available for computing the bounds directly. The provided bounding box sphere should encompass all the vertex positions in the geometry represented by this mesh buffer resource descriptor to ensure correct culling and spatial queries during rendering.

Parameters

bounds

The bounding box sphere to be set for this mesh buffer resource descriptor, used to identify the spatial bounds of this mesh for frustum culling, collision detection, and other spatial queries during rendering. The bounding box sphere should be defined in object space and should encompass all the vertex positions in the geometry represented by this mesh buffer resource descriptor to ensure correct culling and spatial queries during rendering.

SetIndexData()

void xiiMeshBufferResourceDescriptor::SetIndexData	(	xiiArrayPtr< const xiiUInt8 >	pData,
		xiiUInt32	uiIndexCount,
		xiiEnum< xiiGALValueType >	indexType )

Sets the vertex and index data for this mesh buffer resource descriptor, copying the provided data into the internal storage of this descriptor and updating the vertex count, index count, and vertex stride based on the provided data and the vertex stream layout and formats specified in this descriptor.

Parameters

pData	The raw index data to be copied into this mesh buffer resource descriptor, formatted according to the index format specified in this descriptor. The data should be tightly packed based on the index format, with each index represented as either a 16-bit unsigned integer or a 32-bit unsigned integer depending on the index format specified in this descriptor. The size of the data should match the expected index data size based on the index count and index stride for this descriptor.
uiIndexCount	The number of indices represented by the provided index data, used to update the index count for this mesh buffer resource descriptor and to validate that the size of the provided index data matches the expected index data size based on the index count and index stride for this descriptor.
indexType	The data format of the index data, used to validate that the index data is organized according to the index format specified in this descriptor, and to calculate the expected index data size based on the index count and index stride for this descriptor. The index type should match the expected index format specified in this descriptor (e.g., 16-bit unsigned integer or 32-bit unsigned integer) to ensure correct interpretation of the index data by the renderer.

SetVertexData()

void xiiMeshBufferResourceDescriptor::SetVertexData	(	xiiArrayPtr< const xiiUInt8 >	pData,
		xiiUInt32	uiVertexCount,
		xiiUInt32	uiVertexStride )

Sets the vertex and index data for this mesh buffer resource descriptor, copying the provided data into the internal storage of this descriptor and updating the vertex count, index count, and vertex stride based on the provided data and the vertex stream layout and formats specified in this descriptor.

Parameters

pData	The raw vertex data to be copied into this mesh buffer resource descriptor, formatted according to the vertex stream layout and formats specified in this descriptor. The data should be tightly packed based on the vertex stream layout, with each vertex's data organized according to the specified offsets and strides for each vertex stream. The size of the data should match the expected vertex data size based on the vertex count and vertex stride for this descriptor.
uiVertexCount	The number of vertices represented by the provided vertex data, used to update the vertex count for this mesh buffer resource descriptor and to validate that the size of the provided vertex data matches the expected vertex data size based on the vertex count and vertex stride for this descriptor.
uiVertexStride	The byte stride between vertices in the provided vertex data, used to validate that the vertex data is organized according to the vertex stream layout and formats specified in this descriptor, and to calculate the expected vertex data size based on the vertex count and vertex stride for this descriptor. The vertex stride should match the expected vertex stride calculated from the vertex stream layout and formats specified in this descriptor to ensure correct interpretation of the vertex data by the renderer.

---

The documentation for this struct was generated from the following files:

• /home/runner/work/XII/XII/Source/Engine/GraphicsCore/Meshes/MeshBufferResource.h
• /home/runner/work/XII/XII/Source/Engine/GraphicsCore/Meshes/Implementation/MeshBufferResource.cpp
• /home/runner/work/XII/XII/Source/Engine/GraphicsCore/Meshes/Implementation/MeshletBuilder.cpp