Quartz 2D Reference Collection CGAffineTransform Reference

Options
Deployment Target:

On This Page
Language:

# CGAffineTransform Reference

The `CGAffineTransform` data structure represents a matrix used for affine transformations. A transformation specifies how points in one coordinate system map to points in another coordinate system. An affine transformation is a special type of mapping that preserves parallel lines in a path but does not necessarily preserve lengths or angles. Scaling, rotation, and translation are the most commonly used manipulations supported by affine transforms, but skewing is also possible.

Quartz provides functions that create, concatenate, and apply affine transformations using the `CGAffineTransform` data structure. For information on how to use affine transformation functions, see Quartz 2D Programming Guide.

You typically do not need to create an affine transform directly—CGContext Reference describes functions that modify the current affine transform. If you don’t plan to reuse an affine transform, you may want to use `CGContextScaleCTM`, `CGContextRotateCTM`, `CGContextTranslateCTM`, or `CGContextConcatCTM`.

### Functions

• ``` CGAffineTransformMake ```

Returns an affine transformation matrix constructed from values you provide.

#### Declaration

Objective-C

``` CGAffineTransform CGAffineTransformMake ( CGFloat a, CGFloat b, CGFloat c, CGFloat d, CGFloat tx, CGFloat ty ); ```

#### Parameters

 ``` a ``` The value at position [1,1] in the matrix. ``` b ``` The value at position [1,2] in the matrix. ``` c ``` The value at position [2,1] in the matrix. ``` d ``` The value at position [2,2] in the matrix. ``` tx ``` The value at position [3,1] in the matrix. ``` ty ``` The value at position [3,2] in the matrix.

#### Return Value

A new affine transform matrix constructed from the values you specify.

#### Discussion

This function creates a `CGAffineTransform` structure that represents a new affine transformation matrix, which you can use (and reuse, if you want) to transform a coordinate system. The matrix takes the following form:

Because the third column is always `(0,0,1)`, the `CGAffineTransform` data structure returned by this function contains values for only the first two columns.

