public class Transform

  1. Object
  2. Transform

Encapsulates a 3D transform that can be used in com.codename1.ui.Graphics contexts or with com.codename1.ui.geom.Shapes to transform in various ways.

Use the #isSupported and #isPerspectiveSupported to check if transforms and perspective transforms are supported on this platform. If they are not supported, this class will throw RuntimeExceptions if you try to use it.

Nested types

class Transform.NotInvertibleException

Fields

public static final int TYPE_UNKNOWN = -1Constant for transform type.
public static final int TYPE_IDENTITY = 0Constant for transform type.
public static final int TYPE_TRANSLATION = 1Constant for transform type.
public static final int TYPE_SCALE = 2Constant for transform type.

Methods

public static Transform IDENTITY()Deprecated
public static Transform identity()
public static Transform makeIdentity()Makes a new identity transform.
public static Transform makeRotation(float angle, float x, float y, float z)Makes a new rotation transformation.
public static Transform makeRotation(float angle, float x, float y)
public static Transform makeTranslation(float x, float y, float z)Makes a new translation transformation.
public static Transform makeTranslation(float x, float y)
public static Transform makeScale(float x, float y, float z)Makes a new scale transformation.
public static Transform makeScale(float x, float y)Creates a new scale transform.
public static Transform makeAffine(double m00, double m10, double m01, double m11, double m02, double m12)
public static Transform makePerspective(float fovy, float aspect, float zNear, float zFar)Makes a new perspective transform.
public static Transform makeOrtho(float left, float right, float bottom, float top, float near, float far)Makes a new orthographic projection transform.
public static Transform makeCamera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)Makes a transform to simulate a camera’s perspective at a given location.
public static boolean isSupported()Checks if transforms are supported on this platform.
public static boolean isPerspectiveSupported()Checks if perspective transforms are supported on this platform.
public boolean isIdentity()Checks if this transform is the identity transform.
public boolean isTranslation()Checks if this transform is a translation transform.
public float getScaleX()Gets the x scale factor of this transformation.
public float getScaleY()Gets the y scale factor of this transformation.
public float getScaleZ()Gets the z scale factor of this transformation.
public float getTranslateX()Gets the x translation of this transformation.
public float getTranslateY()Gets the y translation of this transformation.
public float getTranslateZ()Gets the z translation of this transformation.
public boolean isScale()Checks if this transform is a scale transformation .
public void setScale(float x, float y, float z)Resets the transformation to a scale transformation.
public void setScale(float x, float y)Resets the transformation to scale transform.
public void rotate(float angle, float x, float y, float z)Rotates the current transform.
public void rotate(float angle, float px, float py)
public void setRotation(float angle, float x, float y, float z)Sets the transform to be the provided rotation.
public void setRotation(float angle, float px, float py)
public void setIdentity()Sets the transform to the identity transform.
public String toString()Returns a string representation of the object.
public void translate(float x, float y, float z)Translates the transform by the specified amounts.
public void translate(float x, float y)
public void setTranslation(float x, float y, float z)Sets the current transform to be the specified translation.
public void setTranslation(float x, float y)
public void scale(float x, float y, float z)Scales the current transform by the provide scale factors.
public void scale(float x, float y)
public Transform getInverse()Deprecated Gets the inverse transformation for this transform.
public void getInverse(Transform inverseOut) throws Transform.NotInvertibleException
public void invert() throws Transform.NotInvertibleException
public void setTransform(Transform t)Sets the current transform to be identical to the provided transform.
public void concatenate(Transform t)Sets the current transform to be the concatenation of the current transform and the provided transform.
public void setPerspective(float fovy, float aspect, float zNear, float zFar)Sets the transform to be the specified perspective transformation.
public void setAffine(double m00, double m10, double m01, double m11, double m02, double m12)
public void setOrtho(float left, float right, float bottom, float top, float near, float far)Sets the transform to be the specified orthogonal view.
public void setCamera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)Sets the transform to the specified camera’s perspective.
public void transformPoints(int pointSize, float[] in, int srcPos, float[] out, int destPos, int numPoints)Transforms a set of points using the current transform.
public float[] transformPoint(float[] point)Transforms a provided point.
public void transformPoint(float[] in, float[] out)Transforms a provided point and places the result in the provided array.
public Object getNativeTransform()Gets the native transform object.
public Transform copy()Creates a copy of the current transform.
public boolean equals(Transform t2)
public boolean equals(Object o)Indicates whether some other object is “equal to” this one.
public int hashCode()Returns a hash code value for the object.

