Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSBitmapImageRep


Inherits from:
NSImageRep : NSObject
Package:
com.apple.yellow.application


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


Setting Up an NSBitmapImageRep


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




Constants


The following constants are provided as a convenience by NSBitmapImageRep:


Constant Type Description
BMPFileType int 1
GIFFileType int 2
ImageColorSyncProfileData String TIFF input/output (NSData)
ImageCompressionFactor String TIFF/JPEG input/output (float in Number)
ImageCompressionMethod String TIFF input/output (NSTIFFCompression in Number)
ImageDitherTransparency String GIF output
ImageInterlaced String PNG output
ImageRGBColorTable String GIF input/output (packed RGB in NSData)
JPEGFileType int 3
PNGFileType int 4
TIFFFileType int 0

The following compression types are supported by NSBitmapImageRep:


Constant Value Description
TIFFCompressionNone 1
TIFFCompressionCCITTFAX3 3 1 bps images only
TIFFCompressionCCITTFAX4 4 1 bps images only
TIFFCompressionLZW 5
TIFFCompressionJPEG 6
TIFFCompressionNEXT 32766 Input only
TIFFCompressionPackBits 32773
TIFFCompressionOldJPEG 32865 Input only



Method Types


Constructors
NSBitmapImageRep
Creating an NSBitmapImageRep
imageRep
imageRepsWithData
colorizeByMappingGray
Getting information about the image
bitsPerPixel
bytesPerPlane
bytesPerRow
compressionFactor
compressionType
isPlanar
numberOfPlanes
samplesPerPixel
Getting image data
bitmapData
Producing a TIFF representation of the image
TIFFRepresentationOfImageReps
TIFFRepresentation
representationOfImageRepsInArray
representationUsingType
Setting and checking compression types
localizedNameForTIFFCompressionType
canBeCompressedUsingType
setCompressionWithFactor
setProperty
valueForProperty


Constructors



NSBitmapImageRep

public NSBitmapImageRep()

Description forthcoming.

public NSBitmapImageRep(NSRect rect)

Initializes a newly allocated NSBitmapImageRep object, with bitmap data read from a rendered image. The image that's read is located in the current window and is bounded by the rect rectangle as specified in the current coordinate system.

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 returns null. Otherwise, it returns this.

public NSBitmapImageRep(NSData bitmapData)

Initializes a newly allocated NSBitmapImageRep from the data found in bitmapData. The contents of bitmapData can be any supported bitmap format. For TIFF data, the NSBitmapImageRep is initialized from the first header and image data found in bitmapData.

This method returns an initialized NSBitmapImageRep if the initialization was successful, or null if it was unable to interpret the contents of bitmapData.

public NSBitmapImageRep( int width, int height, int bps, int spp, boolean alpha, boolean isPlanar, String colorNameSpace, int rowBytes, int pixelBits)

Initializes a newly allocated NSBitmapImageRep object, so it can render the image described by the arguments. If the object can't be initialized, this method frees it and returns null. Otherwise, it returns this. This method allocates enough memory to hold the image described by the arguments. You can then obtain pointers to this memory (with the bitmapDataPlanes or bitmapData method) and fill in the image data. Each of the arguments informs the NSBitmapImageRep object about the image. They're explained below:


Static Methods



imageRep

public static NSBitmapImageRep imageRep(NSData bitmapData)

Creates and returns an initialized NSBitmapImageRep corresponding to the first image in bitmapData, or null if NSBitmapImageRep is unable to interpret bitmapData. bitmapData can contain data in any supported bitmap format.

imageRepsWithData

public static NSArray imageRepsWithData(NSData bitmapData)

Creates and returns an array of initialized NSBitmapImageRep objects corresponding to the images in bitmapData. If NSBitmapImageRep is unable to interpret bitmapData, the returned array is empty. bitmapData can contain data in any supported bitmap format.

localizedNameForTIFFCompressionType

public static String localizedNameForTIFFCompressionType(int compression)

Returns a string containing the localized name for the compression type represented by compression, or null if compression is unrecognized. Compression types are listed in "Constants" . When implementing a user interface for selecting TIFF compression types, use TIFFCompressionTypes to get the list of supported compression types, then use this method to get the localized names for each compression type.

See Also: TIFFCompressionTypes



representationOfImageRepsInArray

public static NSData representationOfImageRepsInArray( NSArray imageReps, int storageType, NSDictionary properties)

Description forthcoming.

TIFFCompressionTypes

public static int[] TIFFCompressionTypes()

Description forthcoming.

TIFFRepresentationOfImageReps

public static NSData TIFFRepresentationOfImageReps(NSArray array)

Returns a TIFF representation of the images in array, using the compression returned by getCompression:factor: (if applicable).

If a problem is encountered during generation of the TIFF, throws a TIFFException or a BadBitmapParametersException.

public static NSData TIFFRepresentationOfImageReps( NSArray array, int compression, float factor)

