ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Application Kit Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSBitmapImageRep

Inherits from
Implements
Package
com.apple.cocoa.application
Companion guide
Drawing and Images

Overview

An NSBitmapImageRep is an object that can render an image from bitmap data. Bitmap data formats supported include GIF, JPEG, TIFF, PNG, and various permutations of raw bitmap data.

Alpha Premultiplication

If a coverage (alpha) plane exists, a bitmap’s color components are premultiplied with it. If you modify the contents of the bitmap, you are therefore responsible for premultiplying the data. For this reason, though, if you want to manipulate the actual data, NSBitmapImageRep is not recommended for storage. If you need to work with unpremultiplied data, you should use Quartz, specifically CGImageCreate with kCGImageAlphaLast.

Note that premultiplying does not affect the output quality. Given source bitmap pixel s, destination pixel d, and alpha value a, a blend is basically

d' = a * s + (1 - a) * d

All premultiplication does is precalculate a * s.

Tasks

Constructors

Creating an NSBitmapImageRep

Getting Information About the Image

Getting Image Data

Producing a TIFF Representation of the Image

Setting and Checking Compression Types

Incremental Image Loading

Getting and Setting Pixel Values

Constructors

NSBitmapImageRep

Throws an exception. Use one of the other constructors instead.

public NSBitmapImageRep()

Creates an NSBitmapImageRep, with bitmap data read from a rendered image.

public NSBitmapImageRep(NSRect rect)

Discussion

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 created, this method returns null.

Creates an NSBitmapImageRep from the data found in bitmapData.

public NSBitmapImageRep(NSData bitmapData)

Discussion

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 creation was successful or null if it was unable to interpret the contents of bitmapData.

Creates an NSBitmapImageRep, so it can render the image described by the arguments. If the object can’t be created, this method returns null.

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

Discussion

This constructor 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. If the image has an alpha channel, you are responsible for premultiplying the color samples. Each of the arguments informs the NSBitmapImageRep object about the image. They’re explained below:

Creates a NSBitmapImageRep object for incremental loading.

public NSBitmapImageRep(boolean bool)

Discussion

The receiver returns itself after setting its size and data buffer to zero. You can then call incrementalLoadFromData to incrementally add image data.

Availability
See Also

Static Methods

imageRep

Creates and returns an initialized NSBitmapImageRep corresponding to the first image in bitmapData, or null if NSBitmapImageRep is unable to interpret bitmapData.

public static NSBitmapImageRep imageRep(NSData bitmapData)

Discussion

bitmapData can contain data in any supported bitmap format.

imageRepsWithData

Creates and returns an array of initialized NSBitmapImageRep objects corresponding to the images in bitmapData.

public static NSArray imageRepsWithData(NSData bitmapData)

Discussion

If NSBitmapImageRep is unable to interpret bitmapData, the returned array is empty. bitmapData can contain data in any supported bitmap format.

localizedNameForTIFFCompressionType

Returns a string containing the localized name for the compression type represented by compression, or null if compression is unrecognized.

public static String localizedNameForTIFFCompressionType(int compression)

Discussion

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

representationOfImageRepsInArray

Returns a bitmap version of the NSBitmapImageRep objects in imageReps, using the format storageType and the properties properties.

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

Discussion

The storageType can be BMPFileType, GIFFileType, JPEGFileType, PNGFileType, or TIFFFileType. The contents of the properties dictionary is described in “Constants.”

TIFFCompressionTypes

Returns the list of available compression types, which are defined in “Constants.”

public static int[] TIFFCompressionTypes()

TIFFRepresentationOfImageReps

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

public static NSData TIFFRepresentationOfImageReps(NSArray array)

Discussion

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

Returns a TIFF representation of the images in array, which are compressed using the specified compression type and factor.

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

Discussion

Legal values for compression 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. JPEG compression in TIFF files is not supported, and factor is ignored.

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

Returns a pointer to the bitmap data.

public byte[] bitmapData()

Discussion

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

See Also

bitmapDataPlanes

Provides access to bitmap data for the receiver separated into planes.

public byte[][] bitmapDataPlanes()

Discussion

