Class UIUtil

Provides general utility methods for uGUI operations including DPI-aware scaling, Unity layer management, GameObject creation, and coordinate conversion helpers.

Inheritance

object

UIUtil

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.UI

Assembly: ScyllaCore.dll

Syntax

public static class UIUtil

Remarks

DPI scaling methods use STANDARD_DPI (96 DPI) as the baseline. On devices where Screen.dpi returns zero or a negative value the scale factor falls back to 1.0.

Layer management methods look up the Unity layer named UI_LAYER_NAME once and cache the result. If the project does not define a layer with that name a warning is logged and the operation returns false.

Object-creation helpers always attach a RectTransform component and assign the created GameObject to the UI layer automatically.

Fields

STANDARD_DPI

Standard DPI baseline (96 DPI) used for scale-factor calculations. A display that reports exactly 96 DPI yields a scale factor of 1.0.

Declaration

public const float STANDARD_DPI = 96

Field Value

Type	Description
float

UI_LAYER_NAME

Name of the default UI layer in Unity. Used by layer assignment helpers when looking up the layer ID via LayerMask.NameToLayer.

Declaration

public const string UI_LAYER_NAME = "UI"

Field Value

Type	Description
string

Methods

AddToUILayer(GameObject)

Assigns the specified GameObject to the UI layer by setting its layer property. Only the root GameObject is affected; children are not changed. Use AddToUILayerRecursive(GameObject) to assign the entire hierarchy.

Declaration

