CGGeometry Reference
Overview
CGGeometry Reference defines structures for geometric primitives and functions that operate on them. The data structure CGPoint
represents a point in a twodimensional 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 by Task
Creating a Dictionary Representation from a Geometric Primitive

CGPointCreateDictionaryRepresentation

CGSizeCreateDictionaryRepresentation

CGRectCreateDictionaryRepresentation
Creating a Geometric Primitive from a Dictionary Representation

CGPointMakeWithDictionaryRepresentation

CGSizeMakeWithDictionaryRepresentation

CGRectMakeWithDictionaryRepresentation
Creating a Geometric Primitive from Values
Modifying Rectangles

CGRectDivide

CGRectInset

CGRectIntegral

CGRectIntersection

CGRectOffset

CGRectStandardize

CGRectUnion
Comparing Values
Checking for Membership
Getting Min, Mid, and Max Values
Getting Height and Width
Checking Rectangle Characteristics
Functions
CGPointCreateDictionaryRepresentation
Returns a dictionary representation of the specified point.
CFDictionaryRef CGPointCreateDictionaryRepresentation( CGPoint point );
Parameters
 point
A point.
Return Value
The dictionary representation of the point.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGPointEqualToPoint
Returns whether two points are equal.
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
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGPointMake
Returns a point with the specified coordinates.
CGPoint CGPointMake ( CGFloat x, CGFloat y );
Parameters
 x
The xcoordinate of the point to construct.
 y
The ycoordinate of the point to construct.
Return Value
A point.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGPointMakeWithDictionaryRepresentation
Fills in a point using the contents of the specified dictionary.
bool CGPointMakeWithDictionaryRepresentation( CFDictionaryRef dict, CGPoint *point );
Parameters
 dict
A dictionary that was previously returned from the function
CGPointCreateDictionaryRepresentation
. point
On return, the point created from the provided dictionary.
Return Value
true
if successful; otherwise false
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectContainsPoint
Returns whether a rectangle contains a specified point.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectContainsRect
Returns whether the first rectangle contains the second rectangle.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectCreateDictionaryRepresentation
Returns a dictionary representation of the provided rectangle.
CFDictionaryRef CGRectCreateDictionaryRepresentation( CGRect rect );
Parameters
 rect
A rectangle.
Return Value
The dictionary representation of the rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectDivide
Divides a source rectangle into two component rectangles.
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 beNULL
. 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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectEqualToRect
Returns whether two rectangles are equal in size and position.
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
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetHeight
Returns the height of a rectangle.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMaxX
Returns the largest value of the xcoordinate for the rectangle.
CGFloat CGRectGetMaxX ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The largest value of the xcoordinate for the rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMaxY
Returns the largest value for the ycoordinate of the rectangle.
CGFloat CGRectGetMaxY ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The largest value for the ycoordinate of the rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMidX
Returns the x coordinate that establishes the center of a rectangle.
CGFloat CGRectGetMidX ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The xcoordinate of the center of the specified rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMidY
Returns the ycoordinate that establishes the center of the rectangle.
CGFloat CGRectGetMidY ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The ycoordinate of the center of the specified rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMinX
Returns the smallest value for the xcoordinate of the rectangle.
CGFloat CGRectGetMinX ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The smallest value for the xcoordinate of the rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetMinY
Returns the smallest value for the ycoordinate of the rectangle.
CGFloat CGRectGetMinY ( CGRect rect );
Parameters
 rect
The rectangle to examine.
Return Value
The smallest value for the ycoordinate of the rectangle.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectGetWidth
Returns the width of a rectangle.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectInset
Returns a rectangle that is smaller or larger than the source rectangle, with the same center point.
CGRect CGRectInset ( CGRect rect, CGFloat dx, CGFloat dy );
Parameters
 rect
The source
CGRect
structure. dx
The xcoordinate 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 ycoordinate 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 xaxis by the distance specified by the dx parameter and in the yaxis 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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectIntegral
Returns the smallest rectangle that results from converting the source rectangle values to integers.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectIntersection
Returns the intersection of two rectangles.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectIntersectsRect
Returns whether two rectangles intersect.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectIsEmpty
Returns whether a rectangle has zero width or height, or is a null rectangle.
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.
Availability
 Available in iOS 2.0 and later.
See Also
Declared In
CGGeometry.h
CGRectIsInfinite
Returns whether a rectangle is infinite.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectIsNull
Returns whether the rectangle is equal to the null rectangle.
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.
Availability
 Available in iOS 2.0 and later.
See Also
Declared In
CGGeometry.h
CGRectMake
Returns a rectangle with the specified coordinate and size values.
CGRect CGRectMake ( CGFloat x, CGFloat y, CGFloat width, CGFloat height );
Parameters
 x
The xcoordinate of the rectangle’s origin point.
 y
The ycoordinate 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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectMakeWithDictionaryRepresentation
Fills in a rectangle using the contents of the specified dictionary.
bool CGRectMakeWithDictionaryRepresentation( CFDictionaryRef dict, CGRect *rect );
Parameters
 dict
A dictionary that was previously returned from the function
CGRectCreateDictionaryRepresentation
. rect
On return, the rectangle created from the specified dictionary.
Return Value
true
if successful; otherwise, false
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectOffset
Returns a rectangle with an origin that is offset from that of the source rectangle.
CGRect CGRectOffset ( CGRect rect, CGFloat dx, CGFloat dy );
Parameters
 rect
The source rectangle.
 dx
The offset value for the xcoordinate.
 dy
