Class MaterialMapper

Serves as an abstract base class for converting TriLib virtual materials into Unity UnityEngine.Material objects. Classes inheriting from MaterialMapper must implement or override the provided methods and properties to handle specific pipeline requirements (e.g., Standard, HDRP, URP, custom shaders, etc.).

Inheritance

object

MaterialMapper

HDRPMaterialMapper

CustomizableMaterialMapper

StandardMaterialMapper

UniversalRPMaterialMapper

Namespace: TriLibCore.Mappers

Assembly: TriLibCore.dll

Syntax

public abstract class MaterialMapper : ScriptableObject

Constructors

MaterialMapper()

Declaration

protected MaterialMapper()

Fields

CheckingOrder

A numeric priority determining the order in which this mapper is checked for compatibility against a given material. Higher values mean earlier checks; mappers with lower priority values are evaluated later if no suitable match is found.

Declaration

public int CheckingOrder

Field Value

Type	Description
int

DisableAlpha

If enabled, alpha-based material features (e.g., transparency) will be disabled, effectively forcing the usage of a purely opaque workflow.

Declaration

public bool DisableAlpha

Field Value

Type	Description
bool

Properties

ConvertMaterialTextures

Indicates whether this Material Mapper does "Metallic/Smoothness/Specular/Roughness/Emission" automatic texture creation.

Declaration

public virtual bool ConvertMaterialTextures { get; }

Property Value

Type	Description
bool

CutoutMaterialPreset

A cutout material preset for materials that use alpha testing (fully transparent vs. fully opaque).

Declaration

public virtual Material CutoutMaterialPreset { get; }

Property Value

Type	Description
Material

CutoutMaterialPresetNoMetallicTexture

A cutout material preset for materials with no metallic texture usage.

Declaration

public virtual Material CutoutMaterialPresetNoMetallicTexture { get; }

Property Value

Type	Description
Material

ExtractMetallicAndSmoothness

Indicates whether this Material Mapper automatically extracts Metallic and Smoothness textures.

Declaration

public virtual bool ExtractMetallicAndSmoothness { get; }

Property Value

Type	Description
bool

LoadingMaterial

An optional placeholder material used while a model’s final materials and textures are still loading.

Declaration

public virtual Material LoadingMaterial { get; }

Property Value

Type	Description
Material

MaterialPreset

The default (opaque) material preset.

Declaration

public virtual Material MaterialPreset { get; }

Property Value

Type	Description
Material

MaterialPresetNoMetallicTexture

The default (opaque) material preset for materials with no metallic texture usage.

Declaration

public virtual Material MaterialPresetNoMetallicTexture { get; }

Property Value

Type	Description
Material

RegisteredMapperNamespaces

A list of default namespaces used to register TriLib material mappers (e.g., "TriLibCore.HDRP.Mappers", "TriLibCore.URP.Mappers").

Declaration

public static List<string> RegisteredMapperNamespaces { get; }

Property Value

Type	Description
List<string>

RegisteredMappers

A list of default mapper class names recognized by TriLib (e.g., "HDRPMaterialMapper", "UniversalRPMaterialMapper", "StandardMaterialMapper").

Declaration

public static List<string> RegisteredMappers { get; }

Property Value

Type	Description
List<string>

TransparentComposeMaterialPreset

A “compose” material preset used in layered alpha workflows when AlphaMaterialMode is set to CutoutAndTransparent. This is applied as a secondary pass for partially transparent regions.

Declaration

public virtual Material TransparentComposeMaterialPreset { get; }

Property Value

Type	Description
Material

TransparentComposeMaterialPresetNoMetallicTexture

The “compose” material preset for partially transparent materials that have no metallic texture usage.

Declaration

public virtual Material TransparentComposeMaterialPresetNoMetallicTexture { get; }

Property Value

Type	Description
Material

TransparentMaterialPreset

A fully transparent (alpha) material preset.

Declaration

public virtual Material TransparentMaterialPreset { get; }

Property Value

Type	Description
Material

TransparentMaterialPresetNoMetallicTexture

A fully transparent (alpha) material preset for materials without a metallic texture.

Declaration

public virtual Material TransparentMaterialPresetNoMetallicTexture { get; }

Property Value

Type	Description
Material

UseShaderVariantCollection

If overridden to return true, indicates that this mapper uses a Shader Variant Collection instead of the usual material presets. By default, it returns false.

Declaration

public virtual bool UseShaderVariantCollection { get; }

Property Value

Type	Description
bool

Remarks

Implementers can override this to provide advanced material handling, especially when working with different pipelines or specialized shader setups.

UsesCoroutines

Indicates whether this mapper’s Map(MaterialMapperContext) process requires an asynchronous coroutine approach (true), or can run synchronously (false).

Declaration

public virtual bool UsesCoroutines { get; }

Property Value

Type	Description
bool

Remarks

Returning true means MapCoroutine(MaterialMapperContext) will be called instead of Map(MaterialMapperContext).

Methods

ApplyMaterialToRenderer(MaterialRendererContext)

Applies the final Unity UnityEngine.Material to the given UnityEngine.Renderer based on the materialRendererContext. If AlphaMaterialMode is set to CutoutAndTransparent, a second pass material may be created for partial translucency.

Declaration

public void ApplyMaterialToRenderer(MaterialRendererContext materialRendererContext)

Parameters

Type	Name	Description
MaterialRendererContext	materialRendererContext	The context containing a UnityEngine.Renderer, geometry data, and references to the TriLib MaterialMapperContext.

BuildMaterial(MaterialMapperContext)

Composes a final Unity material based on the TriLib VirtualMaterial properties and the specific property names or overrides provided by an inheriting mapper.

Declaration

