Frame Filter Component

Overview

This component enables easily adding a framed outline to UI components. It supports automatic resizing to fit the content, padding, different shapes, anti-aliased rendering, rounded corners and different fill modes.

WebGL Demo

Properties

Property	Type	Range	Default	Description
Shape
Shape	Enum		Rectangle	The base shape to render around the source content. Options are: • Rectangle: Has the most flexibility. • Square: Ensures the frame has equal width and height. • Circle: Ensures the frame has constant radius.
Padding	Float	[-inf..inf]	16.0	For each Rectangle edge expands the edge length in pixels. For Square and Circle shapes this is a single value that controls radius padding.
Pad To Edge	Bool		False	For each Rectangle edge allows padding value to be ignored and instead extends the length to the screen edge.
Corner
Size	Enum		Percent	The type of corner size to use for the Rectangle or Square shapes. Options are: • None: No shaped corners. • Small: 12.5% rounded corners. • Medium: 25% rounded corners. • Large: 50% rounded corners. • Circular: 100% rounded corners • Percent: Value between 0..1 relative to the size of shape. • Custom Percent: Specify each of the 4 corner sizes in 0..1 range. • Pixels: A single value in pixel units. • Custom Pixels: Specifyt each of the 4 corner sizes in pixels.
Shape	Enum		Round	The type of corner shape to use for the Rectangle or Square shapes. Options are: • Round: Rounded corners. • Chamfer: Chamfered corners.
Fill
Fill Mode	Enum		Color	The mode to use to fill the frame background with. Options are: • None: The frame background has no fill. • Color: A single color. • Texture: A texture is used to fill the background. • Gradient: A gradient used to fill the background.
Color	Color		Black	The color to fill the frame with in Color fill mode.
Texture	Texture			The texture to fill the frame with in Texture fill mode.
Gradient	Gradient			The gradient to fill the frame with in Gradient fill mode.
Gradient Shape	Enum		Horizontal	The shape of the gradient in Gradient fill mode. Options are: • Horizontal: Colors run from left to right. • Vertical: Colors run from top to bottom. • Diagonal: Colors run from top-left to bottom-right. • Radial: Colors start in the center and expand in a circle shape. • Linear: Gradient follows the W3C definition for a linear gradient going in the direction specified by an angle. • Conic: Gradient sweeps clockwise from the top middle (12:00 position) based on the angle.
Gradient Scale	Float	[-inf..inf]	1.0	Scale the gradient position.
Gradient Offset	Float	[-inf..inf]	0.0	Offset the gradient position.
Gradient Scroll Speed	Float	[-inf..inf]	0.0	Set an animation speed to offset the gradient.
Radius	Float	[-inf..inf]	1.0	The radius of the gradient in Radial mode.
Angle	Float	[0..360]	0.0	The angle of the gradient in Linear mode.
Softness	Float	[1..inf]	2.0	Softness of the frame. 1 = no softness.
Border
Fill Mode	Enum		Color	The mode to use to fill the frame broder with. Options are: • None: No border. • Color: A single color. • Texture: A texture is used to fill the background. • Gradient: A gradient used to fill the background.
Color	Color		White	The color to fill the frame border with in Color fill mode.
Texture	Texture			The texture to fill the frame border with in Texture fill mode.
Gradient	Gradient			The gradient to fill the frame border with in Gradient fill mode.
Gradient Shape	Enum		Horizontal	The shape of the border gradient in Gradient fill mode. Options are: • Horizontal: Colors run from left to right. • Vertical: Colors run from top to bottom. • Diagonal: Colors run from top-left to bottom-right. • Radial: Colors start in the center and expand in a circle shape. • Linear: Gradient follows the W3C definition for a linear gradient going in the direction specified by an angle. • Conic: Gradient sweeps clockwise from the top middle (12:00 position) based on the angle.
Gradient Scale	Float	[-inf..inf]	1.0	Scale the border gradient position.
Gradient Offset	Float	[-inf..inf]	0.0	Offset the border gradient position.
Gradient Scroll Speed	Float	[-inf..inf]	0.0	Set an animation speed to offset the border gradient.
Radius	Float	[-inf..inf]	1.0	The radius of the border gradient in Radial mode.
Angle	Float	[0..360]	0.0	The angle of the border gradient in Linear mode.
Size	Float	[0..inf]	4.0	The size of the border in pixels.
Softness	Float	[1..inf]	2.0	Softness of the border. 1 = no softness.
Apply
Cutout Source	Bool		False	Whether to render the source graphic on top of the frame, or to use the source graphic to make a hole in the frame.
Strength	Float	[0..1]	1.0	Strength of the effect.
Render Space	Enum		Canvas	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.
Source Area	Enum		Geometry	Changing this to RectTransform will make the bounds of the frame conform to the RectTransform area.
Expand	Enum		Expand	Whether to expand the Graphic area to accomodate this filter overflowing the original bounds. Setting this to None can be useful whhen applying effects to content you want to enclose in a frame using something like the FrameFilter component.