Inherited methods

From Object

getClass, notify, notifyAll, wait, wait, wait, clone

Field details

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN = -1
Constant for transform type. Transform is not a special matrix.

TYPE_IDENTITY

public static final int TYPE_IDENTITY = 0
Constant for transform type. Transform is the identity transform.

TYPE_TRANSLATION

public static final int TYPE_TRANSLATION = 1
Constant for transform type. Transform is a translation transform only.

TYPE_SCALE

public static final int TYPE_SCALE = 2
Constant for transform type. Transform is a scale transform only.

Method details

IDENTITY

public static Transform IDENTITY()
Deprecated. Use #identity().

identity

public static Transform identity()

makeIdentity

public static Transform makeIdentity()
Makes a new identity transform.

Returns

An identity transform.

makeRotation

public static Transform makeRotation(float angle, float x, float y, float z)

Makes a new rotation transformation.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

angle float
The angle of the rotation in radians.
x float
The x component of the vector around which the rotation occurs.
y float
The y component of the vector around which the rotation occurs.
z float
The z component of the vector around which the rotation occurs.

Returns

A transform that makes the appropriate rotation.

Throws

RuntimeException
If #isSupported() is false.

makeRotation

public static Transform makeRotation(float angle, float x, float y)

makeTranslation

public static Transform makeTranslation(float x, float y, float z)
Makes a new translation transformation.

Parameters

x float
The x component of the translation.
y float
The y component of the translation.
z float
The z component of the translation.

Returns

A transform that makes the specified translation.

makeTranslation

public static Transform makeTranslation(float x, float y)

makeScale

public static Transform makeScale(float x, float y, float z)
Makes a new scale transformation.

Parameters

x float
The x scale factor.
y float
The y scale factor.
z float
The z scale factor.

Returns

A transform that scales values according to the provided scale factors.

makeScale

public static Transform makeScale(float x, float y)
Creates a new scale transform.

Parameters

x float
Factor to scale in x axis.
y float
Factor to scale by in y axis.

Returns

A new transform with the specified scale.

makeAffine

public static Transform makeAffine(double m00, double m10, double m01, double m11, double m02, double m12)

makePerspective

public static Transform makePerspective(float fovy, float aspect, float zNear, float zFar)

Makes a new perspective transform.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

fovy float
The y field of view angle.
aspect float
The aspect ratio.
zNear float
The nearest visible z coordinate.
zFar float
The farthest z coordinate.

Returns

A transform for the given perspective.

makeOrtho

public static Transform makeOrtho(float left, float right, float bottom, float top, float near, float far)

Makes a new orthographic projection transform.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

left float
x-coordinate that is the left edge of the view.
right float
The x-coordinate that is the right edge of the view.
bottom float
The y-coordinate that is the bottom edge of the view.
top float
The y-coordinate that is the top edge of the view.
near float
The nearest visible z-coordinate.
far float
The farthest visible z-coordinate.

Returns

A transform with the provided orthographic projection.

makeCamera

public static Transform makeCamera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)

Makes a transform to simulate a camera’s perspective at a given location.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

eyeX float
The x-coordinate of the camera’s eye.
eyeY float
The y-coordinate of the camera’s eye.
eyeZ float
The z-coordinate of the camera’s eye.
centerX float
The center x coordinate of the view.
centerY float
The center y coordinate of the view.
centerZ float
The center z coordinate of the view.
upX float
The x-coordinate of the up vector for the camera.
upY float
The y-coordinate of the up vector for the camera.
upZ float
The z-coordinate of the up vector for the camera.

