ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Vector3D

Package | flash.geom
Class | public class Vector3D
Inheritance | Vector3D Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The Vector3D class represents a point or a location in the three-dimensional space using the Cartesian coordinates x, y, and z. As in a two-dimensional space, the x property represents the horizontal axis and the y property represents the vertical axis. In three-dimensional space, the z property represents depth. The value of the x property increases as the object moves to the left. The value of the y property increases as the object moves down. The z property increases as the object moves farther from the point of view. Using perspective projection and scaling, the object is seen to be bigger when near and smaller when farther away from the screen. As in a left-handed three-dimensional coordinate system, the positive z-axis points away from the viewer and the value of the z property increases as the object moves away from the viewer's eye. The origin point (0,0,0) of the global space is the upper left corner of the stage.

The Vector3D class can also represent a direction, an arrow pointing from the origin of the coordinates, such as (0,0,0), to an endpoint; or a floating-point component of an RGB (Red, Green, Blue) color model.

Quaternion notation introduces a fourth element, the w property, which provides additional orientation information. For example, the w property can define an angle of rotation of a Vector3D object. The combination of the angle of rotation and the coordinates x, y, and z can determine the display object's orientation. Here is a representation of Vector3D elements in matrix notation:

See also

flash.display.DisplayObject
flash.geom.Point
flash.geom.Matrix3D
flash.geom.Utils3D
Vector

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | length : Number [read-only] The length, magnitude, of the current Vector3D object from the origin (0,0,0) to the object's x, y, and z coordinates. | Vector3D
|  | lengthSquared : Number [read-only] The square of the length of the current Vector3D object, calculated using the x, y, and z properties. | Vector3D
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | w : Number The fourth element of a Vector3D object (in addition to the x, y, and z properties) can hold data such as the angle of rotation. | Vector3D
|  | x : Number The first element of a Vector3D object, such as the x coordinate of a point in the three-dimensional space. | Vector3D
|  | y : Number The second element of a Vector3D object, such as the y coordinate of a point in the three-dimensional space. | Vector3D
|  | z : Number The third element of a Vector3D object, such as the z coordinate of a point in three-dimensional space. | Vector3D

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | Vector3D(x:Number = 0., y:Number = 0., z:Number = 0., w:Number = 0.) Creates an instance of a Vector3D object. | Vector3D
|  | add(a:Vector3D):Vector3D Adds the value of the x, y, and z elements of the current Vector3D object to the values of the x, y, and z elements of another Vector3D object. | Vector3D
|  | angleBetween(a:Vector3D):Number Returns the angle in radians between the current and a specified Vector3D object. | Vector3D
|  | clone():Vector3D Returns a new Vector3D object that is an exact copy of the current Vector3D object. | Vector3D
|  | crossProduct(a:Vector3D):Vector3D Returns a new Vector3D object that is perpendicular (at a right angle) to the current Vector3D and another Vector3D object. | Vector3D
|  | decrementBy(a:Vector3D):void Decrements the value of the x, y, and z elements of the current Vector3D object by the values of the x, y, and z elements of specified Vector3D object. | Vector3D
|  | distance(pt1:Vector3D, pt2:Vector3D):Number [static] Returns the distance between two Vector3D objects. | Vector3D
|  | dotProduct(a:Vector3D):Number If the current Vector3D object and the one specified as the parameter are unit vertices, this method returns the cosine of the angle between the two vertices. | Vector3D
|  | equals(toCompare:Vector3D, allFour:Boolean = false):Boolean Determines whether two Vector3D objects are equal by comparing the x, y, and z elements of the current Vector3D object with a specified Vector3D object. | Vector3D
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | incrementBy(a:Vector3D):void Increments the value of the x, y, and z elements of the current Vector3D object by the values of the x, y, and z elements of a specified Vector3D object. | Vector3D
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | nearEquals(toCompare:Vector3D, tolerance:Number, allFour:Boolean = false):Boolean Compares the elements of the current Vector3D object with the elements of a specified Vector3D object to determine if they are nearly equal. | Vector3D
|  | negate():void Sets the current Vector3D object to its inverse. | Vector3D
|  | normalize():Number Converts a Vector3D object to a unit vector by dividing the first three elements (x, y, z) by the vector's length. | Vector3D
|  | project():void Divides the value of the x, y, and z properties of the current Vector3D object by the value of its w property. | Vector3D
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | scaleBy(s:Number):void Scales the current Vector3D object by a scalar, a magnitude. | Vector3D
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | subtract(a:Vector3D):Vector3D Subtracts the value of the x, y, and z elements of the current Vector3D object from the values of the x, y, and z elements of another Vector3D object. | Vector3D
|  | toString():String Returns a string representation of the current Vector3D object. | Vector3D
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Public Constants

