Helper methods – AssetHandling helpers - TiberiumFusion/TTPlugins GitHub Wiki

← Back to the Helper methods overview article.

These helpers are located in the nested HHelpers.AssetHandling class and deal with XNA assets, such as Texture2D.

All helper methods are static.

Method Texture2DCreateTexture2DFromImageBytes(byte[] imageBytes, GraphicsDevice graphicsDevice, bool doPremultiply = false, Vector4? gammaCorrection = null)

Creates a new Texture2D from the provided byte[] imageBytes. The contents of imageBytes must be a JPG, PNG, or GIF image. Internally uses Texture2D.FromStream(). This helper is particularly useful under plugin Security Level 3 or higher, which prohibits the use of all System.IO types, including Streams.

Optional parameters:

  • doPremultiply - Default is false. If true, the source image's channels are premultiplied. You should set this to true only if your source image has non-premultiplied colors. JPGs do not have transparency and will be unaffected by this parameter. See the PremultiplyTexture() method for more information.
  • gammaCorrection - Default is null. If a valid Vector4 (e.g. new Vector4(1f, 1f, 1f, 2.2f)), the XYZW components will be used to apply gamma correction to the individual RGBA channels of the source image. See the GammaCorrectTexture() method for more information. Only use this parameter if you know what you are doing.

Example usage:

byte[] pngBytes = /* code */;
Texture2D tex = HHelpers.AssetHandling.CreateTexture2DFromImageBytes(pngBytes, Terraria.Main.instance.GraphicsDevice);

NOTE: Because this method requires a GraphicsDevice, you typically cannot use this helper in your plugin's base instance methods (Initialize(), ConfigurationLoaded(), and PrePatch()). Instead, call CreateTexture2DFromImageBytes() in a stub patch method that runs some time after Terraria has run its Initialize() method. For example:

private static byte[] pngBytes = /* code */;
public override void PrePatch()
{
	CreateHPatchOperation("Terraria.Main", "LoadContent", "LoadPluginAssets", HPatchLocation.Postfix);
}
public static void LoadPluginAssets(Terraria.Main __instance)
{
	Texture2D tex = HHelpers.AssetHandling.CreateTexture2DFromImageBytes(pngBytes, __instance.GraphicsDevice);
}

This method has overloads:

  • Texture2DCreateTexture2DFromImageBytes(byte[] imageBytes, GraphicsDevice graphicsDevice, int width, int height, bool zoom, bool doPremultiply = false, Vector4? gammaCorrection = null)
    • Adds the width, height, and zoom parameters. These parameters are mirrored directly to Texture2D.FromStream()'s width, height, and zoom parameters. Setting width and height allows you to change the dimensions of the created Texture2D. The definition of zoom is somewhat ambigious; quoted from the XNA docs: "Control the aspect ratio when zooming (scaling); set to false to maintain a constant aspect ratio, true otherwise".

TIP: If you precompiled your plugin and you embedded JPG, PNG, or GIF files in the output assembly, you can use GetPluginAssemblyResourceBytes() to retrieve the bytes of those embedded assets. See Helpful inherited members for more information.

Method voidPremultiplyTexture(Texture2D texture)

Premultiplies the color channels of the provided texture. Should only be used on non-premultiplied textures. This is only useful on PNGs and GIFs with partial transparency (think gradients). Common image editors like Photoshop save PNGs and GIFs with straight or indexed color, which is non-premultiplied. JPGs do not have transparency and will experience no change when premultiplied.

Example usage:

Texture2D tex = /* code */;
HHelpers.AssetHandling.PremultiplyTexture(tex); // tex is now premultiplied

Method voidGammaCorrectTexture(Texture2D texture, Vector4 gammaPower)

Performs gamma correction on the specified texture. Gamma correction is performed individually for each color channel, where gammaPower.X modulates the red channel, gammaPower.Y modulates the green channel, gammaPower.Z modulates the blue channel, and gammaPower.W modulates the alpha channel. The modulation formula is: newValue = Math.Pow(oldValue, 1.0 / gammaPower).

Example usage:

Texture2D tex = /* code */;
HHelpers.AssetHandling.GammaCorrectTexture(tex, new Vector4(1f / 2.2f)); // tex is now gamma corrected

NOTE: Most image editors will display and write images with a gamma space of 2.2 or sometimes 2.0. If a texture looks different in Photoshop versus in Terraria, try applying a 1/2.2 or 2.2 gamma correction to the texture.

← Back to the Helper methods overview article.