/// <summary>
/// Function to create a <see cref="GorgonTexture1D"/> from a <see cref="GorgonImage"/>.
/// </summary>
/// <param name="image">The image used to create the texture.</param>
/// <param name="graphics">The graphics interface used to create the texture.</param>
/// <param name="options">[Optional] Options used to further define the texture.</param>
/// <returns>A new <see cref="GorgonTexture1D"/> containing the data from the <paramref name="image"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="image"/>, or the <paramref name="graphics"/> parameter is <b>null</b>.</exception>
/// <remarks>
/// <para>
/// A <see cref="GorgonImage"/> is useful to holding image data in memory, but it cannot be sent to the GPU for use as a texture. This method allows an application to convert the
/// <see cref="GorgonImage"/> into a <see cref="GorgonTexture1D"/>.
/// </para>
/// <para>
/// If specified, the <paramref name="options"/>parameter will define how Gorgon and shaders should handle the texture. The <see cref="GorgonTextureLoadOptions"/> type contains the following:
/// <list type="bullet">
/// <item>
/// <term>Binding</term>
/// <description>When defined, will indicate the <see cref="TextureBinding"/> that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be
/// <see cref="TextureBinding.ShaderResource"/>.</description>
/// </item>
/// <item>
/// <term>Usage</term>
/// <description>When defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to <see cref="ResourceUsage.Default"/>.</description>
/// </item>
/// <item>
/// <term>Multisample info</term>
/// <description>This is not available on 1D textures, and is ignored.</description>
/// </item>
/// <item>
/// <term>ConvertToPremultipliedAlpha</term>
/// <description>Converts the image to premultiplied alpha before uploading the image data to the texture.</description>
/// </item>
/// </list>
/// </para>
/// </remarks>
public static GorgonTexture1D ToTexture1D(this IGorgonImage image,
GorgonGraphics graphics,
GorgonTextureLoadOptions options = null)
{
if (image == null)
{
throw new ArgumentNullException(nameof(image));
}
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (options == null)
{
options = _defaultLoadOptions;
}
if (string.IsNullOrEmpty(options.Name))
{
options.Name = GorgonGraphicsResource.GenerateName(GorgonTexture1D.NamePrefix);
}
if (options.ConvertToPremultipliedAlpha)
{
image.ConvertToPremultipliedAlpha();
}
return(new GorgonTexture1D(graphics, image, options));
}
/// <summary>
/// Function to load a texture from a <see cref="Stream"/>.
/// </summary>
/// <param name="graphics">The graphics interface that will own the texture.</param>
/// <param name="stream">The stream containing the texture image data.</param>
/// <param name="codec">The codec that is used to decode the the data in the stream.</param>
/// <param name="size">[Optional] The size of the image in the stream, in bytes.</param>
/// <param name="options">[Optional] Options used to further define the texture.</param>
/// <returns>A new <see cref="GorgonTexture3DReadWriteView"/></returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="graphics"/>, <paramref name="stream"/>, or the <paramref name="codec"/> parameter is <b>null</b>.</exception>
/// <exception cref="IOException">Thrown if the <paramref name="stream"/> is write only.</exception>
/// <exception cref="EndOfStreamException">Thrown if reading the image would move beyond the end of the <paramref name="stream"/>.</exception>
/// <remarks>
/// <para>
/// This will load an <see cref="IGorgonImage"/> from a <paramref name="stream"/> and put it into a <see cref="GorgonTexture3D"/> object and return a <see cref="GorgonTexture3DReadWriteView"/>.
/// </para>
/// <para>
/// If the <paramref name="size"/> option is specified, then the method will read from the stream up to that number of bytes, so it is up to the user to provide an accurate size. If it is omitted
/// then the <c>stream length - stream position</c> is used as the total size.
/// </para>
/// <para>
/// If specified, the <paramref name="options"/>parameter will define how Gorgon and shaders should handle the texture. The <see cref="GorgonTextureLoadOptions"/> type contains the following:
/// <list type="bullet">
/// <item>
/// <term>Binding</term>
/// <description>When defined, will indicate the <see cref="TextureBinding"/> that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be
/// <see cref="TextureBinding.ShaderResource"/>.</description>
/// </item>
/// <item>
/// <term>Usage</term>
/// <description>When defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to <see cref="ResourceUsage.Default"/>.</description>
/// </item>
/// <item>
/// <term>Multisample info</term>
/// <description>When defined (i.e. not <b>null</b>), defines the multisampling to apply to the texture. If omitted, then the default is <see cref="GorgonMultisampleInfo.NoMultiSampling"/>.</description>
/// </item>
/// </list>
/// </para>
/// <para>
/// Since the <see cref="GorgonTexture3D"/> created by this method is linked to the <see cref="GorgonTexture3DReadWriteView"/> returned, disposal of either one will dispose of the other on your behalf. If
/// the user created a <see cref="GorgonTexture3DReadWriteView"/> from the <see cref="GorgonTexture3D.GetShaderResourceView"/> method on the <see cref="GorgonTexture3D"/>, then it's assumed the user knows
/// what they are doing and will handle the disposal of the texture and view on their own.
/// </para>
/// </remarks>
public static GorgonTexture3DReadWriteView FromStream(GorgonGraphics graphics,
Stream stream,
IGorgonImageCodec codec,
long?size = null,
GorgonTextureLoadOptions options = null)
{
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (stream == null)
{
throw new ArgumentNullException(nameof(stream));
}
if (codec == null)
{
throw new ArgumentNullException(nameof(codec));
}
if (!stream.CanRead)
{
throw new IOException(Resources.GORGFX_ERR_STREAM_WRITE_ONLY);
}
if (size == null)
{
size = stream.Length - stream.Position;
}
if ((stream.Length - stream.Position) < size)
{
throw new EndOfStreamException();
}
using (IGorgonImage image = codec.LoadFromStream(stream, size))
{
GorgonTexture3D texture = image.ToTexture3D(graphics, options);
GorgonTexture3DReadWriteView view = texture.GetReadWriteView();
view.OwnsResource = true;
return(view);
}
}
/// <summary>
/// Function to load a texture from a file.
/// </summary>
/// <param name="graphics">The graphics interface that will own the texture.</param>
/// <param name="filePath">The path to the file.</param>
/// <param name="codec">The codec that is used to decode the the data in the stream.</param>
/// <param name="options">[Optional] Options used to further define the texture.</param>
/// <returns>A new <see cref="GorgonTexture3DView"/></returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="graphics"/>, <paramref name="filePath"/>, or the <paramref name="codec"/> parameter is <b>null</b>.</exception>
/// <exception cref="ArgumentEmptyException">Thrown when the <paramref name="filePath"/> parameter is empty.</exception>
/// <remarks>
/// <para>
/// This will load an <see cref="IGorgonImage"/> from a file on disk and put it into a <see cref="GorgonTexture3D"/> object and return a <see cref="GorgonTexture3DView"/>.
/// </para>
/// <para>
/// If specified, the <paramref name="options"/>parameter will define how Gorgon and shaders should handle the texture. The <see cref="GorgonTextureLoadOptions"/> type contains the following:
/// <list type="bullet">
/// <item>
/// <term>Binding</term>
/// <description>When defined, will indicate the <see cref="TextureBinding"/> that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be
/// <see cref="TextureBinding.ShaderResource"/>.</description>
/// </item>
/// <item>
/// <term>Usage</term>
/// <description>When defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to <see cref="ResourceUsage.Default"/>.</description>
/// </item>
/// <item>
/// <term>Multisample info</term>
/// <description>When defined (i.e. not <b>null</b>), defines the multisampling to apply to the texture. If omitted, then the default is <see cref="GorgonMultisampleInfo.NoMultiSampling"/>.</description>
/// </item>
/// </list>
/// </para>
/// <para>
/// Since the <see cref="GorgonTexture3D"/> created by this method is linked to the <see cref="GorgonTexture3DView"/> returned, disposal of either one will dispose of the other on your behalf. If
/// the user created a <see cref="GorgonTexture3DView"/> from the <see cref="GorgonTexture3D.GetShaderResourceView"/> method on the <see cref="GorgonTexture3D"/>, then it's assumed the user knows
/// what they are doing and will handle the disposal of the texture and view on their own.
/// </para>
/// </remarks>
public static GorgonTexture3DView FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTextureLoadOptions options = null)
{
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (filePath == null)
{
throw new ArgumentNullException(nameof(filePath));
}
if (string.IsNullOrWhiteSpace(filePath))
{
throw new ArgumentEmptyException(nameof(filePath));
}
if (codec == null)
{
throw new ArgumentNullException(nameof(codec));
}
using (IGorgonImage image = codec.LoadFromFile(filePath))
{
GorgonTexture3D texture = image.ToTexture3D(graphics, options);
GorgonTexture3DView view = texture.GetShaderResourceView();
view.OwnsResource = true;
return(view);
}
}
