14. Images and Imageviews

GNUstep provides mechanisms for the retreival and display of images. A number of objects beginning with NSImage(17) exist, each with slightly different functions.

An image is represented using an instance of the NSImage class. You can create these using the path or URL of a file, raw image data or a pasteboard.

Images may contain zero or more image representations, or imagereps. For example, a photographic image may contain both black and white and colour representations, or representations at different resolutions. The purpose of this is to allow GNUstep to select the best representation for a particular device. GNUstep may select a lower-resolution representation for a screen, while selecting the highest resolution representation for printed output. If there was also a vector representation, it may choose to use it for printed output. An imagerep is represented by an instance of a NSImageRep subclass.

An image by itself is not enough for rendering. Images are rendered on a window using an NSImageView object. These let you set the alignment and scaling for displaying the image. They also let you set a graphical border using the -setFrameStyle: method. NSImageView is a control, so the normal control/cell model applies to it.

If you only need to display an image on it's own, use NSImageView. For more complicated image rendering, e.g. inside of custom views, use NSImage to draw or composite at a certain point.

14.1 Using NSImage

Whether using NSImageView or not, you will have to create an NSImage object. It provides a number of constructors for loading an image with a path, a URL or a data object (NSData). Note that for loading from a file or URL, two sets of methods are provided. These have subtly different meanings, as shown below:

-initWithContentsOfFile:

-initWithContentsOfURL:

These methods load the image from the specified location, and create image representations for rendering later.

-initByReferencingFile:

-initByReferencingURL:

These methods don't actually load the image straight away. Instead, when you try to composite or draw the image at a location, it loads the image from disk and generates a representation at that time.

From here, an image can be drawn within a view using any of the drawing/compositing/dissolving methods. You can also get at the imagereps using the -representations method (amongst others).

14.2 Drawing Images

NSImage provides a number of methods for drawing an image. It also provides quite a number means to control how an image is composited at its destination.(18) Compositing refers to the way the image is rendered onto the destination surface.

Simply drawing an image into your view may be achieved with the -drawRepresentation:inRect: method. In other cases, you may wish to draw it onto a destination surface with a compositing operation, in which case you can use the -drawAtPoint:fromRect:operation:fraction: or -drawInRect:fromRect:operation:fraction: methods.

These take a rectangle from the source image, and composite it onto a destination surface. The compositing operation specifies how the image is blended with the destination surface, and is a constant in NSCompositingOperation. These constants define what the destination image looks like after a composite, as a result of combining the source and destination image. (19)

NSCompositeClear

The destination is left transparent.

NSCompositeCopy

The source image appears at the destination.

NSCompositeSourceOver

The source image appears wherever it is opaque, and the destination image elsewhere.

NSCompositeSourceIn

The source image appears wherever both the source and destination are opaque, and is transparent elsewhere.

NSCompositeSourceOut

The source image appears where the source image is opaque but the destination image is transparent, and is transparent elsewhere.

NSCompositeSourceAtop

The source image appears wherever both images are opaque, the destination appears wherever the destination is opaque but the source image is transparent, and the result is transparent elsewhere.

NSCompositeDestinationOver

The destination image appears wherever it is opaque, and the source image elsewhere.

NSCompositeDestinationIn

The destination image appears where both images are opaque, and the result is transparent elsewhere.

NSCompositeDestinationOut

The destination image appears wherever it is opaque but the source image is transparent, and it is transparent elsewhere.

NSCompositeDestinationAtop

The destination image appears wherever both images are opaque, the source image appears wherever the source image is opaque but the destination is transparent, and the result is transparent elsewhere.

NSCompositeXOR

The result of and exclusive OR operation between the bits defining the pixels in bothe images.

NSCompositePlusDarker

The result of adding the values of the colour components of the pixels in both images, with the result approaching zero as a limit.

NSCompositePlusLighter

The result of adding the values of the colour components of the pixels in both images, with the result approaching one as a limit.

The fraction parameter corresponds to the coverage of the source alpha channel with zero making the source transparent and one making the source fully opaque.

14.3 Working with image representations

Quite a number of classes inherit from NSImageRep to provide means to load different types of image formats, such as bitmaps, TIFF images, etc:

NSBitmapImageRep

For bitmap (raster) images, NSBitmapImageRep is used. PNG, JPG and TIFF image file formats would be represented with the class.

You can retreive information about the image with methods such as -bitsPerPixel or -isPlanar. For image formats that can store metadata (such as resolution information or camera settings), the -valueForProperty: and -setProperty:withValue: methods can be used to manipulate it.

If necessary, it contains initialisers for instantiating it from raw data(-initWithData:) and from the display (-initWithFocusedViewRect:.

NSCachedImageRep

This image representation is cached bitmap left over from the result of executing some instructions or data. It lives inside an off-screen window.

NSCustomImageRep

These are representations which can be drawn in a manner that is defined by the application. You initialize these with a selector that is executed against a delegate object when -draw is called on the representation.

NSEPSImageRep

Unsupported.

The NSImageRep class itself also provides a number of methods for gaining information about what kinds of file formats GNUstep supports, and for instantiating images dynamically based on raw image data or the contents of a file or URL.