<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.0//EN" "http://www.gnustep.org/gsdoc-1_0_0.xml">
<gsdoc base="NSBitmapImageRep" up="Gui">
  <head>
    <title>NSBitmapImageRep.m</title>
    <author name="Adam Fedor">
      <email address="fedor@gnu.org">
        fedor@gnu.org
      </email>
    </author>
    <abstract>Bitmap image representation.</abstract>
    <copy>1996 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>Class Description</heading>
      <p>
        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.
      </p>
      <class name="NSBitmapImageRep" super="NSImageRep">
        <declared>AppKit/NSBitmapImageRep.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="NSData*" factory="yes">
          <sel>TIFFRepresentationOfImageRepsInArray:</sel>
          <arg type="NSArray*">anArray</arg>
          <desc>
            Produces an NSData object containing a TIFF
            representation of all the images stored in
            <var>anArray</var>. BUGS: Currently this only works
            if the images are NSBitmapImageRep objects, and it only
            creates an TIFF from the first image in the array.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSData*" factory="yes">
          <sel>TIFFRepresentationOfImageRepsInArray:</sel>
          <arg type="NSArray*">anArray</arg>
          <sel>usingCompression:</sel>
          <arg type="NSTIFFCompression">type</arg>
          <sel>factor:</sel>
          <arg type="float">factor</arg>
          <desc>
            Produces an NSData object containing a TIFF
            representation of all the images stored in
            <var>anArray</var>. The image is compressed according
            to the compression <var>type</var> and <var>factor</var>
            . BUGS: Currently this only works if the images are
            NSBitmapImageRep objects, and it only
            creates an TIFF from the first image in the array.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void" factory="yes">
          <sel>getTIFFCompressionTypes:</sel>
          <arg type="const NSTIFFCompression**">list</arg>
          <sel>count:</sel>
          <arg type="int*">numTypes</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id" factory="yes">
          <sel>imageRepWithData:</sel>
          <arg type="NSData*">imageData</arg>
          <desc>
            Returns a newly allocated NSBitmapImageRep object
            representing the image stored in
            <var>imageData</var>. If the image data contains more
            than one image, the first one is choosen.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSArray*" factory="yes">
          <sel>imageRepsWithData:</sel>
          <arg type="NSData*">imageData</arg>
          <desc>
            Returns an array containing newly allocated
            NSBitmapImageRep objects representing the
            images stored in <var>imageData</var>.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSString*" factory="yes">
          <sel>localizedNameForTIFFCompressionType:</sel>
          <arg type="NSTIFFCompression">type</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSData*" factory="yes">
          <sel>representationOfImageRepsInArray:</sel>
          <arg type="NSArray*">imageReps</arg>
          <sel>usingType:</sel>
          <arg type="NSBitmapImageFileType">storageType</arg>
          <sel>properties:</sel>
          <arg type="NSDictionary*">properties</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSData*">
          <sel>TIFFRepresentation</sel>
          <desc>
            Returns an NSData object containing a TIFF
            representation of the receiver.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSData*">
          <sel>TIFFRepresentationUsingCompression:</sel>
          <arg type="NSTIFFCompression">type</arg>
          <sel>factor:</sel>
          <arg type="float">factor</arg>
          <desc>
            Returns an NSData object containing a TIFF
            representation of the receiver. The TIFF
            data is compressed using compresssion <var>type</var>
            and <var>factor</var>.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="unsigned char*">
          <sel>bitmapData</sel>
          <desc>
            Returns the first plane of data representing the
            image.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>bitsPerPixel</sel>
          <desc>
            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.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>bytesPerPlane</sel>
          <desc>
            Returns the number of bytes in a plane. This is the
            number of bytes in a row times tne height of the
            image.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>bytesPerRow</sel>
          <desc>
            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
            <ref type="method" id="-initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:">-initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:</ref>.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>canBeCompressedUsing:</sel>
          <arg type="NSTIFFCompression">compression</arg>
          <desc>
            Returns <code>YES</code> if the receiver can be
            stored in a representation compressed using the
            <var>compression</var> type.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>colorizeByMappingGray:</sel>
          <arg type="float">midPoint</arg>
          <sel>toColor:</sel>
          <arg type="NSColor*">midPointColor</arg>
          <sel>blackMapping:</sel>
          <arg type="NSColor*">shadowColor</arg>
          <sel>whiteMapping:</sel>
          <arg type="NSColor*">lightColor</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>getBitmapDataPlanes:</sel>
          <arg type="unsigned char**">data</arg>
          <desc>
            Files the array <var>data</var> with pointers to each
            of the <var>data</var> planes representing the image.
            The <var>data</var> array must be allocated to contain
            at least
            <ref type="method" id="-samplesPerPixel">
              -samplesPerPixel
            </ref>
            pointers.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>getCompression:</sel>
          <arg type="NSTIFFCompression*">compression</arg>
          <sel>factor:</sel>
          <arg type="float*">factor</arg>
          <desc>
            Returns the receivers <var>compression</var> and
            <var>compression</var> <var>factor</var>, which is
            set either when the image is read in or by
            <ref type="method" id="-setCompression:factor:">
              -setCompression:factor:
            </ref>
            . Factor is ignored in many <var>compression</var>
            schemes. For JPEG <var>compression</var>,
            <var>factor</var> can be any value from 0 to 255,
            with 255 being the maximum <var>compression</var>.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id" init="yes">
          <sel>initWithBitmapDataPlanes:</sel>
          <arg type="unsigned char**">planes</arg>
          <sel>pixelsWide:</sel>
          <arg type="int">width</arg>
          <sel>pixelsHigh:</sel>
          <arg type="int">height</arg>
          <sel>bitsPerSample:</sel>
          <arg type="int">bps</arg>
          <sel>samplesPerPixel:</sel>
          <arg type="int">spp</arg>
          <sel>hasAlpha:</sel>
          <arg type="BOOL">alpha</arg>
          <sel>isPlanar:</sel>
          <arg type="BOOL">isPlanar</arg>
          <sel>colorSpaceName:</sel>
          <arg type="NSString*">colorSpaceName</arg>
          <sel>bytesPerRow:</sel>
          <arg type="int">rowBytes</arg>
          <sel>bitsPerPixel:</sel>
          <arg type="int">pixelBits</arg>
          <desc>
            <p>
              Initializes a newly created NSBitmapImageRep
              object to hold image data specified in the
              <var>planes</var> buffer and organized according to
              the additional arguments passed into the method.
            </p>
            <p>
              The <var>planes</var> 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 <var>planes</var>, the
              data is NOT copied and not freed when the object is
              deallocated. It is assumed that the data
              will always be available. If <var>planes</var> is
              NULL, then a suitable amount of memory will be
              allocated to store the information needed. One
              can then obtain a pointer to the <var>planes</var>
              data using the
              <ref type="method" id="-bitmapData">
                -bitmapData
              </ref>
              or
              <ref type="method" id="-getBitmapDataPlanes:">
                -getBitmapDataPlanes:
              </ref>
              method.
            </p>
            <p>
              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.
            </p>
            <p>The other arguments to the method consist of:</p>
            <deflist>
              <term>
                <var>width</var> and <var>height</var>
              </term>
              <desc>
                The <var>width</var> and <var>height</var> of the
                image in pixels
              </desc>
              <term><var>bps</var></term>
              <desc>
                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.
              </desc>
              <term><var>spp</var></term>
              <desc>
                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.
              </desc>
              <term><var>alpha</var></term>
              <desc>
                Set to <code>YES</code> if the image has a
                transparency component.
              </desc>
              <term><var>isPlanar</var></term>
              <desc>
                Set to <code>YES</code> if the data is arranged in
                <var>planes</var>, i.e. one component per buffer
                as stored in the <var>planes</var> array. If
                <code>NO</code>, 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.
              </desc>
              <term><var>colorSpaceName</var></term>
              <desc>
                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)
              </desc>
              <term><var>rowBytes</var></term>
              <desc>
                Specifies the number of bytes contained in a
                single scan line of the data. Normally this can
                be computed from the <var>width</var> 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 <var>rowBytes</var> is 0, the method
                will calculate the value assuming there are no
                extra bytes at the end of the scan line.
              </desc>
              <term><var>pixelBits</var></term>
              <desc>
                This is normally <var>bps</var> for planar data
                and <var>bps</var> times <var>spp</var> for
                non-planar data, but sometimes images have
                extra bits. If <var>pixelBits</var> is 0 it will
                be calculated as described above.
              </desc>
            </deflist>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id">
          <sel>initWithBitmapHandle:</sel>
          <arg type="void*">bitmap</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id">
          <sel>initWithData:</sel>
          <arg type="NSData*">imageData</arg>
          <desc>
            Loads only the default (first) image from the TIFF
            image contained in data.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id">
          <sel>initWithFocusedViewRect:</sel>
          <arg type="NSRect">rect</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id">
          <sel>initWithIconHandle:</sel>
          <arg type="void*">icon</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="BOOL">
          <sel>isPlanar</sel>
          <desc>
            Returns <code>YES</code> if the image components
            are stored separately. Returns <code>NO</code> if the
            components are meshed (i.e. all the samples for
            one pixel come before the next pixel).
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>numberOfPlanes</sel>
          <desc>
            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.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="NSData*">
          <sel>representationUsingType:</sel>
          <arg type="NSBitmapImageFileType">storageType</arg>
          <sel>properties:</sel>
          <arg type="NSDictionary*">properties</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="int">
          <sel>samplesPerPixel</sel>
          <desc>
            Returns the number of samples in a pixel. For
            instance, a normal RGB image with transparency
            would have a samplesPerPixel of 4.
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setCompression:</sel>
          <arg type="NSTIFFCompression">compression</arg>
          <sel>factor:</sel>
          <arg type="float">factor</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="void">
          <sel>setProperty:</sel>
          <arg type="NSString*">property</arg>
          <sel>withValue:</sel>
          <arg type="id">value</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <method type="id">
          <sel>valueForProperty:</sel>
          <arg type="NSString*">property</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <NotOpenStep /> <GNUstep />
          </standards>
        </method>
        <standards>
          <MacOS-X /> <OpenStep /> <GNUstep />
        </standards>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the
        NSBitmapImageRep(GNUstepExtension)
        category
      </heading>
      <category name="GNUstepExtension" class="NSBitmapImageRep">
        <declared>AppKit/NSBitmapImageRep.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="NSArray*" factory="yes">
          <sel>imageRepsWithFile:</sel>
          <arg type="NSString*">filename</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
          <standards>
            <MacOS-X /> <OpenStep /> <GNUstep />
          </standards>
        </method>
        <standards>
          <MacOS-X /> <OpenStep /> <GNUstep />
        </standards>
      </category>
    </chapter>
  </body>
</gsdoc>