| Constant | Defined By
--- | --- | ---
|  | XAXIS : Vector3D [static] The x-axis defined as a Vector3D object with coordinates (1,0,0). | Vector3D
|  | YAXIS : Vector3D [static] The y-axis defined as a Vector3D object with coordinates (0,1,0). | Vector3D
|  | ZAXIS : Vector3D [static] The z-axis defined as a Vector3D object with coordinates (0,0,1). | Vector3D

Property Detail

length | property

`length:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The length, magnitude, of the current Vector3D object from the origin (0,0,0) to the object's x, y, and z coordinates. The w property is ignored. A unit vector has a length or magnitude of one.

Implementation
`public function get length():Number`

See also

lengthSquared

lengthSquared | property |

`lengthSquared:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The square of the length of the current Vector3D object, calculated using the x, y, and z properties. The w property is ignored. Use the `lengthSquared()` method whenever possible instead of the slower `Math.sqrt()` method call of the `Vector3D.length()` method.

Implementation
`public function get lengthSquared():Number`

See also

length

w | property |

`public var w:Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The fourth element of a Vector3D object (in addition to the x, y, and z properties) can hold data such as the angle of rotation. The default value is 0.

Quaternion notation employs an angle as the fourth element in its calculation of three-dimensional rotation. The w property can be used to define the angle of rotation about the Vector3D object. The combination of the rotation angle and the coordinates (x,y,z) determines the display object's orientation.

In addition, the w property can be used as a perspective warp factor for a projected three-dimensional position or as a projection transform value in representing a three-dimensional coordinate projected into the two-dimensional space. For example, you can create a projection matrix, using the `Matrix3D.rawData` property, that, when applied to a Vector3D object, produces a transform value in the Vector3D object's fourth element (the w property). Dividing the Vector3D object's other elements by the transform value then produces a projected Vector3D object. You can use the `Vector3D.project()` method to divide the first three elements of a Vector3D object by its fourth element.

See also

project()

x | property |

`public var x:Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The first element of a Vector3D object, such as the x coordinate of a point in the three-dimensional space. The default value is 0.

y | property |

`public var y:Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The second element of a Vector3D object, such as the y coordinate of a point in the three-dimensional space. The default value is 0.

z | property |

`public var z:Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The third element of a Vector3D object, such as the z coordinate of a point in three-dimensional space. The default value is 0.

Constructor Detail

Vector3D | () | Constructor

`public function Vector3D(x:Number = 0., y:Number = 0., z:Number = 0., w:Number = 0.)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates an instance of a Vector3D object. If you do not specify a parameter for the constructor, a Vector3D object is created with the elements (0,0,0,0).

Parameters

| `x:Number` (default = `0.`)`` — The first element, such as the x coordinate.
| `y:Number` (default = `0.`)`` — The second element, such as the y coordinate.
| `z:Number` (default = `0.`)`` — The third element, such as the z coordinate.
| `w:Number` (default = `0.`)`` — An optional element for additional data such as the angle of rotation.

Method Detail

add | () | method

`public function add(a:Vector3D):Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Adds the value of the x, y, and z elements of the current Vector3D object to the values of the x, y, and z elements of another Vector3D object. The `add()` method does not change the current Vector3D object. Instead, it returns a new Vector3D object with the new values.

The result of adding two vectors together is a resultant vector. One way to visualize the result is by drawing a vector from the origin or tail of the first vector to the end or head of the second vector. The resultant vector is the distance between the origin point of the first vector and the end point of the second vector.

Parameters

| `a:Vector3D` — A Vector3D object to be added to the current Vector3D object.

Returns

| `Vector3D` — A Vector3D object that is the result of adding the current Vector3D object to another Vector3D object.

