Class CanvasScaler
Inherited Members
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. |