/// <summary>
/// Function to create a constant buffer and an associated view, initialized with the specified set of values.
/// </summary>
/// <typeparam name="T">The type of data to store in the buffer. Must be an unmanaged value type.</typeparam>
/// <param name="graphics">The graphics interface to use when creating the target.</param>
/// <param name="value">The array of values to store in the buffer.</param>
/// <param name="name">[Optional] The name of the buffer.</param>
/// <param name="usage">[Optional] The intended usage of the buffer.</param>
/// <param name="firstElement">[Optional] The index of the first constant within the buffer to view.</param>
/// <param name="elementCount">[Optional] The number of constants in the buffer to view.</param>
/// <returns>A new <see cref="GorgonConstantBufferView"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="graphics"/> parameter is <b>null</b>.</exception>
/// <remarks>
/// <para>
/// This is a convenience method that will create a <see cref="GorgonConstantBuffer"/> and a <see cref="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 <typeparamref name="T"/> (adjusted to the nearest 16 bytes), multiplied by the length of the array and it will also
/// upload the <paramref name="value"/> array specified into the buffer.
/// </para>
/// <para>
/// Since the <see cref="GorgonConstantBuffer"/> created by this method is linked to the <see cref="GorgonConstantBufferView"/> returned, disposal of either one will dispose of the other on your
/// behalf. If the user created a <see cref="GorgonConstantBufferView"/> from the <see cref="GorgonConstantBuffer.GetView"/> method on the <see cref="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.
/// </para>
/// <para>
/// The <paramref name="firstElement"/> parameter must be between 0 and <seealso cref="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.
/// </para>
/// <para>
/// If the <paramref name="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.
/// </para>
/// <para>
/// The <paramref name="usage"/> parameter defines where the GPU should place the resource for best performance.
/// </para>
/// <para>
/// A constant buffer constant is a single float4 value (4 floating point values).
/// </para>
/// </remarks>
/// <seealso cref="GorgonConstantBuffer"/>
public static GorgonConstantBufferView CreateConstantBuffer <T>(GorgonGraphics graphics, T[] value, string name = null, ResourceUsage usage = ResourceUsage.Default, int firstElement = 0, int elementCount = 0)
where T : unmanaged
{
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (value == null)
{
throw new ArgumentNullException(nameof(value));
}
var buffer = new GorgonConstantBuffer(graphics, new GorgonConstantBufferInfo(name)
{
Usage = usage,
SizeInBytes = Unsafe.SizeOf <T>() * value.Length
});
buffer.SetData(value);
GorgonConstantBufferView view = buffer.GetView(firstElement, elementCount);
view._ownsBuffer = true;
return(view);
}
/// <summary>
/// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
/// </summary>
public void Dispose()
{
if (!_ownsBuffer)
{
return;
}
GorgonConstantBuffer buffer = Interlocked.Exchange(ref _buffer, null);
buffer?.Dispose();
_ownsBuffer = false;
}
/// <summary>
/// Function to retrieve a copy of this buffer as a staging resource.
/// </summary>
/// <returns>The staging buffer to retrieve.</returns>
public GorgonConstantBuffer GetStaging()
{
var buffer = new GorgonConstantBuffer(Graphics,
new GorgonConstantBufferInfo(_info, $"{Name}_Staging")
{
Usage = ResourceUsage.Staging
});
CopyTo(buffer);
return(buffer);
}
/// <summary>
/// Function to find the index of the resource in the array.
/// </summary>
/// <param name="resource">The resource to look up.</param>
/// <returns>The index, if found. -1 if not.</returns>
internal int IndexOf(GorgonGraphicsResource resource)
{
(int start, int count) = GetDirtyItems(true);
for (int i = 0; i < count; ++i)
{
GorgonConstantBuffer buffer = BackingArray[i + start]?.Buffer;
if (buffer == resource)
{
return(i + start);
}
}
return(-1);
}
/// <summary>
/// Function to create a constant buffer and an associated view.
/// </summary>
/// <param name="graphics">The graphics interface to use when creating the target.</param>
/// <param name="info">The information about the texture.</param>
/// <param name="startConstant">[Optional] The index of the first constant within the buffer to view.</param>
/// <param name="constantCount">[Optional] The number of constants in the buffer to view.</param>
/// <returns>A new <see cref="GorgonConstantBufferView"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="graphics"/>, or <paramref name="info"/> parameter is <b>null</b>.</exception>
/// <remarks>
/// <para>
/// This is a convenience method that will create a <see cref="GorgonConstantBuffer"/> and a <see cref="GorgonConstantBufferView"/> as a single object that can be used to pass constant information
/// to a shader.
/// </para>
/// <para>
/// Since the <see cref="GorgonConstantBuffer"/> created by this method is linked to the <see cref="GorgonConstantBufferView"/> returned, disposal of either one will dispose of the other on your
/// behalf. If the user created a <see cref="GorgonConstantBufferView"/> from the <see cref="GorgonConstantBuffer.GetView"/> method on the <see cref="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.
/// </para>
/// <para>
/// If provided, the <paramref name="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.
/// </para>
/// <para>
/// If the <paramref name="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.
/// </para>
/// <para>
/// A constant buffer constant is a single float4 value (4 floating point values).
/// </para>
/// </remarks>
/// <seealso cref="GorgonConstantBuffer"/>
public static GorgonConstantBufferView CreateConstantBuffer(GorgonGraphics graphics, IGorgonConstantBufferInfo info, int startConstant = 0, int constantCount = 0)
{
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (info == null)
{
throw new ArgumentNullException(nameof(info));
}
var buffer = new GorgonConstantBuffer(graphics, info);
GorgonConstantBufferView view = buffer.GetView(startConstant, constantCount);
view._ownsBuffer = true;
return(view);
}
