Class Gorgon2DEditorExtensions

Extension methods to load editor content.

Inheritance

object

Gorgon2DEditorExtensions

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.IO

Assembly: Gorgon.Editor.API.dll

Syntax

public static class Gorgon2DEditorExtensions

Remarks

A set of convenience methods to load data from an editor file system.

important

These methods load the data using the layout and metadata information as provided by the default plug ins for the editor. Custom plug ins for sprite data, etc... may not work with these methods unless those plug ins follow the same file layout as the default plug ins.

Methods

| Edit this page View Source

CreateContentLoader(IGorgonFileSystem, Gorgon2D, GorgonTextureCache<GorgonTexture2D>)

Function to create a loader object for reading content from an editor file system.

Declaration

public static IGorgonContentLoader CreateContentLoader(this IGorgonFileSystem fileSystem, Gorgon2D renderer, GorgonTextureCache<GorgonTexture2D> textureCache)

Parameters

Type	Name	Description
IGorgonFileSystem	fileSystem	The file system that holds the content to load.
Gorgon2D	renderer	The 2D renderer used to handle loading of additional resources.
GorgonTextureCache<GorgonTexture2D>	textureCache	The cache used to host any texture dependencies for the content.

Returns

Type	Description
IGorgonContentLoader	A new IGorgonContentLoader.

Exceptions

Type	Condition
ArgumentNullException	Thrown when any of the parameters are null.
GorgonException	Thrown if the `fileSystem` is not a Gorgon Editor file system, or is an unsupported version.

| Edit this page View Source

LoadImage(IGorgonFileSystem, string, IReadOnlyList<IGorgonImageCodec>)

Function to load an image from the editor file system.

Declaration

[Obsolete("This method is no longer used. Please use the IGorgonFileSystem.CreateEditorLoader method and use the resulting object to load images.")]
public static IGorgonImage LoadImage(this IGorgonFileSystem fileSystem, string path, IReadOnlyList<IGorgonImageCodec> imageCodecs = null)

Parameters

Type	Name	Description
IGorgonFileSystem	fileSystem	The file system containing the editor data.
string	path	The path to the sprite.
IReadOnlyList<IGorgonImageCodec>	imageCodecs	[Optional] A list of additonal codecs used to read image data.

Returns

Type	Description
IGorgonImage	A new IGorgonImage containing the image data from the file system.

Remarks

warning

This method is obsolete and may not work correctly with the latest version of the editor file system. Please use the CreateContentLoader(IGorgonFileSystem, Gorgon2D, GorgonTextureCache<GorgonTexture2D>) method to create an instance of the IGorgonContentLoader to read image data instead.

This method will load an image from a Gorgon Editor file system mounted as a IGorgonFileSystem.

The 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.

Technical info

Plug ins must generate the following metadata for the files in the editor file system.

The image file metadata must have the following attributes: Type with a value of "Image", and ImageCodec or else the image will not load.

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.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `fileSystem`, or the `path` parameter is null.
ArgumentEmptyException	Thrown when the `path` parameter is empty.
GorgonException	Thrown if the file system isn't a Gorgon Editor file system, or the file could not be read.

| Edit this page View Source

LoadSprite(IGorgonFileSystem, Gorgon2D, string, ResourceUsage, IReadOnlyList<IGorgonSpriteCodec>, IReadOnlyList<IGorgonImageCodec>, GorgonTexture2DView)

Function to load a sprite from the editor file system.

Declaration

[Obsolete("This method is no longer used. Please use the IGorgonFileSystem.CreateEditorLoader method and use the resulting object to load sprites.")]
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)

Parameters

Type	Name	Description
IGorgonFileSystem	fileSystem	The file system containing the editor data.
Gorgon2D	renderer	The current renderer.
string	path	The path to the sprite.
ResourceUsage	textureUsage	[Optional] The intended usage for the texture.
IReadOnlyList<IGorgonSpriteCodec>	spriteCodecs	[Optional] A list of additonal codecs used to read sprite data.
IReadOnlyList<IGorgonImageCodec>	imageCodecs	[Optional] A list of additonal codecs used to read image data.
GorgonTexture2DView	overrideTexture	[Optional] A texture view to use instead of loading the texture from the file system.

Returns

Type	Description
(GorgonSprite sprite, GorgonTexture2D texture)	A new GorgonSprite, along with its associated texture.

Remarks

warning

This method will load a sprite from a Gorgon Editor file system mounted as a IGorgonFileSystem.

The 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 imageCodecs is used in exactly the same way, but only for image data.

Providing the overrideTexture will skip the texture loading and use the texture passed in. In this case, the texture return value will be null as it is assumed the user already knows about the texture resource and is managing the lifetime of the texture elsewhere.

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 overrideTexture parameter is null, then the texture return value will be null, and no texture will be assigned to the sprite.

Technical info

Plug ins must generate the following metadata for the files in the editor file system.

The sprite file metadata must have the following attributes: Type with a value of "Sprite", and SpriteCodec, and its associated texture must have a dependency type of Image or else the sprite will not load.

The associated texture file metadata must have the following attributes: Type with a value of "Image", and ImageCodec or the texure will not load.

If the associated texture 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.

important

Regarding textures: 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 GorgonTexture2D returned by this method if unloading the texture data is desired (e.g. a level changes and new graphics need to be loaded).

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `fileSystem`, `renderer`, or the `path` parameter is null.
ArgumentEmptyException	Thrown when the `path` parameter is empty.
GorgonException	Thrown if the file system isn't a Gorgon Editor file system, or the file could not be read.