# CGGeometry Reference

 Framework ApplicationServices/ApplicationServices.h Companion guide Declared in CGBase.hCGGeometry.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

### CGPointCreateDictionaryRepresentation

Returns a dictionary representation of the specified point.

```CFDictionaryRef CGPointCreateDictionaryRepresentation(
CGPoint point
);
```
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.

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
);
```
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.
##### 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.
##### 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.
##### 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.
##### 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.
• `CGRectIsNull`
##### 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.
• `CGRectIsEmpty`
##### 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.
##### 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.
##### Declared In
`CGGeometry.h`

### CGSizeCreateDictionaryRepresentation

Returns a dictionary representation of the specified size.

```CFDictionaryRef CGSizeCreateDictionaryRepresentation(
CGSize size
);
```
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
);
```
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;
```
`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`.