Class GorgonConstantBufferView

A view for a GorgonConstantBuffer.

Inheritance
object
GorgonConstantBufferView
Implements
Inherited Members
Namespace: Gorgon.Graphics.Core
Assembly: Gorgon.Graphics.Core.dll
Syntax
public sealed class GorgonConstantBufferView : IGorgonGraphicsObject, IGorgonConstantBufferInfo, IGorgonNamedObject, IDisposable, IEquatable<GorgonConstantBufferView>
Remarks

This type of view will allow applications to access a GorgonConstantBuffer that may be larger than the 4096 constant limit. This is performed by offering a "window" into the constant buffer data that can be used to tell a shader which portion of the buffer to access at any given time.

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.

Properties

| Edit this page View Source

Buffer

Property to return the buffer associated with this view.

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

ConstantSize

Property to return the size of a single float4 constant in the buffer, in bytes.

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

ElementCount

Property to return the number of elements to view.

Declaration
public int ElementCount { get; }
Property Value
Type Description
int
Remarks

An element refers to a group fo 16 constants (where a constant is a single float4, or 16 bytes). If the element count is set to 4, then the view will cover 1024 bytes (or 64 constants).

See Also
| Edit this page View Source

ElementSize

Property to return the size of a single element in the buffer, in bytes.

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

Graphics

Property to return the graphics interface that built this object.

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

SizeInBytes

Property to return the number of bytes to allocate for the buffer.

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

StartElement

Property to return the index of the first element in the buffer to view.

Declaration
public int StartElement { get; }
Property Value
Type Description
int
Remarks

An element refers to a group fo 16 constants (where a constant is a single float4, or 16 bytes). If the start element is set to 2, then the offset in the buffer will be 512 bytes (or 32 constants).

See Also
| Edit this page View Source

TotalConstantCount

Property to return the total number of constants in the buffer.

Declaration
public int TotalConstantCount { get; }
Property Value
Type Description
int
Remarks

A constant is a single float4 value (16 bytes).

See Also
| Edit this page View Source

TotalElementCount

Property to return the total number of elements in the buffer.

Declaration
public int TotalElementCount { get; }
Property Value
Type Description
int

An element is equal to 16 constants, or 256 bytes.
See Also
| Edit this page View Source

Usage

Property to return the intended usage flags for this texture.

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

Methods

| Edit this page View Source

AdjustView(int, int)

Function to change the view element range in the associated constant buffer.

Declaration
public void AdjustView(int firstElement, int elementCount = 0)
Parameters
Type Name Description
int firstElement

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

[Optional] The number of constants to view.
Remarks

This will adjust the StartElement, and ElementCount to allow an application to change the area in the buffer being viewed by a shader. This allows applications to move the range of viewed constants around on demand.

The firstElement parameter must be between 0 and TotalElementCount - 1. 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.

See Also
| Edit this page View Source

CreateConstantBuffer(GorgonGraphics, GorgonConstantBufferInfo, int, int)

Function to create a constant buffer and an associated view.

Declaration
public static GorgonConstantBufferView CreateConstantBuffer(GorgonGraphics graphics, GorgonConstantBufferInfo info, int startConstant = 0, int constantCount = 0)
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface to use when creating the target.
GorgonConstantBufferInfo info

The information about the texture.
int startConstant

[Optional] The index of the first constant within the buffer to view.
int constantCount

[Optional] The number of constants in the buffer to view.
Returns
Type Description
GorgonConstantBufferView

A new GorgonConstantBufferView.
Remarks

This is a convenience method that will create a GorgonConstantBuffer and a GorgonConstantBufferView as a single object that can be used to pass constant information to a shader.

Since the GorgonConstantBuffer created by this method is linked to the GorgonConstantBufferView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonConstantBufferView from the GetView(int, int) method on the GorgonConstantBuffer, then it's assumed the user knows what they are doing and will handle the disposal of the buffer and view on their own.

If provided, the startConstant parameter must be between 0 and the total number of constants in 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 constantCount parameter is omitted (or equal to or less than 0), then the remainder of the buffer is mapped to the view up to 4096 constants. If it is provided, then the number of constants will be mapped to the view, up to a maximum of 4096 constants. If the value exceeds 4096, then it will be constrained to 4096.

