Images and Imageviews
*********************

GNUstep provides mechanisms for the retreival and display of images. A number of objects beginning with NSImage (Including NSImage) 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.

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).

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. (Note that many of the mechanisms provided for compositing may not be supported in some backends i.e. the Windows backend.) 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.  (These compositing operations are the same as those described in the (now well-studied) academic paper, Compositing Digital Images by Thomas Porter and Tom Duff in 1984.)

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.

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.