/// <summary>
/// Function to load a sprite from the editor file system.
/// </summary>
/// <param name="fileSystem">The file system containing the editor data.</param>
/// <param name="renderer">The current renderer.</param>
/// <param name="path">The path to the sprite.</param>
/// <param name="textureUsage">[Optional] The intended usage for the texture.</param>
/// <param name="spriteCodecs">[Optional] A list of additonal codecs used to read sprite data.</param>
/// <param name="imageCodecs">[Optional] A list of additonal codecs used to read image data.</param>
/// <param name="overrideTexture">[Optional] A texture view to use instead of loading the texture from the file system.</param>
/// <returns>A new <see cref="GorgonSprite"/>, along with its associated texture.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="fileSystem"/>, <paramref name="renderer"/>, or the <paramref name="path"/> parameter is <b>null</b>.</exception>
/// <exception cref="ArgumentEmptyException">Thrown when the <paramref name="path"/> parameter is empty.</exception>
/// <exception cref="GorgonException">Thrown if the file system isn't a Gorgon Editor file system, or the file could not be read.</exception>
/// <remarks>
/// <para>
/// This method will load a sprite from a Gorgon Editor file system mounted as a <see cref="IGorgonFileSystem"/>.
/// </para>
/// <para>
/// The <paramref name="spriteCodecs"/> parameter is used to allow custom sprite codecs to be used when loading data (assuming the sprite data was generated using one of the codecs supplied). This
/// allows a user to create a custom sprite codec plug in and use that to read sprite data. The <paramref name="imageCodecs"/> is used in exactly the same way, but only for image data.
/// </para>
/// <para>
/// Providing the <paramref name="overrideTexture"/> will skip the texture loading and use the texture passed in. In this case, the texture return value will be <b>null</b> as it is assumed the
/// user already knows about the texture resource and is managing the lifetime of the texture elsewhere.
/// </para>
/// <para>
/// When the method returns, it returns a tuple containing the sprite that was loaded, and the associated texture resource for the sprite. If the texture could not be loaded for any reason,
/// and the <paramref name="overrideTexture"/> parameter is <b>null</b>, then the texture return value will be <b>null</b>, and no texture will be assigned to the sprite.
/// </para>
/// <para>
/// <h2>Technical info</h2>
/// <para>
/// Plug ins must generate the following metadata for the files in the editor file system.
/// </para>
/// <para>
/// The sprite file metadata must have the following attributes: <c>Type</c> with a value of "Sprite", and <c>SpriteCodec</c>, and its associated texture must have a dependency type of <c>Image</c> or else the sprite will not load.
/// </para>
/// <para>
/// The associated texture file metadata must have the following attributes: <c>Type</c> with a value of "Image", and <c>ImageCodec</c> or the texure will not load.
/// </para>
/// </para>
/// <para>
/// <note type="important">
/// <para>
/// <b>Regarding textures:</b> This method will load the associated texture for the sprite into memory, and will do its best to only load that texture one time. When the texture is loaded, it will
/// remain resident until Gorgon is shut down (typically when the application shuts down). In many cases, this is not ideal, so users must dispose of the <see cref="GorgonTexture2D"/> returned by
/// this method if unloading the texture data is desired (e.g. a level changes and new graphics need to be loaded).
/// </para>
/// </note>
/// </para>
/// </remarks>
public static (GorgonSprite sprite, GorgonTexture2D texture) LoadSprite(this IGorgonFileSystem fileSystem, Gorgon2D renderer, string path, ResourceUsage textureUsage = ResourceUsage.Default, IReadOnlyList <IGorgonSpriteCodec> spriteCodecs = null, IReadOnlyList <IGorgonImageCodec> imageCodecs = null, GorgonTexture2DView overrideTexture = null)
{
if (fileSystem == null)
{
throw new ArgumentNullException(nameof(fileSystem));
}
if (renderer == null)
{
throw new ArgumentNullException(nameof(renderer));
}
if (path == null)
{
throw new ArgumentNullException(nameof(path));
}
if (string.IsNullOrWhiteSpace(path))
{
throw new ArgumentEmptyException(nameof(path));
}
IProjectMetadata metaData = fileSystem.GetMetadata();
if (!metaData.ProjectItems.TryGetValue(path, out ProjectItemMetadata fileMetadata))
{
throw new FileNotFoundException(string.Format(Resources.GOREDIT_ERR_FILE_NOT_FOUND, path));
}
IReadOnlyDictionary <string, IGorgonSpriteCodec> supportedSpriteCodecs = GetSpriteCodecs(renderer, spriteCodecs);
IReadOnlyDictionary <string, IGorgonImageCodec> supportedImageCodecs = GetImageCodecs(imageCodecs);
if ((!fileMetadata.Attributes.TryGetValue(CommonEditorConstants.ContentTypeAttr, out string contentType)) ||
(!string.Equals(contentType, CommonEditorContentTypes.SpriteType, StringComparison.OrdinalIgnoreCase)))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_NOT_SPRITE, path));
}
if (!fileMetadata.Attributes.TryGetValue("SpriteCodec", out string codecTypeName))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_UNSUPPORTED_CODEC, string.Empty));
}
if (!supportedSpriteCodecs.TryGetValue(codecTypeName, out IGorgonSpriteCodec spriteCodec))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_UNSUPPORTED_CODEC, codecTypeName));
}
IGorgonVirtualFile file = fileSystem.GetFile(path);
if (file == null)
{
throw new FileNotFoundException(string.Format(Resources.GOREDIT_ERR_FILE_NOT_FOUND, path));
}
GorgonTexture2D texture = null;
if (overrideTexture == null)
{
if (fileMetadata.DependsOn.TryGetValue(CommonEditorContentTypes.ImageType, out string imagePath))
{
texture = GetTexture(renderer.Graphics, fileSystem, metaData, imagePath, textureUsage, supportedImageCodecs);
overrideTexture = texture.GetShaderResourceView();
}
}
using (Stream stream = file.OpenStream())
{
return(spriteCodec.FromStream(stream, overrideTexture, (int)file.Size), texture);
}
}
/// <summary>
/// Function to load a <see cref="GorgonSprite"/> from a <see cref="GorgonFileSystem"/>.
/// </summary>
/// <param name="fileSystem">The file system to load the sprite from.</param>
/// <param name="renderer">The renderer for the sprite.</param>
/// <param name="path">The path to the sprite file in the file system.</param>
/// <param name="spriteCodecs">The list of sprite codecs to try and load the sprite with.</param>
/// <param name="imageCodecs">The list of image codecs to try and load the sprite texture with.</param>
/// <returns>The sprite data in the file as a <see cref="GorgonSprite"/>.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="fileSystem"/>, <paramref name="renderer"/>, or <paramref name="path"/> parameter is <b>null</b>.</exception>
/// <exception cref="ArgumentEmptyException">Thrown when the <paramref name="path"/> parameter is empty.</exception>
/// <exception cref="FileNotFoundException">Thrown if the file in the <paramref name="path"/> was not found.</exception>
/// <exception cref="GorgonException">Thrown if the sprite data in the file system could not be loaded because a suitable codec was not found.</exception>
/// <remarks>
/// <para>
/// This method extends a <see cref="GorgonFileSystem"/> so that sprites can be loaded by calling a method on the file system object itself. This negates the need for users to create complex code
/// for loading a sprite.
/// </para>
/// <para>
/// When loading a sprite, the method will attempt to locate the <see cref="GorgonTexture2DView"/> associated with the sprite (if it exists). When loading, it will check:
/// <list type="number">
/// <item>
/// <description>For a texture resource with the same name that is already loaded into memory.</description>
/// </item>
/// <item>
/// <description>Use the local <see cref="IGorgonVirtualDirectory"/> for the sprite file and search for the texture in that directory.</description>
/// </item>
/// <item>
/// <description>Check the entire <paramref name="fileSystem"/> for a file if the texture name contains path information (this is done by the GorgonEditor from v2).</description>
/// </item>
/// </list>
/// If the file is found, and can be loaded by one of the <paramref name="imageCodecs"/>, then it is loaded and assigned to the sprite.
/// </para>
/// <para>
/// The <paramref name="spriteCodecs"/> is a list of codecs for loading sprite data. If the user specifies this parameter, the only the codecs provided will be used for determining if a sprite can
/// be read. If it is not supplied, then all built-in (i.e. not plug in based) sprite codecs will be used.
/// </para>
/// <para>
/// The <paramref name="imageCodecs"/> is a list of codecs for loading image data. If the user specifies this parameter, the only the codecs provided will be used for determining if an image can be
/// read. If it is not supplied, then all built-in (i.e. not plug in based) image codecs will be used.
/// </para>
/// </remarks>
/// <seealso cref="GorgonFileSystem"/>
/// <seealso cref="GorgonTexture2DView"/>
/// <seealso cref="GorgonSprite"/>
public static GorgonSprite LoadSpriteFromFileSystem(this IGorgonFileSystem fileSystem,
Gorgon2D renderer,
string path,
IEnumerable <IGorgonSpriteCodec> spriteCodecs = null,
IEnumerable <IGorgonImageCodec> imageCodecs = null)
{
if (fileSystem == null)
{
throw new ArgumentNullException(nameof(fileSystem));
}
IGorgonVirtualFile file = fileSystem.GetFile(path);
if (file == null)
{
throw new FileNotFoundException(string.Format(Resources.GOR2DIO_ERR_FILE_NOT_FOUND, path));
}
if ((imageCodecs == null) || (!imageCodecs.Any()))
{
// If we don't specify any codecs, then use the built in ones.
imageCodecs = new IGorgonImageCodec[]
{
new GorgonCodecPng(),
new GorgonCodecBmp(),
new GorgonCodecDds(),
new GorgonCodecGif(),
new GorgonCodecJpeg(),
new GorgonCodecTga(),
};
}
else
{
// Only use codecs that can decode image data.
imageCodecs = imageCodecs.Where(item => item.CanDecode);
}
if ((spriteCodecs == null) || (!spriteCodecs.Any()))
{
// Use all built-in codecs if we haven't asked for any.
spriteCodecs = new IGorgonSpriteCodec[]
{
new GorgonV3SpriteBinaryCodec(renderer),
new GorgonV3SpriteJsonCodec(renderer),
new GorgonV2SpriteCodec(renderer),
new GorgonV1SpriteBinaryCodec(renderer),
};
}
else
{
// Only use codecs that can decode sprite data.
spriteCodecs = spriteCodecs.Where(item => item.CanDecode);
}
// We need to copy the sprite data into a memory stream since the underlying stream may not be seekable.
Stream spriteStream = file.OpenStream();
try
{
if (!spriteStream.CanSeek)
{
Stream newStream = new DataStream((int)spriteStream.Length, true, true);
spriteStream.CopyTo(newStream);
spriteStream.Dispose();
newStream.Position = 0;
spriteStream = newStream;
}
IGorgonSpriteCodec spriteCodec = GetSpriteCodec(spriteStream, spriteCodecs);
if (spriteCodec == null)
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOR2DIO_ERR_NO_SUITABLE_SPRITE_CODEC_FOUND, path));
}
// Try to locate the texture.
string textureName = spriteCodec.GetAssociatedTextureName(spriteStream);
GorgonTexture2DView textureForSprite = null;
// Let's try and load the texture into memory.
// This does this by:
// 1. Checking to see if a texture resource with the name specified is already available in memory.
// 2. Checking the local directory of the file to see if the texture is there.
// 3. A file system wide search.
// ReSharper disable once InvertIf
if (!string.IsNullOrWhiteSpace(textureName))
{
(IGorgonImageCodec codec, IGorgonVirtualFile textureFile, bool loaded) =
LocateTextureCodecAndFile(fileSystem, file.Directory, renderer, textureName, imageCodecs);
// We have not loaded the texture yet. Do so now.
// ReSharper disable once InvertIf
if ((!loaded) && (textureFile != null) && (codec != null))
{
using (Stream textureStream = textureFile.OpenStream())
{
textureForSprite = GorgonTexture2DView.FromStream(renderer.Graphics,
textureStream,
codec,
textureFile.Size,
new GorgonTexture2DLoadOptions
{
Name = textureFile.FullPath,
Usage = ResourceUsage.Default,
Binding = TextureBinding.ShaderResource
});
}
}
}
return(spriteCodec.FromStream(spriteStream, textureForSprite, (int)file.Size));
}
finally
{
spriteStream?.Dispose();
}
}
/// <summary>
/// Function to load an image from the editor file system.
/// </summary>
/// <param name="fileSystem">The file system containing the editor data.</param>
/// <param name="path">The path to the sprite.</param>
/// <param name="imageCodecs">[Optional] A list of additonal codecs used to read image data.</param>
/// <returns>A new <see cref="IGorgonImage"/> containing the image data from the file system.</returns>
/// <exception cref="ArgumentNullException">Thrown when the <paramref name="fileSystem"/>, or the <paramref name="path"/> parameter is <b>null</b>.</exception>
/// <exception cref="ArgumentEmptyException">Thrown when the <paramref name="path"/> parameter is empty.</exception>
/// <exception cref="GorgonException">Thrown if the file system isn't a Gorgon Editor file system, or the file could not be read.</exception>
/// <remarks>
/// <para>
/// This method will load an image from a Gorgon Editor file system mounted as a <see cref="IGorgonFileSystem"/>.
/// </para>
/// <para>
/// The <paramref name="imageCodecs"/> parameter is used to allow custom image codecs to be used when loading data (assuming the image data was saved using one of the codecs supplied). This
/// allows a user to create a custom image codec plug in and use that to read image data.
/// </para>
/// <para>
/// <h2>Technical info</h2>
/// <para>
/// Plug ins must generate the following metadata for the files in the editor file system.
/// </para>
/// <para>
/// The image file metadata must have the following attributes: <c>Type</c> with a value of "Image", and <c>ImageCodec</c> or else the image will not load.
/// </para>
/// <para>
/// If image file has been marked as premultiplied in the editor, then the texture will be converted to use premultiplied alpha when loading. This is only done when the texture is read from the
/// file system, cached textures will left as-is.
/// </para>
/// </para>
/// </remarks>
public static IGorgonImage LoadImage(this IGorgonFileSystem fileSystem, string path, IReadOnlyList <IGorgonImageCodec> imageCodecs = null)
{
if (fileSystem == null)
{
throw new ArgumentNullException(nameof(fileSystem));
}
if (path == null)
{
throw new ArgumentNullException(nameof(path));
}
if (string.IsNullOrWhiteSpace(path))
{
throw new ArgumentEmptyException(nameof(path));
}
IProjectMetadata metaData = fileSystem.GetMetadata();
if (!metaData.ProjectItems.TryGetValue(path, out ProjectItemMetadata fileMetadata))
{
throw new FileNotFoundException(string.Format(Resources.GOREDIT_ERR_FILE_NOT_FOUND, path));
}
IReadOnlyDictionary <string, IGorgonImageCodec> supportedImageCodecs = GetImageCodecs(imageCodecs);
if ((!fileMetadata.Attributes.TryGetValue(CommonEditorConstants.ContentTypeAttr, out string contentType)) ||
(!string.Equals(contentType, CommonEditorContentTypes.ImageType, StringComparison.OrdinalIgnoreCase)))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_NOT_IMAGE, path));
}
if (!fileMetadata.Attributes.TryGetValue("ImageCodec", out string codecTypeName))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_UNSUPPORTED_CODEC, string.Empty));
}
if (!supportedImageCodecs.TryGetValue(codecTypeName, out IGorgonImageCodec imageCodec))
{
throw new GorgonException(GorgonResult.CannotRead, string.Format(Resources.GOREDIT_ERR_UNSUPPORTED_CODEC, codecTypeName));
}
IGorgonVirtualFile file = fileSystem.GetFile(path);
if (file == null)
{
throw new FileNotFoundException(string.Format(Resources.GOREDIT_ERR_FILE_NOT_FOUND, path));
}
bool shouldConvertToPremultiplied = false;
if (fileMetadata.Attributes.TryGetValue("PremultipliedAlpha", out string isPremultiplied))
{
#pragma warning disable CA1806 // Do not ignore method results
bool.TryParse(isPremultiplied, out shouldConvertToPremultiplied);
#pragma warning restore CA1806 // Do not ignore method results
}
using (Stream stream = file.OpenStream())
{
return(shouldConvertToPremultiplied ? imageCodec.LoadFromStream(stream, (int)file.Size).ConvertToPremultipliedAlpha() : imageCodec.LoadFromStream(stream, (int)file.Size));
}
}