Converting to and from Views

To support high resolution, you might need to convert rectangles or points from the coordinate system of one NSView instance to another (typically the superview or subview), or from one NSView instance to the containing window. The NSView class defines six methods that convert rectangles, points, and sizes in either direction.

The convert...:fromView: methods convert values to the receiver’s coordinate system from the coordinate system of the view passed as the second parameter. If you pass nil as the view, the values are assumed to be in the window coordinate system and are converted to the receiver coordinate system. The convert..:toView: methods perform the inverse operation—converting values in the receiver coordinate system to the coordinate system of the view passed as a parameter. If the view parameter is nil, the values are converted to the coordinate system of the receiver’s window.

NSView also defines the centerScanRect: method, which converts a given rectangle to device coordinates, adjusts the rectangle to lie in the center of the area (pixels), and then converts the resulting rectangle back to the receiver’s coordinate system (points). Although this method works well for high resolution, some situations might require more precise control over the rounding behavior of the alignment operation on each edge of a rectangle. If you need a high level of control, consider using backingAlignedRect:options: (see Aligning a Rectangle on Pixel Boundaries).

For more information about coordinate conversion in views, see:

• Working with the View Hierarchy in View Programming Guide

• Coordinate Systems and Transforms in Cocoa Drawing Guide

Converting to and from Layers

The NSView class provides methods for converting between a view’s local coordinate system and the interior coordinate system of the layer (for layer-backed views). Use these methods when you have custom layer trees and need to position the layers appropriately in the parent view.

The coordinate system of a layer that backs an NSView object is not necessarily identical to its local view coordinate system. For example, Core Animation layers always use an unflipped coordinate system, whereas the NSView class allows a given view class to choose whether or not it is flipped. For the case of a flipped NSView object that is layer-backed, the following conversion methods account for this difference.

Converting to and from the Screen

The NSWindow class provides these methods for converting between window local coordinates and screen global coordinates:

• convertRectToScreen:

• convertRectFromScreen:

Use them instead of the deprecated convertBaseToScreen: and convertScreenToBase: methods.

Converting to and from the Backing Store

Views, windows, and screens each have their own backing coordinate system. In other words, backing store coordinates are relative to an object; they do not refer to absolute positions onscreen. By default, coordinate values increase up and to the right in coordinate system units.

The backing coordinate system is suitable for pixel alignment for that specific object. Always use the same object for round-tripping to and from the backing store.

Each of the following methods converts between the object’s local coordinate system and a pixel-aligned coordinate system that matches the characteristics of the backing store for that object. In the case of the NSScreen class, the backing coordinate system is the native frame buffer of the display.

