Grayscale Image

Shader-based Image element that renders in greyscale with adjustable intensity.

Utilities utilities image grayscale shader effect

1 Overview

2 Properties

3 USS Classes

4 Events

5 Methods

6 Usage

7 Using the Control

8 Example Scenes

9 Credits and Donation

10 External links

Overview

GrayscaleImage is an ImmediateModeElement that renders a sprite or texture using Graphics.DrawTexture and supports toggling a greyscale effect via a material property. The greyscale effect requires a custom Material that exposes _MainTex and _GreyscaleEnabled shader properties; without a compatible material the image renders in full color only.

Typical use cases:

Profile or media images that switch to greyscale when disabled or locked
Toggling greyscale on achievement/badge imagery for locked states
Any image that needs a shader-driven color/greyscale toggle without a separate texture asset

Properties

Name	Description	Options
`SpriteProperty`	The `Sprite` to render. Mutually exclusive with `TextureProperty`.	`Sprite`
`TextureProperty`	The `Texture` to render. Mutually exclusive with `SpriteProperty`.	`Texture`
`scaleMode`	How the image is scaled within its bounds.	`ScaleMode`
`Material`	The material used for rendering. Must expose `_MainTex` and `_GreyscaleEnabled` for the greyscale feature.	`Material`
`GreyscaleEnabled`	Gets or sets whether the greyscale shader effect is active. Only functional when a compatible material is assigned.	`bool`
`MainTextureProperty`	The shader property name for the main texture.	`string` (default `"_MainTex"`)
`GreyscaleToggleProperty`	The shader property name for the greyscale toggle.	`string` (default `"_GreyscaleEnabled"`)

Constants

Name	Value	Description
`DefaultMainTextureProperty`	`"_MainTex"`	Default shader property name for the main texture.
`DefaultGreyscaleToggleProperty`	`"_GreyscaleEnabled"`	Default shader property name for the greyscale toggle.

USS Classes

Class	Description
`grayscaleImage`	Root element. Dimensions should be set via USS or inline style; the element uses its resolved layout rect for `Graphics.DrawTexture`.

Events

This control does not emit events. Repaint is triggered automatically by the immediate-mode element lifecycle.

Methods

This control exposes its API entirely through properties. No additional public methods are defined beyond those inherited from ImmediateModeElement.

Usage

Add the control to your scene using:

GameObject -> UI Toolkit -> Extensions -> Grayscale Image

This creates a UIDocument in the scene (plus a PanelSettings with the default runtime theme, if the project has none) and assigns an editable starter template with demo content, copied to Assets/UI Toolkit Extensions.

A starter template can also be added to an existing document using:

Assets -> Create -> UI Toolkit -> Extensions -> Grayscale Image Starter

Alternatively, drag the control into a document from the UI Builder Library (Project -> Custom Controls -> UnityUIToolkit.Extensions) or declare it directly in UXML:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:ext="UnityUIToolkit.Extensions" editor-extension-mode="False">
    <ext:GrayscaleImage scale-mode="ScaleToFit" greyscale-enabled="true" />
</ui:UXML>

The shared extensions stylesheet is applied automatically when the control is created in the Editor and in Play Mode, so no manual stylesheet reference is needed while authoring. The starter templates also reference the stylesheet explicitly, which covers player builds; for hand-written UXML or code-first UI in builds, add the stylesheet to your UXML or panel theme.

Using the Control

Toggle Greyscale on a Locked Achievement

using UnityEngine;
using UnityEngine.UIElements;
using UnityUIToolkit.Extensions;

public class AchievementBadgeController : MonoBehaviour
{
    [SerializeField] private UIDocument _document;
    [SerializeField] private Sprite _badgeSprite;
    [SerializeField] private Material _greyscaleMaterial; // shader with _MainTex + _GreyscaleEnabled

    private GrayscaleImage _badgeImage;

    private void OnEnable()
    {
        var root = _document.rootVisualElement;

        _badgeImage = new GrayscaleImage();
        _badgeImage.style.width = 80;
        _badgeImage.style.height = 80;
        _badgeImage.SpriteProperty = _badgeSprite;
        _badgeImage.Material = _greyscaleMaterial;
        _badgeImage.scaleMode = ScaleMode.ScaleToFit;

        root.Q<VisualElement>("badgeContainer").Add(_badgeImage);
    }

    public void SetLocked(bool locked)
    {
        _badgeImage.GreyscaleEnabled = locked;
    }
}

Texture-Based Rendering with Custom Property Names

// If your shader uses different property names:
_badgeImage.MainTextureProperty = "_BaseMap";
_badgeImage.GreyscaleToggleProperty = "_UseGreyscale";
_badgeImage.TextureProperty = _photoTexture;
_badgeImage.GreyscaleEnabled = true;

Example Scenes

This control is demonstrated in the following package example:

Profile Editor

Credits and Donation

SimonDarksideJ

External links

UI Toolkit Extensions repository

OpenUPM package

Demonstrated In

Profile Editor — An editable profile screen with an avatar, toggles, and colour-tinted option groups.

Contents