NSBitmapImageRep Class Reference

The new colorSpace

The rendering intent specifies how to handle colors that are not located within the target color space. The supported values are NSColorRenderingIntent.

The desired colorSpace.

A TIFF compression type. NSTIFFCompression types are defined in “Constants.”

The x-axis coordinate.

The y-axis coordinate.

A float value representing the midpoint of the grayscale image.

A color object representing the midpoint of the color to map the image to.

A color object representing the black mapping to use for shadows.

A color object representing the white mapping to be used in the image.

On return, a C array of five character pointers. If the bitmap data is in planar configuration, each pointer will be initialized to point to one of the data planes. If there are less than five planes, the remaining pointers will be set to NULL. If the bitmap data is in meshed configuration, only the first pointer will be initialized; the others will be NULL.

On return, an enum constant that represents the compression type used on the data; it corresponds to one of the values returned by the class method getTIFFCompressionTypes:count:.

A float value that is 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.

On return, an array of integers containing 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.

The x-axis coordinate of the pixel.

The y-axis coordinate of the pixel.

A data object that contains the image to be loaded.

YES if the image is entirely downloaded, NO otherwise.

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 a coverage plane exists, the bitmap’s color components must be premultiplied with it. If the data is in meshed configuration (that is, 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 getPixel:atX:y: 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 returned object will only reference the image data; it will not copy it. The object treats the image data in the buffers as immutable and will not attempt to alter it. When the object itself is freed, it will not attempt to free the buffers.

The width of the image in pixels. This value must be greater than 0.

The height of the image in pixels. This value must be greater than 0.

The number of bits used to specify one pixel in a single component of the data. All components are assumed to have the same bits per sample. bps should be one of these values: 1, 2, 4, 8, 12, or 16.

The number of data components, or samples per pixel. This value includes both color components and the coverage component (alpha), if present. Meaningful values range from 1 through 5. An image with cyan, magenta, yellow, and black (CMYK) color components plus a coverage component would have an spp of 5; a grayscale image that lacks a coverage component would have an spp of 1.

YES if one of the components counted in the number of samples per pixel (spp) is a coverage (alpha) component, and NO if there is no coverage component. If YES, the color components in the bitmap data must be premultiplied with their coverage component.

YES if the data components are laid out in a series of separate “planes” or channels (“planar configuration”) and NO if component values are interwoven in a single channel (“meshed configuration”). If NO, only the first buffer of planes is read.

For example, in meshed configuration, the red, green, blue, and coverage values for the first pixel of an image would precede the red, green, blue, and coverage values for the second pixel, and so on. In planar configuration, red values for all the pixels in the image would precede all green values, which would precede all blue values, which would precede all coverage values.

A string constant that indicates how data values are to be interpreted. It should be one of the following values:

• NSCalibratedWhiteColorSpace

• NSCalibratedBlackColorSpace

• NSCalibratedRGBColorSpace

• NSDeviceWhiteColorSpace

• NSDeviceBlackColorSpace

• NSDeviceRGBColorSpace

• NSDeviceCMYKColorSpace

• NSNamedColorSpace

• NSCustomColorSpace

If bps is 12, you cannot specify the monochrome color space.

An integer that specifies the ordering of the bitmap components. It is a mask created by combining the NSBitmapFormat constants NSAlphaFirstBitmapFormat, NSAlphaNonpremultipliedBitmapFormat and NSFloatingPointSamplesBitmapFormat using the C bitwise OR operator.

The number of bytes that are allocated for each scan line in each plane of data. A scan line is a single row of pixels spanning the width of the image.

Normally, rowBytes can be figured from the width of the image, the number of bits per pixel in each sample (bps), and, if the data is in a meshed configuration, the number of samples per pixel (spp). However, if the data for each row is aligned on word or other boundaries, it may have been necessary to allocate more memory for each row than there is data to fill it. rowBytes lets the object know whether that’s the case.

If you pass in a rowBytes value of 0, the bitmap data allocated may be padded to fall on long word or larger boundaries for performance. If your code wants to advance row by row, use bytesPerRow and do not assume the data is packed. Passing in a non-zero value allows you to specify exact row advances.

This integer value informs NSBitmapImageRep how many bits are actually allocated per pixel in each plane of data. If the data is in planar configuration, this normally equals bps (bits per sample). If the data is in meshed configuration, it normally equals bps times spp (samples per pixel). However, it’s possible for a pixel specification to be followed by some meaningless bits (empty space), as may happen, for example, if pixel data is aligned on byte boundaries. NSBitmapImageRep supports only a limited number of pixelBits values (other than the default): for RGB images with 4 bps, pixelBits may be 16; for RGB images with 8 bps, pixelBits may be 32. The legal values for pixelBits are system dependent.

If you specify 0 for this parameter, the object interprets the number of bits per pixel using the values in the bps and spp parameters, as described in the preceding paragraph, without any meaningless bits.

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 a coverage plane exists, the bitmap’s color components must be premultiplied with it. If the data is in meshed configuration (that is, 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 getPixel:atX:y: 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 returned object will only reference the image data; it will not copy it. The object treats the image data in the buffers as immutable and will not attempt to alter it. When the object itself is freed, it will not attempt to free the buffers.

The width of the image in pixels. This value must be greater than 0.

The height of the image in pixels. This value must be greater than 0.

The number of bits used to specify one pixel in a single component of the data. All components are assumed to have the same bits per sample. bps should be one of these values: 1, 2, 4, 8, 12, or 16.

The number of data components, or samples per pixel. This value includes both color components and the coverage component (alpha), if present. Meaningful values range from 1 through 5. An image with cyan, magenta, yellow, and black (CMYK) color components plus a coverage component would have an spp of 5; a grayscale image that lacks a coverage component would have an spp of 1.

YES if one of the components counted in the number of samples per pixel (spp) is a coverage (alpha) component, and NO if there is no coverage component. If YES, the color components in the bitmap data must be premultiplied with their coverage component.

YES if the data components are laid out in a series of separate “planes” or channels (“planar configuration”) and NO if component values are interwoven in a single channel (“meshed configuration”). If NO, only the first buffer of planes is read.

For example, in meshed configuration, the red, green, blue, and coverage values for the first pixel of an image would precede the red, green, blue, and coverage values for the second pixel, and so on. In planar configuration, red values for all the pixels in the image would precede all green values, which would precede all blue values, which would precede all coverage values.

A string constant that indicates how data values are to be interpreted. It should be one of the following values:

• NSCalibratedWhiteColorSpace

• NSCalibratedBlackColorSpace

• NSCalibratedRGBColorSpace

• NSDeviceWhiteColorSpace

• NSDeviceBlackColorSpace

• NSDeviceRGBColorSpace

• NSDeviceCMYKColorSpace

• NSNamedColorSpace

• NSCustomColorSpace

If bps is 12, you cannot specify the monochrome color space.

The number of bytes that are allocated for each scan line in each plane of data. A scan line is a single row of pixels spanning the width of the image.

Normally, rowBytes can be figured from the width of the image, the number of bits per pixel in each sample (bps), and, if the data is in a meshed configuration, the number of samples per pixel (spp). However, if the data for each row is aligned on word or other boundaries, it may have been necessary to allocate more memory for each row than there is data to fill it. rowBytes lets the object know whether that’s the case.

If you pass in a rowBytes value of 0, the bitmap data allocated may be padded to fall on long word or larger boundaries for performance. If your code wants to advance row by row, use bytesPerRow and do not assume the data is packed. Passing in a non-zero value allows you to specify exact row advances.

This integer value informs NSBitmapImageRep how many bits are actually allocated per pixel in each plane of data. If the data is in planar configuration, this normally equals bps (bits per sample). If the data is in meshed configuration, it normally equals bps times spp (samples per pixel). However, it’s possible for a pixel specification to be followed by some meaningless bits (empty space), as may happen, for example, if pixel data is aligned on byte boundaries. NSBitmapImageRep supports only a limited number of pixelBits values (other than the default): for RGB images with 4 bps, pixelBits may be 16; for RGB images with 8 bps, pixelBits may be 32. The legal values for pixelBits are system dependent.

If you specify 0 for this parameter, the object interprets the number of bits per pixel using the values in the bps and spp parameters, as described in the preceding paragraph, without any meaningless bits.

A Core Graphics image object (an opaque type) from which to create the receiver. This opaque type is retained.

A Core Image object whose contents are to be copied to the receiver. This image rectangle must be of a finite size.

A data object containing image data. 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.

A rectangle that specifies an area of the current window in the current coordinate system.

An enum constant specifying a file type for bitmap images. It can be NSBMPFileType, NSGIFFileType, NSJPEGFileType, NSPNGFileType, or NSTIFFFileType.

A dictionary that contains key-value pairs specifying image properties. These string constants used as keys and the valid values are described in “Bitmap image properties.”

A color object representing the color to be set.

The x-axis coordinate of the pixel.

The y-axis coordinate of the pixel.

An enum constant that identifies one of the supported compression types as described in “Constants.”

A floating point value that is 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.

An array of integers representing the raw pixel values. The values must be in an order appropriate to the receiver's bitmapFormat. Small pixel sample values should be passed as an integer value. Floating point values should be cast int[].

The x-axis coordinate of the pixel.

The y-axis coordinate of the pixel.

A string constant used as a key for an image property. These properties are described in “Constants.”

A value specific to property. If value is nil, the value of the property is cleared.

An enum constant that represents a TIFF data-compression scheme. Legal values for compression can be found in NSBitmapImageRep.h and are described in “Constants.”

A float value that 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.

A string constant used as a key for an image property. These properties are described in “Constants.”