If you want only to transform an object to be drawn, it is not necessary to construct an affine transform to do so. The most direct way to transform your drawing is by calling the appropriate `CGContext` function to adjust the current transformation matrix. For a list of functions, see CGContext Reference.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformMakeRotation(_:) CGAffineTransformMakeRotation ```

Returns an affine transformation matrix constructed from a rotation value you provide.

#### Declaration

Swift

``` func CGAffineTransformMakeRotation(_ angle: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformMakeRotation ( CGFloat angle ); ```

#### Parameters

 ``` angle ``` The angle, in radians, by which this matrix rotates the coordinate system axes. In iOS, a positive value specifies counterclockwise rotation and a negative value specifies clockwise rotation. In OS X, a positive value specifies clockwise rotation and a negative value specifies counterclockwise rotation.

#### Return Value

A new affine transformation matrix.

#### Discussion

This function creates a `CGAffineTransform` structure, which you can use (and reuse, if you want) to rotate a coordinate system. The matrix takes the following form:

The actual direction of rotation is dependent on the coordinate system orientation of the target platform, which is different in iOS and OS X. Because the third column is always `(0,0,1)`, the `CGAffineTransform` data structure returned by this function contains values for only the first two columns.

These are the resulting equations that Quartz uses to apply the rotation to a point (x, y):

If you want only to rotate an object to be drawn, it is not necessary to construct an affine transform to do so. The most direct way to rotate your drawing is by calling the function `CGContextRotateCTM`.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformMakeScale(_:_:) CGAffineTransformMakeScale ```

Returns an affine transformation matrix constructed from scaling values you provide.

#### Declaration

Swift

``` func CGAffineTransformMakeScale(_ sx: CGFloat, _ sy: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformMakeScale ( CGFloat sx, CGFloat sy ); ```

#### Parameters

 ``` sx ``` The factor by which to scale the x-axis of the coordinate system. ``` sy ``` The factor by which to scale the y-axis of the coordinate system.

#### Return Value

A new affine transformation matrix.

#### Discussion

This function creates a `CGAffineTransform` structure, which you can use (and reuse, if you want) to scale a coordinate system. The matrix takes the following form:

Because the third column is always `(0,0,1)`, the `CGAffineTransform` data structure returned by this function contains values for only the first two columns.

These are the resulting equations that Quartz uses to scale the coordinates of a point (x,y):

If you want only to scale an object to be drawn, it is not necessary to construct an affine transform to do so. The most direct way to scale your drawing is by calling the function `CGContextScaleCTM`.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformMakeTranslation(_:_:) CGAffineTransformMakeTranslation ```

Returns an affine transformation matrix constructed from translation values you provide.

#### Declaration

Swift

``` func CGAffineTransformMakeTranslation(_ tx: CGFloat, _ ty: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformMakeTranslation ( CGFloat tx, CGFloat ty ); ```

#### Parameters

 ``` tx ``` The value by which to move the x-axis of the coordinate system. ``` ty ``` The value by which to move the y-axis of the coordinate system.

#### Return Value

A new affine transform matrix.

#### Discussion

This function creates a `CGAffineTransform` structure. which you can use (and reuse, if you want) to move a coordinate system. The matrix takes the following form:

Because the third column is always `(0,0,1)`, the `CGAffineTransform` data structure returned by this function contains values for only the first two columns.

These are the resulting equations Quartz uses to apply the translation to a point (x,y):

If you want only to move the location where an object is drawn, it is not necessary to construct an affine transform to do so. The most direct way to move your drawing is by calling the function `CGContextTranslateCTM`.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformTranslate(_:_:_:) CGAffineTransformTranslate ```

Returns an affine transformation matrix constructed by translating an existing affine transform.

#### Declaration

Swift

``` func CGAffineTransformTranslate(_ t: CGAffineTransform, _ tx: CGFloat, _ ty: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformTranslate ( CGAffineTransform t, CGFloat tx, CGFloat ty ); ```

#### Parameters

 ``` t ``` An existing affine transform. ``` tx ``` The value by which to move x values with the affine transform. ``` ty ``` The value by which to move y values with the affine transform.

#### Return Value

A new affine transformation matrix.

#### Discussion

You use this function to create a new affine transform by adding translation values to an existing affine transform. The resulting structure represents a new affine transform, which you can use (and reuse, if you want) to move a coordinate system.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformScale(_:_:_:) CGAffineTransformScale ```

Returns an affine transformation matrix constructed by scaling an existing affine transform.

#### Declaration

Swift

``` func CGAffineTransformScale(_ t: CGAffineTransform, _ sx: CGFloat, _ sy: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformScale ( CGAffineTransform t, CGFloat sx, CGFloat sy ); ```

#### Parameters

 ``` t ``` An existing affine transform. ``` sx ``` The value by which to scale x values of the affine transform. ``` sy ``` The value by which to scale y values of the affine transform.

#### Return Value

A new affine transformation matrix.

#### Discussion

You use this function to create a new affine transformation matrix by adding scaling values to an existing affine transform. The resulting structure represents a new affine transform, which you can use (and reuse, if you want) to scale a coordinate system.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformRotate(_:_:) CGAffineTransformRotate ```

Returns an affine transformation matrix constructed by rotating an existing affine transform.

#### Declaration

Swift

``` func CGAffineTransformRotate(_ t: CGAffineTransform, _ angle: CGFloat) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformRotate ( CGAffineTransform t, CGFloat angle ); ```

#### Parameters

 ``` t ``` An existing affine transform. ``` angle ``` The angle, in radians, by which to rotate the affine transform. In iOS, a positive value specifies counterclockwise rotation and a negative value specifies clockwise rotation. In OS X, a positive value specifies clockwise rotation and a negative value specifies counterclockwise rotation.

#### Return Value

A new affine transformation matrix.

#### Discussion

You use this function to create a new affine transformation matrix by adding a rotation value to an existing affine transform. The resulting structure represents a new affine transform, which you can use (and reuse, if you want) to rotate a coordinate system.

The actual direction of rotation is dependent on the coordinate system orientation of the target platform, which is different in iOS and OS X.

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformInvert(_:) CGAffineTransformInvert ```

Returns an affine transformation matrix constructed by inverting an existing affine transform.

#### Declaration

Swift

``` func CGAffineTransformInvert(_ t: CGAffineTransform) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformInvert ( CGAffineTransform t ); ```

#### Parameters

 ``` t ``` An existing affine transform.

#### Return Value

A new affine transformation matrix. If the affine transform passed in parameter `t` cannot be inverted, Quartz returns the affine transform unchanged.

#### Discussion

Inversion is generally used to provide reverse transformation of points within transformed objects. Given the coordinates (x,y), which have been transformed by a given matrix to new coordinates (x’,y’), transforming the coordinates (x’,y’) by the inverse matrix produces the original coordinates (x,y).

#### Availability

Available in OS X v10.0 and later.

• ``` CGAffineTransformConcat(_:_:) CGAffineTransformConcat ```

Returns an affine transformation matrix constructed by combining two existing affine transforms.

#### Declaration

Swift

``` func CGAffineTransformConcat(_ t1: CGAffineTransform, _ t2: CGAffineTransform) -> CGAffineTransform ```

Objective-C

``` CGAffineTransform CGAffineTransformConcat ( CGAffineTransform t1, CGAffineTransform t2 ); ```

#### Parameters

 ``` t1 ``` The first affine transform. ``` t2 ``` The second affine transform. This affine transform is concatenated to the first affine transform.

#### Return Value

A new affine transformation matrix. That is, t’ = t1*t2.

#### Discussion

Concatenation combines two affine transformation matrices by multiplying them together. You might perform several concatenations in order to create a single affine transform that contains the cumulative effects of several transformations.

Note that matrix operations are not commutative—the order in which you concatenate matrices is important. That is, the result of multiplying matrix `t1` by matrix `t2` does not necessarily equal the result of multiplying matrix `t2` by matrix `t1`.

#### Availability

Available in OS X v10.0 and later.

• ``` CGPointApplyAffineTransform ```

Returns the point resulting from an affine transformation of an existing point.

#### Declaration

Objective-C

``` CGPoint CGPointApplyAffineTransform ( CGPoint point, CGAffineTransform t ); ```

#### Parameters

 ``` point ``` A point that specifies the x- and y-coordinates to transform. ``` t ``` The affine transform to apply.

#### Return Value

A new point resulting from applying the specified affine transform to the existing point.

#### Availability

Available in OS X v10.0 and later.

• ``` CGSizeApplyAffineTransform ```

Returns the height and width resulting from a transformation of an existing height and width.

#### Declaration

Objective-C

``` CGSize CGSizeApplyAffineTransform ( CGSize size, CGAffineTransform t ); ```

#### Parameters

 ``` size ``` A size that specifies the height and width to transform. ``` t ``` The affine transform to apply.

#### Return Value

A new size resulting from applying the specified affine transform to the existing size.

#### Availability

Available in OS X v10.0 and later.

• ``` CGRectApplyAffineTransform(_:_:) CGRectApplyAffineTransform ```

Applies an affine transform to a rectangle.

#### Declaration

Swift

``` func CGRectApplyAffineTransform(_ rect: CGRect, _ t: CGAffineTransform) -> CGRect ```

Objective-C

``` CGRect CGRectApplyAffineTransform ( CGRect rect, CGAffineTransform t ); ```

#### Parameters

 ``` rect ``` The rectangle whose corner points you want to transform. ``` t ``` The affine transform to apply to the `rect` parameter.

#### Return Value

The transformed rectangle.

#### Discussion

Because affine transforms do not preserve rectangles in general, the function `CGRectApplyAffineTransform` returns the smallest rectangle that contains the transformed corner points of the `rect` parameter. If the affine transform `t` consists solely of scaling and translation operations, then the returned rectangle coincides with the rectangle constructed from the four transformed corners.

#### Availability

Available in OS X v10.4 and later.

• ``` CGAffineTransformIsIdentity(_:) CGAffineTransformIsIdentity ```

Checks whether an affine transform is the identity transform.

#### Declaration

Swift

``` func CGAffineTransformIsIdentity(_ t: CGAffineTransform) -> Bool ```

Objective-C

``` bool CGAffineTransformIsIdentity ( CGAffineTransform t ); ```

#### Parameters

 ``` t ``` The affine transform to check.

#### Return Value

Returns `true` if `t` is the identity transform, `false` otherwise.

#### Availability

Available in OS X v10.4 and later.

• ``` CGAffineTransformEqualToTransform(_:_:) CGAffineTransformEqualToTransform ```

Checks whether two affine transforms are equal.

#### Declaration

Swift

``` func CGAffineTransformEqualToTransform(_ t1: CGAffineTransform, _ t2: CGAffineTransform) -> Bool ```

Objective-C

``` bool CGAffineTransformEqualToTransform ( CGAffineTransform t1, CGAffineTransform t2 ); ```

#### Parameters

 ``` t1 ``` An affine transform. ``` t2 ``` An affine transform.

#### Return Value

Returns `true` if `t1` and `t2` are equal, `false` otherwise.

#### Availability

Available in OS X v10.4 and later.

### Data Types

• ``` CGAffineTransform ```

A structure for holding an affine transformation matrix.

#### Declaration

Swift

``` struct CGAffineTransform { var a: CGFloat var b: CGFloat var c: CGFloat var d: CGFloat var tx: CGFloat var ty: CGFloat init() init(a a: CGFloat, b b: CGFloat, c c: CGFloat, d d: CGFloat, tx tx: CGFloat, ty ty: CGFloat) } ```

Objective-C

``` struct CGAffineTransform { CGFloat a; CGFloat b; CGFloat c; CGFloat d; CGFloat tx; CGFloat ty; }; typedef struct CGAffineTransform CGAffineTransform; ```

#### Fields

``` a ```

The entry at position [1,1] in the matrix.

``` b ```

The entry at position [1,2] in the matrix.

``` c ```

The entry at position [2,1] in the matrix.

``` d ```

The entry at position [2,2] in the matrix.

``` tx ```

The entry at position [3,1] in the matrix.

``` ty ```

The entry at position [3,2] in the matrix.

#### Discussion

In Quartz 2D, an affine transformation matrix is used to rotate, scale, translate, or skew the objects you draw in a graphics context. The `CGAffineTransform` type provides functions for creating, concatenating, and applying affine transformations.

In Quartz, affine transforms are represented by a 3 by 3 matrix:

Because the third column is always `(0,0,1)`, the `CGAffineTransform` data structure contains values for only the first two columns.

Conceptually, a Quartz affine transform multiplies a row vector representing each point (x,y) in your drawing by this matrix, producing a vector that represents the corresponding point (x’,y’):

Given the 3 by 3 matrix, Quartz uses the following equations to transform a point (x, y) in one coordinate system into a resultant point (x’,y’) in another coordinate system.

The matrix thereby “links” two coordinate systems—it specifies how points in one coordinate system map to points in another.

Note that you do not typically need to create affine transforms directly. If you want only to draw an object that is scaled or rotated, for example, it is not necessary to construct an affine transform to do so. The most direct way to manipulate your drawing—whether by movement, scaling, or rotation—is to call the functions `CGContextTranslateCTM`, `CGContextScaleCTM`, or `CGContextRotateCTM`, respectively. You should generally only create an affine transform if you want to reuse it later.

#### Availability

Available in OS X v10.0 and later.

### Constants

• ``` CGAffineTransformIdentity ```

The identity transform.

#### Declaration

Swift

`let CGAffineTransformIdentity: CGAffineTransform`

Objective-C

```const CGAffineTransform CGAffineTransformIdentity; ```

#### Constants

• `CGAffineTransformIdentity`

`CGAffineTransformIdentity`

The identity transform:

Available in OS X v10.0 and later.