2.3 Drawing Classes
2.3.1 bitmap%
2.3.2 bitmap-dc%
2.3.3 brush%
2.3.4 brush-list%
2.3.5 color%
2.3.6 color-database<%>
2.3.7 dc<%>
2.3.8 dc-path%
2.3.9 font%
2.3.10 font-list%
2.3.11 font-name-directory<%>
2.3.12 gl-config%
2.3.13 gl-context<%>
2.3.14 pen%
2.3.15 pen-list%
2.3.16 point%
2.3.17 post-script-dc%
2.3.18 printer-dc%
2.3.19 ps-setup%
2.3.20 region%
On this page:
get-argb-pixels
get-depth
get-gl-config
get-height
get-loaded-mask
get-width
is-color?
load-file
ok?
save-file
set-gl-config
set-loaded-mask

bitmap% : class?

  superclass: object%

A 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 ok? method returns #f, and the bitmap cannot be supplied to methods that consume or operate on bitmaps (otherwise, an exn:fail:contract exception is raised).

(make-object bitmap% width    
  height    
  [monochrome?])  (is-a?/c bitmap%)
  width : (integer-in 1 10000)
  height : (integer-in 1 10000)
  monochrome? : any/c = #f
(make-object bitmap% filename [kind bg-color])  (is-a?/c bitmap%)
  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
(make-object bitmap% bits width height)  (is-a?/c bitmap%)
  bits : bytes?
  width : (integer-in 1 10000)
  height : (integer-in 1 10000)
When width and height are provided: Creates a new bitmap. If monochrome? is #f, the bitmap matches the display depth of the screen. The initial content of the bitmap is undefined.

When filename is provided: Creates a bitmap from a file, where kind specifies the kind of image file. 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.

(send a-bitmap get-argb-pixels x    
  y    
  width    
  height    
  pixels    
  [alpha?])  void?
  x : real?
  y : real?
  width : (integer-in 1 10000)
  height : (integer-in 1 10000)
  pixels : (and/c bytes? mutable?)
  alpha? : any/c = #f
Produces the same result as get-argb-pixels in bitmap-dc%, 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.).

Gets the color depth of the bitmap. See also is-color?.

(send a-bitmap get-gl-config config)  void?
  config : (is-a?/c gl-config%)
Returns a copy of this bitmap’s requested OpenGL configuration. See also set-gl-config.

(send a-bitmap get-height)  (integer-in 1 10000)
Gets the height of the bitmap in pixels.

(send a-bitmap 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 '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).

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.

(send a-bitmap get-width)  (integer-in 1 10000)
Gets the width of the bitmap in pixels.

(send a-bitmap is-color?)  boolean?
Returns #f if the bitmap is monochrome, #t otherwise.

(send a-bitmap load-file name [kind bg-color])  boolean?
  name : 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
Loads a bitmap from a file. If the bitmap is in use by a 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 kind argument specifies the file’s format:

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 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, even if 'unknown/mask or '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 'GRacket:gamma preference (see Preferences) if it is set, or else 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.

(send a-bitmap ok?)  boolean?
Returns #t if the bitmap is usable (created or changed successfully). If #f is returned, the bitmap cannot be supplied to methods that consume or operate on bitmaps (otherwise, an exn:fail:contract exception is raised).

(send a-bitmap save-file name kind [quality])  boolean?
  name : path-string?
  kind : (one-of/c 'png 'jpeg 'xbm 'xpm 'bmp)
  quality : (integer-in 0 100) = 75
Saves a bitmap in the named file.

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

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.)

(send a-bitmap set-gl-config config)  void?
  config : (is-a?/c gl-config%)
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 gl-config% object is copied, so that changes to the object do not affect the bitmap’s configuration.

(send a-bitmap set-loaded-mask mask)  void?
  mask : (is-a?/c bitmap%)