[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
Single

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
Single

m_FallbackScreenDPI

Declaration

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

Field Value

Type	Description
Single

m_MatchWidthOrHeight

Declaration

[Tooltip("Determines if the scaling is using the width or height as reference, or a mix in between.")]
[Range(0F, 1F)]
[SerializeField]
protected float m_MatchWidthOrHeight

Field Value

Type	Description
Single

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
Boolean

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
Single

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
Single

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
Single

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
Single

fallbackScreenDPI

The DPI to assume if the screen DPI is not known.

Declaration

public float fallbackScreenDPI { get; set; }

Property Value

Type	Description
Single

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
Single

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
Single

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
Single

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

UIBehaviour.OnDisable()

OnEnable()

Declaration

protected override void OnEnable()

Overrides

UIBehaviour.OnEnable()

SetReferencePixelsPerUnit(Single)

Sets the referencePixelsPerUnit on the Canvas.

Declaration

protected void SetReferencePixelsPerUnit(float referencePixelsPerUnit)

Parameters

Type	Name	Description
Single	referencePixelsPerUnit	The new reference pixels per Unity value

SetScaleFactor(Single)

Sets the scale factor on the canvas.

Declaration

protected void SetScaleFactor(float scaleFactor)

Parameters

Type	Name	Description
Single	scaleFactor	The scale factor to use.

Extension Methods

UIBehaviourExtensions.InvokeOnEnable(UIBehaviour)

UIBehaviourExtensions.InvokeOnDisable(UIBehaviour)

UIBehaviourExtensions.InvokeAwake(UIBehaviour)

UIBehaviourExtensions.InvokeRebuild(UIBehaviour, CanvasUpdate)

UIBehaviourExtensions.InvokeLateUpdate(UIBehaviour)

UIBehaviourExtensions.InvokeUpdate(UIBehaviour)

UIBehaviourExtensions.InvokeOnRectTransformDimensionsChange(UIBehaviour)

UIBehaviourExtensions.InvokeOnCanvasGroupChanged(UIBehaviour)

UIBehaviourExtensions.InvokeOnDidApplyAnimationProperties(UIBehaviour)