Inherits from: NSImageRep : NSObject
Conforms to: NSCoding
(from NSImageRep)
NSCopying (from NSImageRep)
NSObject (from NSObject)
Declared in: AppKit/NSImage.h
An NSBitmapImageRep is an object that can render an image from bitmap data. The data can be in Tag Image File Format (TIFF), Windows bitmap format (BMP), 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 or BMP data, the object can get this information from the various 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.
You pass bitmap data for an image to a new NSBitmapImageRep when you first initialize it. You can also create an NSBitmapImageRep 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 fields included with the bitmap data, or use methods defined in this class to supply this information when the object is initialized.
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 gray-scale 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.
- Creating an NSBitmapImageRep
- + imageRepsWithData:
- + imageRepWithData:
- - initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:
- - initWithBitmapHandle:
- - initWithData:
- - initWithFocusedViewRect:
- - initWithIconHandle:
- Getting information about the image
- - bitsPerPixel
- - bytesPerPlane
- - bytesPerRow
- - isPlanar
- - numberOfPlanes
- - samplesPerPixel
- Getting image data
- - bitmapData
- - getBitmapDataPlanes:
- Producing a TIFF representation of the image
- + TIFFRepresentationOfImageRepsInArray:
- + TIFFRepresentationOfImageRepsInArray:usingCompression:factor:
- - TIFFRepresentation
- - TIFFRepresentationUsingCompression:factor:
- Setting and checking compression types
- + getTIFFCompressionTypes:count:
- + localizedNameForTIFFCompressionType:
- - canBeCompressedUsing:
- - getCompression:factor:
- - setCompression:factor:
+ (void)getTIFFCompressionTypes:(const NSTIFFCompression
**)list
count:(int *)numTypes
The following compression types are supported:
Constant | Value | Usage |
NSTIFFCompressionNone |
1 | |
NSTIFFCompressionCCITTFAX3 |
3 | 1 bps images only |
NSTIFFCompressionCCITTFAX4 |
4 | 1 bps images only |
NSTIFFCompressionLZW |
5 | |
NSTIFFCompressionJPEG |
6 | |
NSTIFFCompressionNEXT |
32766 | Input only |
NSTIFFCompressionPackBits |
32773 | |
NSTIFFCompressionOldJPEG |
32865 | Input only |
Note that not all compression types can be used for
all images: NSTIFFCompressionNEXT
can
be used only to retrieve image data. Because future releases of
OpenStep may include other compression types, always use this method
to get the available compression types-for example, when you implement
a user interface for selecting compression types.
See Also: + localizedNameForTIFFCompressionType:, - canBeCompressedUsing:
+ (NSArray *)imageRepsWithData:(NSData *)bitmapData
+ (id)imageRepWithData:(NSData *)bitmapData
nil
if NSBitmapImageRep is unable
to interpret bitmapData. bitmapData can
contain data in any supported bitmap format.+ (NSString *)localizedNameForTIFFCompressionType:(NSTIFFCompression)compression
nil
if compression is unrecognized. Compression
types are listed in the getTIFFCompressionTypes:count: class
method description. When implementing a user interface for selecting
TIFF compression types, use getTIFFCompressionTypes:count: to
get the list of supported compression types, then use this method
to get the localized names for each compression type.See Also: + getTIFFCompressionTypes:count:
+ (NSData *)TIFFRepresentationOfImageRepsInArray:(NSArray
*)array
If a problem is encountered during generation of the TIFF, TIFFRepresentationOfImageRepsInArray raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: - TIFFRepresentation
+ (NSData *)TIFFRepresentationOfImageRepsInArray:(NSArray
*)array
usingCompression:(NSTIFFCompression)compression
factor:(float)factor
NSBitmapImageRep.h
,
and are described in "Tiff Compression" in NSBitmapImageRep's
class description. factor provides
a hint for those compression types that implement variable compression
ratios; currently only JPEG compression uses a compression factor.
If your compression type doesn't implement variable compression
ratios, or it does and you don't want the image to be compressed,
specify a compression factor of 0.0.If the specified compression isn't applicable, no compression is used. If a problem is encountered during generation of the TIFF, TIFFRepresentationOfImageRepsInArray:usingCompression:factor: raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: - TIFFRepresentationUsingCompression:factor:
- (unsigned char *)bitmapData
See Also: - getBitmapDataPlanes:
- (int)bitsPerPixel
- (int)bytesPerPlane
See Also: - bytesPerRow
- (int)bytesPerRow
See Also: - bytesPerPlane
- (BOOL)canBeCompressedUsing:(NSTIFFCompression)compression
NSBitmapImageRep.h
,
and are described in "Tiff Compression" in the class description.
This method returns YES if the receiver's data matches compression; for
example, if compression is NSTIFFCompressionCCITTFAX3,
then the data must be one bit-per-sample and one sample-per-pixel.
It returns NO if the data doesn't match compression or
if compression is unsupported. See Also: + getTIFFCompressionTypes:count:
- (void)getBitmapDataPlanes:(unsigned char **)data
Color components in planar configuration are arranged in the expected order-for example, red before green before blue for RGB color. All color planes precede the coverage plane.
See Also: - isPlanar
- (void)getCompression:(NSTIFFCompression *)compression
factor:(float *)factor
- (id)initWithBitmapDataPlanes:(unsigned char
**)planes
pixelsWide:(int)width
pixelsHigh:(int)height
bitsPerSample:(int)bps
samplesPerPixel:(int)spp
hasAlpha:(BOOL)alpha
isPlanar:(BOOL)isPlanar
colorSpaceName:(NSString *)colorSpaceName
bytesPerRow:(int)rowBytes
bitsPerPixel:(int)pixelBits
nil
.
Otherwise, it returns the object (self).planes is an array of character pointers, each of which points to a buffer containing raw image data. If the data is in planar configuration, each buffer holds one component-one plane-of the data. Color planes are arranged in the standard order-for example, red before green before blue for RGB color. All color planes precede the coverage plane.
If the data is in meshed configuration (isPlanar is NO), only the first buffer is read.
If planes is NULL or an array of NULL pointers, this method allocates enough memory to hold the image described by the other arguments. You can then obtain pointers to this memory (with the getBitmapDataPlanes: or bitmapData method) and fill in the image data. In this case, the allocated memory will belong to the object and will be freed when it's freed.
If planes is not NULL and the array contains at least one data pointer, the object will only reference the image data; it won't copy it. The buffers won't be freed when the object is freed.
Each of the other arguments (besides planes) informs the NSBitmapImageRep object about the image. They're explained below:
- (id)initWithBitmapHandle:(void *)bitmap
nil
is
returned.- (id)initWithData:(NSData *)bitmapData
initWithData: returns
an initialized NSBitmapImageRep if the initialization was successful,
or nil
if it was unable to interpret
the contents of bitmapData.
- (id)initWithFocusedViewRect:(NSRect)rect
This method uses PostScript imaging operators to read the image data into a buffer; the object is then created from that data. The object is initialized with information about the image obtained from the Window Server.
If
for any reason the new object can't be initialized, this method
frees it and returns nil
. Otherwise,
it returns the initialized object (self).
- (id)initWithIconHandle:(void *)icon
nil
is
returned.- (BOOL)isPlanar
See Also: - samplesPerPixel
- (int)numberOfPlanes
See Also: - samplesPerPixel, - hasAlpha (NSImageRep) - bitsPerSample (NSImageRep)
- (int)samplesPerPixel
See Also: - hasAlpha (NSImageRep) - bitsPerSample (NSImageRep)
- (void)setCompression:(NSTIFFCompression)compression
factor:(float)factor
When an NSBitmapImageRep is created, the instance stores the compression type and factor for the source data. TIFFRepresentation and TIFFRepresentationOfImageRepsInArray: (class method) try to use the stored compression type and factor. Use this method to change the compression type and factor.
See Also: - canBeCompressedUsing:
- (NSData *)TIFFRepresentation
If a problem is encountered during generation of the TIFF, TIFFRepresentation raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: + TIFFRepresentationOfImageRepsInArray:
- (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)comp
factor:(float)factor
If a problem is encountered during generation of the TIFF, TIFFRepresentation raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: - canBeCompressedUsing:, + TIFFRepresentationOfImageRepsInArray: