draw-bitmap in dc<%>

Displays a bitmap. For color bitmaps, the drawing style and color arguments are ignored. For monochrome bitmaps, draw-bitmap uses the style and color arguments in the same way that a brush uses its style and color settings to draw a monochrome stipple (see brush% for more information).

If a mask bitmap is supplied, it must have the same width and height as the bitmap to display, and its ok? must return true, otherwise an exn:fail:contract exception is raised. The bitmap to draw and the mask bitmap can be the same object, but if the drawing context is a bitmap-dc% object, both bitmaps must be distinct from the destination bitmap, otherwise an exn:fail:contract exception is raised.

If the mask bitmap is monochrome, drawing occurs in the target dc<%> only where the mask bitmap contains black pixels.

If the mask bitmap is grayscale and the bitmap to draw is not monochrome, then the blackness of each mask pixel controls the opacity of the drawn pixel (i.e., the mask acts as an inverted alpha channel), at least on most platforms.¹⁴ Other combinations involving a non-monochrome mask (i.e., a non-grayscale mask or a monochrome bitmap to draw) produce platform-specific results.

See also draw-bitmap-section.

The current brush, current pen, and current text settings for the DC have no effect on how the bitmap is drawn, but the bitmap is scaled if the DC has a scale.

For post-script-dc% output, the mask bitmap is currently ignored, and the 'solid style is treated the same as 'opaque. (However, mask bitmaps and 'solid drawing may become supported for post-script-dc% in the future.)

The result is #t if the bitmap is successfully drawn, #f otherwise (possibly because the bitmap's ok? method returns #f).

• (send a-dc draw-bitmap source dest-x dest-y style color mask) -> boolean
     source : bitmap% object
     dest-x : real number
     dest-y : real number
     style = 'solid : symbol in '(solid opaque xor)
   color = black : color% object
     mask = #f : bitmap% object or #f

  The dest-x and dest-y arguments are in DC coordinates.

  Restrictions on the magnitude of drawing coordinates are described with dc<%>.