Usage

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

Usage with TextMeshPro

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

Render Space

The RenderSpace property effectively controls whether the filter is rendered before or after the Transform is applied. There are two options:

• Canvas - This is the default mode for all filters. In this mode the filter is rendered to the Graphic before it is transformed into screen-space by the local Transform and by the Canvas. This means that any changes or animations to the transform (or it's parents) will not cause the filter to re-render (unless Canvas has pixel-perfect mode enabled), which is a performance benefit! This also means that when the Graphic is rotated, the filter will not be aware of this, so the filter will rotate as well.
• Screen - This was the default mode before version 1.8.0 was released. In this mode the filter is rendered to the Graphic after it is transformed into screne-space. This means that any changes or animations to the transform (or it's parents) will cause the filter to re-render which can become expensive. It has the advantage that it is possible to do some screen-aware options, such as clamping the filter to the edges of the screen, or extending an edge to the edge of the screen (for example in the Frame Filter component)

RenderSpace Rotation Example

In the above example you can see that Canvas RenderSpace renders the filters before the transforms are applied, so the drop shadow offset rotates with text and it is only rendered once which is good for performance. In the Screen RenderSpace the filter is rendered after the transform is applies, so the drop shadow offset is not affected by the transform (both situations are valid depending on the use-case), however each time the transform is updated the filter must render which is more expensive.

RenderSpace Scaling Example

Again in this example we can see that transform affects how often the filters are rendered. This example also shows how scaling looks in the two RenderSpace modes. In Canvas mode the scaling transform is applied after the filter, so the drop shadow distance appears to scale naturally. In the Screen mode, the scaling transform is applied before the filter, so the filter is using unscaled distance values so the drop shadow offset appears incorrect when scaled as the properties are in screen-space. This is also why the FilterStackTextMeshPro component has the Relative To Transform Scale property.

RenderSpace Canvas Example

In Unity it is common to use the Canvas Scaler component to allow the UI to scale to fit different device resolutions. UIFX supports this, but there are some subtle differences depending on the RenderSpace mode used. If you don't use the Canvas Scaler component, or your device resolution is the same as the Canvas Scaler reference resolution, then UIFX will render the filters at the same resolution in both Canvas and Screen RenderSpace modes. If however your device resolution is lower than the reference resolution (eg reference is 1080p but your device is 720p), then Canvas mode will still render the filter at the same resolution before, but Screen mode will render it at half the resolution. This means Screen mode will use less texture memory and will be faster. If your device resolkution is higher than the reference resolution (eg reference is 1080p but your device is 4K), then Canvas mode will still render the filter at the same resolution as before, but Screen mode will render at double the resolution. This means Screen mode will use double the texture memory compared to Canvas, however it also means that Screen will give slightly better quality results.

For example if you have reference resolution on the Canvas Scaler set to 1920x1080 and you have a UI text object is 400x200 on the screen with a filter applied to it:

• if your output resolution is 1920x1080, UIFX will render the filters at 400x200.
• if your output resolution is 3840x2160, UIFX will render the filter at 400x200 if it's in Canvas mode because the object is still 400x200 relative to the renference resolution - but in Screen mode it will render it at 800x400 because that is the size it will be on the screen.
• if your output resolution is 1280x720, UIFX will render the filter at 400x200 if it's in Canvas mode because the object is still 400x200 relative to the renference resolution - but in Screen mode it will render it at 266x133 because that is the size it will be on the screen.

Summary

A summary of the differences:

Feature	Canvas	Screen
Adjusting local/parent transforms causes filter re-render	No (unless Canvas has pixel-perfect mode enabled)	Yes
In WorldSpace Canvas adjusting camera transform causes filter re-render	No	Yes
Best performance when using ScrollRect	Yes	No
Filter offset/direction properties affected by rotation	Yes	No
Filter offset/direction properties affected by scale	Yes	No
Filter rendering resolution scales with screen resolution	No	Yes

In general, Canvas is usually the best option in terms of balance between performance, memory usage and functionlity. If you need higher quality rendering because you are targeting higher resolution devices than your reference resolution (on Canvas Scaler component), then use Screen mode. If you need the filter offset/direction properties to always run in screen-space (ie not be affected by rotation or other transforms), then use Screen mode.