On this page:
make-object
get-argb-pixels
get-backing-scale
get-data-from-file
get-depth
get-handle
get-height
get-loaded-mask
get-width
has-alpha-channel?
is-color?
load-file
make-dc
ok?
save-file
set-argb-pixels
set-loaded-mask

class

bitmap% : class?

  superclass: object%

A bitmap% object is a pixel-based image, either monochrome, color, or color with an alpha channel. See also make-bitmap, make-platform-bitmap, make-screen-bitmap (from racket/gui/base), make-bitmap in canvas% (from racket/gui/base), and Portability and Bitmap Variants.

A bitmap has a backing scale, which is the number of pixels that correspond to a drawing unit for the bitmap, either when the bitmap is used as a target for drawing or when the bitmap is drawn into another context. For example, on Mac OS when the main monitor is in Retina mode, make-screen-bitmap returns a bitmap whose backing scale is 2.0. On Windows and Unix, the backing scale of a screen bitmap corresponds to the system-wide text scale (see Screen Resolution and Text Scaling). A monochrome bitmap always has a backing scale of 1.0.

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

constructor

(make-object bitmap% width    
  height    
  [monochrome?    
  alpha?    
  backing-scale])  (is-a?/c bitmap%)
  width : exact-positive-integer?
  height : exact-positive-integer?
  monochrome? : any/c = #f
  alpha? : any/c = #f
  backing-scale : (>/c 0.0) = 1.0
(make-object bitmap% in    
  [kind    
  bg-color    
  complain-on-failure?    
  backing-scale    
  save-data-from-file?])  (is-a?/c bitmap%)
  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
  backing-scale : (>/c 0.0) = 1.0
  save-data-from-file? : any/c = #f
(make-object bitmap% bits width height)  (is-a?/c bitmap%)
  bits : bytes?
  width : exact-positive-integer?
  height : exact-positive-integer?
The make-bitmap, make-monochrome-bitmap, and read-bitmap functions create bitmap% instances, but they are also preferred over using make-object with bitmap% directly, because the functions are less overloaded and they enable alpha channels by default. See also Portability and Bitmap Variants.

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 backing-scale argument sets the bitmap’s backing scale, and it must be 1.0 if monochrome is true. 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. The backing-scale argument sets the bitmap’s backing scale, so that the bitmap’s size (as reported by get-width and get-height) is the ceiling of the bitmap’s size from in divided by backing-scale; the backing scale must be 1.0 if the bitmap is monochrome or loaded with a mask.

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.

See get-data-from-file for information on save-data-from-file?

Changed in version 1.1 of package draw-lib: Added the backing-scale optional arguments.
Changed in version 1.17: Added save-data-from-file?

method

(send a-bitmap get-argb-pixels x    
  y    
  width    
  height    
  pixels    
  [just-alpha?    
  pre-multiplied?    
  #:unscaled? unscaled?])  void?
  x : exact-nonnegative-integer?
  y : exact-nonnegative-integer?
  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
  unscaled? : any/c = #f
Produces the same result as get-argb-pixels in bitmap-dc% when unscaled? is #f, 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.).

If the bitmap has a backing scale other than 1.0 and unscaled? is true, then the result corresponds to the bitmap’s pixels ignoring the backing scale. In that case, x, y, width, and height are effectively in pixels instead of drawing units.

Changed in version 1.1 of package draw-lib: Added the #:unscaled? optional argument.

method

(send a-bitmap get-backing-scale)  (>/c 0.0)

Returns the bitmap’s backing scale.

Added in version 1.1 of package draw-lib.

method

(send a-bitmap get-data-from-file)

  
(or/c (vector/c (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)
                (or/c (is-a?/c color%) #f)
                (and/c bytes? immutable?)
                #:immutable? #t)
      #f)
If the bitmap data in this bitmap was read from a file and the save-data-from-file? was passed with a true value when it was read (either in the constructor or in load-file), then this method returns the contents of the loaded file as bytes. Otherwise, it returns #f.

Added in version 1.17 of package draw-lib.

method

(send a-bitmap get-depth)  exact-nonnegative-integer?

Gets the color depth of the bitmap, which is 1 for a monochrome bitmap and 32 for a color bitmap. See also is-color?.

method

(send a-bitmap get-handle)  cpointer?

Returns a low-level handle to the bitmap content. Currently, on all platforms, a handle is a cairo_surface_t. For a bitmap created with make-bitmap, the handle is specifically a Cairo image surface.

method

(send a-bitmap get-height)  exact-positive-integer?

Gets the height of the bitmap in drawing units (which is the same as pixels if the backing scale is 1.0).

method

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

method

(send a-bitmap get-width)  exact-positive-integer?

Gets the width of the bitmap in drawing units (which is the same as pixels of the backing scale is 1.0).

method

(send a-bitmap has-alpha-channel?)  boolean?

Returns #t if the bitmap has an alpha channel, #f otherwise.

method

(send a-bitmap is-color?)  boolean?

Returns #f if the bitmap is monochrome, #t otherwise.

method

(send a-bitmap load-file 
  in 
  [kind 
  bg-color 
  complain-on-failure? 
  #:save-data-from-file? save-data-from-file?]) 
  boolean?
  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
  save-data-from-file? : any/c = #f
Loads a bitmap from a file format that read from in, unless the bitmap was produced by make-platform-bitmap, make-screen-bitmap, or make-bitmap in canvas% (in which case an exn:fail:contract exception is raised). If the bitmap is in use by a 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 complain-on-failure? is true (which is not the default).

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

For PNG and BMP 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.

After a bitmap is created, load-file can be used only if the bitmap’s backing scale is 1.0.

See get-data-from-file for information on save-data-from-file?

Changed in version 1.17 of package draw-lib: Added save-data-from-file?

method

(send a-bitmap make-dc)  (is-a?/c bitmap-dc%)

method

(send a-bitmap ok?)  boolean?

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

method

(send a-bitmap save-file name    
  kind    
  [quality    
  #:unscaled? unscaled?])  boolean?
  name : (or/c path-string? output-port?)
  kind : (or/c 'png 'jpeg 'xbm 'xpm 'bmp)
  quality : (integer-in 0 100) = 75
  unscaled? : any/c = #f
Writes a bitmap to the named file or output stream.

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

If the bitmap has a backing scale other than 1.0, then it is effectively converted to a single pixel per drawing unit before saving unless unscaled? is true.

Changed in version 1.1 of package draw-lib: Added the #:unscaled? optional argument.

method

(send a-bitmap set-argb-pixels x    
  y    
  width    
  height    
  pixels    
  [just-alpha?    
  pre-multiplied?    
  #:unscaled? unscaled?])  void?
  x : real?
  y : real?
  width : exact-nonnegative-integer?
  height : exact-nonnegative-integer?
  pixels : bytes?
  just-alpha? : any/c = #f
  pre-multiplied? : any/c = #f
  unscaled? : any/c = #f
The same as set-argb-pixels in bitmap-dc% when unscaled? is #f, but the bitmap does not have to be selected into the DC.

If the bitmap has a backing scale other than 1.0 and unscaled? is true, then pixel values are installed ignoring the backing scale. In that case, x, y, width, and height are effectively in pixels instead of drawing units.

Changed in version 1.1 of package draw-lib: Added the #:unscaled? optional argument.

method

(send a-bitmap set-loaded-mask mask)  void?

  mask : (is-a?/c bitmap%)