#lang scribble/doc
@require["common.ss"]

@defclass/title[bitmap% object% ()]{

A @scheme[bitmap%] object is a pixel-based image, either
 monochrome or color.

Sometimes, a bitmap object creation fails in a low-level manner. In
 that case, the @method[bitmap% ok?] method returns @scheme[#f], and
 the bitmap cannot be supplied to methods that consume or operate on
 bitmaps (otherwise, @|MismatchExn|).


@defconstructor*/make[(([width (integer-in 1 10000)]
                        [height (integer-in 1 10000)]
                        [monochrome? any/c #f])
                       ([filename path-string?]
                        [kind (one-of/c 'unknown 'unknown/mask 
                                        'gif 'gif/mask 'jpeg 'png 'png/mask 
                                        'xbm 'xpm 'bmp 'pict)
                              'unknown]
                        [bg-color (or/c (is-a?/c color%) false/c) #f])
                       ([bits bytes?]
                        [width (integer-in 1 10000)]
                        [height (integer-in 1 10000)]))]{

When @scheme[with] and @scheme[height] are provided: Creates a new
 bitmap. If @scheme[monochrome?] is @scheme[#f], the bitmap matches
 the display depth of the screen. The initial content of the bitmap is
 undefined.

When @scheme[filename] is provided: Creates a bitmap from a file,
 where @scheme[kind] specifies the kind of image file. See
 @method[bitmap% load-file] for details.


When a @scheme[bits] byte string is provided: Creates a monochrome
 bitmap from an array of bit values, where each byte in @scheme[bits]
 specifies eight bits, and padding bits are added so that each bitmap
 line starts on a character boundary. A @scheme[1] bit value indicates
 black, and @scheme[0] indicates white. If @scheme[width] times
 @scheme[height] is larger than 8 times the length of @scheme[bits],
 @|MismatchExn|.


}

@defmethod[(get-argb-pixels [x real?]
                            [y real?]
                            [width (integer-in 1 10000)]
                            [height (integer-in 1 10000)]
                            [pixels (and/c byte-string? mutable?)]
                            [alpha? any/c @scheme[#f]])
           void?]{

Produces the same result as @xmethod[bitmap-dc% get-pixel] with the
bitmap selected into the DC, but the bitmap does not have to be
selected anywhere (and this method works even if the bitmap is
selected into another DC, attached as a button label, etc.).

}

@defmethod[(get-depth)
           nonnegative-exact-integer?]{

Gets the color depth of the bitmap. See also @method[bitmap%
is-color?].

}

@defmethod[(get-gl-config [config (is-a?/c gl-config%)])
           void?]{

Returns a copy of this bitmap's requested OpenGL configuration. See
 also @method[bitmap% set-gl-config].

}

@defmethod[(get-height)
           (integer-in 1 10000)]{

Gets the height of the bitmap in pixels.

}

@defmethod[(get-loaded-mask)
           (or/c (is-a?/c bitmap%) false/c)]{

Returns a mask bitmap that is stored with this bitmap.

When a GIF file is loaded with @scheme['gif/mask] or
 @scheme['unknown/mask] and the file contains a transparent ``color,''
 a mask bitmap is generated to identify the transparent pixels. The
 mask bitmap is monochrome, with white pixels where the loaded bitmap
 is transparent and black pixels everywhere else.

When a PNG file is loaded with @scheme['png/mask] or
 @scheme['unknown/mask] and the file contains a mask or alpha channel,
 a mask bitmap is generated to identify the mask or alpha channel.  If
 the file contains a mask or an alpha channel with only extreme
 values, the mask bitmap is monochrome, otherwise it is grayscale
 (representing the alpha channel inverted).

The mast bitmap is @italic{not} used automatically by drawing
 routines. The mask bitmap can be extracted and supplied explicitly as
 a mask (e.g., as the sixth argument to @method[dc<%>
 draw-bitmap]). The mask bitmap is used by @method[bitmap% save-file]
 when saving a bitmap as @scheme['png] if the mask has the same
 dimensions as the saved bitmap. The mask bitmap is also used
 automatically when the bitmap is a control label.

}

@defmethod[(get-width)
           (integer-in 1 10000)]{

Gets the width of the bitmap in pixels.

}

@defmethod[(is-color?)
           boolean?]{

Returns @scheme[#f] if the bitmap is monochrome, @scheme[#t] otherwise.

}

@defmethod[(load-file [name pat-string?]
                      [kind (one-of/c 'unknown 'unknown/mask 
                                      'gif 'gif/mask 'jpeg 'png 'png/mask 
                                      'xbm 'xpm 'bmp 'pict)
                            'unknown]
                      [bg-color (or/c (is-a?/c color%) false/c) #f])
           boolean?]{

Loads a bitmap from a file. If the bitmap is in use by a
 @scheme[bitmap-dc%] object or a control, the bitmap file is not
 loaded. The bitmap changes its size and depth to match that of 
 the loaded image.

The @scheme[kind] argument specifies the file's format:

@itemize{
@item{@scheme['unknown] --- examine the file to determine its format}
@item{@scheme['unknown/mask] --- like @scheme['unknown], but see @method[bitmap% get-loaded-mask]}
@item{@scheme['gif] --- load a GIF bitmap file (X, Windows, Mac OS X)}
@item{@scheme['gif/mask] --- like @scheme['gif], but see @method[bitmap% get-loaded-mask] (X, Windows, Mac OS X)}
@item{@scheme['jpeg] --- load a JPEG bitmap file (X, Windows, Mac OS X)}
@item{@scheme['png] --- load a PNG bitmap file (X, Windows, Mac OS X)}
@item{@scheme['png/mask] --- like @scheme['png], but see @method[bitmap% get-loaded-mask] (X, Windows, Mac OS X)}
@item{@scheme['xbm] --- load an X bitmap file (X, Windows, Mac OS X); creates a monochrome bitmap}
@item{@scheme['xpm] --- load an XPM bitmap file (X, Windows, Mac OS X)}
@item{@scheme['bmp] --- load a Windows bitmap file (X, Windows, Mac OS X)}
@item{@scheme['pict] --- load a PICT bitmap file (Mac OS X)}
}

An XBM image is always loaded as a monochrome bitmap. A 1-bit
 grayscale PNG without a mask or alpha channel is also loaded as a
 monochrome bitmap. An image in any other format is always loaded as a
 bitmap that matches the depth of the screen.

For PNG loading, if @scheme[bg-color] is not @scheme[#f], then it is
 combined with the file's alpha channel or mask (if any) while loading
 the image; in this case, no separate mask bitmap is generated, even
 if @scheme['unknown/mask] or @scheme['png/mask] is specified for the
 format. If the format is specified as @scheme['unknown] or
 @scheme['png] and @scheme[bg-color] is not specified, the PNG file is
 consulted for a background color to use for loading, and white is
 used if no background color is indicated in the file.

@index["gamma correction"]{In} all PNG-loading modes, gamma correction
 is applied when the file provides a gamma value, otherwise gamma
 correction is not applied. The current display's gamma factor is
 determined by the @ResourceFirst{gamma} (see @|mrprefsdiscuss|) if it
 is set, or else by the @indexed-envvar{SCREEN_GAMMA} environment
 variable if it is defined. If the preference and environment variable
 are both undefined, a platform-specific default is used.

}

@defmethod[(ok?)
           boolean?]{

Returns @scheme[#t] if the bitmap is usable (created or changed
 successfully). If @scheme[#f] is returned, the bitmap cannot be
 supplied to methods that consume or operate on bitmaps (otherwise,
 @|MismatchExn|).

}

@defmethod[(save-file [name pat-string?]
                      [kind (one-of/c 'png 'jpeg 'xbm 'xpm 'bmp)]
                      [quality (integer-in 0 100) 75])
           boolean?]{

Saves a bitmap in the named file.

The @scheme[kind] argument determined the type of file that is created,
 one of:

@itemize{

 @item{@scheme['png] --- save a PNG file (X, Windows, Mac OS X)}

 @item{@scheme['jpeg] --- save a JPEG file (X, Windows, Mac OS X)}

 @item{@scheme['xbm] --- save an X bitmap file (X, Windows, Mac OS X)}

 @item{@scheme['xpm] --- save an XPM bitmap file (X, Windows, Mac OS X)}

 @item{@scheme['bmp] --- save a Windows bitmap file (Windows)}

}

The @scheme[quality] argument is used only for saving as @scheme['jpeg], in
 which case it specifies the trade-off between image precision (high
 quality matches the content of the @scheme[bitmap%] object more
 precisely) and size (low quality is smaller).

When saving as @scheme['png], if @method[bitmap% get-loaded-mask]
returns a bitmap of the same size as this one, a grayscale version is
included in the PNG file as the alpha channel.

A monochrome bitmap saved as @scheme['png] without a mask bitmap
 produces a 1-bit grayscale PNG file (which , when read with
 @method[bitmap% load-file], creates a monochrome @scheme[bitmap%]
 object.)

}

@defmethod[(set-gl-config [config (is-a?/c gl-config%)])
           void?]{

Sets the requested OpenGL configuration for this bitmap. The
 configuration is used when the bitmap selected into a drawing
 context, and then a GL context is created for the drawing context.

The given @scheme[gl-config%] object is copied, so that changes to
 the object do not affect the bitmap's configuration.

}

@defmethod[(set-loaded-mask [mask (or/c (is-a?/c bitmap%) false/c)])
           void?]{

See @method[bitmap% get-loaded-mask].

}}