com.codename1.ui

Class Transform

java.lang.Object

com.codename1.ui.Transform

public class Transform
extends Object

Encapsulates a 3D transform that can be used in Graphics contexts or with 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.

Author:

shannah

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Transform.NotInvertibleException

Field Summary

Fields

Modifier and Type	Field and Description
static int	TYPE_IDENTITY Constant for transform type.
static int	TYPE_SCALE Constant for transform type.
static int	TYPE_TRANSLATION Constant for transform type.
static int	TYPE_UNKNOWN Constant for transform type.

Method Summary

Modifier and Type	Method and Description
void	concatenate(Transform t) Sets the current transform to be the concatenation of the current transform and the provided transform.
Transform	copy() Creates a copy of the current transform.
boolean	equals(Transform t2)
Transform	getInverse() Deprecated. Use getInverse(com.codename1.ui.Transform) instead.
void	getInverse(Transform inverseOut)
Object	getNativeTransform() Gets the native transform object.
float	getScaleX() Gets the x scale factor of this transformation.
float	getScaleY() Gets the y scale factor of this transformation.
float	getScaleZ() Gets the z scale factor of this transformation.
float	getTranslateX() Gets the x translation of this transformation.
float	getTranslateY() Gets the y translation of this transformation.
float	getTranslateZ() Gets the z translation of this transformation.
static Transform	IDENTITY()
void	invert()
boolean	isIdentity() Checks if this transform is the identity transform.
static boolean	isPerspectiveSupported() Checks if perspective transforms are supported on this platform.
boolean	isScale() Checks if this transform is a scale transformation .
static boolean	isSupported() Checks if transforms are supported on this platform.
boolean	isTranslation() Checks if this transform is a translation transform.
static Transform	makeAffine(double m00, double m10, double m01, double m11, double m02, double m12)
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.
static Transform	makeIdentity() Makes a new identity transform.
static Transform	makeOrtho(float left, float right, float bottom, float top, float near, float far) Makes a new orthographic projection transform.
static Transform	makePerspective(float fovy, float aspect, float zNear, float zFar) Makes a new perspective transform.
static Transform	makeRotation(float angle, float x, float y)
static Transform	makeRotation(float angle, float x, float y, float z) Makes a new rotation transformation.
static Transform	makeScale(float x, float y) Creates a new scale transform.
static Transform	makeScale(float x, float y, float z) Makes a new scale transformation.
static Transform	makeTranslation(float x, float y)
static Transform	makeTranslation(float x, float y, float z) Makes a new translation transformation.
void	rotate(float angle, float px, float py)
void	rotate(float angle, float x, float y, float z) Rotates the current transform.
void	scale(float x, float y)
void	scale(float x, float y, float z) Scales the current transform by the provide scale factors.
void	setAffine(double m00, double m10, double m01, double m11, double m02, double m12)
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.
void	setIdentity() Sets the transform to the identity transform.
void	setOrtho(float left, float right, float bottom, float top, float near, float far) Sets the transform to be the specified orthogonal view.
void	setPerspective(float fovy, float aspect, float zNear, float zFar) Sets the transform to be the specified perspective transformation.
void	setRotation(float angle, float px, float py)
void	setRotation(float angle, float x, float y, float z) Sets the transform to be the provided rotation.
void	setScale(float x, float y) Resets the transformation to scale transform.
void	setScale(float x, float y, float z) Resets the transformation to a scale transformation.
void	setTransform(Transform t) Sets the current transform to be identical to the provided transform.
void	setTranslation(float x, float y)
void	setTranslation(float x, float y, float z) Sets the current transform to be the specified translation.
String	toString()
float[]	transformPoint(float[] point) Transforms a provided point.
void	transformPoint(float[] in, float[] out) Transforms a provided point and places the result in the provided array.
void	transformPoints(int pointSize, float[] in, int srcPos, float[] out, int destPos, int numPoints) Transforms a set of points using the current transform.
void	translate(float x, float y)
void	translate(float x, float y, float z) Translates the transform by the specified amounts.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TYPE_UNKNOWN

public static final int TYPE_UNKNOWN

Constant for transform type. Transform is not a special matrix.

See Also:

Constant Field Values

TYPE_IDENTITY

public static final int TYPE_IDENTITY

Constant for transform type. Transform is the identity transform.

See Also:

Constant Field Values

TYPE_TRANSLATION

public static final int TYPE_TRANSLATION

Constant for transform type. Transform is a translation transform only.

See Also:

Constant Field Values

TYPE_SCALE

public static final int TYPE_SCALE

Constant for transform type. Transform is a scale transform only.

See Also:

Constant Field Values

Method Detail

IDENTITY

public static Transform IDENTITY()

makeIdentity

public static Transform makeIdentity()

Makes a new identity transform.

Returns:

An identity transform.

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:

isScale(), #setScale()

getScaleY

public float getScaleY()

Gets the y scale factor of this transformation. This value is only reliable if the transform is a scale transform.

Returns:

The y scale factor of this transformation.

See Also:

isScale(), #setScale()

getScaleZ

public float getScaleZ()

Gets the z scale factor of this transformation. This value is only reliable if the transform is a scale transform.

Returns:

The z scale factor of this transformation.

See Also:

isScale(), #setScale()

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:

isTranslation(), #setTranslation(), #translate()

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:

isTranslation(), #setTranslation(), #translate()

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:

isTranslation(), #setTranslation(), #translate()

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.

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 - The angle of the rotation in radians.

x - The x component of the vector around which the rotation occurs.

y - The y component of the vector around which the rotation occurs.

z - 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 - The x component of the translation.

y - The y component of the translation.

z - 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 - The x scale factor.

y - The y scale factor.

z - 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 - Factor to scale in x axis.

y - 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)

setScale

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

Resets the transformation to a scale transformation.

Parameters:

x - x-axis scaling

y - y-axis scaling

z - z-axis scaling

setScale

public void setScale(float x,
                     float y)

Resets the transformation to scale transform.

Parameters:

x - x-axis scaling.

y - y-axis scaling.

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 - The y field of view angle.

aspect - The aspect ratio.

zNear - The nearest visible z coordinate.

zFar - 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 - x-coordinate that is the left edge of the view.

right - The x-coordinate that is the right edge of the view.

bottom - The y-coordinate that is the bottom edge of the view.

top - The y-coordinate that is the top edge of the view.

near - The nearest visible z-coordinate.

far - 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 - The x-coordinate of the camera's eye.

eyeY - The y-coordinate of the camera's eye.

eyeZ - The z-coordinate of the camera's eye.

centerX - The center x coordinate of the view.

centerY - The center y coordinate of the view.

centerZ - The center z coordinate of the view.

upX - The x-coordinate of the up vector for the camera.

upY - The y-coordinate of the up vector for the camera.

upZ - The z-coordinate of the up vector for the camera.

Returns:

A transform with the provided camera's view perspective.

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 - The angle to rotate in radians.

x - The x-coordinate of the vector around which to rotate.

y - The y-coordinate of the vector around which to rotate.

z - The z-coordinate of the vector around which to rotate.

See Also:

setRotation(float, float, float, float)

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 - The angle to rotate in radians.

x - The x-coordinate of the vector around which to rotate.

y - The y-coordinate of the vector around which to rotate.

z - 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()

Overrides:

toString in class Object

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 - The x translation.

y - The y translation.

z - 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 - The x translation.

y - The y translation.

z - 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 - The x-scale factor

y - The y-scale factor

z - 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 - 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 - 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 - Y-field of view angle.

aspect - Apspect ratio of the view window.

zNear - Nearest visible z-coordinate.

zFar - 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 - Left x-coord of view.

right - Right x-coord of view.

bottom - Bottom y-coord of view.

top - Top y-coord of view.

near - Nearest visible z-coordinate

far - 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 - The x-coordinate of the camera's eye.

eyeY - The y-coordinate of the camera's eye.

eyeZ - The z-coordinate of the camera's eye.

centerX - The center x coordinate of the view.

centerY - The center y coordinate of the view.

centerZ - The center z coordinate of the view.

upX - The x-coordinate of the up vector for the camera.

upY - The y-coordinate of the up vector for the camera.

upZ - 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 - The size of the points to transform (2 or 3)

in - Input array of points.

srcPos - Start position in input array

out - Output array of points

destPos - Start position in output array

numPoints - 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 - 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 - A 2 or 3 element array representing either an (x,y) or (x,y,z) tuple.

out - 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.

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.

equals

public boolean equals(Transform t2)