Draws a bitmap image.
- macOS 10.0+
This function is marginally obsolete. Most applications are better served using the
NSBitmap class to read and display bitmap images.
This function renders an image from a bitmap, binary data that describes the pixel values for the image.
This function renders a bitmap image using an appropriate display operator. It puts the image in the rectangular area specified by its first argument,
rect; the rectangle is specified in the current coordinate system and is located in the current window. The next two arguments,
pixels, give the width and height of the image in pixels. If either of these dimensions is larger or smaller than the corresponding dimension of the destination rectangle, the image will be scaled to fit.
The remaining arguments describe the bitmap data, as explained in the following paragraphs.
bits argument is the number of bits per sample for each pixel and
samples is the number of samples per pixel.
bits is based on
samples and the configuration of the bitmap: if the configuration is planar, then the value of
bits should equal the value of
bits; if the configuration isn’t planar (is meshed instead),
bits should equal
bytes argument is calculated in one of two ways, depending on the configuration of the image data (data configuration is described below). If the data is planar,
bytes. If the data is meshed,
A sample is data that describes one component of a pixel. In an RGB color system, the red, green, and blue components of a color are specified as separate samples, as are the cyan, magenta, yellow, and black components in a CMYK system. Color values in a grayscale are a single sample. Alpha values that determine transparency and opaqueness are specified as a coverage sample separate from color. In bitmap images with alpha, the color (or gray) components have to be premultiplied with the alpha. This is the way images with alpha are displayed, this is the way they are read back, and this is the way they are stored in TIFFs.
is argument refers to the way data is configured in the bitmap. This flag should be set to
YES if a separate data channel is used for each sample. The function provides for up to five channels,
data5. It should be set
NO if sample values are interwoven in a single channel (meshed); all values for one pixel are specified before values for the next pixel.
Grayscale windows store pixel data in planar configuration; color windows store it in meshed configuration.
NSDraw can render meshed data in a planar window, or planar data in a meshed window. However, it’s more efficient if the image has a depth (
bits) and configuration (
is) that match the window.
has argument indicates whether the image contains alpha. If it does, the number of samples should be 1 greater than the number of color components in the model (for example, 4 for RGB).
color argument can be
NSCustom, indicating that the image data is to be interpreted according to the current color space in the graphics state. This allows for imaging using custom color spaces. The image parameters supplied as the other arguments should match what the color space is expecting.
If the image data is planar,
samples–1] point to the planes; if the
data is meshed, only
data needs to be set.