Inherits From:
NSObject
Conforms To:
NSCoding
NSCopying
NSObject (NSObject)
Declared In:
AppKit/NSAffineTransform.h
If you create an NSAffineTransform object using the transform
class method then the matrix will be initialized to the identity matrix. The identity matrix transforms any point to itself. Use alloc...
and initWithTransform:
method if you want to specify the initial values of the transform.
Use the translateXBy:yBy:
, rotate...
, and scale...
methods to apply translate, rotate and scale operations. Using the transform...
methods you can apply the transformation to an NSPoint, NSSize, or NSBezierPath object. Or using the concat
method you can concatenate it to the current transformation. The current transformation is stored in the current graphics context and will be applied to subsequent drawing operations.
The most common sequence of actions is to create an NSAffineTransform object, send it a sequence of translateXBy:yBy:
, rotate...
and scale...
messages to produce the desired transformation, and then concatenate it to the current transformation matrix as in this example implementation of a custom NSView's drawRect:
method:
By the time the drawRect: method is invoked, the current transformation is already a concatenation of the screen's, window's and any superview's transformations. Concatenating your transformation to the current transformation modifies subsequent drawing operations within the bounds of your NSView object.The Mathematics An NSAffineTransform object uses a 3x3 transformation matrix of the form:
m11 m12 0.0
m21 m22 0.0
tx ty 1.0
where a point (x,y) is transformed into another point (x',y') using these linear equations:
x' = m11x + m21y + tx
y' = m12x + m22y + ty
Concatenation, translation, rotation, and scaling are performed by matrix multiplication. The order in which transformations are multiplied is important because matrix operations are associative, but not commutative (matrix1 matrix2
matrix2
matrix1).
Apart from performing linear transformations, you can append and concatenate a matrix to the receiver's matrix using the appendTransform:
and prependTransform:
methods. The prependTransform:
method concatenates the supplied transform to the receiver, so that it is the last transform applied to the user coordinate. Conversely, appendTransform:
appends the supplied transform to the receiver so that it is the first transform applied to the user coordinate.
The transformation matrix values can also be represented by a six-element NSAffineTransformStruct:
[m11 m12 m21 m22 tx ty]
NSAffineTransformStruct is provided as an alternate representation of a affine transformation matrix that you can use to perform matrix operations more efficiently (or to create custom transforms). Use the transfromStruct
method to obtain this six-element structure representation, perform your specific mathematics on the NSAffineTransformStruct returned, and use setTransformStruct:
to set the NSAffineTransform object's matrix to the computed values. You may also use an NSAffineTransformStruct to set the initial values of an NSAffineTransform object.
transform
Creates and returns a new instance of NSAffineTransform initialized to the identity matrix. The identity matrix transforms any point to itself.
See also:
- initWithTransform:
appendTransform:
(NSAffineTransform *)aTransform
Appends aTransform's matrix to the receiver's transformation matrix. Performs a multiplication of the receiver's matrix and aTransform's matrix, and replaces the receiver's matrix with the result. This has the effect of applying aTransform's matrix before the receiver's matrix
See also:
- prependTransform:
concat
Concatenates the receiver's matrix with the current transformation matrix stored in the current graphics context replacing the current transformation matrix with the result (concatenation is performed by matrix multiplication, see "Class Description" above). If this method is invoked from within an NSView's drawRect:
method, then the current transformation matrix is an accumulation of the screen, window and any superview's transformation matrices. Invoking this method defines a new user coordinate system whose coordinates are mapped into the former coordinate system according to the receiver's transformation matrix.
See also:
- set
initWithTransform:
(NSAffineTransform *)aTransform
Initializes the receiver's matrix to aTransform's matrix and returns the receiver.
See also:
+ transform
invert
Replaces the receiver's matrix with the result of inverting its matrix. If a previous point (x,y) was transformed to (x',y'), then after inverting the matrix, point (x',y') will be transformed to (x,y).
prependTransform:
(NSAffineTransform *)aTransform
Concatenates aTransform's matrix with the receiver's matrix. Performs a multiplication of aTransform's matrix and the receiver's matrix, and replaces the receiver's matrix with the result. This has the effect of applying aTransform after the receiver's transform.
See also:
- appendTransform:
rotateByDegrees:
(float)angle
Rotates the receiver's transformation matrix by angle degrees, replacing the receiver's matrix with the result. After invoking this method, applying the receiver's matrix will turn the axes about the current origin by angle degrees.
See also:
- rotateByRadians:
, - scaleBy:
,
- scaleXBy:yBy:
, - translateXBy:yBy:
rotateByRadians:
(float)angle
Rotates the receiver's transformation matrix by angle radians, replacing the receiver's matrix with the result. After invoking this method, applying the receiver's matrix will turn the axes about the current origin by angle radians.
See also:
- rotateByDegrees:
, - scaleBy:
,
- scaleXBy:yBy:
, - translateXBy:yBy:
scaleBy:
(float)scale
Scales the receiver's transformation matrix by the factor scale in both x and y, replacing the receiver's matrix with the result. Hereafter, applying the receiver's matrix will modify the unit lengths along the current x and y axes by a factor of scale.
See also:
- rotateByDegrees:
, - rotateByRadians:
, - scaleXBy:yBy:
,
- translateXBy:yBy:
scaleXBy:
(float)scaleX yBy:
(float)scaleY
Scales the receiver's transformation matrix by the factor scaleX in x and scaleY in y, replacing the receiver's matrix with the result. After invoking this method, applying the receiver's matrix will modify the unit length on the x axes by a factor of scaleX and the y axes by a factor of scaleY.
See also:
- rotateByDegrees:
, - rotateByRadians:
, - scaleBy:
,
- translateXBy:yBy:
set
Sets the current transformation matrix to the receiver's transformation matrix. The current transformation is stored in the current graphics context and will be applied to subsequent drawing operations. You rarely use this method because it wipes out the existing transformation matrix, an accumulation of the screen's, window's and any superview's transformation matrices. Instead use concat
to modify the current transformation matrix.
setTransformStruct:
(NSAffineTransformStruct)aTransformStruct
Sets the receiver's transformation matrix using the values in aTransformStruct where the matrix is of the form:
m11 m12 0.0
m21 m22 0.0
tx ty 1.0
and the six-element structure defined by an NSAffineTransformStruct is of the form:
[m11 m12 m21 m22 tx ty]
NSAffineTransformStruct is an alternate representation of a transformation matrix that can be used to perform matrix operations more efficiently.
See also:
- initWithTransform:
, - transformStruct
transformStruct
Returns the NSAffineTransformationStruct equivalent to the receiver's matrix where the matrix is of the form:
m11 m12 0.0
m21 m22 0.0
tx ty 1.0
and the six-element structure defined by an NSAffineTransformStruct is of the form:
[m11 m12 m21 m22 tx ty]
NSAffineTransformStruct is an alternate representation of a transformation matrix that can be used to perform matrix operations more efficiently.
See also:
- initWithTransform:
, - setTransformStruct:
transformBezierPath:
(NSBezierPath *)aPath
Creates and returns a new NSBezierPath object with each point in the curve defined by aPath transformed by the receiver. The original aPath is not modified.
See also:
- transformPoint:
, - transformSize:
transformPoint:
(NSPoint)aPoint
Returns the result of applying the receiver's transform to aPoint.
See also:
- transformBezierPath:
, - transformSize:
transformSize:
(NSSize)aSize
Returns the result of applying the receiver's transform to aSize. Since aSize specifies a width and height, not an x and y coordinate, any translation operations made to the receiver are not applied. This method is useful for transforming delta, or distance values.
See also:
- transformBezierPath:
, - transformPoint:
translateXBy:
(float)deltaX yBy:
(float)deltaY
Translates the receiver's transformataion matrix by deltaX in the x and deltaY in the y directions, replacing the receiver's matrix with the result. After invoking this method, applying the receiver's matrix will move the coordinate system's origin to (deltaX,deltaY).
See also:
- rotateByDegrees:
, - rotateByRadians:
, - scaleBy:
,
- scaleXBy:yBy: