ScreenTransform
ClassUsed for positioning objects in 2D screen space.
- Available on all platforms
Used for positioning objects in 2D screen space. Modifies the position, size, and anchoring of a rectangle relatively to a parent ScreenTransform.
Index
Properties
Methods
Remarks
It overrides the regular Transform component on the SceneObject it's attached to.
Example
// @input Component.ScreenTransform screenTransform
// Move the ScreenTransform's anchor center
script.screenTransform.anchors.setCenter(new vec2(-0.25, 0.5));
// Change the ScreenTransform's anchor size
script.screenTransform.anchors.setSize(new vec2(0.25, 0.25));
// @input Component.ScreenTransform screenTransform
// Move the ScreenTransform to match the position of touch events
function onTouch(eventData) {
var touchPos = eventData.getTouchPosition();
var parentPos = script.screenTransform.screenPointToParentPoint(touchPos);
script.screenTransform.anchors.setCenter(parentPos);
}
script.createEvent("TouchStartEvent").bind(onTouch);
script.createEvent("TouchMoveEvent").bind(onTouch);
// @input Component.ScreenTransform screenTransform
// Check if a touch starts inside the ScreenTransform
script.createEvent("TouchStartEvent").bind(function(eventData) {
var touchPos = eventData.getTouchPosition();
if (script.screenTransform.containsScreenPoint(touchPos)) {
print("contains screen point!");
}
});
// @input Component.ScreenTransform screenTransform
// @input Component.ScreenTransform other
// Move the ScreenTransform to match the world position of another ScreenTransform
var worldPos = script.other.localPointToWorldPoint(new vec2(0, 0));
var parentPos = script.screenTransform.worldPointToParentPoint(worldPos);
script.screenTransform.anchors.setCenter(parentPos);
Extends
Properties
anchors
anchors:
Rect
The anchor rect positioning this ScreenTransform proportional to its parent's bounds.
For each field, a value of 0 equals the parent's center point, and value of -1 or 1 (depending on the side) equals the parent's full boundary.
For example, a top value of 1.0 means this ScreenTransform's top edge will be exactly at the top edge of its parent.
A bottom value of -0.5 means this ScreenTransform's bottom edge will be halfway between its parent's bottom edge and center.
A right value of 0 means this ScreenTransform's right edge will be exactly at its parent's center.
A left value of -2 means this ScreenTransform's left edge will be twice as far from its parent's center as its parent's left edge is.
enabled
enabled:
boolean
If disabled, the Component will stop enacting its behavior.
Default Value
true
Inherited from
enableDebugRendering
enableDebugRendering:
boolean
Display the debug view of the screen transform.
Since
Lens Scripting Version 271
Default Value
false
isBeingDestroyed
readonlyisBeingDestroyed:boolean
Returns true if this Component is currently being destroyed. Becomes true as soon as
destruction begins via Component#destroy or destruction of its owning SceneObject,
before any OnDestroyEvent callbacks fire.
Since
Lens Scripting Version 364
Example
if (!script.isBeingDestroyed) {
// Component is still fully alive
}
Inherited from
isEnabledInHierarchy
readonlyisEnabledInHierarchy:boolean
Returns true if this Component, its SceneObject, and all of that SceneObjects parents are enabled.
Inherited from
Component.isEnabledInHierarchy
offsets
offsets:
Rect
This rect is applied after anchors to determine the final boundaries of the ScreenTransform.
It adds an offset in world units (based on the parent Camera's to each edge of the ScreenTransform's boundaries.
For example, a value of 0 for any side will have no effect on boundaries.
A value of 1.0 for any side will offset that edge by 1.0 world unit.
pivot
pivot:
vec2
Normalized (x, y) position of the center point used in rotation. (-1, -1) being bottom left, (0, 0) being center, and (1, 1) being top right of the image.
Default Value
(0, 0)
position
position:
vec3
Basic local position in world units relative to the parent's center. Useful for animating screen elements with a simple offset.
Default Value
(0, 0, 0)
rotation
rotation:
quat
Basic local rotation applied to the SceneObject.
Default Value
(1, 0, 0, 0)
scale
scale:
vec3
Basic local scaling applied to the SceneObject.
Default Value
(1, 1, 1)
sceneObject
readonlysceneObject:SceneObject
The SceneObject this component is on.
Inherited from
uniqueIdentifier
readonlyuniqueIdentifier:string
Since
Lens Scripting Version 176
Inherited from
Methods
containsLocalPoint()
containsLocalPoint(
localPoint):boolean
Returns true if the local point is within the boundaries of this ScreenTransform--that is: its position is within -1 and 1 in both the x and y coordinates.
Parameters
| Parameter | Type |
|---|---|
localPoint | vec2 |
Returns
boolean
Since
Lens Scripting Version 188
containsScreenPoint()
containsScreenPoint(
screenPoint):boolean
Returns true if the screen position is within the boundaries of this ScreenTransform. Useful for checking if a touch event overlaps with this object. This function will calculate the ScreenPoint by heuristically looking for a camera: first checking for a camera in it's parent's hierarchy, then looking for a camera with the same render layer, and finally just choosing the first camera in the scene.
Parameters
| Parameter | Type |
|---|---|
screenPoint | vec2 |
Returns
boolean
containsWorldPoint()
containsWorldPoint(
worldPoint):boolean
Returns true if the world position is within the boundaries of this ScreenTransform.
The z value of the world position is ignored.
Parameters
| Parameter | Type |
|---|---|
worldPoint | vec3 |
Returns
boolean
destroy()
destroy():
void
Destroys the component.
Returns
void
Inherited from
getSceneObject()
getSceneObject():
SceneObject
Returns the SceneObject the component is attached to.
Returns
Inherited from
getTransform()
getTransform():
Transform
Returns the Transform this component is attached to.
Returns
Inherited from
getTypeName()
staticgetTypeName():TypeName<ScreenTransform>
Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().
Returns
TypeName<ScreenTransform>
Overrides
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isInScreenHierarchy()
isInScreenHierarchy():
boolean
Returns true if this ScreenTransform is in a valid screen hierarchy, which is required for anchoring to work. To be in a valid screen hierarchy there must be a Camera component upward in the parent hierarchy, and every object between the Camera and this one must also have a ScreenTransform.
Returns
boolean
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
isSame()
isSame(
other):boolean
Returns true if this object is the same as other. Useful for checking if two references point to the same thing.
Parameters
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
localPointToScreenPoint()
localPointToScreenPoint(
relativeLocalPoint):vec2
Converts from a normalized (-1 to 1) position within this ScreenTransform's bounds to a screen position. This function will calculate the ScreenPoint by heuristically looking for a camera: first checking for a camera in it's parent's hierarchy, then looking for a camera with the same render layer, and finally just choosing the first camera in the scene.
Parameters
| Parameter | Type |
|---|---|
relativeLocalPoint | vec2 |
Returns
localPointToWorldPoint()
localPointToWorldPoint(
relativeLocalPoint):vec3
Converts from a normalized (-1 to 1) position within this ScreenTransform's bounds to a world position.
Parameters
| Parameter | Type |
|---|---|
relativeLocalPoint | vec2 |
Returns
screenPointToLocalPoint()
screenPointToLocalPoint(
screenPoint):vec2
Converts from a screen position to a normalized (-1 to 1) position within this ScreenTransform's bounds.
Parameters
| Parameter | Type |
|---|---|
screenPoint | vec2 |
Returns
screenPointToParentPoint()
screenPointToParentPoint(
screenPoint):vec2
Converts from a screen position to a normalized (-1 to 1) position within the parent object's bounds. This value is useful because it can be used directly for this ScreenTransform's anchor positioning.
Parameters
| Parameter | Type |
|---|---|
screenPoint | vec2 |
Returns
worldPointToLocalPoint()
worldPointToLocalPoint(
worldPoint):vec2
Converts from a world position to a normalized (-1 to 1) position within this ScreenTransform's bounds.
Parameters
| Parameter | Type |
|---|---|
worldPoint | vec3 |
Returns
worldPointToParentPoint()
worldPointToParentPoint(
worldPoint):vec2
Converts from a world position to a normalized (-1 to 1) position within the parent object's bounds. This value is useful because it can be used directly for this ScreenTransform's anchor positioning.
Parameters
| Parameter | Type |
|---|---|
worldPoint | vec3 |
Returns
See also
Screen Transform guide.