Class GorgonConstantBuffer

A buffer for constant shader data.

Inheritance
object
GorgonGraphicsResource
GorgonBufferCommon
GorgonConstantBuffer
Implements
Inherited Members
Namespace: Gorgon.Graphics.Core
Assembly: Gorgon.Graphics.Core.dll
Syntax
public sealed class GorgonConstantBuffer : GorgonBufferCommon, IGorgonGraphicsObject, IGorgonNativeResource, IDisposable, IGorgonConstantBufferInfo, IGorgonNamedObject
Remarks

To send changing data to a shader from you application to a constant buffer, an application can upload a value type (or primitive) value to the buffer using one of the SetData<T>(ReadOnlySpan<T>, int, CopyMode) methods. This allows an application to update the state of a shader to reflect changes in the application. Things like animation or setup information can easily be sent to modify the state of a shader (hence somewhat making the term constant a bit of a misnomer).

A constant buffer must be a minimum of 16 bytes in size (4 float values), and be aligned to 16 bytes. The maximum size of the buffer is limited to 134,217,728 elements (one element = 4x 32 bit float values). However, the GPU can only address 4096 (64K) of these elements at a time. As such the buffer will have to be bound to the GPU using a range defined by a GorgonConstantBufferView.

If the IGorgonConstantBufferInfo SizeInBytes value is less than 16 bytes, or is not aligned to 16 bytes, it will be adjusted before buffer creation to ensure the buffer is adequate.

Constant buffers are bound to a finite number of slots in the shader. Typically these are declared as follows: 

cbuffer ViewMatrix : register(b0)
{
   Vector3 viewMatrix;
   Vector3 other;
}
This binds a matrix used for the view to constant buffer slot 0. Note that the register slot name starts with a b.

For example, to update a view matrix to shift to the right every frame: 

Vector3 _lastPosition;
GorgonConstantBuffer _viewMatrixBuffer;		// This is created elsewhere with a size of 64 bytes to hold a Matrix.

void IdleMethod()
{
// Move 2 units to the right every second.
_lastPosition = new Vector3(_lastPosition.X + 2 * GorgonTiming.Delta, 0, -2.0f);
Matrix viewMatrix = Matrix.Identity;


// Adjust the matrix to perform the translation.
// We use ref/out here for better performance.
Matrix.Translation(ref _lastPosition, out viewMatrix);

// Send to the shader (typically, this would be the vertex shader).
_viewMatrixBuffer.SetData<Matrix>(ref viewMatrix);

// Send again to the shader, but this time, at the fourth float value index.
// This would skip the first 4 float values in viewMatrix, and write into
// the remaining 60 float values, and the first 4 float values in "other".
_viewMatrixBuffer.SetData<Matrix>(ref viewMatrix, 4 * sizeof(float));



}

Constructors

| Edit this page View Source

GorgonConstantBuffer(GorgonGraphics, GorgonConstantBufferInfo, ReadOnlySpan<byte>)

Initializes a new instance of the GorgonConstantBuffer class.

Declaration
public GorgonConstantBuffer(GorgonGraphics graphics, GorgonConstantBufferInfo info, ReadOnlySpan<byte> initialData = default)
Parameters
Type Name Description
GorgonGraphics graphics

The GorgonGraphics object used to create and manipulate the buffer.
GorgonConstantBufferInfo info

Information used to create the buffer.
ReadOnlySpan<byte> initialData

[Optional] The initial data used to populate the buffer.
Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, or info parameters are null.
GorgonException

Thrown when the size of the constant buffer exceeds the maximum constant buffer size. See MaxConstantBufferSize to determine the maximum size of a constant buffer.
See Also

Properties

| Edit this page View Source

IsCpuReadable

Property to return whether or not the user has requested that the buffer be readable from the CPU.

Declaration
public override bool IsCpuReadable { get; }
Property Value
Type Description
bool
Overrides
See Also
| Edit this page View Source

Name

Property to return the name of this object.

Declaration
public override string Name { get; }
Property Value
Type Description
string
Overrides
See Also
| Edit this page View Source

SizeInBytes

Property to return the size, in bytes, of the resource.

Declaration
public override int SizeInBytes { get; }
Property Value
Type Description
int
Overrides
See Also
| Edit this page View Source

TotalConstantCount

Property to return the number of 4 component floating point values (16 bytes) that can be stored in this buffer.

Declaration
public int TotalConstantCount { get; }
Property Value
Type Description
int
See Also
| Edit this page View Source

Usage

Property to return the usage for the resource.

Declaration
public override ResourceUsage Usage { get; }
Property Value
Type Description
ResourceUsage
Overrides
See Also

Methods

| Edit this page View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public override void Dispose()
Overrides
Remarks

Objects that override this method should be sure to call this base method or else a memory leak may occur.

See Also
| Edit this page View Source

GetStaging()

Function to retrieve a copy of this buffer as a staging resource.

Declaration
public GorgonConstantBuffer GetStaging()
Returns
Type Description
GorgonConstantBuffer

The staging buffer to retrieve.
See Also
| Edit this page View Source

GetStagingInternal()

Function to retrieve a copy of this buffer as a staging resource.

Declaration
protected override GorgonBufferCommon GetStagingInternal()
Returns
Type Description
GorgonBufferCommon

The staging buffer to retrieve.
Overrides
See Also
| Edit this page View Source

GetView(int, int)

Function to retrieve a view of the constant buffer elements to pass to a shader.

Declaration
public GorgonConstantBufferView GetView(int firstElement = 0, int elementCount = 0)
Parameters
Type Name Description
int firstElement

[Optional] The index of the first element in the buffer to view.
int elementCount

[Optional] The number of elements to view.
Returns
Type Description
GorgonConstantBufferView

A new GorgonConstantBufferView used to map a portion of a constant buffer to a shader.
Remarks

This will create a view of the buffer so that a shader can access a portion (or all, if the buffer is less than or equal to 4096 constants in size) of a constant buffer. Shaders can only access up to 4096 constants in a constant buffer, and this allows us to bind and use a much larger buffer to the shader while still respecting the maximum constant accessibility.

A single constant buffer constant is a float4 value (4 floating point values, or 16 bytes).

The firstElement parameter must be between 0 and the total element count (minus one) of the buffer. If it is not it will be constrained to those values to ensure there is no out of bounds access to the buffer.

If the elementCount parameter is omitted (or less than 1), then the remainder of the buffer is mapped to the view up to 256 elements (4096 constants, or 65536 bytes). If it is provided, then the number of elements will be mapped to the view, up to a maximum of 256 elements. If the value exceeds 256, then it will be constrained to 256.

important

Due to the nature of constant buffers on GPU hardware, these views are not aligned to a constant (which is a float4, or 16 bytes), but rather aligned to 16 constants (16 float4 values, or 256 bytes). This requires that your buffer be set up to be a multiple of 256 bytes in its SizeInBytes. This makes each element in the view the same as 16 float4 values (or 256 bytes). That means when an offset of 2, and a count of 4 is set in the view, it is actually at an offset of 32 float4 values (512 bytes), and covers a range of 64 float4 values (1024 bytes). Because of this, care should be taken to ensure the buffer matches this alignment if constant buffer offsets/counts are to be used in your application.

If no offsetting into the buffer is required, then the above information is not applicable and the method can be called with its default parameters (i.e. no parameters).

See Also

Implements

Extension Methods

See Also