Returns an array of five character pointers. If the receiver is in planar configuration, each pointer is initialized to point to one of the data planes. If there are less than five planes, the remaining pointers are set to null. If the receiver is in meshed configuration, only the first pointer is initialized; the others are null.

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. If a coverage plane exists, the bitmap’s color components are premultiplied with it. If you modify the contents of the bitmap, you are responsible for premultiplying the data.

See Also

bitmapFormat

Returns the bitmap format of the receiver.

public int bitmapFormat()

Discussion

The default is 0.

Availability
See Also

bitsPerPixel

Returns the number of bits allocated for each pixel in each plane of data.

public int bitsPerPixel()

Discussion

This number 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

Returns the number of bytes in each plane or channel of data.

public int bytesPerPlane()

Discussion

This number is calculated from the number of bytes per row and the height of the image.

See Also

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.

public int bytesPerRow()

Discussion

If not explicitly set to another value , this number 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

canBeCompressedUsingType

Tests whether the receiver can be compressed by compression type compression.

public boolean canBeCompressedUsingType(int compression)

Discussion

Legal values for compression can be found in NSBitmapImageRep.h and are described in “TIFF Compression in NSBitmapImageReps”. This method returns true if the receiver’s data matches compression; for example, if compression is TIFFCompressionCCITTFAX3, then the data must be 1 bit per sample and 1 sample per pixel. It returns false if the data doesn’t match compression or if compression is unsupported.

color

public native NSColor color(int x, int y)

Discussion

Returns the color of the pixel located at the coordinates x,y.

Availability
See Also

colorizeByMappingGray

Support for colorization of grayscale images.

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

Discussion

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

Returns the receiver’s compression factor.

public float compressionFactor()

Discussion

The compression factor is a value that is specific to the compression type; many types of compression don’t support varying degrees of compression and thus ignore the factor. JPEG compression allows a compression factor ranging from 0.0 to 1.0, with 0.0 being the lowest and 1.0 being the highest.

See Also

compressionType

Returns the receiver’s compression type.

public int compressionType()

Discussion

The compression type represents the compression type used on the data and corresponds to one of the values returned by the class method TIFFCompressionTypes.

See Also

getPixel

Provides access to the pixel data for the location x,y in the receiver.

public long[] getPixel(int x, int y)

Discussion

The array returned will contain raw pixel data in the appropriate order for the receiver’s bitmapFormat. Smaller integer samples, such as 4-bit, are returned as an integer. Floating point values are cast to integer values and returned.

See Also

incrementalLoadFromData

Loads the current image data into an incrementally-loaded image representation and returns the current status of the image.

public int incrementalLoadFromData(NSData data, boolean complete)

Discussion

After initializing the receiver with the constructor with the boolean parameter, you should call this method to incrementally load the image. Call this method each time new data becomes available. Always pass the entire image data buffer in data, not just the newest data, because the image decompressor may need the original data in order to backtrack. This method will block until the data is decompressed; it will decompress as much of the image as possible based on the length of the data. The image rep does not retain data, so you must ensure that data is not released for the duration of this method call. Pass false for complete until the entire image is downloaded, at which time you should pass true. You should also pass true for complete if you have only partially downloaded the data, but cannot finish the download.

This method returns ImageRepLoadStatusUnknownType if you did not pass enough data to determine the image format; you should continue to invoke this method with additional data.

This method returns ImageRepLoadStatusReadingHeader if it has enough data to determine the image format, but needs more data to determine the size and depth and other characteristics of the image. You should continue to invoke this method with additional data.

This method returns ImageRepLoadStatusWillNeedAllData if the image format does not support incremental loading or the Application Kit does not yet implement incremental loading for the image format. You may continue to invoke this method in this case, but until you pass true for complete, this method will continue to return ImageRepLoadStatusWillNeedAllData, and will perform no decompression. Once you pass true, the image will be decompressed and one of the final three status messages will be returned.

If the image format does support incremental loading, then once enough data has been read, the image is decompressed from the top down a row at a time. In this case, instead of a status value, this method returns the number of pixel rows that have been decompressed, starting from the top of the image. You can use this information to draw the part of the image that is valid. The rest of the image is filled with opaque white. Note that if the image is progressive (as in a progressive JPEG or 2D interlaced PNG), this method may quickly return the full height of the image, but the image may still be loading, so do not use this return value as an indication of how much of the image remains to be decompressed.