protected void BuildMaterial(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	References the TriLib virtual material, the in-progress Unity material, and the overall AssetLoaderContext.

CheckTextureOffsetAndScaling(MaterialMapperContext, ITexture, bool)

(Obsolete) An older version of CheckTextureOffsetAndScaling(TextureLoadingContext) that takes separate parameters for the TriLib texture and a loaded flag. Please use the newer single-parameter method instead.

Declaration

[Obsolete("Please use the new method (with a single parameter).")]
protected static void CheckTextureOffsetAndScaling(MaterialMapperContext materialMapperContext, ITexture texture, bool textureLoaded)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Contains references to the TriLib virtual material and the Unity material being generated.
ITexture	texture	The TriLib ITexture being applied.
bool	textureLoaded	Whether the texture has successfully loaded into memory.

CheckTextureOffsetAndScaling(TextureLoadingContext)

Ensures that the loaded texture respects any offset or scaling set in the TriLib virtual material. This method updates either the Unity UnityEngine.Material or the VirtualMaterial properties depending on the setup.

Declaration

protected static void CheckTextureOffsetAndScaling(TextureLoadingContext textureLoadingContext)

Parameters

Type	Name	Description
TextureLoadingContext	textureLoadingContext	Contains texture data, references to the MaterialMapperContext, and flags indicating if the texture was successfully loaded.

CheckTextureOffsetAndScalingCoroutine(TextureLoadingContext)

A coroutine-based version of CheckTextureOffsetAndScaling(TextureLoadingContext), useful for stepped or asynchronous processing in complex loading workflows.

Declaration

protected static IEnumerable CheckTextureOffsetAndScalingCoroutine(TextureLoadingContext textureLoadingContext)

Parameters

Type	Name	Description
TextureLoadingContext	textureLoadingContext	Contains the texture data and references to the MaterialMapperContext.

Returns

Type	Description
IEnumerable	An IEnumerable that yields immediately after applying offset and scale (for consistency with async logic).

Cleanup(MaterialRendererContext)

Releases CPU mesh data (if allowed) once the material has been assigned, and if no blend shape mapper is in use. This can reduce runtime memory usage.

Declaration

public static void Cleanup(MaterialRendererContext materialRendererContext)

Parameters

Type	Name	Description
MaterialRendererContext	materialRendererContext	The context for a particular UnityEngine.Renderer and submesh, containing the model’s mesh reference.

GetDiffuseColorName(MaterialMapperContext)

Retrieves the property name for the diffuse (albedo) color within this mapper’s target shaders.

Declaration

public virtual string GetDiffuseColorName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetDiffuseTextureName(MaterialMapperContext)

Retrieves the property name for the diffuse (albedo) texture within this mapper’s target shaders.

Declaration

public virtual string GetDiffuseTextureName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetEmissionColorName(MaterialMapperContext)

Retrieves the property name for the emissive color within this mapper’s target shaders.

Declaration

public virtual string GetEmissionColorName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetGlossinessOrRoughnessName(MaterialMapperContext)

Retrieves the property name for glossiness or roughness, depending on the shader’s workflow.

Declaration

public virtual string GetGlossinessOrRoughnessName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetGlossinessOrRoughnessTextureName(MaterialMapperContext)

Retrieves the property name for the glossiness or roughness texture, if applicable.

Declaration

public virtual string GetGlossinessOrRoughnessTextureName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetMetallicName(MaterialMapperContext)

Retrieves the property name for metallic values in PBR workflows.

Declaration

public virtual string GetMetallicName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

GetMetallicTextureName(MaterialMapperContext)

Retrieves the property name for the metallic texture, if used in the target shader.

Declaration

public virtual string GetMetallicTextureName(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context containing the TriLib virtual material and Unity material references.

Returns

Type	Description
string

IsCompatible(MaterialMapperContext)

Determines whether this mapper can handle the specified material (e.g., by checking shader keywords, pipeline features, or other criteria). Mappers with false returns are skipped in favor of others with higher compatibility.

Declaration

public virtual bool IsCompatible(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	The context providing references to both the TriLib VirtualMaterial data and the underlying Unity UnityEngine.Material.

Returns

Type	Description
bool	true if compatible; otherwise false.

LoadTextureWithCallbacks(MaterialMapperContext, TextureType, ITexture, params Action<TextureLoadingContext>[])

Loads a texture synchronously while providing optional callback actions that are triggered once the texture is fully processed.

Declaration

protected void LoadTextureWithCallbacks(MaterialMapperContext materialMapperContext, TextureType textureType, ITexture texture, params Action<TextureLoadingContext>[] onTextureProcessed)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Provides references to the TriLib virtual material, the Unity material, and the broader AssetLoaderContext.
TextureType	textureType	Indicates the conceptual role of the texture (e.g., diffuse, normal, metallic).
ITexture	texture	The TriLib ITexture to be loaded.
Action<TextureLoadingContext>[]	onTextureProcessed	Zero or more callback actions invoked after the texture is processed. Each action receives a TextureLoadingContext with details about the load result.

LoadTextureWithCoroutineCallbacks(MaterialMapperContext, TextureType, ITexture, params Func<TextureLoadingContext, IEnumerable>[])

Loads a texture asynchronously, returning a coroutine-like sequence of steps which can be interleaved with other tasks. This is useful for large textures or slower I/O operations.

Declaration

protected IEnumerable LoadTextureWithCoroutineCallbacks(MaterialMapperContext materialMapperContext, TextureType textureType, ITexture texture, params Func<TextureLoadingContext, IEnumerable>[] onTextureProcessed)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Context referencing the TriLib virtual material, the target Unity material, and the broader AssetLoaderContext.
TextureType	textureType	Indicates the conceptual role of the texture (e.g., diffuse, normal, metallic).
ITexture	texture	The TriLib ITexture to be loaded.
Func<TextureLoadingContext, IEnumerable>[]	onTextureProcessed	Zero or more callback functions (coroutines) executed after texture loading to apply post-processing or run custom logic (e.g., compressing, adjusting channels, etc.).

Returns

Type	Description
IEnumerable	An IEnumerable enumerator that yields at various stages of texture loading for cooperative multitasking.

Map(MaterialMapperContext)

Begins the material mapping process synchronously, converting TriLib’s VirtualMaterial into a Unity UnityEngine.Material (or multiple passes).

Declaration

public virtual void Map(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Holds references to the TriLib virtual material, the target Unity material, and the overall AssetLoaderContext.

MapCoroutine(MaterialMapperContext)

Begins the material mapping process asynchronously, yielding control back to the caller to allow frame updates or concurrent loading. Called if UsesCoroutines returns true.

Declaration

public virtual IEnumerable MapCoroutine(MaterialMapperContext materialMapperContext)

Parameters

Type	Name	Description
MaterialMapperContext	materialMapperContext	Holds references to the TriLib virtual material, the target Unity material, and the overall AssetLoaderContext.

Returns

Type	Description
IEnumerable	An IEnumerable sequence that yields at intermediate steps for cooperative asynchronous processing.

Extension Methods

IObjectExtensions.TryToDispose<T>(object)