Class GorgonVertexBuffer

A buffer for holding vertex data.

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

To send vertices to the GPU using a vertex buffer, an application can upload vertices, represented as a value type, to the buffer using one of the SetData<T>(ReadOnlySpan<T>, int, CopyMode) overloads. For best performance, it is recommended to upload vertex data only once, or rarely. However, in some scenarios, and with the correct Usage flag, vertex animation is possible by uploading data to a Dynamic vertex buffer.

To use a vertex buffer with the GPU pipeline, one must create a GorgonVertexBufferBinding to inform the GPU on how to use the vertex buffer.

Examples

For example, to send a list of vertices to a vertex buffer:

// Our vertex, with a position and color component.
[StructLayout(LayoutKind = LayoutKind.Sequential)] 
struct MyVertex
{
	public Vector4 Position;
	public Vector4 Color;
}

GorgonGraphics graphics;
MyVertex[] _vertices = new MyVertex[100];
GorgonVertexBuffer _vertexBuffer;

void InitializeVertexBuffer()
{
	_vertices = ... // Fill your vertex array here.

	// Create the vertex buffer large enough so that it'll hold 100 vertices.
	_vertexBuffer = new GorgonVertexBuffer(graphics, GorgonVertexBufferInfo.CreateFromType<MyVertex>(_vertices.Length, Usage.Default));

	// Copy our data to the vertex buffer.
    _vertexBuffer.SetData<MyVertex>(_vertices);

	// Copy our data to the vertex buffer, using the 5th index in the vertex array, and 25 vertices.
    _vertexBuffer.SetData<MyVertex>(_vertices, 5, 25);

	// Copy our data to the vertex buffer, using the 5th index in the vertex array, 25 vertices, and storing at index 2 in the vertex buffer.
    _vertexBuffer.SetData<MyVertex>(_vertices, 5, 25, 2);

    // Copy our data to the vertex buffer, using the 5th index in the native buffer, 25 vertices, and storing at index 2 in the vertex buffer, using a copy mode.
    _vertexBuffer.SetData(vertices, 5, 25, 2, CopyMode.NoOverWrite);

    // Copy our data from a GorgonNativeBuffer.
    using (GorgonNativeBuffer<MyVertex> vertices = new GorgonNativeBuffer<MyVertex>(100))
    {
       // Copy vertices into the native buffer here....

       // Copy everything.
       _vertexBuffer.SetData(vertices);

       // Copy our data to the vertex buffer, using the 5th index in the native buffer, 25 vertices, and storing at index 2 in the vertex buffer.
       _vertexBuffer.SetData(vertices, 5, 25, 2);

       // Copy our data to the vertex buffer, using the 5th index in the native buffer, 25 vertices, and storing at index 2 in the vertex buffer, using a copy mode.
       _vertexBuffer.SetData(vertices, 5, 25, 2, CopyMode.NoOverWrite);

       // Get the data back out from the buffer, using index 5 and up to 10 vertices, storing at index 2 of the native buffer.
       _vertexBuffer.GetData<MyVertex>(vertices, 5, 10, 2); 
    }

    // Get the data back out from the buffer.
    MyVertex[] readBack = _vertexBuffer.GetData<MyVertex>();

    // Get the data back out from the buffer, starting at index 5 and a count of 10 vertices.
    readBack = _vertexBuffer.GetData<MyVertex>(5, 10);

    // Get the data back out from the buffer, using index 5 and up to 10 vertices, storing at index 2.
    _vertexBuffer.GetData<MyVertex>(readBack, 5, 10, 2);
}

Constructors

| Edit this page View Source

GorgonVertexBuffer(GorgonGraphics, GorgonVertexBufferInfo, ReadOnlySpan<byte>)

Initializes a new instance of the GorgonVertexBuffer class.

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

The GorgonGraphics object used to create and manipulate the buffer.
GorgonVertexBufferInfo 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 the info parameters are null.
See Also

