Class PanelSettings

Defines a Panel Settings asset that instantiates a panel at runtime. The panel makes it possible for Unity to display UXML-file based UI in the Game view.

Inheritance

Object

PanelSettings

Namespace: UnityEngine.UIElements

Syntax

public class PanelSettings : ScriptableObject

Fields

textSettings

Specifies a PanelTextSettings that will be used by every UI Document attached to the panel.

Declaration

public PanelTextSettings textSettings

Field Value

Type	Description
PanelTextSettings

Properties

clearColor

Determines whether the color buffer is cleared before the panel is rendered.

Declaration

public bool clearColor { get; set; }

Property Value

Type	Description
Boolean

clearDepthStencil

Determines whether the depth/stencil buffer is cleared before the panel is rendered.

Declaration

public bool clearDepthStencil { get; set; }

Property Value

Type	Description
Boolean

colorClearValue

The color used to clear the color buffer.

Declaration

public Color colorClearValue { get; set; }

Property Value

Type	Description
Color

Remarks

The color is specified as a "straight" color but will internally be converted to "premultiplied" before being applied.

depthClearValue

The depth used to clear the depth/stencil buffer.

Declaration

public float depthClearValue { get; }

Property Value

Type	Description
Single

dynamicAtlasSettings

Settings of the dynamic atlas.

Declaration

public DynamicAtlasSettings dynamicAtlasSettings { get; set; }

Property Value

Type	Description
DynamicAtlasSettings

fallbackDpi

The DPI value that Unity uses when it cannot determine the screen DPI.

Declaration

public float fallbackDpi { get; set; }

Property Value

Type	Description
Single

match

Determines whether Unity uses width, height, or a mix of the two as a reference when it scales the panel area.

Declaration

public float match { get; set; }

Property Value

Type	Description
Single

referenceDpi

The DPI that the UI is designed for.

Declaration

public float referenceDpi { get; set; }

Property Value

Type	Description
Single

Remarks

When scaleMode is set to ConstantPhysicalSize, Unity compares this value to the actual screen DPI, and scales the UI accordingly in the Game view.

If Unity cannot determine the screen DPI, it uses the fallbackDpi instead.

referenceResolution

The resolution the UI is designed for.

Declaration

public Vector2Int referenceResolution { get; set; }

Property Value

Type	Description
Vector2Int

Remarks

If the screen resolution is larger than the reference resolution, Unity scales the UI up in the Game view. If it's smaller, Unity scales the UI down. Unity scales the UI according to the screenMatchMode.

scale

A uniform scaling factor that Unity applies to elements in the panel before the panel transform.

Declaration

public float scale { get; set; }

Property Value

Type	Description
Single

Remarks

This value must be greater than 0.

scaleMode

Determines how elements in the panel scale when the screen size changes.

Declaration

public PanelScaleMode scaleMode { get; set; }

Property Value

Type	Description
PanelScaleMode

screenMatchMode

Specifies how to scale the panel area when the aspect ratio of the current resolution does not match the reference resolution.

Declaration

public PanelScreenMatchMode screenMatchMode { get; set; }

Property Value

Type	Description
PanelScreenMatchMode

sortingOrder

When the Scene uses more than one panel, this value determines where this panel appears in the sorting order relative to other panels.

Declaration

public float sortingOrder { get; set; }

Property Value

Type	Description
Single

Remarks

Unity renders panels with a higher sorting order value on top of panels with a lower value.

targetDisplay

When the Scene uses more than one panel, this value determines where this panel appears in the sorting order relative to other panels.

Declaration

public int targetDisplay { get; set; }

Property Value

Type	Description
Int32

Remarks

Unity renders panels with a higher sorting order value on top of panels with a lower value.

targetTexture

Specifies a Render Texture to render the panel's UI on.

Declaration

public RenderTexture targetTexture { get; set; }

Property Value

Type	Description
RenderTexture

Remarks

This is useful when you want to display UI on 3D geometry in the Scene. For an example of UI displayed on 3D objects via renderTextures, see the UI Toolkit samples (menu: Window > UI Toolkit > Examples > Rendering > RenderTexture (Runtime)).

themeStyleSheet

Specifies a style sheet that Unity applies to every UI Document attached to the panel.

Declaration

public ThemeStyleSheet themeStyleSheet { get; set; }

Property Value

Type	Description
ThemeStyleSheet

Remarks

By default this is the main Unity style sheet, which contains default styles for Unity-supplied elements such as buttons, sliders, and text fields.

Methods

SetScreenToPanelSpaceFunction(Func<Vector2, Vector2>)

Sets the function that handles the transformation from screen space to panel space. For overlay panels, this function returns the input value.

Declaration

public void SetScreenToPanelSpaceFunction(Func<Vector2, Vector2> screentoPanelSpaceFunction)

Parameters

Type	Name	Description
Func<Vector2, Vector2>	screentoPanelSpaceFunction	The translation function. Set to null to revert to the default behavior.

Remarks

If the panel's targetTexture is applied to 3D objects, one approach is to use a function that raycasts against MeshColliders in the Scene. The function can first check whether the GameObject that the ray hits has a MeshRenderer with a shader that uses this panel's target texture. It can then return the transformed RaycastHit.textureCoord in the texture's pixel space.

For an example of UI displayed on 3D objects via renderTextures, see the UI Toolkit samples (menu: Window > UI Toolkit > Examples > Rendering > RenderTexture (Runtime)).