Class CanvasScaler
The Canvas Scaler component is used for controlling the overall scale and pixel density of UI elements in the Canvas. This scaling affects everything under the Canvas, including font sizes and image borders.
Inherited Members
Namespace: UnityEngine.UI
Assembly: UnityEngine.UI.dll
Syntax
[RequireComponent(typeof(Canvas))]
[ExecuteAlways]
[AddComponentMenu("Layout/Canvas Scaler", 101)]
[DisallowMultipleComponent]
public class CanvasScaler : UIBehaviourRemarks
For a Canvas set to 'Screen Space - Overlay' or 'Screen Space - Camera', the Canvas Scaler UI Scale Mode can be set to Constant Pixel Size, Scale With Screen Size, or Constant Physical Size.
Using the Constant Pixel Size mode, positions and sizes of UI elements are specified in pixels on the screen. This is also the default functionality of the Canvas when no Canvas Scaler is attached. However, With the Scale Factor setting in the Canvas Scaler, a constant scaling can be applied to all UI elements in the Canvas.
Using the Scale With Screen Size mode, positions and sizes can be specified according to the pixels of a specified reference resolution. If the current screen resolution is larger than the reference resolution, the Canvas will keep having only the resolution of the reference resolution, but will scale up in order to fit the screen. If the current screen resolution is smaller than the reference resolution, the Canvas will similarly be scaled down to fit. If the current screen resolution has a different aspect ratio than the reference resolution, scaling each axis individually to fit the screen would result in non-uniform scaling, which is generally undesirable. Instead of this, the ReferenceResolution component will make the Canvas resolution deviate from the reference resolution in order to respect the aspect ratio of the screen. It is possible to control how this deviation should behave using the ::ref::screenMatchMode setting.
Using the Constant Physical Size mode, positions and sizes of UI elements are specified in physical units, such as millimeters, points, or picas. This mode relies on the device reporting its screen DPI correctly. You can specify a fallback DPI to use for devices that do not report a DPI.
For a Canvas set to 'World Space' the Canvas Scaler can be used to control the pixel density of UI elements in the Canvas.
Constructors
CanvasScaler()
Protected default constructor. Use UnityEngine.GameObject.AddComponent<T>() to add a CanvasScaler to a GameObject.
Declaration
protected CanvasScaler()Fields
m_DefaultSpriteDPI
Serialized backing field for defaultSpriteDPI.
Declaration
[Tooltip("The pixels per inch to use for sprites that have a 'Pixels Per Unit' setting that matches the 'Reference Pixels Per Unit' setting.")]
[SerializeField]
protected float m_DefaultSpriteDPIField Value
| Type | Description |
|---|---|
| float |
m_DynamicPixelsPerUnit
Serialized backing field for dynamicPixelsPerUnit.
Declaration
[Tooltip("The amount of pixels per unit to use for dynamically created bitmaps in the UI, such as Text.")]
[SerializeField]
protected float m_DynamicPixelsPerUnitField Value
| Type | Description |
|---|---|
| float |
m_FallbackScreenDPI
Serialized backing field for fallbackScreenDPI.
Declaration
[Tooltip("The DPI to assume if the screen DPI is not known.")]
[SerializeField]
protected float m_FallbackScreenDPIField Value
| Type | Description |
|---|---|
| float |
m_MatchWidthOrHeight
Serialized backing field for matchWidthOrHeight.
Declaration
[Tooltip("Determines if the scaling is using the width or height as reference, or a mix in between.")]
[Range(0, 1)]
[SerializeField]
protected float m_MatchWidthOrHeightField Value
| Type | Description |
|---|---|
| float |
m_PhysicalUnit
Serialized backing field for physicalUnit.
Declaration
[Tooltip("The physical unit to specify positions and sizes in.")]
[SerializeField]
protected CanvasScaler.Unit m_PhysicalUnitField Value
| Type | Description |
|---|---|
| CanvasScaler.Unit |
m_PresetInfoIsWorld
Flag indicating whether the Canvas is in World Space mode.
Declaration
[SerializeField]
protected bool m_PresetInfoIsWorldField Value
| Type | Description |
|---|---|
| bool |
m_ReferencePixelsPerUnit
Serialized backing field for referencePixelsPerUnit.
Declaration
[Tooltip("If a sprite has this 'Pixels Per Unit' setting, then one pixel in the sprite will cover one unit in the UI.")]
[SerializeField]
protected float m_ReferencePixelsPerUnitField Value
| Type | Description |
|---|---|
| float |
m_ReferenceResolution
Serialized backing field for referenceResolution.
Declaration
[Tooltip("The resolution the UI layout is designed for. If the screen resolution is larger, the UI will be scaled up, and if it's smaller, the UI will be scaled down. This is done in accordance with the Screen Match Mode.")]
[SerializeField]
protected Vector2 m_ReferenceResolutionField Value
| Type | Description |
|---|---|
| Vector2 |
m_ScaleFactor
Serialized backing field for scaleFactor.
Declaration
[Tooltip("Scales all UI elements in the Canvas by this factor.")]
[SerializeField]
protected float m_ScaleFactorField Value
| Type | Description |
|---|---|
| float |
m_ScreenMatchMode
Serialized backing field for screenMatchMode.
Declaration
[Tooltip("A mode used to scale the canvas area if the aspect ratio of the current resolution doesn't fit the reference resolution.")]
[SerializeField]
protected CanvasScaler.ScreenMatchMode m_ScreenMatchModeField Value
| Type | Description |
|---|---|
| CanvasScaler.ScreenMatchMode |
Properties
defaultSpriteDPI
The pixels per inch to use for sprites that have a 'Pixels Per Unit' setting that matches the 'Reference Pixels Per Unit' setting.
Declaration
public float defaultSpriteDPI { get; set; }Property Value
| Type | Description |
|---|---|
| float |
dynamicPixelsPerUnit
The amount of pixels per unit to use for dynamically created bitmaps in the UI, such as Text.
Declaration
public float dynamicPixelsPerUnit { get; set; }Property Value
| Type | Description |
|---|---|
| float |
fallbackScreenDPI
The DPI to assume if the screen DPI is not known.
Declaration
public float fallbackScreenDPI { get; set; }Property Value
| Type | Description |
|---|---|
| float |
matchWidthOrHeight
Setting to scale the Canvas to match the width or height of the reference resolution, or a combination.
Declaration
public float matchWidthOrHeight { get; set; }Property Value
| Type | Description |
|---|---|
| float |
Remarks
If the setting is set to 0, the Canvas is scaled according to the difference between the current screen resolution width and the reference resolution width. If the setting is set to 1, the Canvas is scaled according to the difference between the current screen resolution height and the reference resolution height.
For values in between 0 and 1, the scaling is based on a combination of the relative width and height.
Consider an example where the reference resolution of 640x480, and the current screen resolution is a landscape mode of 480x640.
If the scaleWidthOrHeight setting is set to 0, the Canvas is scaled by 0.75 because the current resolution width of 480 is 0.75 times the reference resolution width of 640. The Canvas resolution gets a resolution of 640x853.33. This resolution has the same width as the reference resolution width, but has the aspect ratio of the current screen resolution. Note that the Canvas resolution of 640x853.33 is the current screen resolution divided by the scale factor of 0.75.
If the scaleWidthOrHeight setting is set to 1, the Canvas is scaled by 1.33 because the current resolution height of 640 is 1.33 times the reference resolution height of 480. The Canvas resolution gets a resolution of 360x480. This resolution has the same height as the reference resolution width, but has the aspect ratio of the current screen resolution. Note that the Canvas resolution of 360x480 is the current screen resolution divided by the scale factor of 1.33.
If the scaleWidthOrHeight setting is set to 0.5, we find the horizontal scaling needed (0.75) and the vertical scaling needed (1.33) and find the average. However, we do the average in logarithmic space. A regular average of 0.75 and 1.33 would produce a result of 1.04. However, since multiplying by 1.33 is the same as diving by 0.75, the two scale factor really corresponds to multiplying by 0.75 versus dividing by 0.75, and the average of those two things should even out and produce a neutral result. The average in logarithmic space of 0.75 and 1.33 is exactly 1.0, which is what we want. The Canvas resolution hence ends up being 480x640 which is the current resolution divided by the scale factor of 1.0.
The logic works the same for all values. The average between the horizontal and vertical scale factor is a weighted average based on the matchWidthOrHeight value.
physicalUnit
The physical unit to specify positions and sizes in.
Declaration
public CanvasScaler.Unit physicalUnit { get; set; }Property Value
| Type | Description |
|---|---|
| CanvasScaler.Unit |
referencePixelsPerUnit
If a sprite has this 'Pixels Per Unit' setting, then one pixel in the sprite will cover one unit in the UI.
Declaration
public float referencePixelsPerUnit { get; set; }Property Value
| Type | Description |
|---|---|
| float |
referenceResolution
The resolution the UI layout is designed for.
Declaration
public Vector2 referenceResolution { get; set; }Property Value
| Type | Description |
|---|---|
| Vector2 |
Remarks
If the screen resolution is larger, the UI will be scaled up, and if it's smaller, the UI will be scaled down. This is done in accordance with the Screen Match Mode.
scaleFactor
Scales all UI elements in the Canvas by this factor.
Declaration
public float scaleFactor { get; set; }Property Value
| Type | Description |
|---|---|
| float |
screenMatchMode
A mode used to scale the canvas area if the aspect ratio of the current resolution doesn't fit the reference resolution.
Declaration
public CanvasScaler.ScreenMatchMode screenMatchMode { get; set; }Property Value
| Type | Description |
|---|---|
| CanvasScaler.ScreenMatchMode |
uiScaleMode
Determines how UI elements in the Canvas are scaled.
Declaration
public CanvasScaler.ScaleMode uiScaleMode { get; set; }Property Value
| Type | Description |
|---|---|
| CanvasScaler.ScaleMode |
Methods
Handle()
Method that handles calculations of canvas scaling.
Declaration
protected virtual void Handle()HandleConstantPhysicalSize()
Handles canvas scaling for a constant physical size.
Declaration
protected virtual void HandleConstantPhysicalSize()HandleConstantPixelSize()
Handles canvas scaling for a constant pixel size.
Declaration
protected virtual void HandleConstantPixelSize()HandleScaleWithScreenSize()
Handles canvas scaling that scales with the screen size.
Declaration
protected virtual void HandleScaleWithScreenSize()HandleWorldCanvas()
Handles canvas scaling for world canvas.
Declaration
protected virtual void HandleWorldCanvas()OnDisable()
Called when it becomes disabled. Resets the Canvas to its default scale.
Declaration
protected override void OnDisable()Overrides
OnEnable()
Called when it becomes enabled. Applies the initial canvas scaling.
Declaration
protected override void OnEnable()Overrides
OnValidate()
Declaration
protected override void OnValidate()Overrides
SetReferencePixelsPerUnit(float)
Sets the referencePixelsPerUnit on the Canvas.
Declaration
protected void SetReferencePixelsPerUnit(float referencePixelsPerUnit)Parameters
| Type | Name | Description |
|---|---|---|
| float | referencePixelsPerUnit | The new reference pixels per Unity value |
SetScaleFactor(float)
Sets the scale factor on the canvas.
Declaration
protected void SetScaleFactor(float scaleFactor)Parameters
| Type | Name | Description |
|---|---|---|
| float | scaleFactor | The scale factor to use. |