Class Transform
Definition
Namespace: StardewUI.Graphics
Assembly: StardewUI.dll
Global transform applied to an ISpriteBatch.
Inheritance
Object ⇦ Transform
Implements
IEquatable<Transform>
Remarks
The order of the different translation parameters reflects the actual order in which the transformations will be applied in a GlobalTransform. Scaling before rotation prevents unexpected skewing, and rotating before translation keeps the coordinate system intact.
To deliberately apply the individual operations in a different order, use separate Transform instances applied in sequence, or simply compute the Matrix directly.
Members
Constructors
| Name | Description |
|---|---|
| Transform(Vector2, Single, Vector2) | Global transform applied to an ISpriteBatch. |
| Transform(Vector2?, Single, Vector2) | Initializes a new Transform instance. |
Fields
| Name | Description |
|---|---|
| Default | Default instance with no transformations applied. |
Properties
| Name | Description |
|---|---|
| EqualityContract | |
| HasNonUniformScale | Whether the current instance has a non-uniform Scale. |
| HasRotation | Whether the current instance has a non-zero Rotation. |
| HasScale | Whether the current instance has non-unity Scale, regardless of uniformity. |
| HasTranslation | Whether the current instance has a non-zero Translation. |
| IsOriginRelative | Whether the current transform is affected by transform origin. |
| Rotation | 2D rotation (always along Z axis) to apply, in radians. |
| Scale | The scale at which to draw. One is unity scale (i.e. no scaling). |
| Translation | Translation offset for drawn content. |
Methods
| Name | Description |
|---|---|
| CanMergeLocally(Transform) | Checks if a subsequent transform can be merged into this one while preserving the result as a simple local transform, i.e. not requiring the use of a transformation matrix. |
| CanMergeLocally(Vector2, Single, Vector2) | Checks if a subsequent transform, represented by its individual components, can be merged into this one while preserving the result as a simple local transform, i.e. not requiring the use of a transformation matrix. |
| FromRotation(Single) | Creates a new Transform that applies a specific 2D rotation. |
| FromScale(Vector2) | Creates a Transform using a specified scale. |
| FromTranslation(Vector2) | Creates a Transform using a specified translation offset. |
| IsRectangular() | Checks if this transform represents a single rectangular area of the parent, i.e. not rotated or skewed. |
| ToMatrix() | Creates a transformation matrix from the properties of this transform. |
Details
Constructors
Transform(Vector2, float, Vector2)
Global transform applied to an ISpriteBatch.
public Transform(Microsoft.Xna.Framework.Vector2 Scale, float Rotation, Microsoft.Xna.Framework.Vector2 Translation);
Parameters
Scale Vector2
The scale at which to draw. One is unity scale (i.e. no scaling).
Rotation Single
2D rotation (always along Z axis) to apply, in radians.
Translation Vector2
Translation offset for drawn content.
Remarks
The order of the different translation parameters reflects the actual order in which the transformations will be applied in a GlobalTransform. Scaling before rotation prevents unexpected skewing, and rotating before translation keeps the coordinate system intact.
To deliberately apply the individual operations in a different order, use separate Transform instances applied in sequence, or simply compute the Matrix directly.
Transform(Vector2?, float, Vector2)
Initializes a new Transform instance.
public Transform(Microsoft.Xna.Framework.Vector2? Scale, float Rotation, Microsoft.Xna.Framework.Vector2 Translation);
Parameters
Scale Nullable<Vector2>
The scale at which to draw. One is unity scale (i.e. no scaling).
Rotation Single
2D rotation (always along Z axis) to apply, in radians.
Translation Vector2
Translation offset for drawn content.
Remarks
This overload supports optional parameters, particularly for use in duck typing.
Fields
Default
Default instance with no transformations applied.
Field Value
Properties
EqualityContract
Property Value
HasNonUniformScale
Whether the current instance has a non-uniform Scale.
Property Value
Remarks
Non-uniform scale sometimes needs to be treated differently from uniform scale because the former is not commutative with rotation.
HasRotation
Whether the current instance has a non-zero Rotation.
Property Value
HasScale
Whether the current instance has non-unity Scale, regardless of uniformity.
Property Value
HasTranslation
Whether the current instance has a non-zero Translation.
Property Value
IsOriginRelative
Whether the current transform is affected by transform origin.
Property Value
Remarks
Some types of transformations, specifically translation, have outcomes independent of the transformation origin and should therefore not attempt to use it or pass it on to global transforms.
Rotation
2D rotation (always along Z axis) to apply, in radians.
Property Value
Scale
The scale at which to draw. One is unity scale (i.e. no scaling).
Property Value
Translation
Translation offset for drawn content.
Property Value
Methods
CanMergeLocally(Transform)
Checks if a subsequent transform can be merged into this one while preserving the result as a simple local transform, i.e. not requiring the use of a transformation matrix.
Parameters
next Transform
The local transformation to apply after the current instance.
Returns
true if the cumulative sequence of transformations can continue to be represented as a simple local Transform; false if the combination requires converting ToMatrix() and subsequent inclusion into a new GlobalTransform.
Remarks
Local transforms can be merged if they are either:
- Mathematically commutative with the existing properties, such as uniform scaling, or additional translation on a local transform that is only translation; or
- Following the same transformation order that applies during the various Draw(Texture2D, Vector2, Rectangle?, Color, Single, Vector2, Vector2, SpriteEffects, Single) and DrawString(SpriteFont, string, Vector2, Color) methods, i.e. Scale followed by Rotation followed by Translation. For example, if the current instance has Scale and Rotation, and the
nexttransform hasRotationonly, then the rotations can be trivially summed.
CanMergeLocally(Vector2, float, Vector2)
Checks if a subsequent transform, represented by its individual components, can be merged into this one while preserving the result as a simple local transform, i.e. not requiring the use of a transformation matrix.
public bool CanMergeLocally(Microsoft.Xna.Framework.Vector2 scale, float rotation, Microsoft.Xna.Framework.Vector2 translation);
Parameters
scale Vector2
The Scale component of the next transform.
rotation Single
The Rotation component of the next transform.
translation Vector2
The Translation component of the next transform.
Returns
FromRotation(float)
Creates a new Transform that applies a specific 2D rotation.
Parameters
angle Single
The rotation angle, in radians.
Returns
A Transform whose Rotation is equal to the specified angle.
FromScale(Vector2)
Creates a Transform using a specified scale.
Parameters
scale Vector2
The scale to apply.
Returns
A Transform whose Scale is equal to the specified scale.
FromTranslation(Vector2)
Creates a Transform using a specified translation offset.
public static StardewUI.Graphics.Transform FromTranslation(Microsoft.Xna.Framework.Vector2 translation);
Parameters
translation Vector2
The translation offset.
Returns
A Transform whose Translation is equal to the specified translation.
IsRectangular()
Checks if this transform represents a single rectangular area of the parent, i.e. not rotated or skewed.
Returns
ToMatrix()
Creates a transformation matrix from the properties of this transform.
Returns
A transformation matrix equivalent to this transform.
Remarks
The created matrix, when used with Begin(SpriteSortMode, BlendState, SamplerState, DepthStencilState, RasterizerState, Effect, Matrix?), will have the same effect as if the current Scale, Rotation and Translation were to be provided directly as arguments to the sprite or text drawing method(s).