A bitmap is convertible to 'png-bytes through the file/convertible protocol.

When width and height are provided: Creates a new bitmap. If monochrome? is true, the bitmap is monochrome; if monochrome? is #f and 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 in is provided: Creates a bitmap from a file format, where kind specifies the format. See load-file for details.

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

When a GIF file is loaded with 'gif/mask or '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 'png/mask or '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 'xpm/mask or 'unknown/mask, a mask bitmap is generated to indicate which pixels are set.

When '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 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 draw-bitmap). The mask bitmap is used by save-file when saving a bitmap as '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.

The kind argument specifies the file’s format:

• 'unknown — examine the file to determine its format; creates either a monochrome or color bitmap without an alpha channel

• 'unknown/mask — like 'unknown, but see get-loaded-mask

• 'unknown/alpha — like 'unknown, but if the bitmap is color, it has an alpha channel, and transparency in the image file is recorded in the alpha channel

• 'gif — load a GIF bitmap file, creating a color bitmap

• 'gif/mask — like 'gif, but see get-loaded-mask

• 'gif/alpha — like 'gif, but with an alpha channel

• 'jpeg — load a JPEG bitmap file, creating a color bitmap

• 'jpeg/alpha — like 'jpeg, but with an alpha channel

• 'png — load a PNG bitmap file, creating a color or monochrome bitmap

• 'png/mask — like 'png, but see get-loaded-mask

• 'png/alpha — like 'png, but always color and with an alpha channel

• 'xbm — load an X bitmap (XBM) file; creates a monochrome bitmap

• 'xbm/alpha — like 'xbm, but creates a color bitmap with an alpha channel

• 'xpm — load an XPM bitmap file, creating a color bitmap

• 'xpm/alpha — like 'xpm, but with an alpha channel

• 'bmp — load a Windows bitmap file, creating a color bitmap

• 'bmp/alpha — like '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 bg-color is not #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 'unknown/mask, 'png/mask is specified for the format. If the format is specified as 'unknown or 'png and 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.

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 SCREEN_GAMMA environment variable if it is defined. If the preference and environment variable are both undefined, a platform-specific default is used.

The kind argument determined the type of file that is created, one of:

• 'png — save a PNG file

• 'jpeg — save a JPEG file

• 'xbm — save an X bitmap (XBM) file

• 'xpm — save an XPM bitmap file

• 'bmp — save a Windows bitmap file

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

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