suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improvements to the bitmap docs

Browse Source
This commit is contained in:
Matthew Flatt 2012-02-22 16:38:23 -06:00 committed by Robby Findler
parent d476d3f21a
commit eb032c2fef
5 changed files with 76 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
collects/scribblings/draw/bitmap-class.scrbl
View File

@ -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

49
collects/scribblings/draw/draw-funcs.scrbl
View File

@ -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

69
collects/scribblings/draw/guide.scrbl
View File

@ -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.}
]

3
collects/scribblings/gui/canvas-class.scrbl
View File

@ -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

7
collects/scribblings/gui/miscwin-funcs.scrbl
View File

@ -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"].
}