Screen Transform Overview
Screen Transform represents position, size, anchor and pivot information of a rectangle on the screen.
While Transform (Object position, rotation and scale) represents a single point, ScreenTransform defines a rectangle that contains 2D elements (Screen Text, Screen Image, or another Screen Transform)
Screen Transforms are usually used for the objects that exist in 2D space (are rendered to the Orthographic camera and are in Camera SceneObject Hierarchy). It is used to create complex layouts and supports various forms of scaling and anchoring based on a parent ScreenTransform. This is important and useful for creating UI for your Lenses that adapt to different device resolutions.
Before looking into Screen Transform Component you can get familiar with couple useful Pages: Screen Transform Properties and Screen Region and Device Simulation
Screen Transform Component
ScreenTransform Component comes up with two modes - Basic and Advanced.
While advanced mode gives you full access to all properties, in Basic mode you have access to the limited amount of ScreenTransform properties, which does make sense for the particular case.
ScreenTransform setup made in Basic mode has corresponding Setup in Advanced mode. But not vice versa.
Screen Transform, Basic
Basic mode allows you to choose one from the most common setups using different combinations of buttons.
By default, Screen Transform opens to the Basic tab. The Basic tab allows you to tune if the 2D object is pinned to an edge and if it's set to fixed width or fixed height. These are relative to the parent's Screen Transform.
Pin to Edge - Anchor the edge of the rectangle to the edge of the parent, so that the rectangle’s position is controlled by a fixed size padding from that edge
- Fix Size - Lock the size of the rectangle at a fixed world unit size. You can lock width and height independently
- Position - When width or height of the rectangle is fixed but not pinned, this represents the shared values of Bounds. Controls the relative position of the Pivot within the parent rectangle on a -1 to 1 scale
- Size - The fixed size of the rectangle, see: Fix Size
- Bounds - The relative position within the parent on a -1 to 1 scale where this edge should be positioned
- Padding - The fixed distance from a parent edge the edge should be positioned when that edge is pinned. See: Pin To Edge
- Pivot Position - The point around which the rectangle should be rotated. The (0, 0) point for any child objects
Below are a number of common use cases for different Basic Screen Transform setups.
Example 1 - Nothing selected
When neither Pin To Edge nor Fix Size are selected - this means that total control on the ScreenTransform is taken by the Anchors. You can see only Bounds Setting available in the UI (which represents Anchors of the edges - their relative positions relative to Parent Screen Transform)
Example 2 - Pin To Edge (Edges)
When we select Pin to Edge - the distance from this Screen Transform edge to the parent screen Transform edge will stay the same and is not affected by the parent screen transform scale (You can see how red segments stay the same) We now have Padding property activated - that represents distance from the parent edge.
Example 3 - Fixed Width and Fixed Height
In this example, we are placing a Screen Image on the screen and not pinning it. Because of this, it simply stays in the fixed local position of the parent.
We now have size property activated, and this Screen Transform’s size does not change as the Parent Screen Transform size changes.
You can mix and match different settings for different edges and axes. Below are some common examples. Also don’t forget that the has its Stretch mode itself, that configures how the image will be displayed inside its screen transform.
You can use pixel units for width, height, and offset by using Camera and Overlay render target. Learn More
Example - Pin Corner + Fixed size
In this example, we are pinning a Screen Image to the top left corner of the screen. This for example would be used for a brand's logo. When pinned, notice that the offset from the top left corner will be maintained as the screen resolution changes. Next, the image is set to both Fix Width and Fix Height. Because of this, notice the pinned image's width and height remains the same (doesn't shrink or grow) as the screen resolution changes.
Example - Pin Banner to Top of Screen
In this example, we are pinning a Screen image to the top, left and right edges of the screen. This for example would be used for a stretching banner. Because Fix Width is disabled, notice that the left and right edges of the Screen Image stretch to the changing screen resolution. But because Fix Height is enabled, the height of the Screen Image does not change.
Screen Transform, Advanced
For most Lens Creators, Basic mode will give you all the functionality you need to create responsive UI. That said, we also offer an Advanced mode that gives you full control of the Screen Transform's properties.
- **Pivot Position -**The point around which the rectangle should be rotated. The (0, 0) point for any child objects
- **Anchors -**The relative position within the parent on a -1 to 1 scale where this edge should be positioned
- **Offset -**After determining the edge positions based on Anchors/Bounds, apply these fixed world unit offsets to each edge position. Only differs from paddings in that: Paddings assume bounds position is -1 or 1, Offset is always positive right negative left, paddings are positive towards the center, negative towards the outside
Example - Advanced Corner Pinning
Also there is a helper UI that allows you to quickly set Anchors, Pivot and Offsets to one of the preset positions (TopLeft, TopCenter and etc.)
- When neither Set Pivot Position nor Set Object Position are selected you can place the Anchors of Screen Transform to the one of the preset positions aligned with edges and center of parent Screen Transform.
- Set Pivot Position - When enabled, the pivot of this Screen Transform will also be placed at the desired corner or edge of this ScreenTransform along with the Anchors placed at the desired corner or edge of Parent Screen transform.
- Set Object Position - When enabled, the Object Position (offsets) will be automatically set to the interface's selected corner or edge along with the anchors.
Scripting Screen Transform
Below are some common scripting use cases for modifying Screen Transform programmatically.
Setting Anchors And Offsets
// @input Component.ScreenTransform screenTransform
// @input vec2 bottomLeft = {-0.5, 0.5}
// @input vec2 topRight = {0,5, 0,5}
// @input float padding = 1.0
var anchors = script.screenTransform.anchors;
anchors.left = script.bottomLeft.x;
anchors.bottom = script.bottomLeft.y;
anchors.right = script.topRight.x;
anchors.top = script.topRight.y;
var offsets = script.screenTransform.offsets;
offsets.left = script.padding;
offsets.bottom = script.padding;
offsets.right = -script.padding;
offsets.top = -script.padding;
Position
The script below will set the local position of the Screen Transform relative to the parent's pivot.
// @input Component.ScreenTransform screenTransform
// @input vec3 position
script.screenTransform.position = script.position;
Scale
The script below will set the local scale of the Screen Transform.
// @input Component.ScreenTransform screenTransform
// @input vec3 scale
script.screenTransform.scale = script.scale;
Rotation
The script below will set the local rotation of the Screen Transform in the Z axis. Often for Screen Transform rotation, the only axis that makes sense to rotate is around the Z.
// @input Component.ScreenTransform screenTransform
// @input float rotation
var DEG_TO_RAD = 0.0174533;
script.screenTransform.rotation = quat.fromEulerAngles(
0.0,
0.0,
script.rotation * DEG_TO_RAD
);