Properties

| Edit this page View Source

Binding

Property to return the binding used to bind this buffer to the GPU.

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

IsCpuReadable

Property to return whether or not the buffer is directly readable by the CPU via one of the GetData<T>(Span<T>, int, int?) methods.

Declaration
public override bool IsCpuReadable { get; }
Property Value
Type Description
bool
Overrides
Remarks

Buffers must meet the following criteria in order to qualify for direct CPU read:

This will always return false for this buffer type, except when its Usage is Staging.

See Also
GetData<T>(Span<T>, int, int?)
GetData<T>(out T, int)
| 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

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

Create<T>(GorgonGraphics, GorgonVertexBufferInfo, ReadOnlySpan<T>)

Function to create a new vertex buffer that is to be filled with a known vertex type.

Declaration
public static GorgonVertexBuffer Create<T>(GorgonGraphics graphics, GorgonVertexBufferInfo info, ReadOnlySpan<T> initialData = default) where T : unmanaged
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface used to create the vertex buffer.
GorgonVertexBufferInfo info

Information about the vertex buffer.
ReadOnlySpan<T> initialData

[Optional] A read only span used to populate the vertex buffer.
Returns
Type Description
GorgonVertexBuffer

A new GorgonVertexBuffer.
Type Parameters
Name Description
T

The type of vertex data to send to the vertex buffer. Must be an unmanaged type.
Remarks

This factory method is used to create a vertex buffer using a known type of data, and, optionally, fill it with data. This avoids the need to convert the data to byte data when initializing from the constructor.

If the SizeInBytes property in the info is less than 1, then the method will create a vertex buffer that is the exact size needed to fit the initialData. If initialData is omitted and the size is less than 1, then an exception will be thrown.

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, or the info parameter is null.
ArgumentException

Thrown if the size of the data in initialData is too large for the buffer.
See Also
| Edit this page View Source

GetReadWriteView(BufferFormat, int, int)

Function to create a new GorgonVertexBufferReadWriteView for this buffer.

Declaration
public GorgonVertexBufferReadWriteView GetReadWriteView(BufferFormat format, int startElement = 0, int elementCount = 0)
Parameters
Type Name Description
BufferFormat format

The format for the view.
int startElement

[Optional] The first element to start viewing from.
int elementCount

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

A GorgonVertexBufferReadWriteView used to bind the buffer to a shader.
Remarks

This will create an unordered access view that makes a buffer accessible to shaders using unordered access to the data. This allows viewing of the buffer data in a different format, or even a subsection of the buffer from within the shader.

The format parameter is used present the buffer data as another format type to the shader.

The startElement parameter defines the starting data element to allow access to within the shader. If this value falls outside of the range of available elements, then it will be clipped to the upper and lower bounds of the element range. If this value is left at 0, then first element is viewed.

The elementCount parameter defines how many elements to allow access to inside of the view. If this value falls outside of the range of available elements, then it will be clipped to the upper or lower bounds of the element range. If this value is left at 0, then the entire buffer is viewed.

Exceptions
Type Condition
GorgonException

Thrown when this buffer does not have a Binding of UnorderedAccess.

-or-

Thrown when this buffer has a usage of Staging.
ArgumentException

Thrown when the format is typeless or is not a supported format for unordered access views.
See Also
| Edit this page View Source

GetStaging()

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

Declaration
public GorgonVertexBuffer GetStaging()
Returns
Type Description
GorgonVertexBuffer

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

GetTotalElementCount(BufferFormat)

Function to retrieve the total number of elements in a buffer.

Declaration
public int GetTotalElementCount(BufferFormat format)
Parameters
Type Name Description
BufferFormat format

The desired format for the view.
Returns
Type Description
int

The total number of elements.
Remarks

Use this to retrieve the number of elements based on the format that will be passed to a shader resource view.

See Also

Implements

Extension Methods

See Also