public static bool AddToUILayer(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to assign. Passing null is safe and returns false.

Returns

Type	Description
bool	true if the GameObject was successfully assigned to the UI layer; false if gameObject is null or the UI layer does not exist in the project.

AddToUILayerRecursive(GameObject)

Assigns the specified GameObject and every descendant in its hierarchy to the UI layer. This is equivalent to calling AddToUILayer(GameObject) on the root and each child recursively.

Declaration

public static bool AddToUILayerRecursive(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The root GameObject whose entire hierarchy will be reassigned. Passing null is safe and returns false.

Returns

Type	Description
bool	true if the entire hierarchy was successfully assigned; false if gameObject is null or the UI layer does not exist in the project.

CreateUIObject(string, Transform)

Creates a new GameObject configured for UI use: adds a RectTransform component and assigns it to the UI layer. Position and size are left at their default values (anchored position zero, size delta zero).

Declaration

public static GameObject CreateUIObject(string name, Transform parent = null)

Parameters

Type	Name	Description
string	name	The name to give the new GameObject.
Transform	parent	Optional parent transform. When provided, the GameObject is parented with worldPositionStays = false so that local transforms are preserved.

Returns

Type	Description
GameObject	The newly created and configured GameObject.

CreateUIObject(string, Transform, float, float, float, float)

Creates a new GameObject configured for UI use with an explicit anchored position and size. Calls CreateUIObject(string, Transform) first, then sets position and size on the resulting RectTransform only when both width and height are greater than zero.

Declaration

public static GameObject CreateUIObject(string name, Transform parent, float x, float y, float width, float height)

Parameters

Type	Name	Description
string	name	The name to give the new GameObject.
Transform	parent	Parent transform; the object is parented with worldPositionStays = false.
float	x	Anchored X position in pixels (local space of the parent canvas).
float	y	Anchored Y position in pixels (local space of the parent canvas).
float	width	Desired width in pixels. Size is only applied when both dimensions are > 0.
float	height	Desired height in pixels. Size is only applied when both dimensions are > 0.

Returns

Type	Description
GameObject	The newly created and configured GameObject.

CreateUIObject<T>(string, Transform)

Creates a new UI GameObject and immediately adds a component of type T. The GameObject receives a RectTransform and is placed on the UI layer, identical to CreateUIObject(string, Transform).

Declaration

public static T CreateUIObject<T>(string name, Transform parent = null) where T : Graphic

Parameters

Type	Name	Description
string	name	The name to give the new GameObject.
Transform	parent	Optional parent transform. When provided, the GameObject is parented with worldPositionStays = false.

Returns

Type	Description
T	The newly added T component.

Type Parameters

Name	Description
T	The Graphic subtype to add (e.g., Image, RawImage). Must derive from UnityEngine.UI.Graphic.

ForceRebuildCanvas(Canvas)

Forces the specified Canvas and all nested canvases to immediately recalculate layout and rebuild dirty graphics. Internally calls Canvas.ForceUpdateCanvases followed by LayoutRebuilder.ForceRebuildLayoutImmediate on the root RectTransform.

Declaration

public static void ForceRebuildCanvas(Canvas canvas)

Parameters

Type	Name	Description
Canvas	canvas	The canvas to rebuild. Passing null is safe and does nothing.

Remarks

This is an expensive synchronous operation that should only be called when layout must be correct in the same frame, for example immediately before reading a RectTransform's rect for positioning logic.

GetDPIScaleFactor(bool)

Returns the current display's DPI scale factor relative to STANDARD_DPI. Useful for sizing UI elements consistently across displays with different pixel densities.

Declaration

public static float GetDPIScaleFactor(bool round = false)

Parameters

Type	Name	Description
bool	round	When true, rounds the raw factor to the nearest integer (e.g., 1.5 becomes 2). Useful when snapping to whole-pixel scales.

Returns

Type	Description
float	The DPI scale factor (always >= 1.0). Returns 1.0 when Screen.dpi reports zero or a negative value (DPI not detectable on the current platform).

GetScreenPosition(RectTransform, Camera)

Returns the screen-space position of the pivot point of the given RectTransform. For ScreenSpaceOverlay canvases, world position directly maps to screen position, so camera can be omitted. For camera-rendered canvases a valid camera must be supplied.

Declaration

public static Vector2 GetScreenPosition(RectTransform rectTransform, Camera camera = null)

Parameters

Type	Name	Description
RectTransform	rectTransform	The RectTransform whose screen position to calculate. Passing null returns Vector2.zero.
Camera	camera	The camera used to project world coordinates to screen coordinates. Pass null for ScreenSpaceOverlay canvases.

Returns

Type	Description
Vector2	The screen-space position of the RectTransform's pivot. Returns Vector2.zero if rectTransform is null.

GetUILayerID()

Returns the Unity layer ID for the layer named UI_LAYER_NAME, caching the result after the first successful lookup.

Declaration

public static int GetUILayerID()

Returns

Type	Description
int	The layer ID (>= 0) when the layer exists; -1 when no layer with name UI_LAYER_NAME is defined in the project's layer settings.

IsOnUILayer(GameObject)

Determines whether the specified GameObject is currently assigned to the UI layer.

Declaration

public static bool IsOnUILayer(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to test. Passing null is safe and returns false.

Returns

Type	Description
bool	true if the GameObject's layer matches the UI layer ID; false if gameObject is null, the UI layer does not exist in the project, or the GameObject is on a different layer.

IsPointInRect(Vector2, RectTransform, Camera)

Determines whether a screen-space point lies within the axis-aligned bounding rectangle of the given RectTransform. Delegates to RectTransformUtility.RectangleContainsScreenPoint.

Declaration

public static bool IsPointInRect(Vector2 screenPoint, RectTransform rectTransform, Camera camera = null)

Parameters

Type	Name	Description
Vector2	screenPoint	The screen-space point to test (pixels from bottom-left).
RectTransform	rectTransform	The RectTransform defining the rectangle to test against. Passing null returns false.
Camera	camera	The camera used for projection. Pass null for ScreenSpaceOverlay canvases.

Returns

Type	Description
bool	true if screenPoint falls inside the rect; false if rectTransform is null or the point is outside the rect.

ScaleByDPI(float)

Multiplies a scalar value by the current DPI scale factor so that sizes expressed in logical pixels remain consistent across high-density displays.

Declaration

public static float ScaleByDPI(float value)

Parameters

Type	Name	Description
float	value	The logical-pixel value to scale.

Returns

Type	Description
float	The value multiplied by the DPI scale factor.

ScaleByDPI(Vector2)

Multiplies both components of a Vector2 by the current DPI scale factor so that sizes expressed in logical pixels remain consistent across high-density displays.

Declaration

public static Vector2 ScaleByDPI(Vector2 value)

Parameters

Type	Name	Description
Vector2	value	The logical-pixel vector to scale.

Returns

Type	Description
Vector2	A new Vector2 with both components multiplied by the DPI scale factor.

ScreenPointToLocalPoint(Vector2, RectTransform, Camera, out Vector2)

Converts a screen-space point to a local point within the coordinate space of the given RectTransform. Delegates to RectTransformUtility.ScreenPointToLocalPointInRectangle.

Declaration

public static bool ScreenPointToLocalPoint(Vector2 screenPoint, RectTransform rectTransform, Camera camera, out Vector2 localPoint)

Parameters

Type	Name	Description
Vector2	screenPoint	The screen-space point to convert (pixels from bottom-left).
RectTransform	rectTransform	The target RectTransform whose local space defines the output. Passing null sets localPoint to Vector2.zero and returns false.
Camera	camera	The camera used for un-projection. Pass null for ScreenSpaceOverlay canvases.
Vector2	localPoint	When this method returns true, receives the converted local-space point. When this method returns false, receives Vector2.zero.

Returns

Type	Description
bool	true if the conversion succeeded; false if rectTransform is null or RectTransformUtility reports failure.

TryGetDPIScaleFactor(out float)

Attempts to read Screen.dpi and compute the scale factor relative to STANDARD_DPI.

Declaration

public static bool TryGetDPIScaleFactor(out float factor)

Parameters

Type	Name	Description
float	factor	When this method returns true, receives the scale factor (always >= 1.0). When this method returns false, receives 1.0 as a safe default.

Returns

Type	Description
bool	true if Screen.dpi is positive and a meaningful factor was computed; false if the platform does not report DPI.