See also

incrementBy()

angleBetween | () | method |

`public function angleBetween(a:Vector3D):Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the angle in radians between the current and a specified Vector3D object. The angle measured from the current Vector3D object is the smallest angle that the current Vector3D object can be rotated until it aligns with the specified Vector3D object.

To convert a degree to a radian, you can use the following formula:

`radian = Math.PI/180 * degree`

Parameters

| `a:Vector3D` — The other Vector3D object.

Returns

| `Number` — The angle between the current Vector3D and the Vector3D object specified as the parameter.

clone | () | method |

`public function clone():Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns a new Vector3D object that is an exact copy of the current Vector3D object.

Returns

| `Vector3D` — A new Vector3D object that is a copy of the current Vector3D object.

crossProduct | () | method |

`public function crossProduct(a:Vector3D):Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns a new Vector3D object that is perpendicular (at a right angle) to the current Vector3D and another Vector3D object. If the returned Vector3D object's coordinates are (0,0,0), then the two Vector3D objects are perpendicular to each other.

You can use the normalized cross product of two vertices of a polygon surface with the normalized vector of the camera or eye viewpoint to get a dot product. The value of the dot product can identify if a surface of a three-dimensional object is hidden from the viewpoint.

Parameters

| `a:Vector3D` — A second Vector3D object.

Returns

| `Vector3D` — A new Vector3D object that is perpendicular to the current Vector3D object and the Vector3D object specified as the parameter.

See also

dotProduct()
normalize()

decrementBy | () | method |

`public function decrementBy(a:Vector3D):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Decrements the value of the x, y, and z elements of the current Vector3D object by the values of the x, y, and z elements of specified Vector3D object. Unlike the `Vector3D.subtract()` method, the `decrementBy()` method changes the current Vector3D object and does not return a new Vector3D object.

Parameters

| `a:Vector3D` — The Vector3D object containing the values to subtract from the current Vector3D object.

See also

subtract()

distance | () | method |

`public static function distance(pt1:Vector3D, pt2:Vector3D):Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns the distance between two Vector3D objects. The `distance()` method is a static method. You can use it directly as a method of the Vector3D class to get the Euclidean distance between two three-dimensional points.

Parameters

| `pt1:Vector3D` — A Vector3D object as the first three-dimensional point.
| `pt2:Vector3D` — A Vector3D object as the second three-dimensional point.

Returns

| `Number` — The distance between two Vector3D objects.

dotProduct | () | method |

`public function dotProduct(a:Vector3D):Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

If the current Vector3D object and the one specified as the parameter are unit vertices, this method returns the cosine of the angle between the two vertices. Unit vertices are vertices that point to the same direction but their length is one. They remove the vector's length as a factor in the result. You can use the `normalize()` method to convert a vector to a unit vector.

The `dotProduct()` method finds the angle between two vertices. It is also used in backface culling or lighting calculations. Backface culling is a procedure for determining which surfaces are hidden from the viewpoint. You can use the normalized vertices from the camera, or eye, viewpoint and the cross product of the vertices of a polygon surface to get the dot product. If the dot product is less than zero, then the surface is facing the camera or the viewer. If the two unit vertices are perpendicular to each other, they are orthogonal and the dot product is zero. If the two vertices are parallel to each other, the dot product is one.

Parameters

| `a:Vector3D` — The second Vector3D object.

Returns

| `Number` — A scalar which is the dot product of the current Vector3D object and the specified Vector3D object.

See also

crossProduct()
normalize()

equals | () | method |

`public function equals(toCompare:Vector3D, allFour:Boolean = false):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Determines whether two Vector3D objects are equal by comparing the x, y, and z elements of the current Vector3D object with a specified Vector3D object. If the values of these elements are the same, the two Vector3D objects are equal. If the second optional parameter is set to `true`, all four elements of the Vector3D objects, including the w property, are compared.

Parameters

| `toCompare:Vector3D` — The Vector3D object to be compared with the current Vector3D object.
| `allFour:Boolean` (default = `false`)`` — An optional parameter that specifies whether the w property of the Vector3D objects is used in the comparison.

Returns

| `Boolean` — A value of `true` if the specified Vector3D object is equal to the current Vector3D object; `false` if it is not equal.

See also

nearEquals()

incrementBy | () | method |

`public function incrementBy(a:Vector3D):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Increments the value of the x, y, and z elements of the current Vector3D object by the values of the x, y, and z elements of a specified Vector3D object. Unlike the `Vector3D.add()` method, the `incrementBy()` method changes the current Vector3D object and does not return a new Vector3D object.

