/// <summary>
/// Function to create a <see cref="GorgonTexture2D"/> from a GDI+ bitmap.
/// </summary>
/// <param name="gdiBitmap">The GDI+ bitmap 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="GorgonTexture2D"/> containing the data from the <paramref name="gdiBitmap"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="gdiBitmap"/>, or the <paramref name="graphics"/> parameter is <b>null</b>.</exception>
/// <remarks>
/// <para>
/// A GDI+ bitmap 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 GDI+ bitmap into a
/// <see cref="GorgonTexture2D"/>.
/// </para>
/// <para>
/// The resulting <see cref="GorgonTexture2D"/> will only contain a single mip level, and single array level. The only image type available will be 2D (i.e. image with a width and height). The GDI+
/// bitmap should have a 32bpp rgba format, or a 24bpp rgb format or else an exception will be thrown.
/// </para>
/// <para>
/// The optional <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>
/// <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 GorgonTexture2D ToTexture2D(this Bitmap gdiBitmap,
GorgonGraphics graphics,
GorgonTexture2DLoadOptions options = null)
{
if (gdiBitmap == null)
{
throw new ArgumentNullException(nameof(gdiBitmap));
}
if (graphics == null)
{
throw new ArgumentNullException(nameof(graphics));
}
if (options == null)
{
options = _defaultLoadOptions;
}
if (string.IsNullOrEmpty(options.Name))
{
options.Name = GorgonGraphicsResource.GenerateName(GorgonTexture2D.NamePrefix);
}
using (IGorgonImage image = gdiBitmap.ToGorgonImage())
{
if (options.ConvertToPremultipliedAlpha)
{
image.ConvertToPremultipliedAlpha();
}
return(new GorgonTexture2D(graphics, image, options));
}
}
/// <summary>
/// Function to create a <see cref="GorgonTexture2D"/> 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="GorgonTexture2D"/> 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="GorgonTexture2D"/>.
/// </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>
/// </remarks>
public static GorgonTexture2D ToTexture2D(this IGorgonImage image,
GorgonGraphics graphics,
GorgonTexture2DLoadOptions 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(GorgonTexture2D.NamePrefix);
}
return(new GorgonTexture2D(graphics, image, options));
}
/// <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="GorgonTexture2DView"/></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="GorgonTexture2D"/> object and return a <see cref="GorgonTexture2DView"/>.
/// </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>
/// <item>
/// <term>ConvertToPremultipliedAlpha</term>
/// <description>Converts the image to premultiplied alpha before uploading the image data to the texture.</description>
/// </item>
/// </list>
/// </para>
/// <para>
/// Since the <see cref="GorgonTexture2D"/> created by this method is linked to the <see cref="GorgonTexture2DView"/> returned, disposal of either one will dispose of the other on your behalf. If
/// the user created a <see cref="GorgonTexture2DView"/> from the <see cref="GorgonTexture2D.GetShaderResourceView"/> method on the <see cref="GorgonTexture2D"/>, 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 GorgonTexture2DView FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTexture2DLoadOptions 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))
{
if (options == null)
{
options = new GorgonTexture2DLoadOptions
{
Name = Path.GetFileNameWithoutExtension(filePath),
Usage = ResourceUsage.Default,
Binding = TextureBinding.ShaderResource,
IsTextureCube = image.ImageType == ImageType.ImageCube
};
}
GorgonTexture2D texture = image.ToTexture2D(graphics, options);
GorgonTexture2DView view = texture.GetShaderResourceView();
view.OwnsResource = true;
return(view);
}
}
/// <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="GorgonTexture2DView"/></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="GorgonTexture2D"/> object and return a <see cref="GorgonTexture2DView"/>.
/// </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>
/// <item>
/// <term>ConvertToPremultipliedAlpha</term>
/// <description>Converts the image to premultiplied alpha before uploading the image data to the texture.</description>
/// </item>
/// </list>
/// </para>
/// <para>
/// Since the <see cref="GorgonTexture2D"/> created by this method is linked to the <see cref="GorgonTexture2DView"/> returned, disposal of either one will dispose of the other on your behalf. If
/// the user created a <see cref="GorgonTexture2DView"/> from the <see cref="GorgonTexture2D.GetShaderResourceView"/> method on the <see cref="GorgonTexture2D"/>, 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 GorgonTexture2DView FromStream(GorgonGraphics graphics, Stream stream, IGorgonImageCodec codec, long?size = null, GorgonTexture2DLoadOptions 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))
{
GorgonTexture2D texture = image.ToTexture2D(graphics, options);
GorgonTexture2DView view = texture.GetShaderResourceView();
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="GorgonTexture2DReadWriteView"/></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="GorgonTexture2D"/> object and return a <see cref="GorgonTexture2DReadWriteView"/>.
/// </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>
/// <item>
/// <term>ConvertToPremultipliedAlpha</term>
/// <description>Converts the image to premultiplied alpha before uploading the image data to the texture.</description>
/// </item>
/// </list>
/// </para>
/// <para>
/// Since the <see cref="GorgonTexture2D"/> created by this method is linked to the <see cref="GorgonTexture2DReadWriteView"/> returned, disposal of either one will dispose of the other on your behalf. If
/// the user created a <see cref="GorgonTexture2DReadWriteView"/> from the <see cref="GorgonTexture2D.GetShaderResourceView"/> method on the <see cref="GorgonTexture2D"/>, 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 GorgonTexture2DReadWriteView FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTexture2DLoadOptions 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))
{
GorgonTexture2D texture = image.ToTexture2D(graphics, options);
GorgonTexture2DReadWriteView view = texture.GetReadWriteView();
view.OwnsResource = true;
return(view);
}
}