The offset value for the ycoordinate.
Return Value
A rectangle that is the same size as the source, but with its origin offset by dx units along the xaxis and dy units along the yaxis with respect to the source.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectStandardize
Returns a rectangle with a positive width and height.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRectUnion
Returns the smallest rectangle that contains the two source rectangles.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGSizeCreateDictionaryRepresentation
Returns a dictionary representation of the specified size.
CFDictionaryRef CGSizeCreateDictionaryRepresentation( CGSize size );
Parameters
 size
A size.
Return Value
The dictionary representation of the size.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGSizeEqualToSize
Returns whether two sizes are equal.
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
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGSizeMake
Returns a size with the specified dimension values.
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.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGSizeMakeWithDictionaryRepresentation
Fills in a size using the contents of the specified dictionary.
bool CGSizeMakeWithDictionaryRepresentation( CFDictionaryRef dict, CGSize *size );
Parameters
 dict
A dictionary that was previously returned from the function
CGSizeCreateDictionaryRepresentation
. size
On return, the size created from the specified dictionary.
Return Value
true
if successful; otherwise, false
.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGVectorMake
Returns a vector with the specified dimension values.
CGSize CGVectorMake ( CGFloat dx, CGFloat dy );
Parameters
 dx
The xcoordinate of the vector to construct.
 dy
The ycoordinate of the vector to construct.
Return Value
Returns a CGVector
structure with the specified coordinates.
Availability
 Available in iOS 7.0 and later.
Declared In
CGGeometry.h
Data Types
CGFloat
The basic type for all floatingpoint values.
typedef float CGFloat;// 32bit 
typedef double CGFloat;// 64bit 
Availability
 Available in iOS 2.0 and later.
Declared In
CGBase.h
CGPoint
A structure that contains a point in a twodimensional coordinate system.
struct CGPoint { CGFloat x; CGFloat y; }; typedef struct CGPoint CGPoint;
Fields
x
The xcoordinate of the point.
y
The ycoordinate of the point.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGRect
A structure that contains the location and dimensions of a rectangle.
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 lowerleft corner of the rectangle and the rectangle extends towards the upperright corner. If the context has a flippedcoordinate space—often the case on iOS—the origin is in the upperleft corner and the rectangle extends towards the lowerright corner.
Availability
 Available in iOS 2.0 and later.
Declared In
CGGeometry.h
CGSize
A structure that contains width and height values.
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.
Declared In
CGGeometry.h
CGVector
A structure that contains a twodimensional vector.
struct CGVector { CGFloat dx; CGFloat dy; }; typedef struct CGVector CGVector;
Fields
dx
The xcoordinate of the vector.
dy
The ycoordinate of the vector.
Availability
 Available in iOS 7.0 and later.
Declared In
CGGeometry.h
Constants
CGRectInfinite
A rectangle that has infinite extent.
const CGRect CGRectInfinite;
Constants
CGRectInfinite
A rectangle that has infinite extent.
Available in iOS 2.0 and later.
Declared in
CGGeometry.h
.
Geometric Zeros
A zero point, zero rectangle, or zero size.
const CGPoint CGPointZero; const CGRect CGRectZero; const CGSize CGSizeZero;
Constants
CGPointZero
A point constant with location
(0,0)
. The zero point is equivalent toCGPointMake(0,0)
.Available in iOS 2.0 and later.
Declared in
CGGeometry.h
.CGRectZero
A rectangle constant with location
(0,0)
, and width and height of 0. The zero rectangle is equivalent toCGRectMake(0,0,0,0)
.Available in iOS 2.0 and later.
Declared in
CGGeometry.h
.CGSizeZero
A size constant with width and height of
0
. The zero size is equivalent toCGSizeMake(0,0)
.Available in iOS 2.0 and later.
Declared in
CGGeometry.h
.
Geometrical Null
The null or empty rectangle.
const CGRect CGRectNull;
Constants
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.
Declared in
CGGeometry.h
.
CGRectEdge
Coordinates that establish the edges of a rectangle.
enum CGRectEdge { CGRectMinXEdge, CGRectMinYEdge, CGRectMaxXEdge, CGRectMaxYEdge }; typedef enum CGRectEdge CGRectEdge;
Constants
CGRectMinXEdge
The minimum value for the xcoordinate 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.
Declared in
CGGeometry.h
.CGRectMinYEdge
The minimum value for the ycoordinate 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.
Declared in
CGGeometry.h
.CGRectMaxXEdge
The maximum value for the xcoordinate 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.
Declared in
CGGeometry.h
.CGRectMaxYEdge
The maximum value for the ycoordinate 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.
Declared in
CGGeometry.h
.
CGFloat Informational Macros
Informational macros for the CGFloat
type.
#define CGFLOAT_MIN FLT_MIN// 32bit 
#define CGFLOAT_MAX FLT_MAX 
#define CGFLOAT_IS_DOUBLE 0 
#define CGFLOAT_MIN DBL_MIN// 64bit 
#define CGFLOAT_MAX DBL_MAX 
#define CGFLOAT_IS_DOUBLE 1 
Constants
CGFLOAT_MIN
The minimum allowable value for a
CGFloat
type. For 32bit code, this value is1.17549435e38F
. For 64bit code, it is2.2250738585072014e308
.Available in iOS 2.0 and later.
Declared in
CGBase.h
.CGFLOAT_MAX
The maximum allowable value for a
CGFloat
type. For 32bit code, this value is3.40282347e+38F
. For 64bit code, it is1.7976931348623157e+308
.Available in iOS 2.0 and later.
Declared in
CGBase.h
.CGFLOAT_IS_DOUBLE
Indicates whether
CGFloat
is defined as afloat
ordouble
type.Available in iOS 2.0 and later.
Declared in
CGBase.h
.
Copyright © 2003, 2013 Apple Inc. All Rights Reserved. Terms of Use  Privacy Policy  Updated: 20130918