For more information on each method, see the appropriate reference documentation (NSView Class Reference, NSWindow Class Reference, NSScreen Class Reference.

CALayer

The contentsScale property of the CALayer class defines the mapping between the coordinate space of the layer (measured in points) and the backing store (measured in pixels). You can change this value as needed to indicate to Core Animation that the bitmap of the backing layer needs to be bigger or smaller.

For example, to avoid blurry text for a layer that is magnified when composited to the screen, use the contentsScale property to specify a text-layer bitmap at twice the layer size, with mipmaps enabled.

NSScreen

The backingScaleFactor method of the NSScreen class returns the scale factor that represents the number of backing store pixels that correspond to each linear unit in screen space on the NSScreen object. You should not use this method except in the rare case when the explicit scale factor is needed. Instead, use the backing store conversion methods (see Converting to and from the Backing Store).

Note that the value returned by backingScaleFactor does not represent anything concrete, such as pixel density or physical size, because it can vary based on the configured display mode. For example, the display might be in a mirrored configuration that is still scaled for high resolution, resulting in pixel geometry that might not match the native resolution of the display device.

NSWindow

The backingScaleFactor method of the NSWindow class returns the scale factor for a specific window. As with its NSScreen counterpart, it is preferable that you use the backing store conversion methods.

CGContextRef

The preferred way to get the scaling information for a CGContext object is to call the conversion function CGContextConvertRectToDeviceSpace:

deviceRect = CGContextConvertRectToDeviceSpace(context, userRect);

Then you can divide deviceRect.size.height by userRect.size.height. This works for both implicitly scaled window contexts and explicitly scaled bitmap contexts.

An alternative is to get the transform applied to the CGContext object by calling the function CGContextGetUserSpaceToDeviceSpaceTransform. The scaling information is in the a and d components of the returned transform. For example:

CGAffineTransform  deviceTransform =

        CGContextGetUserSpaceToDeviceSpaceTransform(myContext);

NSLog(@"x-scaling = %f y-scaling = %f", deviceTransform.a, deviceTransform.d);

If you applied any additional scaling to the context, that will be reflected in the values. Note that this function reports a scale for the implicitly scaled window contexts, and it does not handle bitmap contexts because those are not implicitly scaled.

For simple conversions between user space and device space, you can also use one of the conversion functions listed below (for details, see CGContext Reference). However, they convert only global coordinates, so you need to perform additional calculations to translate the results to view-centric coordinates.

• CGContextConvertPointToDeviceSpace and CGContextConvertPointToUserSpace

• CGContextConvertSizeToDeviceSpacee and CGContextConvertSizeToUserSpace

• CGContextConvertRectToDeviceSpace and CGContextConvertRectToUserSpace

Additions to AppKit

Additions to Carbon

HIWindowGetBackingScaleFactor

Replaces the HIGetScaleFactor function; see Getting Scale Factors.

kHIWindowBitHighResolutionCapable

Represents the bit that sets the high-resolution-capable attribute.

kWindowHighResolutionCapableAttribute

Designates a window as being capable of supporting high-resolution content.

NSImage Class

Use this method for offscreen drawing. See Use the Block-Based Drawing Method for Offscreen Images.

+ (id)imageWithSize:(NSSize)size flipped:(BOOL)drawingHandlerShouldBeCalledWithFlippedContext drawingHandler:(BOOL (^)(NSRect dstRect))drawingHandler;

The drawing handler is a block that can be invoked whenever the image is drawn to, and on whatever thread the drawing occurs. You should make sure that any state you access within the block is done in a thread-safe manner.

The code in the block is the same code that you would use between the lockFocus and unlockFocus methods.

Quartz Display Services

These functions return points (not pixels) as of OS X v10.8:

size_t CGDisplayModeGetWidth(CGDisplayModeRef mode);

Returns the width in points of the specified display mode.

size_t CGDisplayModeGetHeight(CGDisplayModeRef mode);

Returns the height in points of the specified display mode.

Converting to and from the Base Coordinate System

The following methods of the NSView class are deprecated:

• convertPointToBase: and convertPointFromBase:

• convertSizeToBase: and convertSizeFromBase:

• convertRectToBase: and convertRectFromBase:

The following methods of the NSWindow class are deprecated:

• convertBaseToScreen: and convertScreenToBase:

The appropriate replacement depends on the conversion you want to perform:

• To convert between view and layer coordinates, use the appropriate convertXXXToLayer: method. See Converting to and from Layers.

• To convert to window coordinates, use the appropriate convertXXXToView: method, specifying a nil view. See Converting to and from Views.

Getting Scale Factors

These are not compatible with the high-resolution model in OS X:

• The userSpaceScaleFactor methods of the NSScreen and NSWindow classes

• The HIGetScaleFactor function; use HIWindowGetBackingScaleFactor instead

Creating an Unscaled Window

The NSUnscaledWindowMask constant of the NSWindow class is deprecated. This mask currently does nothing. The scale factor for a window backing store is dynamic and is dependent on the screen on which the window is placed. If you currently use this mask to achieve pixel-precise rendering, you should replace it with the backing store conversion methods (see Converting to and from the Backing Store).

Drawing Images

The NSImage class methods compositeToPoint:... and dissolveToPoint:... operate on the base coordinate system. The behavior of these methods is not compatible with high resolution in OS X because there is no way to specify the source rectangle.

Instead, you should use one of the methods that begin with draw, such as:

• drawAtPoint:fromRect:operation:fraction:

• drawInRect:fromRect:operation:fraction:

• drawInRect:fromRect:operation:fraction:respectFlipped:hints:

These methods allow you to specify a source rectangle, and they draw all or part of the image in the current coordinate system.