#lang scribble/doc
@(require "common.rkt"
          (for-label (only-in ffi/unsafe cpointer?)))

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

A @racket[bitmap%] object is a pixel-based image, either monochrome,
 color, or color with an alpha channel. See also @racket[make-bitmap],
 @racket[make-platform-bitmap], @racket[make-screen-bitmap] (from
 @racketmodname[racket/gui/base]), @xmethod[canvas% make-bitmap] (from
 @racketmodname[racket/gui/base]), and @secref["Portability"].

A bitmap is convertible to @racket['png-bytes] through the
@racketmodname[file/convertible] protocol.


@defconstructor*/make[(([width exact-positive-integer?]
                        [height exact-positive-integer?]
                        [monochrome? any/c #f]
                        [alpha? any/c #f])
                       ([in (or/c path-string? input-port?)]
                        [kind (or/c 'unknown 'unknown/mask 'unknown/alpha
                                    'gif 'gif/mask 'gif/alpha 
                                    'jpeg 'jpeg/alpha
                                    'png 'png/mask 'png/alpha
                                    'xbm 'xbm/alpha 'xpm 'xpm/alpha
                                    'bmp 'bmp/alpha)
                              'unknown]
                        [bg-color (or/c (is-a?/c color%) #f) #f]
                        [complain-on-failure? any/c #f])
                       ([bits bytes?]
                        [width exact-positive-integer?]
                        [height exact-positive-integer?]))]{

The @racket[make-bitmap], @racket[make-monochrome-bitmap], and
 @racket[read-bitmap] functions create @racket[bitmap%] instances, but
 they are also preferred over using @racket[make-object] 
 with @racket[bitmap%] directly, because the functions are
 less overloaded and they enable alpha channels by default.
 See also @secref["Portability"].
 
When @racket[width] and @racket[height] are provided: Creates a new
 bitmap. If @racket[monochrome?] is true, the bitmap is monochrome; if
 @racket[monochrome?] is @racket[#f] and @racket[alpha?] is true, the
 bitmap has an alpha channel; otherwise, the bitmap is color without
 an alpha channel. The initial content of the bitmap is ``empty'': all white, and with
 zero alpha in the case of a bitmap with an alpha channel.

When @racket[in] is provided: Creates a bitmap from a file format,
 where @racket[kind] specifies the format. See @method[bitmap%
 load-file] for details.

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


}

@defmethod[(get-argb-pixels [x real?]
                            [y real?]
                            [width exact-nonnegative-integer?]
                            [height exact-nonnegative-integer?]
                            [pixels (and/c bytes? (not/c immutable?))]
                            [just-alpha? any/c #f]
                            [pre-multiplied? any/c #f])
           void?]{

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

}

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

Gets the color depth of the bitmap, which is @racket[1] for a
monochrome bitmap and @racket[32] for a color bitmap. See also
@method[bitmap% is-color?].

}


@defmethod[(get-handle) cpointer?]{

Returns a low-level handle to the bitmap content. Currently, on all
platforms, a handle is a @tt{cairo_surface_t}. For a bitmap created
with @racket[make-bitmap], the handle is specifically a Cairo
image surface.}


@defmethod[(get-height)
           exact-positive-integer?]{

Gets the height of the bitmap in pixels.

}

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

Returns a mask bitmap that is stored with this bitmap.

When a GIF file is loaded with @racket['gif/mask] or
 @racket['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 @racket['png/mask] or
 @racket['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).

When an XPM file is loaded with @racket['xpm/mask] or
 @racket['unknown/mask], a mask bitmap is generated to indicate which
 pixels are set.

When @racket['unknown/alpha] and similar modes are used to load a
 bitmap, transparency information is instead represented by an alpha
 channel, not by a mask bitmap.

Unlike an alpha channel, the mask 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 @racket['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)
           exact-positive-integer?]{

Gets the width of the bitmap in pixels.

}

@defmethod[(has-alpha-channel?)
           boolean?]{

Returns @racket[#t] if the bitmap has an alpha channel,
@racket[#f] otherwise.

}

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

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

}

@defmethod[(load-file [in (or/c path-string? input-port?)]
                      [kind (or/c 'unknown 'unknown/mask 'unknown/alpha
                                  'gif 'gif/mask 'gif/alpha 
                                  'jpeg 'jpeg/alpha
                                  'png 'png/mask 'png/alpha
                                  'xbm 'xbm/alpha 'xpm 'xpm/alpha
                                  'bmp 'bmp/alpha)
                            'unknown]
                      [bg-color (or/c (is-a?/c color%) #f) #f]
                      [complain-on-failure? any/c #f])
           boolean?]{

Loads a bitmap from a file format that read from @racket[in], unless
 the bitmap was produced by @racket[make-platform-bitmap], @racket[make-screen-bitmap],
 or @xmethod[canvas% make-bitmap] (in which case @|MismatchExn|).
 If the bitmap is in use by a
 @racket[bitmap-dc%] object or a control, the image data is not
 loaded. The bitmap changes its size and depth to match that of 
 the loaded image. If an error is encountered when reading the file format,
 an exception is raised only if @racket[complain-on-failure?] is true (which is
 @emph{not} the default).

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

@itemize[

@item{@racket['unknown] --- examine the file to determine its format; creates
  either a monochrome or color bitmap without an alpha channel}
@item{@racket['unknown/mask] --- like @racket['unknown], but see
  @method[bitmap% get-loaded-mask]}
@item{@racket['unknown/alpha] --- like @racket['unknown], but if the bitmap is
  color, it has an alpha channel, and transparency in the image file is
  recorded in the alpha channel}
@item{@racket['gif] --- load a @as-index{GIF} bitmap file, creating a color
  bitmap}
@item{@racket['gif/mask] --- like @racket['gif], but see
  @method[bitmap% get-loaded-mask]}
@item{@racket['gif/alpha] --- like @racket['gif], but with an alpha channel}
@item{@racket['jpeg] --- load a @as-index{JPEG} bitmap file, creating a color
  bitmap}
@item{@racket['jpeg/alpha] --- like @racket['jpeg], but with an alpha channel}
@item{@racket['png] --- load a @as-index{PNG} bitmap file, creating a color or
  monochrome bitmap}
@item{@racket['png/mask] --- like @racket['png], but see
  @method[bitmap% get-loaded-mask]}
@item{@racket['png/alpha] --- like @racket['png], but always color and with an
  alpha channel}
@item{@racket['xbm] --- load an X bitmap (@as-index{XBM}) file; creates a
  monochrome bitmap}
@item{@racket['xbm/alpha] --- like @racket['xbm], but creates a color bitmap
  with an alpha channel}
@item{@racket['xpm] --- load an @as-index{XPM} bitmap file, creating a color
  bitmap}
@item{@racket['xpm/alpha] --- like @racket['xpm], but with an alpha channel}
@item{@racket['bmp] --- load a Windows bitmap file, creating a color bitmap}
@item{@racket['bmp/alpha] --- like @racket['bmp], but with an alpha channel}
]

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
 color bitmap.

For PNG loading, if @racket[bg-color] is not @racket[#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 and the
 alpha channel fills the bitmap, even if @racket['unknown/mask],
 @racket['png/mask] is specified for the format. If the format is
 specified as @racket['unknown] or @racket['png] and @racket[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 @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[(make-dc)
           boolean?]{

Return @racket[(make-object bitmap-dc% this)].}


@defmethod[(ok?)
           boolean?]{

Returns @racket[#t] if the bitmap is valid in the sense that an image
 file was loaded successfully. If @method[bitmap% ok?] returns
 @racket[#f], then drawing to or from the bitmap has no effect.

}


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

Writes a bitmap to the named file or output stream.

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

@itemize[

 @item{@racket['png] --- save a @as-index{PNG} file}

 @item{@racket['jpeg] --- save a @as-index{JPEG} file}

 @item{@racket['xbm] --- save an X bitmap (@as-index{XBM}) file}

 @item{@racket['xpm] --- save an @as-index{XPM} bitmap file}

 @item{@racket['bmp] --- save a Windows bitmap file}

]

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

When saving as @racket['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 @racket['png] without a mask bitmap
 produces a 1-bit grayscale PNG file (which, when read with
 @method[bitmap% load-file], creates a monochrome @racket[bitmap%]
 object.)

}

@defmethod[(set-argb-pixels [x real?]
                            [y real?]
                            [width exact-nonnegative-integer?]
                            [height exact-nonnegative-integer?]
                            [pixels bytes?]
                            [just-alpha? any/c #f]
                            [pre-multiplied? any/c #f])
           void?]{

The same as @xmethod[bitmap-dc% set-argb-pixels], but the
bitmap does not have to be selected into the DC.

}

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

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

}}