<commit_before>#lang scribble/doc
@(require "common.rkt")

@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-screen-bitmap] and @xmethod[canvas% make-bitmap].

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 (one-of/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%) false/c) #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 are preferred over using
 @racket[make-object] with @racket[bitmap%], because the functions are
 less overloaded and they enable alpha channels by default.

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-height)
           exact-positive-integer?]{

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 @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[(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 (one-of/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%) false/c) #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-screen-bitmap] or 
 @xmethod[canvas% make-bitmap] (in which case @|MismatchExn|).
 If the bitmap is in use by a<commit_msg>doc `has-alpha-channel?' method<commit_after>#lang scribble/doc
@(require "common.rkt")

@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-screen-bitmap] and @xmethod[canvas% make-bitmap].

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 (one-of/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%) false/c) #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 are preferred over using
 @racket[make-object] with @racket[bitmap%], because the functions are
 less overloaded and they enable alpha channels by default.

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-height)
           exact-positive-integer?]{

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 @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 (one-of/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%) false/c) #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-screen-bitmap] or 
 @xmethod[canvas% make-bitmap] (in which case @|MismatchExn|).
 If the bitmap is in use by a
{'fraction_non_alphanumeric': 0.09634760705289673, 'fraction_numerical': 0.0009445843828715365, 'mean_word_length': 2.276173285198556, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 36, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '664539', 'n_tokens_mistral': 3597, 'n_tokens_neox': 3534, 'n_words': 1386}