Up

NSBitmapImageRep.m

Authors

Adam Fedor (fedor@gnu.org)
Bitmap image representation.

Copyright: (C) 1996, 2003, 2004 Free Software Foundation, Inc.


Contents -

  1. Class
  2. Software documentation for the NSBitmapImageRep(GNUstepExtension) category

Class Description

NSBitmapImageRep is an image representation for handling images composed of pixels. The standard image format for NSBitmapImageRep is the TIFF format. However, through the use of image filters and other methods, many other standard image formats can be handled by NSBitmapImageRep. Images are typically handled through the NSImage class and there is often no need to use the NSBitmapImageRep class directly. However there may be cases where you want to manipulate the image bitmap data directly.

NSBitmapImageRep : NSImageRep

Declared in:
AppKit/NSBitmapImageRep.h
Availability: OpenStep

Description forthcoming.

Instance Variables

Method summary

TIFFRepresentationOfImageRepsInArray: 

+ (NSData*) TIFFRepresentationOfImageRepsInArray: (NSArray*)anArray;
Availability: OpenStep

Produces an NSData object containing a TIFF representation of all the images stored in anArray. BUGS: Currently this only works if the images are NSBitmapImageRep objects, and it only creates an TIFF from the first image in the array.

TIFFRepresentationOfImageRepsInArray: usingCompression: factor: 

+ (NSData*) TIFFRepresentationOfImageRepsInArray: (NSArray*)anArray usingCompression: (NSTIFFCompression)type factor: (float)factor;
Availability: OpenStep

Produces an NSData object containing a TIFF representation of all the images stored in anArray. The image is compressed according to the compression type and factor . BUGS: Currently this only works if the images are NSBitmapImageRep objects, and it only creates an TIFF from the first image in the array.

getTIFFCompressionTypes: count: 

+ (void) getTIFFCompressionTypes: (const NSTIFFCompression**)list count: (int*)numTypes;
Availability: OpenStep

Returns a C-array of available TIFF compression types.

imageRepWithData: 

+ (id) imageRepWithData: (NSData*)imageData;
Availability: OpenStep

Returns a newly allocated NSBitmapImageRep object representing the image stored in imageData. If the image data contains more than one image, the first one is choosen.

See Also: +imageRepsWithData:


imageRepsWithData: 

+ (NSArray*) imageRepsWithData: (NSData*)imageData;
Availability: OpenStep

Returns an array containing newly allocated NSBitmapImageRep objects representing the images stored in imageData.

See Also: +imageRepWithData:


localizedNameForTIFFCompressionType: 

+ (NSString*) localizedNameForTIFFCompressionType: (NSTIFFCompression)type;
Availability: OpenStep

Returns a localized string describing a TIFF compression type.

representationOfImageRepsInArray: usingType: properties: 

+ (NSData*) representationOfImageRepsInArray: (NSArray*)imageReps usingType: (NSBitmapImageFileType)storageType properties: (NSDictionary*)properties;
Availability: MacOS-X 10.0.0

Returns a data object in the selected format with multiple images.

See Also: -setProperty:withValue: for the options supported in the properties.

FIXME: returns only the first image in the array, and only works for NSBitmapImageRep or subclasses thereof.


TIFFRepresentation 

- (NSData*) TIFFRepresentation;
Availability: OpenStep

Returns an NSData object containing a TIFF representation of the receiver.

TIFFRepresentationUsingCompression: factor: 

- (NSData*) TIFFRepresentationUsingCompression: (NSTIFFCompression)type factor: (float)factor;
Availability: OpenStep

Returns an NSData object containing a TIFF representation of the receiver. The TIFF data is compressed using compresssion type and factor.

bitmapData 

- (unsigned char*) bitmapData;
Availability: OpenStep

Returns the first plane of data representing the image.

bitmapFormat 

- (NSBitmapFormat) bitmapFormat;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

bitsPerPixel 

- (int) bitsPerPixel;
Availability: OpenStep

Returns the number of bits need to contain one pixels worth of data. This is normally the number of samples per pixel times the number of bits in one sample.

bytesPerPlane 

- (int) bytesPerPlane;
Availability: OpenStep

Returns the number of bytes in a plane. This is the number of bytes in a row times tne height of the image.

bytesPerRow 

- (int) bytesPerRow;
Availability: OpenStep

Returns the number of bytes in a row. This is typically based on the width of the image and the bits per sample and samples per pixel (if in medhed configuration). However it may differ from this if set explicitly in -initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel: .

canBeCompressedUsing: 

- (BOOL) canBeCompressedUsing: (NSTIFFCompression)compression;
Availability: OpenStep

Returns YES if the receiver can be stored in a representation compressed using the compression type.

colorAtX: y: 

- (NSColor*) colorAtX: (int)x y: (int)y;
Availability: Not in OpenStep/MacOS-X

Returns an NSColor object representing the color of the pixel (x,y), where (0,0) is the top-left pixel in the image.

colorizeByMappingGray: toColor: blackMapping: whiteMapping: 

- (void) colorizeByMappingGray: (float)midPoint toColor: (NSColor*)midPointColor blackMapping: (NSColor*)shadowColor whiteMapping: (NSColor*)lightColor;
Availability: MacOS-X 10.0.0

Description forthcoming.

getBitmapDataPlanes: 

- (void) getBitmapDataPlanes: (unsigned char**)data;
Availability: OpenStep

Files the array data with pointers to each of the data planes representing the image. The data array must be allocated to contain at least -samplesPerPixel pointers.

getCompression: factor: 

- (void) getCompression: (NSTIFFCompression*)compression factor: (float*)factor;
Availability: OpenStep

Returns the receivers compression and compression factor, which is set either when the image is read in or by -setCompression:factor: . Factor is ignored in many compression schemes. For JPEG compression, factor can be any value from 0 to 255, with 255 being the maximum compression.

getPixel: atX: y: 

- (void) getPixel: (unsigned int[])pixelData atX: (int)x y: (int)y;
Availability: Not in OpenStep/MacOS-X

Returns the values of the components of pixel ( x,y), where (0,0) is the top-left pixel in the image, by storing them in the array pixelData.

incrementalLoadFromData: complete: 

- (int) incrementalLoadFromData: (NSData*)data complete: (BOOL)complete;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

initForIncrementalLoad 

- (id) initForIncrementalLoad;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

initWithBitmapDataPlanes: pixelsWide: pixelsHigh: bitsPerSample: samplesPerPixel: hasAlpha: isPlanar: colorSpaceName: bitmapFormat: bytesPerRow: bitsPerPixel: 

- (id) initWithBitmapDataPlanes: (unsigned char**)planes pixelsWide: (int)width pixelsHigh: (int)height bitsPerSample: (int)bps samplesPerPixel: (int)spp hasAlpha: (BOOL)alpha isPlanar: (BOOL)isPlanar colorSpaceName: (NSString*)colorSpaceName bitmapFormat: (NSBitmapFormat)bitmapFormat bytesPerRow: (int)rowBytes bitsPerPixel: (int)pixelBits;
Availability: Not in OpenStep/MacOS-X

Description forthcoming.

initWithBitmapDataPlanes: pixelsWide: pixelsHigh: bitsPerSample: samplesPerPixel: hasAlpha: isPlanar: colorSpaceName: bytesPerRow: bitsPerPixel: 

- (id) initWithBitmapDataPlanes: (unsigned char**)planes pixelsWide: (int)width pixelsHigh: (int)height bitsPerSample: (int)bitsPerSample samplesPerPixel: (int)samplesPerPixel hasAlpha: (BOOL)alpha isPlanar: (BOOL)isPlanar colorSpaceName: (NSString*)colorSpaceName bytesPerRow: (int)rowBytes bitsPerPixel: (int)pixelBits;
Availability: OpenStep

This is a designated initialiser for the class.

Initializes a newly created NSBitmapImageRep object to hold image data specified in the planes buffer and organized according to the additional arguments passed into the method.

The planes argument is an array of char pointers where each array holds a single component or plane of data. Note that if data is passed into the method via planes, the data is NOT copied and not freed when the object is deallocated. It is assumed that the data will always be available. If planes is NULL, then a suitable amount of memory will be allocated to store the information needed. One can then obtain a pointer to the planes data using the -bitmapData or -getBitmapDataPlanes: method.

Each component of the data is in "standard" order, such as red, green, blue for RGB color images. The transparency component, if these is one, should always be last.

The other arguments to the method consist of:

width and height
The width and height of the image in pixels
bps
The bits per sample or the number of bits used to store a number in one component of one pixel of the image. Typically this is 8 (bits) but can be 2 or 4, although not all values are supported.
spp
Samples per pixel, or the number of components of color in the pixel. For instance this would be 4 for an RGB image with transparency.
alpha
Set to YES if the image has a transparency component.
isPlanar
Set to YES if the data is arranged in planes, i.e. one component per buffer as stored in the planes array. If NO, then the image data is mixed in one buffer. For instance, for RGB data, the first sample would contain red, then next green, then blue, followed by red for the next pixel.
colorSpaceName
This argument specifies how the data values are to be interpreted. Possible values include the typical colorspace names (although not all values are currently supported)
rowBytes
Specifies the number of bytes contained in a single scan line of the data. Normally this can be computed from the width of the image, the samples per pixel and the bits per sample. However, if the data is aligned along word boundaries, this value may differ from this. If rowBytes is 0, the method will calculate the value assuming there are no extra bytes at the end of the scan line.
pixelBits
This is normally bps for planar data and bps times spp for non-planar data, but sometimes images have extra bits. If pixelBits is 0 it will be calculated as described above.

initWithBitmapHandle: 

- (id) initWithBitmapHandle: (void*)bitmap;
Availability: MacOS-X 10.0.0

