4.2 Bitmaps

0.45+9.1.0.1

Rhombus

4.2 Bitmaps🔗ℹ

class

class draw.Bitmap():

constructor (

size :: SizeLike,

~kind: kind :: Bitmap.Kind = #'alpha,

~backing_scale: backing_scale :: PosReal = 1.0

)

Creates a bitmap of the given size in drawing units. The kind argument determines whether the bitmap includes color pixels (versus recording only black or white for each pixel) and whether it includes an alpha channel to record the opacity of each pixel in the bitmap. The initial content of the bitmap is “empty”: all white, and with zero opacity in the case of a bitmap with an alpha channel.

The backing_scale argument determines the bitmap’s 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. A monochrome bitmap must have a backing scale of 1.0.

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

function

fun draw.Bitmap.make_platform(

size :: SizeLike,

~backing_scale: backing_space :: PosReal = 1

) :: Bitmap

Creates a bitmap that uses platform-specific drawing operations as much as possible, which is different than a Bitmap constructor result on Windows and Mac OS. See Portability and Bitmap Variants for more information.

property

property (bm :: draw.Bitmap).width :: PosInt

property

property (bm :: draw.Bitmap).height :: PosInt

property

property (bm :: draw.Bitmap).size :: Size

property

property (bm :: draw.Bitmap).backing_scale :: PosReal

property

property (bm :: draw.Bitmap).depth :: Nat

property

property (bm :: draw.Bitmap).kind :: Bitmap.Kind

property

property (bm :: draw.Bitmap).is_ok :: Boolean

Properties to access bitmap components. The Bitmap.size property combines the Bitmap.width and Bitmap.height properties. The Bitmap.depth property returns the number of bits used to represent each pixel, so it is 1 for a monochrome bitmap.

method

method (bm :: draw.Bitmap).make_dc() :: DC

Creates a drawing context whose destination is the bitmap.

method

method (bm :: draw.Bitmap).argb_pixels(

~x: x :: Nat = 0,

~y: y :: Nat = 0,

~width: width :: Nat = width,

~height: height :: Nat = height,

~dest: dest :: Bytes = Bytes.make(width * height * 4),

~just_alpha: just_alpha :: Any.to_boolean = #false,

~premultiplied: premultiplied :: Any.to_boolean = #false,

~unscaled: unscaled :: Any.to_boolean = #false

) :: Bytes

Copies a rectangle of bitmap content into dest and returns dest.

The pixel red, green blue, and alpha values are copied into dest (or just alpha values if just_alpha is true). The first byte represents an alpha value of the pixel at (x, y), the second byte represents a red value of the pixel at (x, y), the third byte is the green value, etc. In this way, the first width*height*4 bytes of dest are set to reflect the current pixel values in the DC. The pixels are in row-major order: left to right then top to bottom.

If the bitmap has an alpha channel, then the alpha value for each pixel is always set in dest. If just_alpha is false and the bitmap does not have an alpha channel, then the alpha value for each pixel is set to 255. If just_alpha is true, then only the alpha value is set for each pixel; if the bitmap has no alpha channel, then the alpha value is based on each pixel’s inverted red-green-blue average.

If premultiplied is true, just_alpha is false, and the bitmap has an alpha channel, then red, green, and blue values in the result are scaled by the corresponding alpha value (i.e., multiplied by the alpha value and then divided by 255).

If the bitmap has a backing scale other than 1.0 and unscaled is #false, the result of Bitmap.argb_pixels is as if the bitmap is drawn to a bitmap with a backing scale of 1.0 and the pixels of the target bitmap are returned.

method

method (bm :: draw.Bitmap).set_argb_pixels(

src :: Bytes,

~x: x :: Nat = 0,

~y: y :: Nat = 0,

~width: width :: Nat = width,

~height: height :: Nat = height,

~just_alpha: just_alpha :: Any.to_boolean = #false,

~premultiplied: premultiplied :: Any.to_boolean = #false,

~unscaled: unscaled :: Any.to_boolean = #false

) :: Void

The reverse of Bitmap.argb_pixels: adjusts bm so that Bitmap.argb_pixels with all of the same arguments would produce the content in src as its result, or as close as possible.

method

method (bm :: draw.Bitmap).write(

out :: PathString || Port.Output,

~kind: kind :: Any.of(#'png, #'jpeg, #'xbm, #'xpm, #'bmp),

~quality: quality :: Int.in(0 ..= 100) = 75,

~as_unscaled: as_unscaled :: Any = #false,

) :: Void

Writes the bitmap to out. The kind argument determines the file format used.

The quality argument applies only to the #'jpeg format, 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).

The as_unscaled argument is relevant when the bitmap has a backing scale other than 1.0. In that case, if as_unscaled is #false, the bitmap is effectively converted to a single pixel per drawing unit before writing.

function

fun draw.Bitmap.read(in :: PathString || Port.Input) :: Bitmap

Reads a bitmap from in. The file format is detected automatically among the same formats as recognized by Bitmap.write.

property

property (path :: draw.Bitmap).handle :: Any

function

fun draw.Bitmap.from_handle(hand :: Any) :: Bitmap

The Bitmap.handle property returns a Racket object that corresponds to the bitmap for use directly with racket/draw. The Bitmap.from_handle function creates a Bitmap from such a Racket object.

enumeration

enum draw.Bitmap.Kind

| alpha

| color

| mono

Represents the color and alpha content of a bitmap, where #'mono indicates a monochrome bitmap that keeps only black or white for each pixel.

1	Overview
2	Drawing State
3	Drawing Operations
4	Drawing Contexts
5	Drawing Utensils
6	Drawing Geometry

4.1	Generic Drawing Context
4.2	Bitmaps
4.3	Paged Drawing Contexts
4.4	Recording Drawing Contexts