If an error occurred while decompressing, this method returns ImageRepLoadStatusInvalidData. If complete is true but not enough data was available for decompression, ImageRepLoadStatusUnexpectedEOF is returned. If enough data has been provided (regardless of the complete flag), then ImageRepLoadStatusCompleted is returned. When any of these three status results are returned, this method has adjusted the NSBitmapImageRep so that pixelsHigh and size, as well as the bitmap data, only contains the pixels that are valid, if any.

To cancel decompression, just pass in the existing data or null and true for complete. This method stops decompression immediately, adjusts the image size, and returns ImageRepLoadStatusUnexpectedEOF.This method returns ImageRepLoadStatusCompleted if you call it after receiving any error results (ImageRepLoadStatusInvalidData or ImageRepLoadStatusUnexpectedEOF) or if you call it on an NSBitmapImageRep that was not initialized with the constructor with the boolean parameter.

Availability

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

public boolean isPlanar()

See Also

numberOfPlanes

Returns the number of separate planes image data is organized into.

public int numberOfPlanes()

Discussion

This number 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

representationUsingType

Returns a bitmap version of the receiver, using the format storageType and the properties properties.

public NSData representationUsingType(int storageType, NSDictionary properties)

Discussion

The contents of the properties dictionary is described in “Constants.”

See Also

samplesPerPixel

Returns the number of components in the data.

public int samplesPerPixel()

Discussion

It includes both color components and the coverage component, if present.

See Also

setBitmapData

Copies the data from bits to the image’s bitmap.

public void setBitmapData(byte[] bits)

setBitmapDataPlanes

Copies the data from planes to a planar image’s bitmap planes.

public void setBitmapDataPlanes(byte[][] planes)

setColor

public void setColor(NSColor color, int x, int y)

Discussion

Sets the receiver's pixel located at the coordinates x,y to color.

Availability
See Also

setCompressionWithFactor

Sets the receiver’s compression type and compression factor.

public void setCompressionWithFactor(int compression, float factor)

Discussion

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 1.0, with 0.0 being the lowest and 1.0 being the highest.

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

setPixel

Sets the receiver's pixel at the coordinate x,y to the raw pixel values in pixelData.

public void setPixel(long[] pixelData, int x, int y)

Discussion

The values must be in an orderappropriate to the receiver's bitmapFormat. Small pixel sample values should be passed as an integer value. Floating point values should be cast int[].

See Also

setProperty

Sets the image’s property to value.

public void setProperty(String property, Object value)

Discussion

The properties can affect how the image is read in and saved to file. They’re described in “Constants.” If value is null, the value at property is cleared.

TIFFRepresentation

public NSData TIFFRepresentation()

Returns a TIFF representation of the image, using the compression that’s returned by compressionFactor (if applicable).

public NSData TIFFRepresentation(int compression, float factor)

Discussion

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 before the TIFF representation is generated. JPEG compression in TIFF files is not supported, and factor is ignored.

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

See Also

valueForProperty

Returns the value for property.

public Object valueForProperty(String property)

Discussion

The properties can affect how the image is read in and saved to file. They’re described in “Constants.”

Constants

These constants name properties that are used by representationOfImageRepsInArray, representationUsingType, setPixel, and valueForProperty:

Constant

Description

ImageColorSyncProfileData

The ColorSync profile. It can be used for TIFF, JPEG, GIF, and PNG files. The value is NSData. It’s set when reading in and used when writing out image data..

ImageCompressionFactor

The compression factor. Used only for JPEG files. JPEG compression in TIFF files is not supported, and the factor is ignored. The value is a float between 0.0 and 1.0, with 0.0 being the lowest and 1.0 being the highest. It’s set when reading in and used when writing out.

ImageCompressionMethod

The compression method. Used only for TIFF files. The value is NSTIFFCompression, described below. It’s set when reading in and used when writing out.

ImageDitherTransparency

Whether the image is dithered. Used only for GIF files. The value is Boolean. It’s used when writing out.

ImageInterlaced

Whether the image is interlaced. Used only for PNG files. The value is Boolean. It’s used when writing out.

ImageRGBColorTable

