/// <summary>
/// Function to create a structured buffer and initialize it with data.
/// </summary>
/// <param name="name">The name of the structured buffer.</param>
/// <param name="settings">Settings used to create the structured buffer.</param>
/// <param name="stream">[Optional] Stream containing the data used to initialize the buffer.</param>
/// <returns>A new structured buffer.</returns>
/// <remarks>This buffer type allows structures of data to be processed by the GPU without explicit byte mapping.
/// <para>This method should only be called from an immediate graphics context, if it is called from a deferred context an exception will be thrown.</para>
/// <para>Structured buffers can only be used on SM_5 video devices.</para>
/// </remarks>
/// <exception cref="System.ArgumentException">Thrown when the <paramref name="name"/> parameter is empty.
/// <para>-or-</para>
/// <para>Thrown when the ElementSize or ElementCount properties in the <paramref name="settings"/> parameter are not greater than 0.</para>
/// </exception>
/// <exception cref="System.ArgumentNullException">Thrown when the <paramref name="name"/> parameter is NULL (Nothing in VB.Net).
/// <para>-or-</para>
/// <para>Thrown when the <paramref name="settings"/> parameter is NULL.</para>
/// </exception>
/// <exception cref="GorgonLibrary.GorgonException">Thrown when the <see cref="GorgonLibrary.Graphics.GorgonStructuredBufferSettings.StructureSize">StructureSize</see> property of the <paramref name="settings"/> parameter is less than 0 or greater than 2048.
/// <para>-or-</para>
/// <para>Thrown when the <see cref="GorgonLibrary.Graphics.GorgonStructuredBufferSettings.SizeInBytes">SizeInBytes</see> property of the <paramref name="settings"/> parameter is less than 1.</para>
/// <para>-or-</para>
/// <para>Thrown when the usage is set to immutable and the <paramref name="stream"/> parameter is NULL (Nothing in VB.Net) or has no data.</para>
/// <para>-or-</para>
/// <para>Thrown when an attempt to create a structured buffer is made on a video device that does not support SM5 or better.</para>
/// </exception>
public GorgonStructuredBuffer CreateStructuredBuffer(string name, GorgonStructuredBufferSettings settings, GorgonDataStream stream = null)
{
if (_graphics.IsDeferred)
{
throw new GorgonException(GorgonResult.CannotCreate, Resources.GORGFX_CANNOT_USE_DEFERRED_CONTEXT);
}
if (settings == null)
{
throw new ArgumentNullException("settings");
}
if (_graphics.VideoDevice.SupportedFeatureLevel < DeviceFeatureLevel.SM5)
{
throw new GorgonException(GorgonResult.CannotCreate, string.Format(Resources.GORGFX_REQUIRES_SM, DeviceFeatureLevel.SM5));
}
if ((settings.Usage == BufferUsage.Immutable) && ((stream == null) || (stream.Length == 0)))
{
throw new GorgonException(GorgonResult.CannotCreate, Resources.GORGFX_BUFFER_IMMUTABLE_REQUIRES_DATA);
}
ValidateStructuredBufferSettings(settings);
var result = new GorgonStructuredBuffer(_graphics, name, settings);
result.Initialize(stream);
_graphics.AddTrackedObject(result);
return(result);
}
