Class

NSImage

A high-level interface for manipulating image data.

Declaration

@interface NSImage : NSObject

Overview

You use instances of NSImage to load existing images, create new images, and draw the resulting image data into your views. Although you use this class predominantly for image-related operations, the class itself knows little about the underlying image data. Instead, it works in conjunction with one or more image representation objects (subclasses of NSImageRep) to manage and render the image data. For the most part, these interactions are transparent.

The NSImage class serves many purposes, providing support for the following tasks:

  • Loading images stored on disk or at a specified URL.

  • Drawing images into a view or graphics context.

  • Providing the contents of a CALayer object.

  • Creating new images based on a series of captured drawing commands.

  • Producing versions of the image in a different format.

The NSImage class itself is capable of managing image data in a variety of formats. The specific list of formats is dependent on the version of the operating system but includes many standard formats such as TIFF, JPEG, GIF, PNG, and PDF among others. AppKit manages each format using a specific type of image representation object, whose job is to manage the actual image data. You can get a list of supported formats using the methods described in Determining the Supported Image Types.

For more information about how to use image objects in your app, see Cocoa Drawing Guide.

Using Images with Core Animation Layers

Although you can assign an NSImage object directly to the contents property of a CALayer object, doing so may not always yield the best results. Instead of using your image object, you can use the layerContentsForContentsScale: method to obtain an object that you can use for your layer’s contents. The image created by that method serves as the contents of a layer, which also supports all of the layer’s gravity modes. By contrast, the NSImage class supports only the kCAGravityResize, kCAGravityResizeAspect, and kCAGravityResizeAspectFill modes.

Before calling the layerContentsForContentsScale: method, use the recommendedLayerContentsScale: method to get the recommended scale factor for the resulting image. Listing 1 shows a typical example that uses the scale factor of a window’s backing store as the desired scale factor. From that scale factor, the code gets the scale factor for the specified image object and creates an object that you assign to the layer. You might use this code for images that fit the layer bounds precisely or for which you rely on the contentsGravity property of the layer to position or scale the image.

Listing 1

Assigning an image to a layer

static void updateLayerWithImageInWindow1(NSImage *image, CALayer *layer, NSWindow *window) {
   CGFloat desiredScaleFactor = [window backingScaleFactor];
   CGFloat actualScaleFactor = [image recommendedLayerContentsScale:desiredScaleFactor];
 
   id layerContents = [image layerContentsForContentsScale:actualScaleFactor];
 
   [layer setContents:layerContents];
   [layer setContentsScale:actualScaleFactor];
}

Topics

Creating Images by Name

+ imageNamed:

Returns the image object associated with the specified name.

- setName:

Registers the receiver under the specified name.

- name

Returns the name associated with the image, if any.

NSImageName

Named images, defined by the system or you, for use in your app.

Creating a Dynamically Drawn Image

+ imageWithSize:flipped:drawingHandler:

Creates and returns an image object whose contents are drawn using the specified block.

Creating Images from Resource Files

- initByReferencingFile:

Initializes and returns an image object using the specified file.

- initByReferencingURL:

Initializes and returns an image object using the specified URL.

- initWithContentsOfFile:

Initializes and returns an image object with the contents of the specified file.

- initWithContentsOfURL:

Initializes and returns an image object with the contents of the specified URL.

Creating an Image from Existing Data

- initWithData:

Initializes and returns an image object using the provided image data.

- initWithDataIgnoringOrientation:

Initializes and returns an image object using the provided image data and ignoring the EXIF orientation tags.

- initWithCGImage:size:

Initializes and returns an image object using the contents of a Core Graphics image.

- initWithPasteboard:

Initializes and returns an image object with data from the specified pasteboard.

- initWithIconRef:

Initializes the image object with a Carbon-style icon resource.

Deprecated

Creating an Empty Image

- initWithSize:

Initializes and returns an image object with the specified dimensions.

Managing Image Loading and Drawing

delegate

The image’s delegate object.

NSImageDelegate

A set of optional methods that you can use to respond to drawing failures and manage incremental loads.

Setting the Image Attributes

size

The size of the receiver.

template

Sets whether the image represents a template image.

- isTemplate

Returns a Boolean value indicating whether the image is a template image.

Determining the Supported Image Types

+ canInitWithPasteboard:

Tests whether the receiver can create an instance of itself using pasteboard data.

imageTypes

Returns an array of UTI strings identifying the image types supported by the registered NSImageRep objects, either directly or through a user-installed filter service.

imageUnfilteredTypes

Returns an array of UTI strings identifying the image types supported directly by the registered image representation objects.

Working with Image Representations

- addRepresentation:

Adds the specified image representation object to the image.

- addRepresentations:

Adds an array of image representation objects to the receiver.

representations

An array containing all of the receiver's image representations.

- removeRepresentation:

Removes and releases the specified image representation.

- bestRepresentationForRect:context:hints:

Returns the best representation of the image for the specified rectangle using the provided hints.

NSImageHintKey

Constants for the keys to include in a hints dictionary when drawing the image.

NSImageLayoutDirection

The layout direction for the image.

Setting the Image Representation Selection Criteria

prefersColorMatch

A Boolean value indicating whether the image prefers to choose image representations using color-matching or resolution-matching.

usesEPSOnResolutionMismatch

A Boolean value that indicates whether EPS representations are preferred when no other representations match the resolution of the device.

matchesOnMultipleResolution

