Discussion

If deviceDescription is nil, this method uses the attributes of the device on which the content is to be drawn.

For information on how the "best" representation is chosen, see the “Images” chapter of Cocoa Drawing Guide.

Discussion

This method draws the specified portion of the image without checking the bounds rectangle you pass into the srcRect parameter. If you specify a source rectangle that strays outside of the image's bounds rectangle, it is conceivable that you could composite parts of the offscreen cache window that do not belong to the receiver's image. You can avoid this problem using the drawAtPoint:fromRect:operation:fraction: method, which checks the source rectangle before drawing.

During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

Compositing part of an image is as efficient as compositing the whole image, but printing just part of an image is not. When printing, it’s necessary to draw the whole image and rely on a clipping path to be sure that only the desired portion appears.

During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

Discussion

Behaves the same as compositeToPoint:fromRect:operation: except that you can specify the amount of opacity to use when drawing the image.

Discussion

This method draws the receiver's best image representation at the specified point in the currently focused view. The entire image is drawn using its current size information. During drawing, the image is composited from its offscreen window cache. Because the offscreen cache is not created until the image representation is first used, this method may need to render the image before compositing. Bitmap representations in particular are not cached until they are explicitly rendered. You can use the lockFocus and unlockFocus methods to force the cached version to be created.

During printing, this method ignores the op parameter. Even though this parameter is ignored, this method attempts to render the image as close as possible to its appearance when the compositing operation is used on the screen. In either case, the best image representation is chosen for the printing context.

Discussion

Behaves the same as compositeToPoint:operation: except that you can specify the amount of opacity to use when drawing the image.

Discussion

Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:operation: method. During printing, the delta parameter is ignored.

If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

To slowly dissolve this image onto another, you can invoke this method (or the dissolveToPoint:fromRect:fraction: method) repeatedly with an ever-increasing delta value. Because the delta parameter refers to the visible fraction of the source image, increasing the value causes the source image to replace the destination content gradually. You should generally perform this type of operation using a buffered window or other offscreen drawing environment.

Discussion

Except for the choice of compositing operator, this method behaves in the same way as the compositeToPoint:fromRect:operation: method. During printing, the delta parameter is ignored.

If the source image contains alpha information, this operation may promote the destination NSWindow object to contain alpha information.

Discussion

If this method returns NO, it means that the image may be cached in a shared window but is not required to be. Images are cached in a shared window if they have the same general attributes, such as color space, resolution, and bit depth.

Discussion

For image objects initialized using either the initByReferencingFile: or initByReferencingURL: method, this value is YES by default. The reason is that for these methods, data retention simply involves retaining the filename or URL.

Data retention increases the memory used by the NSImage object and its image representations.

Discussion

This method sets the current drawing context to the area of the offscreen window used to cache the specified image representation's contents. Subsequent drawing commands are composited to this offscreen window. If the offscreen drawing area already has some content, any new drawing commands are composited with that content. This method does not modify the original image data directly.

If imageRepresentation is nil, this method acts like the lockFocus method, setting the focus to the best representation for the NSImage object.

A successful lockFocusOnRepresentation: message must be balanced with a matching unlockFocus message to the same NSImage object. These messages bracket the code that draws the image.

If lockFocusOnRepresentation: is unable to focus on the specified image representation, it raises an NSImageCacheException.

Discussion

Images are not resized during drawing if this method returns YES. They are only resized when you change the size by sending the receiver a setSize: message.

Discussion

This method does not cause the receiver to recache itself. The default depth limit is equal to the bit depth of the deepest screen on the system.

Discussion

If you specify NO, a representation can be cached together with other images, though in practice it might not be. This method does not invalidate any existing caches.

If you plan to resize an NSImage object frequently, it is usually more efficient to cache its representations separately. In some situations, you might also want to enable separate caching if you plan to use the compositeToPoint:fromRect:operation: or compositeToPoint:fromRect:operation:fraction:methods to draw the image.

Discussion

Retention of the source image data is important if the source of the image data could change, be moved, or be deleted. Data retention is also useful if you plan to resize an image frequently; otherwise, resizing occurs on a cached copy of the image, which can lose image quality during successive scaling operations. With data retention enabled, the image is resized from the original source data.

If the responsibility for drawing the image is delegated to another object, there is no reason to retain the image data. Similarly, if the source of the image data is not expected to change or you do not plan to resize the image, you do not need to retain the data. In fact, retaining the data leads to increased memory usage, which could have a negative impact on performance.

If you create your image object using the initByReferencingFile: method, the only data retained is the name of the source file.

Discussion

If flag is YES, the y-axis of the image's internal coordinate system is inverted, with the origin in the upper-left corner and the positive y axis extending downward. This method affects only the coordinate system used internally by the image and the orientation of the image when it is drawn; it does not affect the coordinate system used to specify the position of an image in a view. This method does not cause the receiver to recache itself.

If you set flag to YES and then lock focus and draw into the image, the content you draw is cached in the inverted (flipped) orientation. Changing the value for flag does not affect the orientation of the cached image.

Discussion

Most images (especially those loaded from files and URLs) contain only a single image representation whose size is the same as the receiver. It is possible to add image representations using the addRepresentation: or addRepresentations: methods but doing so is rarely necessary because modern hardware is powerful enough to resize and scale images quickly. The only reason to consider creating new representations is if each representations contains a customized version of the image at a specific size. (TIFF images may also contain a thumbnail version of an image, which is stored using a separate image representation.) If you pass YES in the flag parameter, and subsequently send a setSize: message to the receiver, all such image representations would be scaled to the same size. Scaling of bitmap images usually results in the interpolation of the bitmap data.

This method does not invalidate the caches of any of the receiver's image representations. The caches are not invalidated until you change the image size using a setSize: message. Scaling affects only the cached offscreen data for a given image representation.