Docsv2.2.5
Back to API Reference
Class

MaterialModifier

Applies a user-authored Material to a text range by emitting a dedicated sub-mesh with its own CanvasRenderer.

Remarks

The custom shader must include UniText_Custom.cginc and declare _MainTex as a 2DArray — see Assets/Create/UniText/Custom Material Shader for a working template. The atlas Texture2DArray is bound automatically; per-glyph user data is written into TEXCOORD2 / TEXCOORD3 (see constantUv2, constantUv3, glyphDataWriter and OnWriteGlyphUV). Default renderOrder is Replace: the base SDF pass is suppressed on the range (face alpha zeroed in the main mesh, which also hides EffectModifier contributions for those glyphs). Use Over / Under to keep the base pass and layer the custom material on top/behind. Parameter: optional tint color. Format: <mat=#RRGGBBAA> or <mat=red>. The tint multiplies the vertex color that the shader receives. Ordering note (Replace mode): Replace works by zeroing the face-alpha of affected glyphs in the base mesh during the onGlyph callback. UniText invokes onGlyph subscribers in the order the corresponding Styles appear in the component's Styles list. If a ColorModifier / GradientModifier entry comes after MaterialModifier, it will overwrite the zeroed alpha and the base face will become visible again, defeating Replace. Place MaterialModifier after any color-writing modifiers in the Styles list.

Nested Types

S
MaterialGlyphContext
Per-glyph context passed to [[glyphDataWriter]] and [[OnWriteGlyphUV]].
E
MaterialRenderOrder
Controls how the custom material composes with the base text pass on the range.
public Material Material{ get; set }

Gets or sets the custom material. Triggers a mesh rebuild.

public Vector4 ConstantUv2{ get; set }

Constant value written to TEXCOORD2 of every glyph vertex in this modifier's sub-mesh. Use this to animate per-text shader parameters (e.g. dissolve progress, hue offset, flicker phase) without going through Material.Set*, which would affect all texts sharing the cached runtime clone of the material.

public Vector4 ConstantUv3{ get; set }

Constant value written to TEXCOORD3 of every glyph vertex in this modifier's sub-mesh. See ConstantUv2 — same semantics, second channel.

public bool CloneMaterial{ get; set }

When (default), this modifier uses a cached runtime clone of Material — shader property / keyword writes are isolated from the source asset, batching dedup is preserved, and runtime edits to source.SetColor(...) do not propagate to already-rendered text. When the source material is used directly: runtime edits are visible immediately, but the source's keyword state and _MainTex binding become shared with every other consumer — set keywords via the Toggle properties in the shader or Material.EnableKeyword manually.

public MaterialRenderOrder RenderOrder{ get; set }

Controls how the custom material composes with the base text pass on the modifier's ranges: Replace suppresses the base pass (face alpha zeroed); Over / Under keep the base pass and layer the custom material in front of or behind it.

public int SortIndex{ get; set }

Stable sort key within the same RenderOrder group; lower indices render first. Use to deterministically layer multiple MaterialModifier instances with the same render order.

public Material EmojiMaterial{ get; set }

Optional override material for emoji glyphs in the modifier's ranges. (default) means emoji glyphs are rendered by the base emoji pass and the modifier emits no emoji sub-mesh contribution; assigning a material routes emoji quads through the modifier's sub-mesh bound to the emoji atlas.

public float QuadPaddingOverride{ get; set }

Outward em-space padding applied to every sub-mesh quad so shader effects (glow, edge halos, distortion) aren't clipped by the glyph's tight bounding box. Negative reads the value from the bound material's _UniTextMeshPadding property (shader-driven default).

protected bool UseVirtualWriter{ get }

When true, OnQuadAppended calls OnWriteGlyphUV even if glyphDataWriter is null. Set to in subclasses that override OnWriteGlyphUV.

protected override bool ShouldIncludeCurrentGlyph()
protected override Material GetMaterialForSlot()
protected override RenderOrder GetRenderOrder()
protected override int GetSortIndex()
protected override void OnQuadAppended()
protected virtual void OnWriteGlyphUV()

Override to write per-glyph data into the sub-mesh's TEXCOORD2 / TEXCOORD3. Called once per included glyph. Default implementation returns constantUv2 / constantUv3.

protected override void OnEnable()
protected override void OnBeforeRebuild()
public override void PrepareForParallel()
protected override void OnDestroy()
protected override void OnApply()
public MaterialGlyphWriter glyphDataWriter

Optional per-glyph data writer. Takes precedence over OnWriteGlyphUV.

Back to API Reference