- Inherits from:
- NSImageRep : NSObject
- Conforms to:
- NSCoding
- (NSImageRep)
- NSCopying (NSImageRep)
- NSObject (NSObject)
Declared in:
- AppKit/NSBitmapImageRep.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.
The following constants are provided as a convenience by NSBitmapImageRep:
Constant | Type | Description |
NSBMPFileType |
int | 1 |
NSGIFFileType |
int | 2 |
NSImageColorSyncProfileData |
NSString | TIFF input/output (NSData) |
NSImageCompressionFactor |
NSString | TIFF/JPEG input/output (float in NSNumber) |
NSImageCompressionMethod |
NSString | TIFF input/output (NSTIFFCompression in NSNumber) |
NSImageDitherTransparency |
NSString | GIF output (BOOL in NSNumber) |
NSImageInterlaced |
NSString | PNG output (BOOL in NSNumber) |
NSImageRGBColorTable |
NSString | GIF input/output (packed RGB in NSData) |
NSJPEGFileType |
int | 3 |
NSPNGFileType |
int | 4 |
NSTIFFFileType |
int | 0 |
The following compression types are supported by NSBitmapImageRep:
Constant | Value | Description |
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 |
- Creating an NSBitmapImageRep
- + imageRepWithData:
- + imageRepsWithData:
- - colorizeByMappingGray:toColor:blackMapping:whiteMapping:
- - 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:
- + representationOfImageRepsInArray:usingType:properties:
- - representationUsingType:properties:
- Setting and checking compression types
- + getTIFFCompressionTypes:count:
- + localizedNameForTIFFCompressionType:
- - canBeCompressedUsing:
- - getCompression:factor:
- - setCompression:factor:
- - setProperty:withValue:
- - valueForProperty:
+ (void)getTIFFCompressionTypes:(const
NSTIFFCompression **)list
count:(int *)numTypes
See "Constants" for a list of compression types supported.
Note that not
all compression types can be used for all images: NSTIFFCompressionNEXT
can
be used only to retrieve image data. Because future releases 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:
+ (id)imageRepWithData:(NSData
*)bitmapData
nil
if NSBitmapImageRep is unable
to interpret bitmapData. bitmapData can contain
data in any supported bitmap format.+ (NSArray *)imageRepsWithData:(NSData
*)bitmapData
+ (NSString *)localizedNameForTIFFCompressionType:(NSTIFFCompression)compression
nil
if compression is
unrecognized. Compression types are listed in "Constants" .
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 *)representationOfImageRepsInArray:(NSArray
*)imageReps
usingType:(NSBitmapImageFileType)storageType
properties:(NSDictionary *)properties
+ (NSData *)TIFFRepresentationOfImageRepsInArray:(NSArray
*)array
If a problem is encountered during generation of the TIFF, 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 "Constants" . 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, 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" . 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)colorizeByMappingGray:(float)midPoint
toColor:(NSColor *)midPointColor
blackMapping:(NSColor *)shadowColor
whiteMapping:(NSColor *)lightColor
Works on images with 8-bit SPP; thus either 8-bit gray or 24-bit color (with optional alpha).
- (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:
NSCalibratedWhiteColorSpace
NSCalibratedBlackColorSpace
NSCalibratedRGBColorSpace
NSDeviceWhiteColorSpace
NSDeviceBlackColorSpace
NSDeviceRGBColorSpace
NSDeviceCMYKColorSpace
NSNamedColorSpace
NSCustomColorSpace
- (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 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)
- (NSData *)representationUsingType:(NSBitmapImageFileType)storageType
properties:(NSDictionary *)properties
- (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:
- (void)setProperty:(NSString
*)property
withValue:(id)value
- (NSData *)TIFFRepresentation
NSTIFFCompressionNEXT
),
the stored compression is changed to NSTIFFCompressionNone
and
the compression factor to 0.0 before invoking TIFFRepresentationUsingCompression:factor:.If a problem is encountered during generation of the TIFF, TIFFRepresentation raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: + TIFFRepresentationOfImageRepsInArray:
- (NSData *)TIFFRepresentationUsingCompression:(NSTIFFCompression)compression
factor:(float)factor
NSTIFFCompressionNEXT
), the
stored compression is changed to NSTIFFCompressionNone
and
the compression factor to 0.0 before the TIFF representation is
generated.If a problem is encountered during generation of the TIFF, TIFFRepresentationUsingCompression:factor: raises an NSTIFFException or an NSBadBitmapParametersException.
See Also: - canBeCompressedUsing:, + TIFFRepresentationOfImageRepsInArray:
- (id)valueForProperty:(NSString
*)property