diff --git a/collects/scribblings/draw/bitmap-class.scrbl b/collects/scribblings/draw/bitmap-class.scrbl index e82136a112..7d4c101bc3 100644 --- a/collects/scribblings/draw/bitmap-class.scrbl +++ b/collects/scribblings/draw/bitmap-class.scrbl @@ -3,9 +3,11 @@ @defclass/title[bitmap% object% ()]{ -A @racket[bitmap%] object is a pixel-based image, either - monochrome, color, or color with an alpha channel. See also - @racket[make-platform-bitmap]. +A @racket[bitmap%] object is a pixel-based image, either monochrome, + color, or color with an alpha channel. See also @racket[make-bitmap], + @racket[make-platform-bitmap], @racket[make-screen-bitmap] (from + @racketmodname[racket/gui/base]), @xmethod[canvas% make-bitmap] (from + @racketmodname[racket/gui/base]), and @secref["Portability"]. A bitmap is convertible to @racket['png-bytes] through the @racketmodname[file/convertible] protocol. @@ -29,22 +31,18 @@ A bitmap is convertible to @racket['png-bytes] through the [width exact-positive-integer?] [height exact-positive-integer?]))]{ -The function @racket[make-platform-bitmap] is preferred over -using @racket[bitmap%] directly. - The @racket[make-bitmap], @racket[make-monochrome-bitmap], and - @racket[read-bitmap] functions are closer to @racket[bitmap%], but + @racket[read-bitmap] functions create @racket[bitmap%] instances, but they are also preferred over using @racket[make-object] with @racket[bitmap%] directly, because the functions are less overloaded and they enable alpha channels by default. + See also @secref["Portability"]. When @racket[width] and @racket[height] are provided: Creates a new bitmap. If @racket[monochrome?] is true, the bitmap is monochrome; if @racket[monochrome?] is @racket[#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 ``empty'': all white, and with + an alpha channel. 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 @racket[in] is provided: Creates a bitmap from a file format, @@ -164,7 +162,7 @@ Returns @racket[#f] if the bitmap is monochrome, @racket[#t] otherwise. boolean?]{ Loads a bitmap from a file format that read from @racket[in], unless - the bitmap was produced by @racket[make-screen-bitmap], @racket[make-platform-bitmap], + the bitmap was produced by @racket[make-platform-bitmap], @racket[make-screen-bitmap], or @xmethod[canvas% make-bitmap] (in which case @|MismatchExn|). If the bitmap is in use by a @racket[bitmap-dc%] object or a control, the image data is not diff --git a/collects/scribblings/draw/draw-funcs.scrbl b/collects/scribblings/draw/draw-funcs.scrbl index a1339d895a..101414ab58 100644 --- a/collects/scribblings/draw/draw-funcs.scrbl +++ b/collects/scribblings/draw/draw-funcs.scrbl @@ -36,43 +36,6 @@ Returns the built-in default face mapping for a particular font See @racket[font%] for information about @racket[family].} -@defproc[(make-platform-bitmap [width exact-positive-integer?] - [height exact-positive-integer?]) - (is-a?/c bitmap%)]{ - Creates a bitmap that draws in a way that is the same as drawing to a - @racket[canvas%]'s @racket[dc<%>] (in its default configuration) - under Mac OS X and Windows, and creates a bitmap that draws the way - the result of @racket[make-bitmap] draws under Unix. - - In general, @racket[make-platform-bitmap] produces better looking - bitmaps on more platforms than - @racket[make-bitmap], @racket[make-screen-bitmap], or creating - a @racket[bitmap%] object directly. - Also, unlike @racket[make-screen-bitmap], - @racket[make-platform-bitmap]'s implementation does not - depend on @racketmodname[racket/gui/base], making it - available in more contexts. - Accordingly, in the absence - of other constraints, @racket[make-platform-bitmap] - should be used in preference to other ways of creating bitmaps. - - That said, there are two drawbacks to @racket[make-platform-bitmap]. - First, it will use more constrained resources than - @racket[make-bitmap] does, especially under Windows. One possible - approach to dealing with this problem for long-lived bitmaps - is to draw into the result of a @racket[make-platform-bitmap] - and then copy the contents of the drawing into the result - of a @racket[make-bitmap]. This preserves the better quality - drawing, but holds onto the constrained resources only during - the drawing process. - - The other drawback is that @racket[make-platform-bitmap] does not - create bitmaps with an alpha channel under Windows - (instead, the bitmaps have a white, solid background). - If you need bitmaps with alpha channels, use @racket[make-bitmap] - instead. -} - @defproc[(make-bitmap [width exact-positive-integer?] [height exact-positive-integer?] [alpha? any/c #t]) @@ -82,10 +45,9 @@ Returns @racket[(make-object bitmap% width height #f alpha?)], but this procedure is preferred because it defaults @racket[alpha?] in a more useful way. -See also @racket[make-platform-bitmap]. +See also @racket[make-platform-bitmap] and @secref["Portability"]. } - @defproc[(make-font [#:size size (integer-in 1 1024) 12] [#:face face (or/c string? #f) #f] [#:family family (one-of/c 'default 'decorative 'roman 'script @@ -118,6 +80,15 @@ width height)] otherwise. This procedure is preferred to using overloaded.} +@defproc[(make-platform-bitmap [width exact-positive-integer?] + [height exact-positive-integer?]) + (is-a?/c bitmap%)]{ + +Creates a bitmap that uses platform-specific drawing operations +as much as possible, which is different than a @racket[make-bitmap] result +on Windows and Mac OS X. See @secref["Portability"] for more information.} + + @defproc[(read-bitmap [in (or path-string? input-port?)] [kind (one-of/c 'unknown 'unknown/mask 'unknown/alpha 'gif 'gif/mask 'gif/alpha diff --git a/collects/scribblings/draw/guide.scrbl b/collects/scribblings/draw/guide.scrbl index 8caccefa34..17e1e98b37 100644 --- a/collects/scribblings/draw/guide.scrbl +++ b/collects/scribblings/draw/guide.scrbl @@ -16,14 +16,14 @@ (send dc set-bitmap #f)) bm)))] @interaction-eval[#:eval draw-eval (define (line-bitmap mode) - (let* ([bm (make-platform-bitmap 30 4)] + (let* ([bm (make-bitmap 30 4)] [dc (make-object bitmap-dc% bm)]) (send dc set-smoothing mode) (send dc draw-line 0 2 30 2) (send dc set-bitmap #f) (copy-bitmap bm)))] @interaction-eval[#:eval draw-eval (define (path-bitmap zee join brush?) - (let* ([bm (make-platform-bitmap 40 40)] + (let* ([bm (make-bitmap 40 40)] [dc (new bitmap-dc% [bitmap bm])]) (send dc set-smoothing 'aligned) (send dc set-pen (new pen% [width 5] [join join])) @@ -98,12 +98,12 @@ in a GUI window.} @section{Lines and Simple Shapes} To draw into a bitmap, first create the bitmap with -@racket[make-platform-bitmap], and then create a @racket[bitmap-dc%] that draws +@racket[make-bitmap], and then create a @racket[bitmap-dc%] that draws into the new bitmap: @racketblock+eval[ #:eval draw-eval -(define target (make-platform-bitmap 30 30)) (code:comment "A 30x30 bitmap") +(define target (make-bitmap 30 30)) (code:comment "A 30x30 bitmap") (define dc (new bitmap-dc% [bitmap target])) ] @@ -234,7 +234,7 @@ The @racket[set-pen] and @racket[set-brush] methods of a @tech{DC} (send dc set-pen red-pen) (send dc draw-arc 37 37 75 75 (* 5/4 pi) (* 7/4 pi))) -(define target (make-platform-bitmap 150 150)) +(define target (make-bitmap 150 150)) (define dc (new bitmap-dc% [bitmap target])) (draw-face dc) @@ -477,7 +477,7 @@ At this point we can't resist showing an extended example using (send dc set-brush blue-brush) (send dc draw-path right-logo-path)) -(define racket-logo (make-platform-bitmap 170 170)) +(define racket-logo (make-bitmap 170 170)) (define dc (new bitmap-dc% [bitmap racket-logo])) (send dc set-smoothing 'smoothed) @@ -501,7 +501,7 @@ draw and a location for the top-left of the drawn text: @racketblock+eval[ #:eval draw-eval -(define text-target (make-platform-bitmap 100 30)) +(define text-target (make-bitmap 100 30)) (define dc (new bitmap-dc% [bitmap text-target])) (send dc set-brush "white" 'transparent) @@ -559,7 +559,7 @@ transferred, and the background is left alone: @racketblock+eval[ #:eval draw-eval -(define new-target (make-platform-bitmap 100 30)) +(define new-target (make-bitmap 100 30)) (define dc (new bitmap-dc% [bitmap new-target])) (send dc set-pen "black" 1 'transparent) (send dc set-brush "pink" 'solid) @@ -573,7 +573,7 @@ transferred, and the background is left alone: The information about which pixels of a bitmap are drawn (as opposed to ``nothing'') is the bitmap's @deftech{alpha channel}. Not all @tech{DC}s keep an alpha channel, but bitmaps created with -@racket[make-platform-bitmap] keep an alpha channel by default. Bitmaps loaded +@racket[make-bitmap] keep an alpha channel by default. Bitmaps loaded with @racket[read-bitmap] preserve transparency in the image file through the bitmap's alpha channel. @@ -636,7 +636,7 @@ viewed as a convenience alternative to clipping repeated calls of @; ------------------------------------------------------------ -@section{Portability} +@section[#:tag "Portability"]{Portability and Bitmap Variants} Drawing effects are not completely portable across platforms, across different classes that implement @racket[dc<%>], or different @@ -644,9 +644,46 @@ kinds of bitmaps. Fonts and text, especially, can vary across platforms and types of @tech{DC}, but so can the precise set of pixels touched by drawing a line. -For example, drawing to a bitmap produced by -@racket[make-platform-bitmap] may produce slightly different results than -drawing to one produced by -@racket[make-bitmap]. Drawing to a bitmap from -@racket[make-screen-bitmap], however, should be the same as drawing to an -onscreen @racket[canvas%]. +Different kinds of bitmaps can produce different results: + +@itemlist[ + + @item{Drawing to a bitmap produced by @racket[make-bitmap] (or + instantiated from @racket[bitmap%]) draws in the most + consistent way across platforms.} + + @item{Drawing to a bitmap produced by @racket[make-platform-bitmap] + uses platform-specific drawing operations as much as possible. + On Windows, however, a bitmap produced by + @racket[make-platform-bitmap] has no alpha channel, and it uses + more constrained resources than one produced by + @racket[make-bitmap] (due to a system-wide, per-process GDI limit). + + As an example of platform-specific difference, text is smoothed + by default with sub-pixel anti-aliasing on Mac OS X, while text + smoothing in a @racket[make-bitmap] result uses only grays. + Line or curve drawing may touch different pixels than in a + bitmap produced by @racket[make-bitmap], and bitmap scaling may + differ. + + A possible approach to dealing with the GDI limit under Windows + is to draw into the result of a @racket[make-platform-bitmap] + and then copy the contents of the drawing into the result of a + @racket[make-bitmap]. This approach preserves the drawing + results of @racket[make-platform-bitmap], but it retains + constrained resources only during the drawing process.} + + @item{Drawing to a bitmap produced by @racket[make-screen-bitmap] + from @racketmodname[racket/gui/base] or by @xmethod[canvas% + make-bitmap] uses the same platform-specific drawing operations + as drawing into a @racket[canvas%] instance. A bitmap produced + by @racket[make-screen-bitmap] is the same as one produced by + @racket[make-platform-bitmap] on Windows or Mac OS X, but it may + be sensitive to the X11 server on Unix. + + Use @racket[make-screen-bitmap] when drawing to a bitmap as an + offscreen buffer before transferring an image to the screen, or + when consistency with screen drawing is needed for some other + reason.} + +] \ No newline at end of file diff --git a/collects/scribblings/gui/canvas-class.scrbl b/collects/scribblings/gui/canvas-class.scrbl index cdc3edf166..fd40a95a41 100644 --- a/collects/scribblings/gui/canvas-class.scrbl +++ b/collects/scribblings/gui/canvas-class.scrbl @@ -269,7 +269,8 @@ See also (is-a/c? bitmap%)]{ Creates a bitmap that draws in a way that is the same as drawing to the -canvas. See also @racket[make-screen-bitmap].} +canvas. See also @racket[make-screen-bitmap] +and @secref[#:doc '(lib "scribblings/draw/draw.scrbl") "Portability"].} @defmethod[#:mode override diff --git a/collects/scribblings/gui/miscwin-funcs.scrbl b/collects/scribblings/gui/miscwin-funcs.scrbl index b7c3322616..1d681bb50c 100644 --- a/collects/scribblings/gui/miscwin-funcs.scrbl +++ b/collects/scribblings/gui/miscwin-funcs.scrbl @@ -227,7 +227,7 @@ Creates a bitmap that supports both normal @racket[dc<%>] drawing an OpenGL drawing through a context returned by @xmethod[dc<%> get-gl-context]. For @racket[dc<%>] drawing, an OpenGL-supporting bitmap draws like a -bitmap frmo @racket[make-screen-bitmap] on some platforms, while it +bitmap from @racket[make-screen-bitmap] on some platforms, while it draws like a bitmap instantiated directly from @racket[bitmap%] on other platforms.} @@ -252,10 +252,7 @@ environment of the result namespace.} Creates a bitmap that draws in a way that is the same as drawing to a canvas in its default configuration. -A normal @racket[bitmap%] draws in a more platform-independent way and -may use fewer constrained resources, particularly on Windows. - -See also @racket[make-platform-bitmap]. +See also @secref[#:doc '(lib "scribblings/draw/draw.scrbl") "Portability"]. }