Returns

A transform with the provided camera’s view perspective.

isSupported

public static boolean isSupported()
Checks if transforms are supported on this platform. If this returns false, you cannot use this class.

Returns

True if and only if this platform supports transforms.

isPerspectiveSupported

public static boolean isPerspectiveSupported()
Checks if perspective transforms are supported on this platform. If this returns false, you cannot use this class.

Returns

True if and only if this platform supports transforms.

isIdentity

public boolean isIdentity()
Checks if this transform is the identity transform.

Returns

True if the transform is the identity.

isTranslation

public boolean isTranslation()
Checks if this transform is a translation transform.

Returns

True if this transform performs translation only. Note that this will return false if the transform is the identity (i.e. is actually a translation of (0,0,0).

getScaleX

public float getScaleX()
Gets the x scale factor of this transformation. This value is only reliable if the transform is a scale transform.

Returns

The x scale factor of this transformation.

See also

getScaleY

public float getScaleY()
Gets the y scale factor of this transformation. This value is only reliable if the transform is a scale transform.

See also

getScaleZ

public float getScaleZ()
Gets the z scale factor of this transformation. This value is only reliable if the transform is a scale transform.

See also

getTranslateX

public float getTranslateX()
Gets the x translation of this transformation. This value is only reliable if the transform is a translation transform.

Returns

The x translation of this transform.

See also

getTranslateY

public float getTranslateY()
Gets the y translation of this transformation. This value is only reliable if the transform is a translation transform.

Returns

The y translation of this transform.

See also

getTranslateZ

public float getTranslateZ()
Gets the z translation of this transformation. This value is only reliable if the transform is a translation transform.

Returns

The z translation of this transform.

See also

isScale

public boolean isScale()
Checks if this transform is a scale transformation .

Returns

Returns true if and only if this is a non-identity scale transformation.

setScale

public void setScale(float x, float y, float z)
Resets the transformation to a scale transformation.

Parameters

x float
x-axis scaling
y float
y-axis scaling
z float
z-axis scaling

setScale

public void setScale(float x, float y)
Resets the transformation to scale transform.

Parameters

x float
x-axis scaling.
y float
y-axis scaling.

rotate

public void rotate(float angle, float x, float y, float z)

Rotates the current transform.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

angle float
The angle to rotate in radians.
x float
The x-coordinate of the vector around which to rotate.
y float
The y-coordinate of the vector around which to rotate.
z float
The z-coordinate of the vector around which to rotate.

See also

rotate

public void rotate(float angle, float px, float py)

setRotation

public void setRotation(float angle, float x, float y, float z)

Sets the transform to be the provided rotation. This replaces the current transform whereas #rotate() further rotates the current transform.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

angle float
The angle to rotate in radians.
x float
The x-coordinate of the vector around which to rotate.
y float
The y-coordinate of the vector around which to rotate.
z float
The z-coordinate of the vector around which to rotate.

See also

  • #rotate()

setRotation

public void setRotation(float angle, float px, float py)

setIdentity

public void setIdentity()
Sets the transform to the identity transform.

toString

public String toString()
Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())

translate

public void translate(float x, float y, float z)

Translates the transform by the specified amounts. This adds additional translations to whereas #setTranslation() replaces the transform with the specified translation.

Note: If #isSupported() is false, then this may throw a Runtime Exception.

Parameters

x float
The x translation.
y float
The y translation.
z float
The z translation.

See also

  • #setTranslation()

translate

public void translate(float x, float y)

setTranslation

public void setTranslation(float x, float y, float z)
Sets the current transform to be the specified translation. This replaces the current transform with the given translation whereas #translate() adds additional translation to the existing translation.

Parameters

x float
The x translation.
y float
The y translation.
z float
The z translation.

See also

  • #translate()

setTranslation

public void setTranslation(float x, float y)

scale

public void scale(float x, float y, float z)

Scales the current transform by the provide scale factors. Not to be confused with #setScale() which replaces the transform.