Parameters

| `a:Vector3D` — The Vector3D object to be added to the current Vector3D object.

See also

add()

nearEquals | () | method |

`public function nearEquals(toCompare:Vector3D, tolerance:Number, allFour:Boolean = false):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Compares the elements of the current Vector3D object with the elements of a specified Vector3D object to determine if they are nearly equal. The two Vector3D objects are nearly equal if the value of all the elements of the two vertices are equal, or the result of the comparison is within the tolerance range. The difference between two elements must be less than the number specified as the `tolerance` parameter. If the third optional parameter is set to `true`, all four elements of the Vector3D objects, including the w property, are compared. Otherwise, only the x, y, and z elements are included in the comparison.

Parameters

| `toCompare:Vector3D` — The Vector3D object to be compared with the current Vector3D object.
| `tolerance:Number` — A number determining the tolerance factor. If the difference between the values of the Vector3D element specified in the `toCompare` parameter and the current Vector3D element is less than the tolerance number, the two values are considered nearly equal.
| `allFour:Boolean` (default = `false`)`` — An optional parameter that specifies whether the w property of the Vector3D objects is used in the comparison.

Returns

| `Boolean` — A value of `true` if the specified Vector3D object is nearly equal to the current Vector3D object; `false` if it is not equal.

See also

equals()

negate | () | method |

`public function negate():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Sets the current Vector3D object to its inverse. The inverse object is also considered the opposite of the original object. The value of the x, y, and z properties of the current Vector3D object are changed to `-x`, `-y`, and `-z`.

normalize | () | method |

`public function normalize():Number`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Converts a Vector3D object to a unit vector by dividing the first three elements (x, y, z) by the vector's length. Unit vertices are vertices that have a direction but their length is one. They simplify vector calculations by removing length as a factor.

Returns

| `Number` — The length of the current Vector3D object.

project | () | method |

`public function project():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Divides the value of the x, y, and z properties of the current Vector3D object by the value of its w property.

If the current Vector3D object is the result of multiplying a Vector3D object by a projection Matrix3D object, the `w` property can hold the transform value. The `project()` method then can complete the projection by dividing the elements by the w property. Use `Matrix3D.rawData` property to create a projection Matrix3D object.

scaleBy | () | method |

`public function scaleBy(s:Number):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Scales the current Vector3D object by a scalar, a magnitude. The Vector3D object's x, y, and z elements are multiplied by the scalar number specified in the parameter. For example, if the vector is scaled by ten, the result is a vector that is ten times longer. The scalar can also change the direction of the vector. Multiplying the vector by a negative number reverses its direction.

Parameters

| `s:Number` — A multiplier (scalar) used to scale a Vector3D object.

subtract | () | method |

`public function subtract(a:Vector3D):Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Subtracts the value of the x, y, and z elements of the current Vector3D object from the values of the x, y, and z elements of another Vector3D object. The `subtract()` method does not change the current Vector3D object. Instead, this method returns a new Vector3D object with the new values.

Parameters

| `a:Vector3D` — The Vector3D object to be subtracted from the current Vector3D object.

Returns

| `Vector3D` — A new Vector3D object that is the difference between the current Vector3D and the specified Vector3D object.

See also

decrementBy()

toString | () | method |

`public function toString():String`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Returns a string representation of the current Vector3D object. The string contains the values of x, y, and z properties.

Returns

| `String` — A string containing the values of the x, y, and z properties.

Constant Detail

XAXIS | Constant

`public static const XAXIS:Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The x-axis defined as a Vector3D object with coordinates (1,0,0).

YAXIS | Constant |

`public static const YAXIS:Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The y-axis defined as a Vector3D object with coordinates (0,1,0).

ZAXIS | Constant |

`public static const ZAXIS:Vector3D`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The z-axis defined as a Vector3D object with coordinates (0,0,1).

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00