A constant buffer constant is a single float4 value (4 floating point values).

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, or info parameter is null.
See Also
| Edit this page View Source

CreateConstantBuffer<T>(GorgonGraphics, ReadOnlySpan<T>, string, ResourceUsage, int, int)

Function to create a constant buffer and an associated view, initialized with the specified set of values.

Declaration
public static GorgonConstantBufferView CreateConstantBuffer<T>(GorgonGraphics graphics, ReadOnlySpan<T> value, string name = null, ResourceUsage usage = ResourceUsage.Default, int firstElement = 0, int elementCount = 0) where T : unmanaged
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface to use when creating the target.
ReadOnlySpan<T> value

The array of values to store in the buffer.
string name

[Optional] The name of the buffer.
ResourceUsage usage

[Optional] The intended usage of the buffer.
int firstElement

[Optional] The index of the first constant within the buffer to view.
int elementCount

[Optional] The number of constants in the buffer to view.
Returns
Type Description
GorgonConstantBufferView

A new GorgonConstantBufferView.
Type Parameters
Name Description
T

The type of data to store in the buffer. Must be an unmanaged value type.
Remarks

This is a convenience method that will create a GorgonConstantBuffer and a GorgonConstantBufferView as a single object that can be used to pass constant information to a shader. The buffer created will match the size of the type specified by T (adjusted to the nearest 16 bytes), multiplied by the length of the array and it will also upload the value array specified into the buffer.

Since the GorgonConstantBuffer created by this method is linked to the GorgonConstantBufferView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonConstantBufferView from the GetView(int, int) method on the GorgonConstantBuffer, then it's assumed the user knows what they are doing and will handle the disposal of the buffer and view on their own.

The firstElement parameter must be between 0 and TotalElementCount - 1. 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.

The usage parameter defines where the GPU should place the resource for best performance.

A constant buffer constant is a single float4 value (4 floating point values).

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics parameter is null.
See Also
| Edit this page View Source

CreateConstantBuffer<T>(GorgonGraphics, in T, string, ResourceUsage, int, int)

Function to create a constant buffer and an associated view, initialized with the specified value.

Declaration
public static GorgonConstantBufferView CreateConstantBuffer<T>(GorgonGraphics graphics, in T value, string name = null, ResourceUsage usage = ResourceUsage.Default, int firstElement = 0, int elementCount = 0) where T : unmanaged
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface to use when creating the target.
T value

The value to store in the buffer.
string name

[Optional] The name of the buffer.
ResourceUsage usage

[Optional] The intended usage of the buffer.
int firstElement

[Optional] The index of the first constant within the buffer to view.
int elementCount

[Optional] The number of constants in the buffer to view.
Returns
Type Description
GorgonConstantBufferView

A new GorgonConstantBufferView.
Type Parameters
Name Description
T

The type of data to store in the buffer. Must be an unmanaged value type.
Remarks

This is a convenience method that will create a GorgonConstantBuffer and a GorgonConstantBufferView as a single object that can be used to pass constant information to a shader. The buffer created will match the size of the type specified by T (adjusted to the nearest 16 bytes) and it will also upload the value specified into the buffer.

Since the GorgonConstantBuffer created by this method is linked to the GorgonConstantBufferView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonConstantBufferView from the GetView(int, int) method on the GorgonConstantBuffer, then it's assumed the user knows what they are doing and will handle the disposal of the buffer and view on their own.

The firstElement parameter must be between 0 and TotalElementCount - 1. 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.

The usage parameter defines where the GPU should place the resource for best performance.

A constant buffer constant is a single float4 value (4 floating point values).

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics parameter is null.
See Also
| Edit this page View Source

Dispose()

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

Declaration
public void Dispose()
See Also
| Edit this page View Source

Equals(GorgonConstantBufferView)

Indicates whether the current object is equal to another object of the same type.

Declaration
public bool Equals(GorgonConstantBufferView other)
Parameters
Type Name Description
GorgonConstantBufferView other

An object to compare with this object.
Returns
Type Description
bool

true if the current object is equal to the other parameter; otherwise, false.
See Also

Implements

Extension Methods

See Also