Mac Developer Library

Developer

AppKit Framework Reference NSBitmapImageRep Class Reference

Options
Deployment Target:

On This Page
Language:

NSBitmapImageRep

The NSBitmapImageRep class renders an image from bitmap data. Bitmap data formats supported include GIF, JPEG, TIFF, PNG, and various permutations of raw bitmap data. More...

Inheritance


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • Creates and returns an NSBitmapImageRep object initialized with the first image in the supplied data.

    Declaration

    Swift

    convenience init!(data bitmapData: NSData!)

    Objective-C

    + (instancetype)imageRepWithData:(NSData *)bitmapData

    Parameters

    bitmapData

    A data object containing one or more bitmapped images. The bitmapData parameter can contain data in any supported bitmap format.

    Return Value

    An NSBitmapImageRep instance or nil if the class is unable to create an image representation.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns an array of initialized NSBitmapImageRep objects corresponding to the images in the supplied data.

    Declaration

    Swift

    class func imageRepsWithData(_ bitmapData: NSData) -> [AnyObject]

    Objective-C

    + (NSArray *)imageRepsWithData:(NSData *)bitmapData

    Parameters

    bitmapData

    A data object containing one or more bitmapped images or nil if the class is unable to create an image representation. The bitmapData parameter can contain data in any supported bitmap format.

    Return Value

    An array of NSBitmapImageRep instances or an empty array if the class is unable to create any image representations.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Colorizes a grayscale image.

    Declaration

    Swift

    func colorizeByMappingGray(_ midPoint: CGFloat, toColor midPointColor: NSColor?, blackMapping shadowColor: NSColor?, whiteMapping lightColor: NSColor?)

    Objective-C

    - (void)colorizeByMappingGray:(CGFloat)midPoint toColor:(NSColor *)midPointColor blackMapping:(NSColor *)shadowColor whiteMapping:(NSColor *)lightColor

    Parameters

    midPoint

    A float value representing the midpoint of the grayscale image.

    midPointColor

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

    shadowColor

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

    lightColor

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

    Discussion

    This method maps the receiver such that:

    • Gray value of midPoint –> midPointColor;

    • black –> shadowColor;

    • white –> lightColor.

    It works on images with 8-bit SPP, and thus supports either 8-bit gray or 24-bit color (with optional alpha).

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver, a newly allocated NSBitmapImageRep object, so it can render the specified image.

    Declaration

    Swift

    init?(bitmapDataPlanes planes: UnsafeMutablePointer<UnsafeMutablePointer<UInt8>>, pixelsWide width: Int, pixelsHigh height: Int, bitsPerSample bps: Int, samplesPerPixel spp: Int, hasAlpha alpha: Bool, isPlanar isPlanar: Bool, colorSpaceName colorSpaceName: String, bitmapFormat bitmapFormat: NSBitmapFormat, bytesPerRow rowBytes: Int, bitsPerPixel pixelBits: Int)

    Objective-C

    - (instancetype)initWithBitmapDataPlanes:(unsigned char **)planes pixelsWide:(NSInteger)width pixelsHigh:(NSInteger)height bitsPerSample:(NSInteger)bps samplesPerPixel:(NSInteger)spp hasAlpha:(BOOL)alpha isPlanar:(BOOL)isPlanar colorSpaceName:(NSString *)colorSpaceName bitmapFormat:(NSBitmapFormat)bitmapFormat bytesPerRow:(NSInteger)rowBytes bitsPerPixel:(NSInteger)pixelBits

    Parameters

    planes

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

    width

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

    height

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

    bps

    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.

    spp

    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.

    alpha

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

    isPlanar

    YEStrue if the data components are laid out in a series of separate “planes” or channels (“planar configuration”) and NOfalse if component values are interwoven in a single channel (“meshed configuration”). If NOfalse, 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.

    colorSpaceName

    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.

    bitmapFormat

    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.

    rowBytes

    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.

    pixelBits

    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.

    Return Value

    An initialized NSBitmapImageRep object or nil if the object cannot be initialized.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Initializes the receiver, a newly allocated NSBitmapImageRep object, so it can render the specified image.

    Declaration

    Swift

    init?(bitmapDataPlanes planes: UnsafeMutablePointer<UnsafeMutablePointer<UInt8>>, pixelsWide width: Int, pixelsHigh height: Int, bitsPerSample bps: Int, samplesPerPixel spp: Int, hasAlpha alpha: Bool, isPlanar isPlanar: Bool, colorSpaceName colorSpaceName: String, bytesPerRow rowBytes: Int, bitsPerPixel pixelBits: Int)

    Objective-C

    - (instancetype)initWithBitmapDataPlanes:(unsigned char **)planes pixelsWide:(NSInteger)width pixelsHigh:(NSInteger)height bitsPerSample:(NSInteger)bps samplesPerPixel:(NSInteger)spp hasAlpha:(BOOL)alpha isPlanar:(BOOL)isPlanar colorSpaceName:(NSString *)colorSpaceName bytesPerRow:(NSInteger)rowBytes bitsPerPixel:(NSInteger)pixelBits

    Parameters

    planes

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

    width

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

    height

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

    bps

    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.

    spp

    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.

    alpha

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

    isPlanar

    YEStrue if the data components are laid out in a series of separate “planes” or channels (“planar configuration”) and NOfalse if component values are interwoven in a single channel (“meshed configuration”). If NOfalse, 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.

    colorSpaceName

    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.

    rowBytes

    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.

    pixelBits

    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.

    Return Value

    An initialized NSBitmapImageRep object or nil if the object cannot be initialized.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSBitmapImageRep object created from a Core Graphics image object.

    Declaration

    Swift

    init(CGImage cgImage: CGImage)

    Objective-C

    - (instancetype)initWithCGImage:(CGImageRef)cgImage

    Parameters

    cgImage

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

    Return Value

    An NSBitmapImageRep object initialized from the contents of the Core Graphics image or nil if the NSBitmapImageRep couldn’t be created.

    Discussion

    If you use this method, you should treat the resulting bitmap NSBitmapImageRep object as read only. Because it only retains the value in the cgImage parameter, rather than unpacking the data, accessing the pixel data requires the creation of a copy of that data in memory. Changes to that data are not saved back to the Core Graphics image.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – CGImage

  • Returns an NSBitmapImageRep object created from a Core Image object.

    Declaration

    Swift

    init(CIImage ciImage: CIImage)

    Objective-C

    - (instancetype)initWithCIImage:(CIImage *)ciImage

    Parameters

    ciImage

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

    Return Value

    An NSBitmapImageRep object initialized from the contents of the Core Image (CIImage) object or nil if the NSBitmapImageRep couldn’t be created.

    Discussion

    The image in the ciImage parameter must be fully rendered before the receiver can be initialized. If you specify an object whose rendering was deferred (and thus does not have any pixels available now), this method forces the image to be rendered immediately. Rendering the image could result in a performance penalty if the image has a complex rendering chain or accelerated rendering hardware is not available. Rendering uses the current graphics context in the thread from which this method is called; to ensure consistent results across multiple threads, set the current context using the NSGraphicsContext class before calling this method.

    By the time this method returns, the resultant NSBitmapImageRep object can have its raw pixel data inspected, can be put on the pasteboard, and can be encoded to any of the standard image formats that NSBitmapImageRep supports (JPEG, TIFF, and so on.)

    If you pass in a CIImage object whose extents are not finite, this method raises an exception.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – initWithBitmapImageRep: (CIImage)

  • Initializes a newly allocated NSBitmapImageRep from the provided data.

    Declaration

    Swift

    init?(data bitmapData: NSData)

    Objective-C

    - (instancetype)initWithData:(NSData *)bitmapData

    Parameters

    bitmapData

    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.

    Return Value

    Returns an initialized NSBitmapImageRep if the initialization was successful or nil if it was unable to interpret the contents of bitmapData.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes the receiver, a newly allocated NSBitmapImageRep object, with bitmap data read from a rendered image.

    Declaration

    Swift

    init?(focusedViewRect rect: NSRect)

    Objective-C

    - (instancetype)initWithFocusedViewRect:(NSRect)rect

    Parameters

    rect

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

    Return Value

    Returns the initialized object or nil If for any reason the new object can’t be initialized.

    Discussion

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns the receiver, a newly allocated NSBitmapImageRep object, for incremental loading.

    Declaration

    Swift

    init(forIncrementalLoad forIncrementalLoad: ())

    Objective-C

    - (instancetype)initForIncrementalLoad

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns the bitmap format of the receiver.

    Declaration

    Swift

    var bitmapFormat: NSBitmapFormat { get }

    Objective-C

    @property(readonly) NSBitmapFormat bitmapFormat

    Discussion

    Returns 0 by default. The return value can indicate several different attributes, which are described in Constants.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – bytesPerRow

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

    Declaration

    Swift

    var bitsPerPixel: Int { get }

    Objective-C

    @property(readonly) NSInteger 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 initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:) in case extra memory is allocated for each pixel. This may be the case, for example, if pixel data is aligned on byte boundaries.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var bytesPerPlane: Int { get }

    Objective-C

    @property(readonly) NSInteger bytesPerPlane

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    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.

    Declaration

    Swift

    var bytesPerRow: Int { get }

    Objective-C

    @property(readonly) NSInteger bytesPerRow

    Discussion

    If not explicitly set to another value (in initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:), 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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isPlanar isPlanar Available in OS X v10.0 through OS X v10.9

    Returns YEStrue if image data is a planar configuration and NOfalse if its in a meshed configuration.

    Declaration

    Objective-C

    - (BOOL)isPlanar

    Discussion

    In a planar configuration, the image data is segregated into a separate plane for each color and coverage component. In a meshed configuration, the data is integrated into a single plane.

    Import Statement

    Availability

    Available in OS X v10.0 through OS X v10.9.

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

    Declaration

    Swift

    var numberOfPlanes: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfPlanes

    Discussion

    This number is the number of samples per pixel if the data has a separate plane for each component (isPlanar returns YEStrue) and 1 if the data is meshed (isPlanar returns NOfalse).

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – samplesPerPixel
    – hasAlpha (NSImageRep)
    – bitsPerSample (NSImageRep)

  • Returns the number of components in the data.

    Declaration

    Swift

    var samplesPerPixel: Int { get }

    Objective-C

    @property(readonly) NSInteger samplesPerPixel

    Discussion

    The returned value includes both color components and the coverage component, if present.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – hasAlpha (NSImageRep)
    – bitsPerSample (NSImageRep)

  • Returns by indirection an array of all available compression types that can be used when writing a TIFF image.

    Declaration

    Swift

    class func getTIFFCompressionTypes(_ list: UnsafeMutablePointer<UnsafePointer<NSTIFFCompression>>, count numTypes: UnsafeMutablePointer<Int>)

    Objective-C

    + (void)getTIFFCompressionTypes:(const NSTIFFCompression **)list count:(NSInteger *)numTypes

    Parameters

    list

    On return, a C array of NSTIFFCompression constants. This array belongs to the NSBitmapImageRep class; it shouldn’t be freed or altered. See Constants for the supported TIFF compression types.

    numTypes

    The number of constants in list.

    Discussion

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an autoreleased string containing the localized name for the specified compression type.

    Declaration

    Swift

    class func localizedNameForTIFFCompressionType(_ compression: NSTIFFCompression) -> String?

    Objective-C

    + (NSString *)localizedNameForTIFFCompressionType:(NSTIFFCompression)compression

    Parameters

    compression

    A TIFF compression type. NSTIFFCompression types are described in Constants.

    Return Value

    A localized name for compression or nil if compression is unrecognized.

    Discussion

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Tests whether the receiver can be compressed by the specified compression scheme.

    Declaration

    Swift

    func canBeCompressedUsing(_ compression: NSTIFFCompression) -> Bool

    Objective-C

    - (BOOL)canBeCompressedUsing:(NSTIFFCompression)compression

    Parameters

    compression

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

    Return Value

    YEStrue if the receiver's data matches compression with this type, NOfalse if the data doesn’t match compression or if compression is unsupported..

    Discussion

    Legal values for compression can be found in NSBitmapImageRep.h and are described in TIFF Compression in NSBitmapImageReps. This method returns YEStrue if the receiver’s data matches compression; for example, if compression is NSTIFFCompressionCCITTFAX3, then the data must be 1 bit per sample and 1 sample per pixel.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s compression type and compression factor.

    Declaration

    Swift

    func setCompression(_ compression: NSTIFFCompression, factor factor: Float)

    Objective-C

    - (void)setCompression:(NSTIFFCompression)compression factor:(float)factor

    Parameters

    compression

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

    factor

    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.

    Discussion

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns by indirection the receiver’s compression type and compression factor.

    Declaration

    Swift

    func getCompression(_ compression: UnsafeMutablePointer<NSTIFFCompression>, factor factor: UnsafeMutablePointer<Float>)

    Objective-C

    - (void)getCompression:(NSTIFFCompression *)compression factor:(float *)factor

    Parameters

    compression

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

    factor

    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.

    Discussion

    Use this method to get information on the compression type for the source image data.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the image’s property to value.

    Declaration

    Swift

    func setProperty(_ property: String, withValue value: AnyObject?)

    Objective-C

    - (void)setProperty:(NSString *)property withValue:(id)value

    Parameters

    property

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

    value

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

    Discussion

    The properties can affect how the image is read in and saved to file.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the value for the specified property.

    Declaration

    Swift

    func valueForProperty(_ property: String) -> AnyObject?

    Objective-C

    - (id)valueForProperty:(NSString *)property

    Parameters

    property

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

    Return Value

    A value specific to property, or nil if the property is not set for the bitmap.

    Discussion

    Image properties can affect how an image is read in and saved to file. When retrieving the bitmap image properties defined in Bitmap image properties, be sure to check the return value of this method for a nil value. If a particular value is not set for the image, this method may return nil.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func incrementalLoadFromData(_ data: NSData, complete complete: Bool) -> Int

    Objective-C

    - (NSInteger)incrementalLoadFromData:(NSData *)data complete:(BOOL)complete

    Parameters

    data

    A data object that contains the image to be loaded.

    complete

    YEStrue if the image is entirely downloaded, NOfalse otherwise.

    Return Value

    An integer constant indicating the status of the image during the load operation. See the discussion for details.

    Discussion

    After initializing the receiver with initForIncrementalLoad, 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 NOfalse for complete until the entire image is downloaded, at which time you should pass YEStrue. You should also pass YEStrue for complete if you have only partially downloaded the data, but cannot finish the download.

    This method returns NSImageRepLoadStatusUnknownType 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 NSImageRepLoadStatusReadingHeader 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 NSImageRepLoadStatusWillNeedAllData 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 YEStrue for complete, this method will continue to return NSImageRepLoadStatusWillNeedAllData, and will perform no decompression. Once you pass YEStrue, 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 NSImageRepLoadStatusInvalidData. If complete is YEStrue but not enough data was available for decompression, NSImageRepLoadStatusUnexpectedEOF is returned. If enough data has been provided (regardless of the complete flag), then NSImageRepLoadStatusCompleted 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 nil and YEStrue for complete. This method stops decompression immediately, adjusts the image size, and returns NSImageRepLoadStatusUnexpectedEOF. This method returns NSImageRepLoadStatusCompleted if you call it after receiving any error results (NSImageRepLoadStatusInvalidData or NSImageRepLoadStatusUnexpectedEOF) or if you call it on an NSBitmapImageRep that was not initialized with initForIncrementalLoad.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Changes the color of the pixel at the specified coordinates.

    Declaration

    Swift

    func setColor(_ color: NSColor, atX x: Int, y y: Int)

    Objective-C

    - (void)setColor:(NSColor *)color atX:(NSInteger)x y:(NSInteger)y

    Parameters

    color

    A color object representing the color to be set.

    x

    The x-axis coordinate of the pixel.

    y

    The y-axis coordinate of the pixel.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – colorAtX:y:

  • Returns the color of the pixel at the specified coordinates.

    Declaration

    Swift

    func colorAtX(_ x: Int, y y: Int) -> NSColor?

    Objective-C

    - (NSColor *)colorAtX:(NSInteger)x y:(NSInteger)y

    Parameters

    x

    The x-axis coordinate.

    y

    The y-axis coordinate.

    Return Value

    A color object representing the color at the specified coordinates.

    Discussion

    Calling this method creates a new NSColor object. The overhead of object creation means this method is best suited for infrequent color sampling. If you instead need to work with large numbers of pixels, access the bitmap data directly using the bitmapData or getPixel:atX:y: method for better performance.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the receiver's pixel at the specified coordinates to the specified raw pixel values.

    Declaration

    Swift

    func setPixel(_ pixelData: UnsafeMutablePointer<Int>, atX x: Int, y y: Int)

    Objective-C

    - (void)setPixel:(NSUInteger [])pixelData atX:(NSInteger)x y:(NSInteger)y

    Parameters

    pixelData

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

    x

    The x-axis coordinate of the pixel.

    y

    The y-axis coordinate of the pixel.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns by indirection the pixel data for the specified location in the receiver.

    Declaration

    Swift

    func getPixel(_ pixelData: UnsafeMutablePointer<Int>, atX x: Int, y y: Int)

    Objective-C

    - (void)getPixel:(NSUInteger [])pixelData atX:(NSInteger)x y:(NSInteger)y

    Parameters

    pixelData

    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.

    x

    The x-axis coordinate of the pixel.

    y

    The y-axis coordinate of the pixel.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a Core Graphics image object from the receiver’s current bitmap data.

    Declaration

    Swift

    var CGImage: CGImage? { get }

    Objective-C

    @property(readonly) CGImageRef CGImage

    Return Value

    Returns an autoreleased CGImageRef opaque type based on the receiver’s current bitmap data.

    Discussion

    The returned CGImageRef has pixel dimensions that are identical to the receiver’s. This method might return a preexisting CGImageRef opaque type or create a new one. If the receiver is later modified, subsequent invocations of this method might return different CGImageRef opaque types.

    Import Statement

    import AppKit

    Availability

    Available in OS X version 10.5.

Data Types

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

    Declaration

    Swift

    enum NSBitmapImageFileType : UInt { case NSTIFFFileType case NSBMPFileType case NSGIFFileType case NSJPEGFileType case NSPNGFileType case NSJPEG2000FileType }

    Objective-C

    enum { NSTIFFFileType, NSBMPFileType, NSGIFFileType, NSJPEGFileType, NSPNGFileType, NSJPEG2000FileType }; typedef NSUInteger NSBitmapImageFileType;

    Constants

    • NSTIFFFileType

      NSTIFFFileType

      Tagged Image File Format (TIFF)

      Available in OS X v10.0 and later.

    • NSBMPFileType

      NSBMPFileType

      Windows bitmap image (BMP) format

      Available in OS X v10.0 and later.

    • NSGIFFileType

      NSGIFFileType

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

      Available in OS X v10.0 and later.

    • NSJPEGFileType

      NSJPEGFileType

      JPEG format

      Available in OS X v10.0 and later.

    • NSPNGFileType

      NSPNGFileType

      Portable Network Graphics (PNG) format

      Available in OS X v10.0 and later.

    • NSJPEG2000FileType

      NSJPEG2000FileType

      JPEG 2000 file format.

      Available in OS X v10.4 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants represent the various TIFF data-compression schemes supported by NSBitmapImageRep.

    Declaration

    Swift

    enum NSTIFFCompression : UInt { case None case CCITTFAX3 case CCITTFAX4 case LZW case JPEG case NEXT case PackBits case OldJPEG }

    Objective-C

    enum { NSTIFFCompressionNone = 1, NSTIFFCompressionCCITTFAX3 = 3, NSTIFFCompressionCCITTFAX4 = 4, NSTIFFCompressionLZW = 5, NSTIFFCompressionJPEG = 6, NSTIFFCompressionNEXT = 32766, NSTIFFCompressionPackBits = 32773, NSTIFFCompressionOldJPEG = 32865 }; typedef NSUInteger NSTIFFCompression;

    Constants

    • None

      NSTIFFCompressionNone

      No compression.

      Available in OS X v10.0 and later.

    • CCITTFAX3

      NSTIFFCompressionCCITTFAX3

      CCITT Fax Group 3 compression.

      Used for 1-bit fax images sent over telephone lines.

      Available in OS X v10.0 and later.

    • CCITTFAX4

      NSTIFFCompressionCCITTFAX4

      CCITT Fax Group 4 compression.

      Used for 1-bit fax images sent over ISDN lines.

      Available in OS X v10.0 and later.

    • LZW

      NSTIFFCompressionLZW

      LZW compression.

      Available in OS X v10.0 and later.

    • JPEG

      NSTIFFCompressionJPEG

      JPEG compression. No longer supported for input or output.

      Available in OS X v10.0 and later.

    • NEXT

      NSTIFFCompressionNEXT

      NeXT compressed. Supported for input only.

      Available in OS X v10.0 and later.

    • PackBits

      NSTIFFCompressionPackBits

      PackBits compression.

      Available in OS X v10.0 and later.

    • OldJPEG

      NSTIFFCompressionOldJPEG

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

      Available in OS X v10.0 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants represent the various bitmap component formats supported by NSBitmapImageRep. These values are combined using the C bitwise OR operator and passed to initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bitmapFormat:bytesPerRow:bitsPerPixel: as the bitmap format and are returned by bitmapFormat.

    Declaration

    Swift

    struct NSBitmapFormat : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var NSAlphaFirstBitmapFormat: NSBitmapFormat { get } static var NSAlphaNonpremultipliedBitmapFormat: NSBitmapFormat { get } static var NSFloatingPointSamplesBitmapFormat: NSBitmapFormat { get } static var NS16BitLittleEndianBitmapFormat: NSBitmapFormat { get } static var NS32BitLittleEndianBitmapFormat: NSBitmapFormat { get } static var NS16BitBigEndianBitmapFormat: NSBitmapFormat { get } static var NS32BitBigEndianBitmapFormat: NSBitmapFormat { get } }

    Objective-C

    enum { NSAlphaFirstBitmapFormat = 1 << 0, NSAlphaNonpremultipliedBitmapFormat = 1 << 1, NSFloatingPointSamplesBitmapFormat = 1 << 2 }; typedef NSUInteger NSBitmapFormat;

    Constants

    • NSAlphaFirstBitmapFormat

      NSAlphaFirstBitmapFormat

      If 0, alpha values are the last component.

      For example, CMYKA and RGBA.

      Available in OS X v10.4 and later.

    • NSAlphaNonpremultipliedBitmapFormat

      NSAlphaNonpremultipliedBitmapFormat

      If 0, alpha values are premultiplied.

      Available in OS X v10.4 and later.

    • NSFloatingPointSamplesBitmapFormat

      NSFloatingPointSamplesBitmapFormat

      If 0, samples are integer values.

      Available in OS X v10.4 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • These constants represent the various status values returned by incrementalLoadFromData:complete:.

    Declaration

    Swift

    enum NSImageRepLoadStatus : Int { case UnknownType case ReadingHeader case WillNeedAllData case InvalidData case UnexpectedEOF case Completed }

    Objective-C

    enum { NSImageRepLoadStatusUnknownType = -1, NSImageRepLoadStatusReadingHeader = -2, NSImageRepLoadStatusWillNeedAllData = -3, NSImageRepLoadStatusInvalidData = -4, NSImageRepLoadStatusUnexpectedEOF = -5, NSImageRepLoadStatusCompleted = -6 }; typedef NSInteger NSImageRepLoadStatus;

    Constants

    • UnknownType

      NSImageRepLoadStatusUnknownType

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

      Available in OS X v10.2 and later.

    • ReadingHeader

      NSImageRepLoadStatusReadingHeader

      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.

      Available in OS X v10.2 and later.

    • WillNeedAllData

      NSImageRepLoadStatusWillNeedAllData

      Incremental loading cannot be supported. Until you call incrementalLoadFromData:complete: with YEStrue, 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 YEStrue, then the image will be decompressed and one of the final three status messages will be returned.

      Available in OS X v10.2 and later.

    • InvalidData

      NSImageRepLoadStatusInvalidData

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

      Available in OS X v10.2 and later.

    • UnexpectedEOF

      NSImageRepLoadStatusUnexpectedEOF

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

      Available in OS X v10.2 and later.

    • Completed

      NSImageRepLoadStatusCompleted

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

      Available in OS X v10.2 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Declaration

    Swift

    var NSImageColorSyncProfileData: NSString! var NSImageCompressionFactor: NSString! var NSImageCompressionMethod: NSString! var NSImageDitherTransparency: NSString! var NSImageInterlaced: NSString! var NSImageRGBColorTable: NSString! var NSImageEXIFData: NSString! var NSImageFallbackBackgroundColor: NSString! var NSImageFrameCount: NSString! var NSImageGamma: NSString! var NSImageCurrentFrame: NSString! var NSImageCurrentFrameDuration: NSString! var NSImageProgressive: NSString! var NSImageLoopCount: NSString!

    Objective-C

    NSString *NSImageCompressionMethod; NSString *NSImageCompressionFactor; NSString *NSImageDitherTransparency; NSString *NSImageRGBColorTable; NSString *NSImageInterlaced; NSString *NSImageColorSyncProfileData; NSString *NSImageFrameCount; NSString *NSImageCurrentFrame; NSString *NSImageCurrentFrameDuration; NSString *NSImageLoopCount; NSString *NSImageGamma; NSString *NSImageProgressive; NSString *NSImageEXIFData; NSString *NSImageFallbackBackgroundColor;

    Constants

    • NSImageColorSyncProfileData

      NSImageColorSyncProfileData

      Identifies an NSData object containing the ColorSync profile data.

      It can be used for TIFF, JPEG, GIF, and PNG files. This value is set when reading in and used when writing out image data. You can get the profile data for a particular color space from the corresponding NSColorSpace object or from the ColorSync Manager.

      Available in OS X v10.0 and later.

    • NSImageCompressionFactor

      NSImageCompressionFactor

      Identifies an NSNumber object containing the compression factor of the image.

      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 1.0 resulting in no compression and 0.0 resulting in the maximum compression possible. It’s set when reading in and used when writing out the image.

      Available in OS X v10.0 and later.

    • NSImageCompressionMethod

      NSImageCompressionMethod

      Identifies an NSNumber object identifying the compression method of the image.

      Used only for TIFF files. The value corresponds to one of the NSTIFFCompression constants, described below. It’s set when reading in and used when writing out.

      Available in OS X v10.0 and later.

    • NSImageDitherTransparency

      NSImageDitherTransparency

      Identifies an NSNumber object containing a boolean that indicates whether the image is dithered.

      Used only when writing GIF files.

      Available in OS X v10.0 and later.

    • NSImageInterlaced

      NSImageInterlaced

      Identifies an NSNumber object containing a Boolean value that indicates whether the image is interlaced.

      Used only when writing out PNG files.

      Available in OS X v10.0 and later.

    • NSImageRGBColorTable

      NSImageRGBColorTable

      Identifies an NSData object containing 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.

      Available in OS X v10.0 and later.

    • NSImageEXIFData

      NSImageEXIFData

      Identifies an NSDictionary object containing the EXIF data for the image.

      This property is used only when reading or writing JPEG files. The dictionary contains the EXIF keys and values. The standard dictionary keys (that is, those that are not specific to camera vendors) are identical to those for kCGImagePropertyExifDictionary declared in the CGImageSource API. See kCGImagePropertyExifDictionary Keys for details.

      Available in OS X v10.4 and later.

    • NSImageFallbackBackgroundColor

      NSImageFallbackBackgroundColor

      Specifies the background color to use when writing to an image format (such as JPEG) that doesn't support alpha. The color's alpha value is ignored. The default background color, when this property is not specified, is white. The value of the property should be an NSColor object. This constant corresponds to the kCGImageDestinationBackgroundColor constant in Quartz.

      Available in OS X v10.5 and later.

    • NSImageFrameCount

      NSImageFrameCount

      Identifies an NSNumber object containing the number of frames in an animated GIF file.

      This value is used when reading in data.

      Available in OS X v10.2 and later.

    • NSImageGamma

      NSImageGamma

      Identifies an NSNumber object containing the gamma value for the image.

      Used only for PNG files. The gamma values is a floating-point number between 0.0 and 1.0, with 0.0 being black and 1.0 being the maximum color. It’s set when reading in and used when writing out.

      Available in OS X v10.4 and later.

    • NSImageCurrentFrame

      NSImageCurrentFrame

      Identifies an NSNumber object containing the current frame for an animated GIF file.

      The first frame is 0.

      Available in OS X v10.2 and later.

    • NSImageCurrentFrameDuration

      NSImageCurrentFrameDuration

      Identifies an NSNumber object containing the duration (in seconds) of the current frame for an animated GIF image.

      The frame duration can be a floating-point value. It is used when reading in, but not when writing out.

      Available in OS X v10.2 and later.

    • NSImageProgressive

      NSImageProgressive

      Identifies an NSNumber object containing a boolean that indicates whether the image uses progressive encoding.

      Used only for JPEG files. It’s set when reading in and used when writing out.

      Available in OS X v10.4 and later.

    • NSImageLoopCount

      NSImageLoopCount

      Identifies an NSNumber object containing the number of loops to make when animating a GIF image.

      A value of 0 indicates the animation should loop indefinitely. Values should be specified as integer numbers. It is used when reading in but not when writing out the image.

      Available in OS X v10.3 and later.

    Discussion

    When using the valueForProperty: method to retrieve the the value for any of these keys, be sure to check that the returned value is non-nil before you attempt to use it. A bitmap image representation may return nil for any values that have not yet been set.

    Import Statement