Returns a TIFF representation of the images in array, which are compressed using the specified compression type and factor. Legal values for compression can be found in 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, throws a TIFFException or a BadBitmapParametersException.




Instance Methods



bitmapData

public byte[] bitmapData()

Returns a pointer to the bitmap data. If the data is planar, returns a pointer to the first plane.

See Also: getBitmapDataPlanes:



bitmapDataPlanes

public byte[][] bitmapDataPlanes()

Description forthcoming.

bitsPerPixel

public int bitsPerPixel()

Returns the number of bits allocated for each pixel in each plane of data. This is normally equal to the number of bits per sample or, if the data is in meshed configuration, the number of bits per sample times the number of samples per pixel. It can be explicitly set to another value in case extra memory is allocated for each pixel. This may be the case, for example, if pixel data is aligned on byte boundaries.

bytesPerPlane

public int bytesPerPlane()

Returns the number of bytes in each plane or channel of data. This is calculated from the number of bytes per row and the height of the image.

See Also: bytesPerRow



bytesPerRow

public int bytesPerRow()

Returns the minimum number of bytes required to specify a scan line (a single row of pixels spanning the width of the image) in each data plane. If not explicitly set to another value , this will be figured from the width of the image, the number of bits per sample, and, if the data is in a meshed configuration, the number of samples per pixel. It can be set to another value to indicate that each row of data is aligned on word or other boundaries.

See Also: bytesPerPlane



canBeCompressedUsingType

public boolean canBeCompressedUsingType(int compression)

Tests whether the receiver can be compressed by compression type compression. Legal values for compression can be found in NSBitmapImageRep.h, and are described in "TIFF Compression" . This method returns true if the receiver's data matches compression; for example, if compression is TIFFCompressionCCITTFAX3, then the data must be one bit-per-sample and one sample-per-pixel. It returns false if the data doesn't match compression or if compression is unsupported.

colorizeByMappingGray

public void colorizeByMappingGray( float midPoint, NSColor midPointColor, NSColor shadowColor, NSColor lightColor)

Support for colorization of grayscale images. Maps the receiver such that:

Works on images with 8-bit SPP; thus either 8-bit gray or 24-bit color (with optional alpha).



compressionFactor

public float compressionFactor()

Description forthcoming.

compressionType

public int compressionType()

Description forthcoming.

isPlanar

public boolean isPlanar()

Returns true if image data is segregated into a separate plane for each color and coverage component (planar configuration), and false if the data is integrated into a single plane (meshed configuration).

See Also: samplesPerPixel



numberOfPlanes

public int numberOfPlanes()

Returns the number of separate planes image data is organized into. This is the number of samples per pixel if the data has a separate plane for each component ( isPlanar returns true) and 1 if the data is meshed ( isPlanar returns false).

See Also: samplesPerPixel, hasAlpha (NSImageRep), bitsPerSample (NSImageRep)



representationUsingType

public NSData representationUsingType( int storageType, NSDictionary properties)

Description forthcoming.

samplesPerPixel

public int samplesPerPixel()

Returns the number of components in the data. It includes both color components and the coverage component, if present.

See Also: hasAlpha (NSImageRep), bitsPerSample (NSImageRep)



setBitmapData

public void setBitmapData(byte[] aByte[])

Description forthcoming.

setBitmapDataPlanes

public void setBitmapDataPlanes(byte[][] aByte[][])

Description forthcoming.

setCompressionWithFactor

public void setCompressionWithFactor( int compression, float factor)

Sets the receiver's compression type and compression factor. compression identifies one of the supported compression types as described in "Constants" . factor is a value specific to the compression type; many types of compression don't support varying degrees of compression, and thus ignore factor. JPEG compression allows a compression factor ranging from 0.0 to 255.0, with 0.0 representing minimal compression.

When an NSBitmapImageRep is created, the instance stores the compression type and factor for the source data. TIFFRepresentation and TIFFRepresentationOfImageReps (static method) try to use the stored compression type and factor. Use this method to change the compression type and factor.

See Also: canBeCompressedUsingType



setProperty

public void setProperty( String property, Object value)

Description forthcoming.

TIFFRepresentation

public NSData TIFFRepresentation()

public com.apple.yellow.foundation.NSData TIFFRepresentation( int compression, float factor)

Returns a TIFF representation of the image, using the compression that's returned by getCompression:factor: (if applicable). This method uses the stored compression type and factor retrieved from the initial image data or changed using setCompressionWithFactor. If the stored compression type isn't supported for writing TIFF data (for example, TIFFCompressionNEXT), the stored compression is changed to TIFFCompressionNone and the compression factor to 0.0 before the TIFF representation is generated.

If a problem is encountered during generation of the TIFF, throws an TIFFException or a BadBitmapParametersException.

See Also: TIFFRepresentationOfImageReps



valueForProperty

public Object valueForProperty(String property)

Description forthcoming.


Table of Contents