Description forthcoming.

initWithData: 

- (id) initWithData: (NSData*)imageData;
Availability: OpenStep

Loads only the default (first) image from the image contained in data.

initWithFocusedViewRect: 

- (id) initWithFocusedViewRect: (NSRect)rect;
Availability: OpenStep

Initialize with bitmap data from a rect within the focused view

initWithIconHandle: 

- (id) initWithIconHandle: (void*)icon;
Availability: MacOS-X 10.0.0

Description forthcoming.

isPlanar 

- (BOOL) isPlanar;
Availability: OpenStep

Returns YES if the image components are stored separately. Returns NO if the components are meshed (i.e. all the samples for one pixel come before the next pixel).

numberOfPlanes 

- (int) numberOfPlanes;
Availability: OpenStep

Returns the number of planes in an image. Typically this is equal to the number of samples in a planar image or 1 for a non-planar image.

representationUsingType: properties: 

- (NSData*) representationUsingType: (NSBitmapImageFileType)storageType properties: (NSDictionary*)properties;
Availability: MacOS-X 10.0.0

Returns a data object in one of the supported bitmap graphics file types. A limited set of options may be passed via the properties. If the passed in properties is nil, it falls back to the options set with -setProperty:withValue: . File types not yet implemented return nil and log an error message.

See Also: -setProperty:withValue: for supported options in the properties.


samplesPerPixel 

- (int) samplesPerPixel;
Availability: OpenStep

Returns the number of samples in a pixel. For instance, a normal RGB image with transparency would have a samplesPerPixel of 4.

setColor: atX: y: 

- (void) setColor: (NSColor*)color atX: (int)x y: (int)y;
Availability: Not in OpenStep/MacOS-X

Sets the color of pixel (x,y), where (0,0) is the top-left pixel in the image.

setCompression: factor: 

- (void) setCompression: (NSTIFFCompression)compression factor: (float)factor;
Availability: OpenStep

Description forthcoming.

setPixel: atX: y: 

- (void) setPixel: (unsigned int[])pixelData atX: (int)x y: (int)y;
Availability: Not in OpenStep/MacOS-X

Sets the components of pixel (x,y), where (0,0) is the top-left pixel in the image, to the given array of pixel components.

setProperty: withValue: 

- (void) setProperty: (NSString*)property withValue: (id)value;
Availability: MacOS-X 10.0.0

Properties are key-value pairs associated with the representation. Arbitrary key-value pairs may be set. If the value is nil, the key is erased from properties. There are standard keys that are used to pass information and options related to the standard file types that may be read from or written to. Certain properties are automatically set when reading in image data. Certain properties may be set by the user prior to writing image data in order to set options for the data format.

NSImageCompressionMethod
NSNumber; automatically set when reading TIFF data; writing TIFF data
NSImageCompressionFactor
NSNumber 0.0 to 255.0; writing JPEG data (GNUstep extension: JPEG-compressed TIFFs too)
NSImageProgressive
NSNumber boolean; automatically set when reading JPEG data; writing JPEG data. Note: progressive display is not supported in GNUstep at this time.
NSImageInterlaced
NSNumber boolean; only for writing PNG data
NSImageGamma
NSNumber 0.0 to 1.0; only for reading or writing PNG data
NSImageRGBColorTable
NSData; automatically set when reading GIF data; writing GIF data
NSImageFrameCount
NSNumber integer; automatically set when reading animated GIF data. Not currently implemented.
NSImageCurrentFrame
NSNumber integer; only for animated GIF files. Not currently implemented.
NSImageCurrentFrameDuration
NSNumber float; automatically set when reading animated GIF data
NSImageLoopCount
NSNumber integer; automatically set when reading animated GIF data
NSImageDitherTranparency
NSNumber boolean; only for writing GIF data. Not currently supported.

valueForProperty: 

- (id) valueForProperty: (NSString*)property;
Availability: MacOS-X 10.0.0

Returns the value of a property



Instance Variables for NSBitmapImageRep Class

_bitsPerPixel

@protected unsigned int _bitsPerPixel;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_bytesPerRow

@protected unsigned int _bytesPerRow;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_comp_factor

@protected float _comp_factor;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_compression

@protected unsigned short int _compression;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_format

@protected unsigned int _format;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_imageData

@protected NSMutableData* _imageData;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_imagePlanes

@protected unsigned char** _imagePlanes;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_isPlanar

@protected BOOL _isPlanar;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_numColors

@protected unsigned int _numColors;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_properties

@protected NSMutableDictionary* _properties;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.




Software documentation for the NSBitmapImageRep(GNUstepExtension) category

NSBitmapImageRep(GNUstepExtension)

Declared in:
AppKit/NSBitmapImageRep.h
Availability: OpenStep

Description forthcoming.
Method summary

imageRepsWithFile: 

+ (NSArray*) imageRepsWithFile: (NSString*)filename;
Availability: OpenStep

Description forthcoming.


Up