Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSBitmapImageRep

Inherits From:	NSImageRep : NSObject

Conforms To:	NSCoding, NSCopying (NSImageRep)
NSObject (NSObject)

Declared In:	AppKit/NSBitmapImageRep.h 

Class Description

An NSBitmapImageRep is an object that can render an image from bitmap data.  The data can be in Tag Image File Format (TIFF), or it can be raw image data. If it's raw data, the object must be informed about the structure of the imageÐits size, the number of color components, the number of bits per sample, and so onÐwhen it's first initialized. If it's TIFF data, the object can get this information from the various TIFF fields included with the data.

Although NSBitmapImageReps are often used indirectly, through instances of the NSImage class, they can also be used directlyÐfor example to manipulate the bits of an image as you might need to do in a paint program.

Setting Up an NSBitmapImageRep

A new NSBitmapImageRep is passed bitmap data for an image when it's first initialized. An NSBitmapImageRep can also be created from bitmap data that's read from a specified rectangle of a focused NSView.

Although the NSBitmapImageRep class inherits NSImageRep methods that set image attributes, these methods shouldn't be used. Instead, you should either allow the object to find out about the image from the TIFF fields or use methods defined in this class to supply this information when the object is initialized.

TIFF Compression

TIFF data can be read and rendered after it has been compressed using any one of the four schemes briefly described below:

LZW	Compresses and decompresses without information loss, achieving compression ratios up to 5:1. It may be somewhat slower to compress and decompress than the PackBits scheme.

PackBits	Compresses and decompresses without information loss, but may not achieve the same compression ratios as LZW.

JPEG	Compresses and decompresses with some information loss, but can achieve compression ratios anywhere from 10:1 to 100:1. The ratio is determined by a user-settable factor ranging from 1.0 to 255.0, with higher factors yielding greater compression. More information is lost with greater compression, but 15:1 compression is safe for publication quality. Some images can be compressed even more. JPEG compression can be used only for images that specify at least 4 bits per sample.

CCITTFAX	Compresses and decompresses 1 bit grayscale images using international fax compression standards CCITT3 and CCITT4.

An NSBitmapImageRep can also produce compressed TIFF data for its image using any of these schemes.

Allocating and Initializing a New NSBitmapImageRep Object 

+ (id)imageRepWithData:(NSData *)tiffData	Creates and returns an initialized NSBitmapImageRep corresponding to the first image in tiffData.

+ (NSArray *)imageRepsWithData:(NSData *)tiffData
	Creates and returns initialized NSBitmapImageRep objects for all the images in tiffData.

- (id)initWithData:(NSData *)tiffData	Initializes a newly allocated NSBitmapImageRep from the first TIFF header and image data found in tiffData. 

- (id)initWithFocusedViewRect:(NSRect)rect	Initializes the new object using data read from the image contained in the rectangle rect. 

- (id)initWithBitmapDataPlanes:(unsigned char **)planes
pixelsWide:(int)width	Initializes the new object from raw bitmap data in the
pixelsHigh:(int)height		planes data buffers. As the data is raw, the other
bitsPerSample:(int)bps		arguments specify its attributes.
samplesPerPixel:(int)spp
hasAlpha:(BOOL)alpha
isPlanar:(BOOL)config
colorSpaceName:(NSString *)colorSpaceName
bytesPerRow:(int)rowBytes
bitsPerPixel:(int)pixelBits

Getting Information about the Image 

- (int)bitsPerPixel	Returns how many bits are needed to specify one pixel. 

- (int)samplesPerPixel	Returns the number of samples (components) in the data. 

- (BOOL)isPlanar	Returns YES if in planar configuration, NO if meshed. 

- (int)numberOfPlanes	Returns the number of data planes. 

- (int)bytesPerPlane	Returns the number of bytes in each data plane. 

- (int)bytesPerRow	Returns the number of bytes in a scan line. 

Getting Image Data 

- (unsigned char *)bitmapData	Returns a pointer to the bitmap data. If the data is planar, returns a pointer to the first plane.

- (void)getBitmapDataPlanes:(unsigned char **)data
	Provides pointers to each plane of bitmap data.

Producing a TIFF Representation of the Image 

+ (NSData *)TIFFRepresentationOfImageRepsInArray:(NSArray *)anArray
	Returns a TIFF representation of the images in the specified NSArray, using the compression that's returned by getCompression:factor: (if applicable).

+ (NSData *)TIFFRepresentationOfImageRepsInArray:(NSArray *)anArray
usingCompression:(NSTIFFCompression)compressionType
factor:(float)factor	Returns a TIFF representation of the images in the specified NSArray, which are compressed using compressionType and factor. If the specified compression isn't applicable, no compression is used.

- (NSData *)TIFFRepresentation	Returns a TIFF representation of the image, using the compression that's returned by getCompression:factor: (if applicable).

- (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)compressionType
 factor:(float)factor	Returns a compressed TIFF representation of the image, having the specified compression type and compression factor. If the specified compression isn't applicable, no compression is used. Raises NSTIFFException if an atempt is made to create a TIFF representation using OpenStep custom color space bitmaps.

Setting and Checking Compression Types 

+ (void)getTIFFCompressionTypes:(const NSTIFFCompression **)list	 
count:(int *)numTypes	Returns all available compression types. 

+ (NSString *)localizedNameForTIFFCompressionType:(NSTIFFCompression)compression
	Returns the localized name for the compression type. 

- (BOOL)canBeCompressedUsing:(NSTIFFCompression)compression
	Returns YES if the image can be compressed using the specified type of compression. 

- (void)getCompression:(NSTIFFCompression *)compression	 
factor:(float *)factor	Returns, in its arguments, the compression type and compression factor. 

- (void)setCompression:(NSTIFFCompression)compression	 
factor:(float)factor	Sets the compression type and compression factor.