Blur Filter Component

Overview

This component applies a blur filter to the UI object it is applied to.

WebGL Demo

Properties

Property	Type	Details
Blur
Algorithm	Enum	The blur algorithm to use. This affects the visual style of the blur as well as the quality and performance. Options are: • Box - The most basic filter resulting in a boxy blur result. At large blur radius this method will be slower than MultiBox. • Tent - Produces better quality blur compared to Box, but not quite as good as MultiBox, but it only uses a single render pass (like Box). Doesn't use downsampling (as MultiBox does), so for larger texture sizes this may be slower than MultiBox. • MultiBox - Multiple box filters gives a very close approximation of the smooth Gaussian blur but at a much lower cost. (DEFAULT) • Gaussian - Highest quality but also most expensive to render.
Down Sample	Enum	How to downsample the texture before blurring. Downsampling gives improved performance, however the quality can be lower especially when animation the blur amount, but for still images it's usually not noticeable. Options are: • Auto - Automatic downsampling will depend on the platform. Typically mobile platforms will get a half downsample. (DEFAULT) • None - No downsampling. • Half - Downsample to half the size. • Quarter - Downsample to a quarter the size. • Eighth - Downsample to an eighth the size.
Axes	Enum	The 2D axes to blur. Options are: • Both - Both horizontal and vertical blurring. (DEFAULT) • Horizontal - Only horizontal blurring. • Vertical - Only vertical blurring.
Blur	Float	Represents the maximum amount of blur (at Strength == 1.0). The value represents a fraction of the screen size that the Graphic occupies. So a value of 0.1 would create a blur with a kernel width 10% of the image width/height. Default value is 0.01, range is [0..0.1].
Falloff	Float	The falloff factor for the Tent Algorithm mode. Value 0.0 produces the same results as the Box filter algorithm. Value 1.5 is close to the MultiBox/Gaussian algorithms.
Apply
Apply Alpha Curve	Bool	Allows easy toggling between using the Alpha Curve to control transparency or not, without losing the set curve. Default to enabled.
Alpha Curve	Curve	Optional curve to control transparency. The curve ranges from time [0..1] and value [0..1] and is useful for fading down the visual as the Strength increases.
Strength	Float	Strength of the effect. Default value is 1.0, range is [0..1]
Render Space	Enum	Which coordinate system use when rendering this filter. Options are: • Canvas: Render the filter before any transforms (scale/rotation/translation etc) are applied. • Screen: Render the filter after transforms have been applied. Read more about this property here.
Expand	Enum
Global
Strength	Float	Global Strength scale applied to Strength all BlurFilter effects. Default value is 1.0, range is [0..1]

Usage

Add this component to any GameObject that contains a UI Graphic component (eg Text, Image, RawImage, etc). The object will now render with an adjustable blur effect applied.

Usage with TextMeshPro

To use this filter effect with TextMeshPro - Text (UI) use the Filter Stack (TextMeshPro) component.

Examples

There are three axes/directions the blur can use which creates different effects:

Default

Horizontal Axis

Vertical Axis

Focus Effect

By animating the blur Strength property on multiple UI elements a fake camera depth-of-field focus effect can be achieved.

Fade Transition

Alpha Curve can specify the transparency of the effect linked to the Strength property which can be useful for creating appear/disappear transitions.

Scripting

Namespace

The namespace

using ChocDino.UIFX;

Adding Component

Add the BlurFilter component to your GameObject

// Add the component to your GameObject and set default properties
var blur = AddComponent<BlurFilter>();

blur.BeginPropertyChange();
blur.Algorithm = BlurAlgorithm.MultiBox;
blur.Downsample = Downsample.Auto;
blur.Blur = 4f;
blur.BlurAxes2D = BlurAxes2D.Default;
blur.ApplyAlphaCurve = false;
blur.AlphaCurve = new AnimationCurve(new Keyframe(0f, 1f, -1f, -1f), new Keyframe(1f, 0f, -1f, -1f));  // AlphaCurve is optional and can be null
blur.Strength = 1f;
blur.EndPropertyChange();

Global Blur Strength

Globally scale all BlurFilter Strength

BlurFilter.GlobalStrength = 0.5f;

Complete Example

BlurExample.cs

using UnityEngine;
using ChocDino.UIFX;

/// Demonstrates the scripting API for the BlurFilter component

/// Press keys 1 to 5 to test some API functionality.

/// NOTE: The GameObject is required to have a UI component of type Graphic
[RequireComponent(typeof(Graphic))]
public class BlurExample : MonoBehaviour
{
	private BlurFilter _blur;
	private float _blurTarget = 0f;

	void Start()
	{
		// Get or create the component
		_blur = GetComponent<BlurEffect>();
		if (_blur == null)
		{
			_blur = AddComponent<BlurFilter>();
		}
	}

	void Update()
	{
		// Keys 1..5 demonstrate some API functionality
		if (Input.GetKeyDown(KeyCode.Alpha1))
		{
			_blur.BlurAxes2D = BlurAxes2D.Default;
		}
		else if (Input.GetKeyDown(KeyCode.Alpha2))
		{
			_blur.BlurAxes2D = BlurAxes2D.Horizontal;
		}
		else if (Input.GetKeyDown(KeyCode.Alpha3))
		{
			_blur.BlurAxes2D = BlurAxes2D.Vertical;
		}
		else if (Input.GetKeyDown(KeyCode.Alpha4))
		{
			_blurTarget = 0f;
		}
		else if (Input.GetKeyDown(KeyCode.Alpha5))
		{
			_blurTarget = 1f;
		}

		// Animate blur towards target amount
		if (_blur.Strength != _blurTarget)
		{
			_blur.Strength = Mathf.MoveTowards(_blur.Strength, _blurTarget, Time.deltaTime);
		}
	}
}