Class TextureLoader

Namespace

Stride.CommunityToolkit.Rendering

Assembly

Stride.CommunityToolkit.dll

Loads image files into textures the way Game Studio's content pipeline would have prepared them, by what the texture is for: a colour as sRGB and premultiplied, data as linear, a normal map linear with unit normals in every mip, each with a full mipmap chain. Each file is loaded once per role and kept until the loader is disposed.

public sealed class TextureLoader : IDisposable

Inheritance

object

TextureLoader

Implements

IDisposable

Remarks

Texture.Load(device, stream) with its defaults does none of this: it loads every file as linear, straight alpha, one mip. A colour texture comes out pale, a transparent edge gets a halo, a tiled floor shimmers, and nothing warns. The pipeline does the rest at import, which is why the same PNG looks right as an asset and wrong from code.

What the loader does not do is block compression: the texture stays eight bits per channel, four to eight times the memory of the BC formats an asset would use. For that, or for mipmaps built offline, ship a .dds: a path ending in .dds is loaded as it is, only its colour space chosen by the role.

Constructors

TextureLoader(GraphicsDevice, string?)

Loads image files into textures the way Game Studio's content pipeline would have prepared them, by what the texture is for: a colour as sRGB and premultiplied, data as linear, a normal map linear with unit normals in every mip, each with a full mipmap chain. Each file is loaded once per role and kept until the loader is disposed.

public TextureLoader(GraphicsDevice device, string? root = null)

Parameters

device GraphicsDevice

The device the textures are created on.

root string

The folder relative paths are resolved against; the executable's folder by default.

Remarks

Texture.Load(device, stream) with its defaults does none of this: it loads every file as linear, straight alpha, one mip. A colour texture comes out pale, a transparent edge gets a halo, a tiled floor shimmers, and nothing warns. The pipeline does the rest at import, which is why the same PNG looks right as an asset and wrong from code.

What the loader does not do is block compression: the texture stays eight bits per channel, four to eight times the memory of the BC formats an asset would use. For that, or for mipmaps built offline, ship a .dds: a path ending in .dds is loaded as it is, only its colour space chosen by the role.

Properties

Root

The folder relative paths are resolved against.

public string Root { get; }

Property Value

string

Methods

Color(string)

A colour texture: an albedo, an emissive, a sprite. sRGB, premultiplied, mipmapped.

public Texture Color(string path)

Parameters

path string

The file, absolute or relative to Root.

Returns

Texture

Data(string)

A data texture: glossiness, metalness, occlusion, a mask, a height map. Linear, mipmapped.

public Texture Data(string path)

Parameters

path string

The file, absolute or relative to Root.

Returns

Texture

Dispose()

Disposes every texture the loader has loaded; they must no longer be drawn.

public void Dispose()

FromImage(GraphicsDevice, Image, TextureLoadOptions)

Makes a texture from a decoded image, prepared for its role: for pixels edited after decoding and before upload. Not kept: the caller owns it.

public static Texture FromImage(GraphicsDevice device, Image image, TextureLoadOptions options)

Parameters

device GraphicsDevice

The device to create it on.

image Image

A 2D image of eight bits per channel, RGBA or BGRA, as Image.Load decodes a PNG or JPEG.

options TextureLoadOptions

The role and the steps to take.

Returns

Texture

Exceptions

NotSupportedException

The image is not a single 2D image of eight-bit RGBA or BGRA.

Load(GraphicsDevice, Stream, TextureLoadOptions)

Loads a texture from a stream - an embedded resource, a download - prepared for its role. Not kept: the caller owns it.

public static Texture Load(GraphicsDevice device, Stream stream, TextureLoadOptions options)

Parameters

device GraphicsDevice

The device to create it on.

stream Stream

A PNG, JPEG, BMP, GIF or TIFF.

options TextureLoadOptions

The role and the steps to take.

Returns

Texture

Load(string, TextureLoadOptions)

A texture with every option spelled out. Loaded once per path and options, kept until the loader is disposed.

public Texture Load(string path, TextureLoadOptions options)

Parameters

path string

The file, absolute or relative to Root.

options TextureLoadOptions

The role and the steps to take.

Returns

Texture

NormalMap(string, bool)

A tangent-space normal map. Linear, mipmapped with unit normals.

public Texture NormalMap(string path, bool invertY = false)

Parameters

path string

The file, absolute or relative to Root.

invertY bool

Whether to invert the green channel: on for a map whose green points up (Blender, Unity, glTF), off for the engine's own green-down convention.

Returns

Texture