The RGB color table. Used only for GIF files. It’s stored as packed RGB. It’s set when reading in and used when writing out.

ImageEXIFData

The EXIF data for the image. Used only for JPEG files. The value is a NSDictionary containing the EXIF keys and values. It’s set when reading in and used when writing out.

Available in Mac OS X v10.4 and later.

ImageFrameCount

The number of frames in an animated GIF file. The value is an integer. It’s used when reading in.

ImageGamma

The gamma value for the image. Used only for PNG files. Values are between 0.0 and 1.0, with 0.0 being black and 1.0 being the maximum color. The value is a float . It’s set when reading in and used when writing out.

Available in Mac OS X v10.4 and later.

ImageCurrentFrame

The current frame for an animated GIF file. The first frame is 0. The value is an integer.

ImageCurrentFrameDuration

The duration in seconds of the current frame for an animated GIF image. The value is a float. It is used when reading in, but not writing out.

ImageProgressive

Whether the image uses progressive encoding. Used only for JPEG files. The value is a Boolean. It’s set when reading in and used when writing out.

Available in Mac OS X v10.4 and later.

ImageLoopCount

The number of loops to make when animating a GIF image. Zero indicates loop indefinitely. The value must be an integer. It is used when reading in but not when writing out the image.

Available in Mac OS X v10.3 and later.

The following file type constants are provided as a convenience by NSBitmapImageRep:

Constant

Description

BMPFileType

Windows bitmap image (BMP) format

GIFFileType

Graphics Image Format (GIF), originally created by CompuServe for online downloads

JPEGFileType

JPEG format

JPEG2000FileType

JPEG 2000 file format.

Available in Mac OS X v10.4 and later.

PNGFileType

Portable Network Graphics (PNG) format

TIFFFileType

Tagged Image File Format (TIFF)

The following constants represent the various TIFF data-compression schemes supported by NSBitmapImageRep and are returned by TIFFCompressionTypes:

Constant

Description

TIFFCompressionNone

No compression.

TIFFCompressionCCITTFAX3

CCITT Fax Group 3 compression. It’s for 1-bit fax images sent over telephone lines.

TIFFCompressionCCITTFAX4

CCITT Fax Group 4 compression. It’s for 1-bit fax images sent over ISDN lines.

TIFFCompressionLZW

LZW compression.

TIFFCompressionJPEG

JPEG compression. No longer supported for input or output.

TIFFCompressionNEXT

NeXT compressed. Used for input only.

TIFFCompressionPackBits

PackBits compression.

TIFFCompressionOldJPEG

Old JPEG compression. No longer supported for input or output.

The following constants represent the various bitmap component formats supported by NSBitmapImageRep. These values are returned by bitmapFormat.

Constant

Description

AlphaFirstBitmapFormat

If 0, alpha values are the last component. For example, CMYKA and RGBA.

Available in Mac OS X v10.4 and later.

AlphaNonpremultipliedBitmapFormat

If 0, alpha values are premultiplied.

Available in Mac OS X v10.4 and later.

FloatingPointSamplesBitmapFormat

If 0, samples are integer values.

Available in Mac OS X v10.4 and later.

The following constants represent the various status values returned by incrementalLoadFromData:

Constant

Description

ImageRepLoadStatusUnknownType

Not enough data to determine image format. You should continue to provide more data.

ImageRepLoadStatusReadingHeader

The image format is known, but not enough data has been read to determine the size, depth, etc., of the image. You should continue to provide more data.

ImageRepLoadStatusWillNeedAllData

Incremental loading cannot be supported. Until you call incrementalLoadFromData with true, this status will be returned. You can continue to call the method but no decompression will take place. Once you do call the method with true, then the image will be decompressed and one of the final three status messages will be returned.

ImageRepLoadStatusInvalidData

An error occurred during image decompression. The image contains the portions of the data that have already been successfully decompressed, if any

ImageRepLoadStatusUnexpectedEOF

incrementalLoadFromData was called with true, but not enough data was available for decompression. The image contains the portions of the data that have already been succesfully decompressed, if any.

ImageRepLoadStatusCompleted

Enough data has been provided to successfully decompress the image (regardless of the complete flag).



Next Page > Hide TOC

© 1997, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-02-01)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.