CGGeometry Reference

Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGBase.h
CGGeometry.h

Overview

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 by Task

Creating a Dictionary Representation from a Geometric Primitive

Creating a Geometric Primitive from a Dictionary Representation

Creating a Geometric Primitive from Values

Modifying Rectangles

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 OS X v10.5 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 OS X v10.6 and later.
Declared In
CGGeometry.h

CGPointMake

Returns a point with the specified coordinates.

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.

Availability
  • Available in OS X v10.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 OS X v10.5 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 OS X v10.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 OS X v10.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 OS X v10.5 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 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.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 OS X v10.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 OS X v10.0 and later.
Related Sample Code
Declared In
CGGeometry.h

CGRectGetMaxX

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

CGFloat CGRectGetMaxX (
   CGRect rect
);
Parameters
rect

The rectangle to examine.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
CGGeometry.h

CGRectGetMaxY

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

CGFloat CGRectGetMaxY (
   CGRect rect
);
Parameters
rect

The rectangle to examine.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 x-coordinate of the center of the specified rectangle.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGGeometry.h

CGRectGetMidY

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

CGFloat CGRectGetMidY (
   CGRect rect
);
Parameters
rect

The rectangle to examine.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
CGGeometry.h

CGRectGetMinX

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

CGFloat CGRectGetMinX (
   CGRect rect
);
Parameters
rect

The rectangle to examine.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
CGGeometry.h

CGRectGetMinY

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

CGFloat CGRectGetMinY (
   CGRect rect
);
Parameters
rect

The rectangle to examine.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 OS X v10.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 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.

Availability
  • Available in OS X v10.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 OS X v10.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 OS X v10.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 OS X v10.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 OS X v10.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 OS X v10.4 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 OS X v10.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 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.

Availability
  • Available in OS X v10.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 OS X v10.5 and later.
Related Sample Code
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 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.

Availability
  • Available in OS X v10.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 OS X v10.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 OS X v10.0 and later.
Related Sample Code
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 OS X v10.5 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 OS X v10.6 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 OS X v10.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 OS X v10.5 and later.
Declared In
CGGeometry.h

CGVectorMake

Returns a vector with the specified dimension values.

CGSize 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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CGGeometry.h

Data Types

CGFloat

The basic type for all floating-point values.

typedef float CGFloat;// 32-bit
typedef double CGFloat;// 64-bit
Availability
  • Available in OS X v10.5 and later.
Declared In
CGBase.h

CGPoint

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

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 OS X v10.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 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 OS X v10.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 OS X v10.0 and later.
Declared In
CGGeometry.h

CGVector

A structure that contains a two-dimensional vector.

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 OS X v10.9 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 OS X v10.4 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 to CGPointMake(0,0).

Available in OS X v10.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 to CGRectMake(0,0,0,0).

Available in OS X v10.0 and later.

Declared in CGGeometry.h.

CGSizeZero

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

Available in OS X v10.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 OS X v10.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 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 OS X v10.0 and later.

Declared in CGGeometry.h.

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 OS X v10.0 and later.

Declared in CGGeometry.h.

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 OS X v10.0 and later.

Declared in CGGeometry.h.

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 OS X v10.0 and later.

Declared in CGGeometry.h.

CGFloat Informational Macros

Informational macros for the CGFloat type.

#define CGFLOAT_MIN FLT_MIN// 32-bit
#define CGFLOAT_MAX FLT_MAX
#define CGFLOAT_IS_DOUBLE 0
#define CGFLOAT_MIN DBL_MIN// 64-bit
#define CGFLOAT_MAX DBL_MAX
#define CGFLOAT_IS_DOUBLE 1
Constants
CGFLOAT_MIN

The minimum allowable 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 OS X v10.5 and later.

Declared in CGBase.h.

CGFLOAT_MAX

The maximum allowable 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 OS X v10.5 and later.

Declared in CGBase.h.

CGFLOAT_IS_DOUBLE

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

Available in OS X v10.5 and later.

Declared in CGBase.h.