A Boolean value that indicates whether image representations whose resolution is an integral multiple of the device resolution are a match.

Drawing the Image

- drawInRect:

Draws the image in the specified rectangle.

- drawAtPoint:fromRect:operation:fraction:

Draws all or part of the image at the specified point in the current coordinate system.

- drawInRect:fromRect:operation:fraction:

Draws all or part of the image in the specified rectangle in the current coordinate system.

- drawInRect:fromRect:operation:fraction:respectFlipped:hints:

Draws all or part of the image in the specified rectangle respecting the hints and the orientation of the current coordinate system.

- drawRepresentation:inRect:

Draws the image using the specified image representation object.

NSCompositingOperation

Compositing operators, described in terms of having source and destination images, each having an opaque and transparent region.

Managing Drawing Options

valid

A Boolean value that indicates whether it is possible to draw an image representation.

backgroundColor

The background color for the image.

NSImageResizingMode

The resizing mode for the image.

Managing the Focus

- lockFocus

Prepares the image to receive drawing commands.

- lockFocusFlipped:

Prepares the image to receive drawing commands using the specified flipped state.

- unlockFocus

Removes the focus from the receiver.

Working with Alignment Metadata

alignmentRect

A rectangle that you can use to position the image during layout.

Managing Caching Options

cacheMode

The image’s caching mode.

- recache

Invalidates and frees offscreen caches of all image representations.

NSImageCacheMode

Constants that specify the caching policy on a per-image basis.

Producing TIFF Data for the Image

TIFFRepresentation

A data object containing TIFF data for all of the image representations in the receiver.

- TIFFRepresentationUsingCompression:factor:

Returns a data object containing TIFF data with the specified compression settings for all of the image representations in the receiver.

Producing a Core Graphics Image

- CGImageForProposedRect:context:hints:

Returns a Core Graphics image based on the contents of the current image object.

Managing Incremental Loads

- cancelIncrementalLoad

Cancels the current download operation, if any, for an incrementally loaded image.

Hit Testing an Image

- hitTestRect:withImageDestinationRect:context:hints:flipped:

Returns whether the destination rectangle would intersect a non-transparent portion of the image.

Managing Image Accessibility

accessibilityDescription

The image’s accessibility description.

Using an Image with Core Animation

- layerContentsForContentsScale:

Returns an object that may be used as the contents of a layer.

- recommendedLayerContentsScale:

Returns the recommended layer contents scale for this image.

Managing Axis Matching

matchesOnlyOnBestFittingAxis

A Boolean value that indicates whether the image matches only on the best fitting axis.

Deprecated Symbols

+ imageFileTypes

Returns an array of strings identifying the image types supported by the registered image representation objects.

Deprecated
+ imageUnfilteredFileTypes

Returns an array of strings identifying the file types supported directly by the registered image representation objects.

Deprecated
+ imagePasteboardTypes

Returns an array of strings identifying the pasteboard types supported directly by the registered image representation objects.

Deprecated
+ imageUnfilteredPasteboardTypes

Returns an array of strings identifying the pasteboard types supported directly by the registered image representation objects.

Deprecated
- lockFocusOnRepresentation:

Prepares the specified image representation to receive drawing commands.

Deprecated
- bestRepresentationForDevice:

Returns the best representation for the device with the specified characteristics.

Deprecated
- compositeToPoint:operation:

Composites the entire image to the specified point in the current coordinate system.

Deprecated
- compositeToPoint:fromRect:operation:

Composites a portion of the image to the specified point in the current coordinate system.

Deprecated
- compositeToPoint:fromRect:operation:fraction:

Composites a portion of the image at the specified opacity to the current coordinate system.

Deprecated
- compositeToPoint:operation:fraction:

Composites the entire image at the specified opacity in the current coordinate system.

Deprecated
- dissolveToPoint:fraction:

Composites the entire image to the specified location using the source-over operator.

Deprecated
- dissolveToPoint:fromRect:fraction:

Composites a portion of the image to the specified location using the source-over operator.

Deprecated
- setScalesWhenResized:

Sets whether to scale different-sized image representations to fit the image's size.

Deprecated
- scalesWhenResized

Returns a Boolean value indicating whether to scale image representations to fit the image's size.

Deprecated
- setDataRetained:

Sets whether the receiver retains its source image data.

Deprecated
- isDataRetained

Returns a Boolean value indicating whether the receiver retains its source image data.

Deprecated
- setCachedSeparately:

Sets whether each image representation uses a separate offscreen window to cache its contents.

Deprecated
- isCachedSeparately

Returns a Boolean value indicating whether each image representation caches its contents in a separate offscreen window.

Deprecated
- setCacheDepthMatchesImageDepth:

Sets whether the receiver's offscreen window caches use the same bit depth as the image data itself.

Deprecated
- cacheDepthMatchesImageDepth

Returns a Boolean value indicating whether an image's offscreen window caches use the same bit depth as the image data itself.

Deprecated
- setFlipped:

Sets whether the polarity of the y axis is inverted when drawing an image.

Deprecated
- isFlipped

Returns a Boolean value indicating whether the image uses a flipped coordinate system.

Deprecated

Relationships

Inherits From

See Also

Images

Providing Images for Different Appearances

Supply image resources that work for light and dark appearances and for high-contrast environments.

NSImageDelegate

A set of optional methods that you can use to respond to drawing failures and manage incremental loads.

NSImageRep

A semiabstract superclass that provides subclasses that you use to draw an image from a particular type of source data.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software