iOS Developer Library

Developer

ApplicationServices Framework Reference CGGeometry Reference

Options
Deployment Target:

On This Page
Language:

CGGeometry Reference

CGGeometry Reference defines structures for geometric primitives and functions that operate on them. The data structure CGPoint represents a point in a two-dimensional coordinate system. The data structure CGRect represents the location and dimensions of a rectangle. The data structure CGSize represents the dimensions of width and height.

The height and width stored in a CGRect data structure can be negative. For example, a rectangle with an origin of [0.0, 0.0] and a size of [10.0,10.0] is exactly equivalent to a rectangle with an origin of [10.0, 10.0] and a size of [-10.0,-10.0]. Your application can standardize a rectangle—that is, ensure that the height and width are stored as positive values—by calling the CGRectStandardize function. All functions described in this reference that take CGRect data structures as inputs implicitly standardize those rectangles before calculating their results. For this reason, your applications should avoid directly reading and writing the data stored in the CGRect data structure. Instead, use the functions described here to manipulate rectangles and to retrieve their characteristics.

Functions

  • Returns a point with the specified coordinates.

    Declaration

    Swift

    func CGPointMake(_ x: CGFloat, _ y: CGFloat) -> CGPoint

    Objective-C

    CGPoint CGPointMake ( CGFloat x, CGFloat y );

    Parameters

    x

    The x-coordinate of the point to construct.

    y

    The y-coordinate of the point to construct.

    Return Value

    A point.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a rectangle with the specified coordinate and size values.

    Declaration

    Swift

    func CGRectMake(_ x: CGFloat, _ y: CGFloat, _ width: CGFloat, _ height: CGFloat) -> CGRect

    Objective-C

    CGRect CGRectMake ( CGFloat x, CGFloat y, CGFloat width, CGFloat height );

    Parameters

    x

    The x-coordinate of the rectangle’s origin point.

    y

    The y-coordinate of the rectangle’s origin point.

    width

    The width of the rectangle.

    height

    The height of the rectangle.

    Return Value

    A rectangle with the specified location and dimensions.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a size with the specified dimension values.

    Declaration

    Swift

    func CGSizeMake(_ width: CGFloat, _ height: CGFloat) -> CGSize

    Objective-C

    CGSize CGSizeMake ( CGFloat width, CGFloat height );

    Parameters

    width

    A width value.

    height

    A height value.

    Return Value

    Returns a CGSize structure with the specified width and height.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a vector with the specified dimension values.

    Declaration

    Swift

    func CGVectorMake(_ dx: CGFloat, _ dy: CGFloat) -> CGVector

    Objective-C

    CGVector CGVectorMake ( CGFloat dx, CGFloat dy );

    Parameters

    dx

    The x-coordinate of the vector to construct.

    dy

    The y-coordinate of the vector to construct.

    Return Value

    Returns a CGVector structure with the specified coordinates.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 7.0 and later.

  • Divides a source rectangle into two component rectangles.

    Declaration

    Swift

    func CGRectDivide(_ rect: CGRect, _ slice: UnsafeMutablePointer<CGRect>, _ remainder: UnsafeMutablePointer<CGRect>, _ amount: CGFloat, _ edge: CGRectEdge)

    Objective-C

    void CGRectDivide ( CGRect rect, CGRect *slice, CGRect *remainder, CGFloat amount, CGRectEdge edge );

    Parameters

    rect

    The source rectangle.

    slice

    On input, a pointer to an uninitialized rectangle. On return, the rectangle is filled in with the specified edge and values that extends the distance beyond the edge specified by the amount parameter. Must not be NULL.

    remainder

    On input, a pointer to an uninitialized rectangle. On return, the rectangle contains the portion of the source rectangle that remains after CGRectEdge produces the “slice” rectangle. Must not be NULL.

    amount

    A distance from the rectangle side that is specified in the edge parameter. This distance defines the line, parallel to the specified side, that Quartz uses to divide the source rectangle.

    edge

    An edge value that specifies the side of the rectangle from which the distance passed in the amount parameter is measured. CGRectDivide produces a “slice” rectangle that contains the specified edge and extends amount distance beyond it.

    Discussion

    If rect is a null rectangle, this function outputs CGRectNull for both the slice and remainder rectangles.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a rectangle that is smaller or larger than the source rectangle, with the same center point.

    Declaration

    Swift

    func CGRectInset(_ rect: CGRect, _ dx: CGFloat, _ dy: CGFloat) -> CGRect

    Objective-C

    CGRect CGRectInset ( CGRect rect, CGFloat dx, CGFloat dy );

    Parameters

    rect

    The source CGRect structure.

    dx

    The x-coordinate value to use for adjusting the source rectangle. To create an inset rectangle, specify a positive value. To create a larger, encompassing rectangle, specify a negative value.

    dy

    The y-coordinate value to use for adjusting the source rectangle. To create an inset rectangle, specify a positive value. To create a larger, encompassing rectangle, specify a negative value.

    Return Value

    A rectangle. The origin value is offset in the x-axis by the distance specified by the dx parameter and in the y-axis by the distance specified by the dy parameter, and its size adjusted by (2*dx,2*dy), relative to the source rectangle. If dx and dy are positive values, then the rectangle’s size is decreased. If dx and dy are negative values, the rectangle’s size is increased.

    Discussion

    The rectangle is standardized and then the inset parameters are applied. If the resulting rectangle would have a negative height or width, a null rectangle is returned.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the smallest rectangle that results from converting the source rectangle values to integers.

    Declaration

    Swift

    func CGRectIntegral(_ rect: CGRect) -> CGRect

    Objective-C

    CGRect CGRectIntegral ( CGRect rect );

    Parameters

    rect

    The source rectangle.

    Return Value

    A rectangle with the smallest integer values for its origin and size that contains the source rectangle. That is, given a rectangle with fractional origin or size values, CGRectIntegral rounds the rectangle’s origin downward and its size upward to the nearest whole integers, such that the result contains the original rectangle. Returns a null rectangle if rect is a null rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the intersection of two rectangles.

    Declaration

    Swift

    func CGRectIntersection(_ rect1: CGRect, _ rect2: CGRect) -> CGRect

    Objective-C

    CGRect CGRectIntersection ( CGRect r1, CGRect r2 );

    Parameters

    rect1

    The first source rectangle.

    rect2

    The second source rectangle.

    Return Value

    A rectangle that represents the intersection of the two specified rectangles. If the two rectangles do not intersect, returns the null rectangle. To check for this condition, use CGRectIsNull.

    Discussion

    Both rectangles are standardized prior to calculating the intersection.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a rectangle with an origin that is offset from that of the source rectangle.

    Declaration

    Swift

    func CGRectOffset(_ rect: CGRect, _ dx: CGFloat, _ dy: CGFloat) -> CGRect

    Objective-C

    CGRect CGRectOffset ( CGRect rect, CGFloat dx, CGFloat dy );

    Parameters

    rect

    The source rectangle.

    dx

    The offset value for the x-coordinate.

    dy

    The offset value for the y-coordinate.

    Return Value

    A rectangle that is the same size as the source, but with its origin offset by dx units along the x-axis and dy units along the y-axis with respect to the source. Returns a null rectangle if rect is a null rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns a rectangle with a positive width and height.

    Declaration

    Swift

    func CGRectStandardize(_ rect: CGRect) -> CGRect

    Objective-C

    CGRect CGRectStandardize ( CGRect rect );

    Parameters

    rect

    The source rectangle.

    Return Value

    A rectangle that represents the source rectangle, but with positive width and height values. Returns a null rectangle if rect is a null rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the smallest rectangle that contains the two source rectangles.

    Declaration

    Swift

    func CGRectUnion(_ r1: CGRect, _ r2: CGRect) -> CGRect

    Objective-C

    CGRect CGRectUnion ( CGRect r1, CGRect r2 );

    Parameters

    r1

    The first source rectangle.

    r2

    The second source rectangle.

    Return Value

    The smallest rectangle that completely contains both of the source rectangles.

    Discussion

    Both rectangles are standardized prior to calculating the union. If either of the rectangles is a null rectangle, a copy of the other rectangle is returned (resulting in a null rectangle if both rectangles are null). Otherwise a rectangle that completely contains the source rectangles is returned.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns whether two points are equal.

    Declaration

    Objective-C

    bool CGPointEqualToPoint ( CGPoint point1, CGPoint point2 );

    Parameters

    point1

    The first point to examine.

    point2

    The second point to examine.

    Return Value

    true if the two specified points are the same; otherwise, false.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Returns whether two sizes are equal.

    Declaration

    Objective-C

    bool CGSizeEqualToSize ( CGSize size1, CGSize size2 );

    Parameters

    size1

    The first size to examine.

    size2

    The second size to examine.

    Return Value

    true if the two specified sizes are equal; otherwise, false.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Returns whether two rectangles are equal in size and position.

    Declaration

    Swift

    func CGRectEqualToRect(_ rect1: CGRect, _ rect2: CGRect) -> Bool

    Objective-C

    bool CGRectEqualToRect ( CGRect rect1, CGRect rect2 );

    Parameters

    rect1

    The first rectangle to examine.

    rect2

    The second rectangle to examine.

    Return Value

    true if the two specified rectangles have equal size and origin values, or if both rectangles are null rectangles. Otherwise, false.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns whether two rectangles intersect.

    Declaration

    Swift

    func CGRectIntersectsRect(_ rect1: CGRect, _ rect2: CGRect) -> Bool

    Objective-C

    bool CGRectIntersectsRect ( CGRect rect1, CGRect rect2 );

    Parameters

    rect1

    The first rectangle to examine.

    rect2

    The second rectangle to examine.

    Return Value

    true if the two specified rectangles intersect; otherwise, false. The first rectangle intersects the second if the intersection of the rectangles is not equal to the null rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns whether a rectangle contains a specified point.

    Declaration

    Swift

    func CGRectContainsPoint(_ rect: CGRect, _ point: CGPoint) -> Bool

    Objective-C

    bool CGRectContainsPoint ( CGRect rect, CGPoint point );

    Parameters

    rect

    The rectangle to examine.

    point

    The point to examine.

    Return Value

    true if the rectangle is not null or empty and the point is located within the rectangle; otherwise, false.

    Discussion

    A point is considered inside the rectangle if its coordinates lie inside the rectangle or on the minimum X or minimum Y edge.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns whether the first rectangle contains the second rectangle.

    Declaration

    Swift

    func CGRectContainsRect(_ rect1: CGRect, _ rect2: CGRect) -> Bool

    Objective-C

    bool CGRectContainsRect ( CGRect rect1, CGRect rect2 );

    Parameters

    rect1

    The rectangle to examine for containment of the rectangle passed in rect2.

    rect2

    The rectangle to examine for being contained in the rectangle passed in rect1.

    Return Value

    true if the rectangle specified by rect2 is contained in the rectangle passed in rect1; otherwise, false. The first rectangle contains the second if the union of the two rectangles is equal to the first rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the smallest value for the x-coordinate of the rectangle.

    Declaration

    Swift

    func CGRectGetMinX(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMinX ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The smallest value for the x-coordinate of the rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the smallest value for the y-coordinate of the rectangle.

    Declaration

    Swift

    func CGRectGetMinY(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMinY ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The smallest value for the y-coordinate of the rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the x- coordinate that establishes the center of a rectangle.

    Declaration

    Swift

    func CGRectGetMidX(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMidX ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The x-coordinate of the center of the specified rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the y-coordinate that establishes the center of the rectangle.

    Declaration

    Swift

    func CGRectGetMidY(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMidY ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The y-coordinate of the center of the specified rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the largest value of the x-coordinate for the rectangle.

    Declaration

    Swift

    func CGRectGetMaxX(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMaxX ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The largest value of the x-coordinate for the rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the largest value for the y-coordinate of the rectangle.

    Declaration

    Swift

    func CGRectGetMaxY(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetMaxY ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The largest value for the y-coordinate of the rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the height of a rectangle.

    Declaration

    Swift

    func CGRectGetHeight(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetHeight ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The height of the specified rectangle.

    Discussion

    Regardless of whether the height is stored in the CGRect data structure as a positive or negative number, this function returns the height as if the rectangle were standardized. That is, the result is never a negative number.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the width of a rectangle.

    Declaration

    Swift

    func CGRectGetWidth(_ rect: CGRect) -> CGFloat

    Objective-C

    CGFloat CGRectGetWidth ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    The width of the specified rectangle.

    Discussion

    Regardless of whether the width is stored in the CGRect data structure as a positive or negative number, this function returns the width as if the rectangle were standardized. That is, the result is never a negative number.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns whether a rectangle has zero width or height, or is a null rectangle.

    Declaration

    Swift

    func CGRectIsEmpty(_ rect: CGRect) -> Bool

    Objective-C

    bool CGRectIsEmpty ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    true if the specified rectangle is empty; otherwise, false.

    Discussion

    An empty rectangle is either a null rectangle or a valid rectangle with zero height or width.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

    See Also

    CGRectIsNull

  • Returns whether the rectangle is equal to the null rectangle.

    Declaration

    Swift

    func CGRectIsNull(_ rect: CGRect) -> Bool

    Objective-C

    bool CGRectIsNull ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    true if the specified rectangle is null; otherwise, false.

    Discussion

    A null rectangle is the equivalent of an empty set. For example, the result of intersecting two disjoint rectangles is a null rectangle. A null rectangle cannot be drawn and interacts with other rectangles in special ways.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

    See Also

    CGRectIsEmpty

  • Returns whether a rectangle is infinite.

    Declaration

    Swift

    func CGRectIsInfinite(_ rect: CGRect) -> Bool

    Objective-C

    bool CGRectIsInfinite ( CGRect rect );

    Parameters

    rect

    The rectangle to examine.

    Return Value

    Returns true if the specified rectangle is infinite; otherwise, false.

    Discussion

    An infinite rectangle is one that has no defined bounds. Infinite rectangles can be created as output from a tiling filter. For example, the Core Image framework perspective tile filter creates an image whose extent is described by an infinite rectangle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Data Types

  • The basic type for all floating-point values.

    Declaration

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • A structure that contains a point in a two-dimensional coordinate system.

    Declaration

    Swift

    struct CGPoint { var x: CGFloat var y: CGFloat }

    Objective-C

    struct CGPoint { CGFloat x; CGFloat y; }; typedef struct CGPoint CGPoint;

    Fields

    x

    The x-coordinate of the point.

    y

    The y-coordinate of the point.

    Availability

    Available in iOS 2.0 and later.

  • A structure that contains the location and dimensions of a rectangle.

    Declaration

    Swift

    struct CGRect { var origin: CGPoint var size: CGSize }

    Objective-C

    struct CGRect { CGPoint origin; CGSize size; }; typedef struct CGRect CGRect;

    Fields

    origin

    A point that specifies the coordinates of the rectangle’s origin.

    size

    A size that specifies the height and width of the rectangle.

    Discussion

    In the default Quartz coordinate space, the origin is located in the lower-left corner of the rectangle and the rectangle extends towards the upper-right corner. If the context has a flipped-coordinate space—often the case on iOS—the origin is in the upper-left corner and the rectangle extends towards the lower-right corner.

    Availability

    Available in iOS 2.0 and later.

  • A structure that contains width and height values.

    Declaration

    Swift

    struct CGSize { var width: CGFloat var height: CGFloat }

    Objective-C

    struct CGSize { CGFloat width; CGFloat height; }; typedef struct CGSize CGSize;

    Fields

    width

    A width value.

    height

    A height value.

    Discussion

    A CGSize structure is sometimes used to represent a distance vector, rather than a physical size. As a vector, its values can be negative. To normalize a CGRect structure so that its size is represented by positive values, call the CGRectStandardize function.

    Availability

    Available in iOS 2.0 and later.

  • A structure that contains a two-dimensional vector.

    Declaration

    Swift

    struct CGVector { var dx: CGFloat var dy: CGFloat }

    Objective-C

    struct CGVector { CGFloat dx; CGFloat dy; }; typedef struct CGVector CGVector;

    Fields

    dx

    The x-coordinate of the vector.

    dy

    The y-coordinate of the vector.

    Availability

    Available in iOS 7.0 and later.

Constants

  • A rectangle that has infinite extent.

    Declaration

    Swift

    let CGRectInfinite: CGRect

    Objective-C

    const CGRect CGRectInfinite;

    Constants

    • CGRectInfinite

      CGRectInfinite

      A rectangle that has infinite extent.

      Available in iOS 2.0 and later.

    Import Statement

  • A zero point, zero rectangle, or zero size.

    Declaration

    Swift

    let CGPointZero: CGPoint let CGRectZero: CGRect let CGSizeZero: CGSize

    Objective-C

    const CGPoint CGPointZero; const CGRect CGRectZero; const CGSize CGSizeZero;

    Constants

    • CGPointZero

      CGPointZero

      A point constant with location (0,0). The zero point is equivalent to CGPointMake(0,0).

      Available in iOS 2.0 and later.

    • CGRectZero

      CGRectZero

      A rectangle constant with location (0,0), and width and height of 0. The zero rectangle is equivalent to CGRectMake(0,0,0,0).

      Available in iOS 2.0 and later.

    • CGSizeZero

      CGSizeZero

      A size constant with width and height of 0. The zero size is equivalent to CGSizeMake(0,0).

      Available in iOS 2.0 and later.

    Import Statement

  • The null or empty rectangle.

    Declaration

    Swift

    let CGRectNull: CGRect

    Objective-C

    const CGRect CGRectNull;

    Constants

    • CGRectNull

      CGRectNull

      The null rectangle. This is the rectangle returned when, for example, you intersect two disjoint rectangles. Note that the null rectangle is not the same as the zero rectangle. For example, the union of a rectangle with the null rectangle is the original rectangle (that is, the null rectangle contributes nothing).

      Available in iOS 2.0 and later.

    Import Statement

  • Coordinates that establish the edges of a rectangle.

    Declaration

    Swift

    enum CGRectEdge : UInt32 { case MinXEdge case MinYEdge case MaxXEdge case MaxYEdge }

    Objective-C

    enum CGRectEdge { CGRectMinXEdge, CGRectMinYEdge, CGRectMaxXEdge, CGRectMaxYEdge }; typedef enum CGRectEdge CGRectEdge;

    Constants

    • MinXEdge

      CGRectMinXEdge

      The minimum value for the x-coordinate of the rectangle. In OS X and iOS with the default coordinate system this is the left edge of the rectangle.

      Available in iOS 2.0 and later.

    • MinYEdge

      CGRectMinYEdge

      The minimum value for the y-coordinate of the rectangle. In OS X with the default coordinate system this is the bottom edge of the rectangle. In iOS with the default coordinate system this is the top edge of the rectangle.

      Available in iOS 2.0 and later.

    • MaxXEdge

      CGRectMaxXEdge

      The maximum value for the x-coordinate of the rectangle. In OS X and iOS with the default coordinate system this is the right edge of the rectangle.

      Available in iOS 2.0 and later.

    • MaxYEdge

      CGRectMaxYEdge

      The maximum value for the y-coordinate of the rectangle. In OS X with the default coordinate system this is the top edge of the rectangle. In iOS with the default coordinate system this is the bottom edge of the rectangle.

      Available in iOS 2.0 and later.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Informational macros for the CGFloat type.

    Declaration

    Swift

    var CGFLOAT_MIN: Float { get } var CGFLOAT_MAX: Float { get } var CGFLOAT_IS_DOUBLE: Int32 { get }

    Constants

    • CGFLOAT_MIN

      CGFLOAT_MIN

      The minimum non-negative non-subnormal value value for a CGFloat type. For 32-bit code, this value is 1.17549435e-38F. For 64-bit code, it is 2.2250738585072014e-308.

      Available in iOS 2.0 and later.

    • CGFLOAT_MAX

      CGFLOAT_MAX

      The maximum non-infinite value for a CGFloat type. For 32-bit code, this value is 3.40282347e+38F. For 64-bit code, it is 1.7976931348623157e+308.

      Available in iOS 2.0 and later.

    • CGFLOAT_IS_DOUBLE

      CGFLOAT_IS_DOUBLE

      Indicates whether CGFloat is defined as a float or double type.

      Available in iOS 2.0 and later.

    Import Statement