diff --git a/collects/scribblings/gui/bitmap-class.scrbl b/collects/scribblings/gui/bitmap-class.scrbl index 0a840400eb..2c36253cee 100644 --- a/collects/scribblings/gui/bitmap-class.scrbl +++ b/collects/scribblings/gui/bitmap-class.scrbl @@ -4,7 +4,7 @@ @defclass/title[bitmap% object% ()]{ A @scheme[bitmap%] object is a pixel-based image, either - monochrome or color. + monochrome, color, or color with an alpha channel. Sometimes, a bitmap object creation fails in a low-level manner. In that case, the @method[bitmap% ok?] method returns @scheme[#f], and @@ -14,11 +14,15 @@ Sometimes, a bitmap object creation fails in a low-level manner. In @defconstructor*/make[(([width (integer-in 1 10000)] [height (integer-in 1 10000)] - [monochrome? any/c #f]) + [monochrome? any/c #f] + [alpha? any/c #f]) ([filename path-string?] - [kind (one-of/c 'unknown 'unknown/mask - 'gif 'gif/mask 'jpeg 'png 'png/mask - 'xbm 'xpm 'bmp 'pict) + [kind (one-of/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%) false/c) #f]) ([bits bytes?] @@ -26,9 +30,10 @@ Sometimes, a bitmap object creation fails in a low-level manner. In [height (integer-in 1 10000)]))]{ When @scheme[width] and @scheme[height] are provided: Creates a new - bitmap. If @scheme[monochrome?] is @scheme[#f], the bitmap matches - the display depth of the screen. The initial content of the bitmap is - undefined. + bitmap. If @scheme[monochrome?] is true, the bitmap is monochrome; if + @scheme[monochrome?] is @scheme[#f] and @racket[alpha?] is true, the + bitmap has an alpha channel; otherwise, the bitmap is color without + an alpha channel. The initial content of the bitmap is undefined. When @scheme[filename] is provided: Creates a bitmap from a file, where @scheme[kind] specifies the kind of image file. See @@ -63,8 +68,9 @@ the bitmap is selected into another DC, attached as a button label, etc.). @defmethod[(get-depth) exact-nonnegative-integer?]{ -Gets the color depth of the bitmap. See also @method[bitmap% -is-color?]. +Gets the color depth of the bitmap, which is @racket[1] for a +monochrome bitmap and @racket[32] for a color bitmap. See also +@method[bitmap% is-color?]. } @@ -101,13 +107,21 @@ When a PNG file is loaded with @scheme['png/mask] or values, the mask bitmap is monochrome, otherwise it is grayscale (representing the alpha channel inverted). -The mask bitmap is @italic{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 @method[dc<%> - draw-bitmap]). The mask bitmap is used by @method[bitmap% save-file] - when saving a bitmap as @scheme['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. +When an XPM file is loaded with @scheme['xpm/mask] or + @scheme['unknown/mask], a mask bitmap is generated to indicate which + pixels are set. + +When @scheme['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 @italic{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 + @method[dc<%> draw-bitmap]). The mask bitmap is used by + @method[bitmap% save-file] when saving a bitmap as @scheme['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. } @@ -126,9 +140,12 @@ Returns @scheme[#f] if the bitmap is monochrome, @scheme[#t] otherwise. } @defmethod[(load-file [name path-string?] - [kind (one-of/c 'unknown 'unknown/mask - 'gif 'gif/mask 'jpeg 'png 'png/mask - 'xbm 'xpm 'bmp 'pict) + [kind (one-of/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%) false/c) #f]) boolean?]{ @@ -141,32 +158,42 @@ Loads a bitmap from a file. If the bitmap is in use by a The @scheme[kind] argument specifies the file's format: @itemize[ -@item{@scheme['unknown] --- examine the file to determine its format} +@item{@scheme['unknown] --- examine the file to determine its format; creates either a monochrome or + or color bitmap without an alpha channel} @item{@scheme['unknown/mask] --- like @scheme['unknown], but see @method[bitmap% get-loaded-mask]} -@item{@scheme['gif] --- load a @as-index{GIF} bitmap file (X, Windows, Mac OS X)} -@item{@scheme['gif/mask] --- like @scheme['gif], but see @method[bitmap% get-loaded-mask] (X, Windows, Mac OS X)} -@item{@scheme['jpeg] --- load a @as-index{JPEG} bitmap file (X, Windows, Mac OS X)} -@item{@scheme['png] --- load a @as-index{PNG} bitmap file (X, Windows, Mac OS X)} -@item{@scheme['png/mask] --- like @scheme['png], but see @method[bitmap% get-loaded-mask] (X, Windows, Mac OS X)} -@item{@scheme['xbm] --- load an X bitmap (@as-index{XBM}) file (X, Windows, Mac OS X); creates a monochrome bitmap} -@item{@scheme['xpm] --- load an @as-index{XPM} bitmap file (X, Windows, Mac OS X)} -@item{@scheme['bmp] --- load a Windows bitmap file (X, Windows, Mac OS X)} -@item{@scheme['pict] --- load a @as-index{PICT} bitmap file (Mac OS X)} +@item{@scheme['unknown/alpha] --- like @scheme['unknown], but if the bitmap is color, it has an + alpha channel, and transparency in the image file is recorded + in the alpha channel} +@item{@scheme['gif] --- load a @as-index{GIF} bitmap file, creating a color bitmap} +@item{@scheme['gif/mask] --- like @scheme['gif], but see @method[bitmap% get-loaded-mask]} +@item{@scheme['gif/alpha] --- like @scheme['gif], but with an alpha channel} +@item{@scheme['jpeg] --- load a @as-index{JPEG} bitmap file, creating a color bitmap} +@item{@scheme['jpeg/alpha] --- like @racket['jpeg], but with an alpha channel} +@item{@scheme['png] --- load a @as-index{PNG} bitmap file, creating a color or monochrome bitmap} +@item{@scheme['png/mask] --- like @scheme['png], but see @method[bitmap% get-loaded-mask]} +@item{@scheme['png/alpha] --- like @scheme['png], but always color and with an alpha channel} +@item{@scheme['xbm] --- load an X bitmap (@as-index{XBM}) file; creates a monochrome bitmap} +@item{@scheme['xbm/alpha] --- like @racket['xbm], but creates a color bitmap with an alpha channel} +@item{@scheme['xpm] --- load an @as-index{XPM} bitmap file, creating a color bitmap} +@item{@scheme['xpm/alpha] --- like @racket['xpm], but with an alpha channel} +@item{@scheme['bmp] --- load a Windows bitmap file, creating a color bitmap} +@item{@scheme['bmp/alpha] --- like @racket['bmp], but with an alpha channel} ] 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. + color bitmap. For PNG loading, if @scheme[bg-color] is not @scheme[#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 @scheme['unknown/mask] or @scheme['png/mask] is specified for the - format. If the format is specified as @scheme['unknown] or - @scheme['png] and @scheme[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. + the image; in this case, no separate mask bitmap is generated and the + alpha channel fills the bitmap, even if @scheme['unknown/mask], + @scheme['png/mask] is specified for the format. If the format is + specified as @scheme['unknown] or @scheme['png] and @scheme[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. @index["gamma correction"]{In} all PNG-loading modes, gamma correction is applied when the file provides a gamma value, otherwise gamma @@ -200,15 +227,15 @@ The @scheme[kind] argument determined the type of file that is created, @itemize[ - @item{@scheme['png] --- save a @as-index{PNG} file (X, Windows, Mac OS X)} + @item{@scheme['png] --- save a @as-index{PNG} file} - @item{@scheme['jpeg] --- save a @as-index{JPEG} file (X, Windows, Mac OS X)} + @item{@scheme['jpeg] --- save a @as-index{JPEG} file} - @item{@scheme['xbm] --- save an X bitmap (@as-index{XBM}) file (X, Windows, Mac OS X)} + @item{@scheme['xbm] --- save an X bitmap (@as-index{XBM}) file} - @item{@scheme['xpm] --- save an @as-index{XPM} bitmap file (X, Windows, Mac OS X)} + @item{@scheme['xpm] --- save an @as-index{XPM} bitmap file} - @item{@scheme['bmp] --- save a Windows bitmap file (Windows)} + @item{@scheme['bmp] --- save a Windows bitmap file} ] @@ -218,8 +245,8 @@ The @scheme[quality] argument is used only for saving as @scheme['jpeg], in precisely) and size (low quality is smaller). When saving as @scheme['png], if @method[bitmap% 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. + 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 @scheme['png] without a mask bitmap produces a 1-bit grayscale PNG file (which, when read with diff --git a/collects/scribblings/gui/dc-intf.scrbl b/collects/scribblings/gui/dc-intf.scrbl index 18da704a55..a7c56e2de5 100644 --- a/collects/scribblings/gui/dc-intf.scrbl +++ b/collects/scribblings/gui/dc-intf.scrbl @@ -99,12 +99,8 @@ If the mask bitmap is monochrome, drawing occurs in the target 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. (Non-monochrome masks - are collapsed to monochrome under X when the RENDER extension is not - available, and under Windows 95 and NT when @filepath{msing32.dll} is not - available.) Other combinations involving a non-monochrome mask (i.e., - a non-grayscale mask or a monochrome bitmap to draw) produce - platform-specific results. + channel). If a mask bitmap is color, the component values of a given + pixel are averaged to arrive at a gray value for the pixel. The current brush, current pen, current text, and current alpha settings for the DC have no effect on how the bitmap is drawn, but @@ -232,12 +228,7 @@ The @scheme[fill-style] argument specifies the fill rule: point is considered enclosed within the path if it is enclosed by an odd number of sub-path loops. In @scheme['winding] mode, a point is considered enclosed within the path if it is enclosed by more or less - clockwise sub-path loops than counter-clockwise sub-path loops. In - unsmoothed mode, the @scheme['winding] fill rule is not supported - under Mac OS X and it is not supported when @scheme[path] contains - multiple sub-paths; the @scheme['winding] fill rules is always - supported when smoothing is enabled (see -@method[dc<%> set-smoothing]). + clockwise sub-path loops than counter-clockwise sub-path loops. See also @method[dc<%> set-smoothing] for information on the @scheme['aligned] smoothing mode. @@ -281,10 +272,7 @@ The @scheme[fill-style] argument specifies the fill rule: point is considered enclosed within the polygon if it is enclosed by an odd number of loops. In @scheme['winding] mode, a point is considered enclosed within the polygon if it is enclosed by more or - less clockwise loops than counter-clockwise loops. The - @scheme['winding] fill rule is not supported under Mac OS X, - except when smoothing is enabled (see -@method[dc<%> set-smoothing]). + less clockwise loops than counter-clockwise loops. See also @method[dc<%> set-smoothing] for information on the @scheme['aligned] smoothing mode. @@ -516,11 +504,43 @@ See @scheme[gl-context<%>] for more information. } +@defmethod[(get-initial-matrix) + (vector/c real? real? real? real? real? real?)]{ + +Returns a transformation matrix that converts logical coordinates to + device coordinates. The matrix applies before additional origin + offset, scaling, and rotation. + +The vector content corresponds to a transformation matrix in the +following order: + +@itemlist[ + + @item{@racket[_xx]: a scale from the logical @racket[_x] to the device @racket[_x]} + + @item{@racket[_xy]: a scale from the logical @racket[_x] added to the device @racket[_y]} + + @item{@racket[_yx]: a scale from the logical @racket[_y] added to the device @racket[_x]} + + @item{@racket[_yy]: a scale from the logical @racket[_y] to the device @racket[_y]} + + @item{@racket[_x0]: an additional amount added to the device @racket[_x]} + + @item{@racket[_y0]: an additional amount added to the device @racket[_y]} + +] + +See also @method[dc<%> set-initial-matrix]. + +} + + @defmethod[(get-origin) (values real? real?)]{ Returns the device origin, i.e., the location in device coordinates of - @math{(0,0)} in logical coordinates. + @math{(0,0)} in logical coordinates. The origin offset applies after + the initial transformation matrix, but before scaling and rotation. See also @method[dc<%> set-origin]. @@ -534,11 +554,22 @@ Gets the current pen. See also @method[dc<%> set-pen]. } +@defmethod[(get-rotation) real?]{ + +Returns the rotation of logical coordinates in radians to device +coordinates. Rotation applies after the initial transformation matrix, +origin offset, and scaling. + +See also @method[dc<%> set-rotation]. + +} + @defmethod[(get-scale) (values real? real?)]{ Returns the scaling factor that maps logical coordinates to device -coordinates. +coordinates. Scaling applies after the initial transformation matrix +and origin offset, but before rotation. See also @method[dc<%> set-scale]. @@ -667,29 +698,15 @@ Returns @scheme[#t] if the drawing context is usable. } + @defmethod[(set-alpha [opacity (real-in 0 1)]) void?]{ -Determines the opacity of drawing, under certain conditions: +Determines the opacity of drawing. A value of @scheme[0.0] corresponds +to completely transparent (i.e., invisible) drawing, and @scheme[1.0] +corresponds to completely opaque drawing. For intermediate values, +drawing is blended with the existing content of the drawing context.} -@itemize[ - - @item{pen- and brush-based drawing when @method[dc<%> get-smoothing] - produces @scheme['smoothed] or @scheme['aligned], and when the - drawing context is not an instance of @scheme[post-script-dc%]; - and} - - @item{text drawing for most platforms (Mac OS X, X with - Xft/fontconfig; transparency approximated under Windows by - fading the drawing color), and when the drawing context is not - an instance of @scheme[post-script-dc].} - -] - -A value of @scheme[0.0] corresponds to completely transparent (i.e., -invisible) drawing, and @scheme[1.0] corresponds to completely opaque -drawing. For intermediate values, drawing is blended with the existing -content of the drawing context.} @defmethod[(set-background [color (is-a?/c color%)]) void?]{ @@ -763,14 +780,33 @@ Sets the current font for drawing text in this object. } +@defmethod[(set-initial-matrix [m (vector/c real? real? real? real? real? real?)]) + void?]{ + +Set a transformation matrix that converts logical coordinates to + device coordinates. The matrix applies before additional origin + offset, scaling, and rotation. + +See @method[dc<%> get-initial-matrix] for information on the matrix as + represented by a vector @racket[m]. + +Changing a @scheme[dc<%>] object's transformations does not affect + @scheme[region%] objects that were previously created. See + @scheme[region%] for more information. + +@|DrawSizeNote| + +} + @defmethod[(set-origin [x real?] [y real?]) void?]{ Sets the device origin, i.e., the location in device coordinates of - @math{(0,0)} in logical coordinates. + @math{(0,0)} in logical coordinates. The origin offset applies after + the initial transformation matrix, but before scaling and rotation. -Changing a @scheme[dc<%>] object's origin or scale does not affect +Changing a @scheme[dc<%>] object's transformations does not affect @scheme[region%] objects that were previously created. See @scheme[region%] for more information. @@ -807,13 +843,29 @@ While a pen is selected into a drawing context, it cannot be modified. } +@defmethod[(set-rotation [angle real?]) void?]{ + +Set the rotation of logical coordinates in radians to device +coordinates. Rotation applies after the initial transformation matrix, +origin offset, and scaling. + +Changing a @scheme[dc<%>] object's transformations does not affect + @scheme[region%] objects that were previously created. See + @scheme[region%] for more information. + +@|DrawSizeNote| + +} + @defmethod[(set-scale [x-scale (and/c real? (not/c negative?))] [y-scale (and/c real? (not/c negative?))]) void?]{ -Sets a scaling factor that maps logical coordinates to device coordinates. +Sets a scaling factor that maps logical coordinates to device + coordinates. Scaling applies after the initial transformation matrix + and origin offset, but before rotation. -Changing a @scheme[dc<%>] object's origin or scale does not affect +Changing a @scheme[dc<%>] object's transformations does not affect @scheme[region%] objects that were previously created. See @scheme[region%] for more information. @@ -824,17 +876,9 @@ Changing a @scheme[dc<%>] object's origin or scale does not affect @defmethod[(set-smoothing [mode (one-of/c 'unsmoothed 'smoothed 'aligned)]) void?]{ -Enables or disables anti-aliased smoothing of lines, curves, - rectangles, rounded rectangles, ellipses, polygons, paths, and clear - operations. (Text smoothing is not affected by this method, and is - instead controlled through the @scheme[font%] object.) - -Smoothing is supported under Windows only when Microsoft's - @filepath{gdiplus.dll} is installed (which is always the case for Windows - XP). Smoothing is supported under Mac OS X always. Smoothing is - supported under X only when Cairo is installed when GRacket is compiled. - Smoothing is never supported for black-and-white contexts. Smoothing - is always supported (and cannot be disabled) for PostScript output. +Enables or disables anti-aliased smoothing for drawing. (Text + smoothing is not affected by this method, and is instead controlled + through the @scheme[font%] object.) The smoothing mode is either @scheme['unsmoothed], @scheme['smoothed], or @scheme['aligned]. Both @scheme['aligned] and @scheme['smoothed]