3 Drawing Operations🔗ℹ

Drawing operations are methods on a DC. See Drawing Contexts for information on creating a drawing context.

Each pt describing a line endpoint is adjusted by adding dpt as well as dx and dy.

Each pt describing an edge endpoint is adjusted by adding dpt as well as dx and dy.

The fill style determines how points within the lines are handled when they are enclosed by multiple loops formed by the lines. In #'odd_even mode, a point is considered enclosed within the polygon if it is enclosed by an odd number of loops. In #'winding mode, a point is considered enclosed within the polygon if it is enclosed by more or fewer clockwise loops than counter-clockwise loops.

In #'unsmoothed or #'aligned smoothing mode, when the pen is size 0 or 1, the filling precisely overlaps the entire outline, instead of overlapping only the inner half of the outline. More generally, in #'unsmoothed or #'aligned mode, the path for the outline is adjusted by shrinking the rectangle width and height by, after scaling, one drawing unit divided by the alignment scale.

If radius is positive, the value is used as the radius of the rounded corner. If radius is negative, the absolute value is used as the proportion of the smallest dimension of the rectangle.

If radius is less than -0.5 or more than half of the width or height (respectively) of r, then half of the width or height (respectively) of r is used, instead.

In #'unsmoothed or #'aligned smoothing mode, the path for the outline is adjusted by, after scaling, shrinking the rectangle width and height by one drawing unit divided by the alignment scale.

In #'unsmoothed or #'aligned smoothing mode, the path for the outline is adjusted by, after scaling, shrinking the rectangle width and height by one drawing unit divided by the alignment scale.

The current pen is used for the arc. If the current brush is not transparent, it is used to fill the wedge bounded by the arc plus lines (not drawn with the pen) extending to the center of the inscribed ellipse. If both the pen and brush are non-transparent, the wedge is filled with the brush before the arc is drawn with the pen.

In #'unsmoothed or #'aligned smoothing mode, the path for the outline is adjusted by, after scaling, shrinking the rectangle width and height by one drawing unit divided by the alignment scale.

In #'unsmoothed or #'aligned smoothing mode. points in the path are rounded left and down.

The fill style determines how points are handled when they are enclosed by multiple loops formed by the path. In #'odd_even mode, a point is considered enclosed within the path if it is enclosed by an odd number of loops. In #'winding mode, a point is considered enclosed within the path if it is enclosed by more or fewer clockwise loops than counter-clockwise loops.

For color bitmaps, the style and color arguments are ignored. For monochrome bitmaps, drawing 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).

If a mask bitmap is supplied, it must have the same width and height as source, and its Bitmap.is_ok must return true, otherwise an exception is thown. The source bitmap and mask bitmap can be the same object, but if the drawing destination is also a Bitmap object, both bitmaps must be distinct from the destination bitmap, otherwise an exception is thrown.

The effect of mask on drawing depends on the type of the mask bitmap:

• If the mask bitmap is monochrome, drawing occurs in the destination only where the mask bitmap contains black pixels (independent of style, which controls how the white pixels of a monochrome source are handled).

• If the mask bitmap is color with an alpha channel, its alpha channel is used as the mask for drawing source, and its color channels are ignored.

• If the mask bitmap is color without an alpha channel, the color components of a given pixel are averaged to arrive at an inverse alpha value for the pixel. In particular, if the mask bitmap is grayscale, then the blackness of each mask pixel controls the opacity of the drawn pixel (i.e., the mask acts as an inverted alpha channel).

The current pen and current brush have no effect on how the bitmap is drawn, but the DC’s alpha setting determines the opacity of the drawn pixels (in combination with an alpha channel of source, any given mask, and the alpha component of color when source is monochrome).

For unrotated text where angle is 0, the specified point is used as the starting top-left point for drawing characters (e.g, if “W” is drawn, the point is roughly the location of the top-left pixel in the “W”). If angle is not 0, the drawn text is rotated counter-clockwise around the specified starting point.

The combine determines how individual characters in the text are treated:

• #'kern: Text may be drawn with adjacent characters combined to form ligature glyphs, with Unicode combining characters as a single glyph, with kerning, with right-to-left rendering of characters, etc.

• #'grapheme: Unicode grapheme clusters (with may span multiple characters) are drawn individually without (further) combination or kerning.

• #'char: Unicode characters are drawn individually without combination or kerning.

See DC.text_extent for information on the size of the drawn text.

The result is four numbers:

• the total width of the text (depends on both the font and the text);

• the total height of the font (depends only on the font);

• the distance from the baseline of the font to the bottom of the descender (included in the height, depends only on the font); and

• extra vertical space added to the font by the font designer (included in the height, and often zero; depends only on the font).

The returned width and height define a rectangle is that guaranteed to contain the text string when it is drawn, but the fit is not necessarily tight. Some undefined number of pixels on the left, right, top, and bottom of the drawn string may be “whitespace,” depending on the whims of the font designer and the platform-specific font-scaling mechanism.