Class CanvasScaler

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
UIBehaviour
CanvasScaler
Inherited Members
Component.GetComponent<T>()
Component.TryGetComponent<T>(out T)
Component.GetComponentInChildren<T>()
Component.GetComponentsInChildren<T>()
Component.GetComponentInParent<T>()
Component.GetComponentsInParent<T>()
Component.GetComponents<T>()
Object.GetHashCode()
Object.InstantiateAsync<T>(T)
Object.InstantiateAsync<T>(T, Transform)
Object.InstantiateAsync<T>(T, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, Transform, Vector3, Quaternion)
Object.Instantiate<T>(T)
Object.Instantiate<T>(T, Vector3, Quaternion)
Object.Instantiate<T>(T, Vector3, Quaternion, Transform)
Object.Instantiate<T>(T, Transform)
Object.DestroyObject(Object)
Object.FindObjectsOfType<T>()
Object.FindObjectsByType<T>(FindObjectsSortMode)
Object.FindObjectsByType<T>(FindObjectsInactive, FindObjectsSortMode)
Object.FindObjectOfType<T>()
Object.FindFirstObjectByType<T>()
Object.FindAnyObjectByType<T>()
Object.FindFirstObjectByType<T>(FindObjectsInactive)
Object.FindAnyObjectByType<T>(FindObjectsInactive)
Namespace: UnityEngine.UI
Assembly: UnityEngine.UI.dll
Syntax
[RequireComponent(typeof(Canvas))]
[ExecuteAlways]
[AddComponentMenu("Layout/Canvas Scaler", 101)]
[DisallowMultipleComponent]
public class CanvasScaler : UIBehaviour

Constructors

CanvasScaler()

Declaration
protected CanvasScaler()

Fields

m_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_DefaultSpriteDPI
Field Value
Type Description
float

m_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_DynamicPixelsPerUnit
Field Value
Type Description
float

m_FallbackScreenDPI

Declaration
[Tooltip("The DPI to assume if the screen DPI is not known.")]
[SerializeField]
protected float m_FallbackScreenDPI
Field Value
Type Description
float

m_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_MatchWidthOrHeight
Field Value
Type Description
float

m_PhysicalUnit

Declaration
[Tooltip("The physical unit to specify positions and sizes in.")]
[SerializeField]
protected CanvasScaler.Unit m_PhysicalUnit
Field Value
Type Description
CanvasScaler.Unit

m_PresetInfoIsWorld

Declaration
[SerializeField]
protected bool m_PresetInfoIsWorld
Field Value
Type Description
bool

m_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_ReferencePixelsPerUnit
Field Value
Type Description
float

m_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_ReferenceResolution
Field Value
Type Description
Vector2

m_ScaleFactor

Declaration
[Tooltip("Scales all UI elements in the Canvas by this factor.")]
[SerializeField]
protected float m_ScaleFactor
Field Value
Type Description
float

m_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_ScreenMatchMode
Field 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()

Declaration
protected override void OnDisable()
Overrides

OnEnable()

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.