Note: If #isSupported() is false, then this may throw a Runtime Exception.

Parameters

x float
The x-scale factor
y float
The y-scale factor
z float
The z-scale factor

See also

  • #setScale()

scale

public void scale(float x, float y)

getInverse

public Transform getInverse()
Deprecated. Use #getInverse(com.codename1.ui.Transform) instead.

Gets the inverse transformation for this transform.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Returns

The inverse transform.

getInverse

public void getInverse(Transform inverseOut) throws Transform.NotInvertibleException

Throws

Transform.NotInvertibleException

invert

public void invert() throws Transform.NotInvertibleException

Throws

Transform.NotInvertibleException

setTransform

public void setTransform(Transform t)

Sets the current transform to be identical to the provided transform.

Note: If #isSupported() is false, then this will may throw a Runtime Exception.

Parameters

t Transform
A transform to copy into the current transform.

concatenate

public void concatenate(Transform t)

Sets the current transform to be the concatenation of the current transform and the provided transform.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

t Transform
The transform to concatenate to this one.

setPerspective

public void setPerspective(float fovy, float aspect, float zNear, float zFar)

Sets the transform to be the specified perspective transformation.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

fovy float
Y-field of view angle.
aspect float
Apspect ratio of the view window.
zNear float
Nearest visible z-coordinate.
zFar float
Farthest visible z-coordinate.

See also

  • #makePerspective()

setAffine

public void setAffine(double m00, double m10, double m01, double m11, double m02, double m12)

setOrtho

public void setOrtho(float left, float right, float bottom, float top, float near, float far)

Sets the transform to be the specified orthogonal view.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

left float
Left x-coord of view.
right float
Right x-coord of view.
bottom float
Bottom y-coord of view.
top float
Top y-coord of view.
near float
Nearest visible z-coordinate
far float
Farthest visible z-coordinate

setCamera

public void setCamera(float eyeX, float eyeY, float eyeZ, float centerX, float centerY, float centerZ, float upX, float upY, float upZ)

Sets the transform to the specified camera’s perspective.

Note: If #isPerspectiveSupported() is false, then this will throw a Runtime Exception.

Parameters

eyeX float
The x-coordinate of the camera’s eye.
eyeY float
The y-coordinate of the camera’s eye.
eyeZ float
The z-coordinate of the camera’s eye.
centerX float
The center x coordinate of the view.
centerY float
The center y coordinate of the view.
centerZ float
The center z coordinate of the view.
upX float
The x-coordinate of the up vector for the camera.
upY float
The y-coordinate of the up vector for the camera.
upZ float
The z-coordinate of the up vector for the camera.

transformPoints

public void transformPoints(int pointSize, float[] in, int srcPos, float[] out, int destPos, int numPoints)
Transforms a set of points using the current transform.

Parameters

pointSize int
The size of the points to transform (2 or 3)
in float[]
Input array of points.
srcPos int
Start position in input array
out float[]
Output array of points
destPos int
Start position in output array
numPoints int
Number of points to transform.

transformPoint

public float[] transformPoint(float[] point)

Transforms a provided point.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

point float[]
2 or 3 element array representing either an (x,y) or (x,y,z) tuple.

Returns

A 3-element array representing transformed (x,y,z) tuple.

transformPoint

public void transformPoint(float[] in, float[] out)

Transforms a provided point and places the result in the provided array.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Parameters

in float[]
A 2 or 3 element array representing either an (x,y) or (x,y,z) tuple.
out float[]
A 2 or 3 element array in which the transformed point will be stored. Should match the length of the in array.

getNativeTransform

public Object getNativeTransform()

Gets the native transform object. This object is implementation dependent so this method should really only be used by the implementation.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Returns

The native transform object.

copy

public Transform copy()

Creates a copy of the current transform.

Note: If #isSupported() is false, then this will throw a Runtime Exception.

Returns

A copy of the current transform.

equals

public boolean equals(Transform t2)

equals

public boolean equals(Object o)
Indicates whether some other object is “equal to” this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

hashCode

public int hashCode()
Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)