| <!--{ |
| "Title": "The Go image/draw package", |
| "Template": true |
| }--> |
| |
| <p> |
| <a href="/pkg/image/draw/">Package image/draw</a> defines |
| only one operation: drawing a source image onto a destination |
| image, through an optional mask image. This one operation is |
| surprisingly versatile and can perform a number of common image |
| manipulation tasks elegantly and efficiently. |
| </p> |
| |
| <p> |
| Composition is performed pixel by pixel in the style of the Plan 9 |
| graphics library and the X Render extension. The model is based on |
| the classic "Compositing Digital Images" paper by Porter and Duff, |
| with an additional mask parameter: <code>dst = (src IN mask) OP dst</code>. |
| For a fully opaque mask, this reduces to the original Porter-Duff |
| formula: <code>dst = src OP dst</code>. In Go, a nil mask image is equivalent |
| to an infinitely sized, fully opaque mask image. |
| </p> |
| |
| <p> |
| The Porter-Duff paper presented |
| <a href="http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png">12 different composition operators</a>, |
| but with an explicit mask, only 2 of these are needed in practice: |
| source-over-destination and source. In Go, these operators are |
| represented by the <code>Over</code> and <code>Src</code> constants. The <code>Over</code> operator |
| performs the natural layering of a source image over a destination |
| image: the change to the destination image is smaller where the |
| source (after masking) is more transparent (that is, has lower |
| alpha). The <code>Src</code> operator merely copies the source (after masking) |
| with no regard for the destination image's original content. For |
| fully opaque source and mask images, the two operators produce the |
| same output, but the <code>Src</code> operator is usually faster. |
| </p> |
| |
| <p><b>Geometric Alignment</b></p> |
| |
| <p> |
| Composition requires associating destination pixels with source and |
| mask pixels. Obviously, this requires destination, source and mask |
| images, and a composition operator, but it also requires specifying |
| what rectangle of each image to use. Not every drawing should write |
| to the entire destination: when updating an animating image, it is |
| more efficient to only draw the parts of the image that have |
| changed. Not every drawing should read from the entire source: when |
| using a sprite that combines many small images into one large one, |
| only a part of the image is needed. Not every drawing should read |
| from the entire mask: a mask image that collects a font's glyphs is |
| similar to a sprite. Thus, drawing also needs to know three |
| rectangles, one for each image. Since each rectangle has the same |
| width and height, it suffices to pass a destination rectangle `r` |
| and two points <code>sp</code> and <code>mp</code>: the source rectangle is equal to <code>r</code> |
| translated so that <code>r.Min</code> in the destination image aligns with |
| <code>sp</code> in the source image, and similarly for <code>mp</code>. The effective |
| rectangle is also clipped to each image's bounds in their |
| respective co-ordinate space. |
| </p> |
| |
| <p> |
| <img src="image-20.png"> |
| </p> |
| |
| <p> |
| The <a href="/pkg/image/draw/#DrawMask"><code>DrawMask</code></a> |
| function takes seven arguments, but an explicit mask and mask-point |
| are usually unnecessary, so the |
| <a href="/pkg/image/draw/#Draw"><code>Draw</code></a> function takes five: |
| </p> |
| |
| <pre> |
| // Draw calls DrawMask with a nil mask. |
| func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op) |
| func DrawMask(dst Image, r image.Rectangle, src image.Image, sp image.Point, |
| mask image.Image, mp image.Point, op Op) |
| </pre> |
| |
| <p> |
| The destination image must be mutable, so the image/draw package |
| defines a <a href="/pkg/image/draw/#Image"><code>draw.Image</code></a> |
| interface which has a <code>Set</code> method. |
| </p> |
| |
| {{code "../src/pkg/image/draw/draw.go" `/type Image/` `/}/`}} |
| |
| <p><b>Filling a Rectangle</b></p> |
| |
| <p> |
| To fill a rectangle with a solid color, use an <code>image.Uniform</code> |
| source. The <code>Uniform</code> type re-interprets a <code>Color</code> as a |
| practically infinite-sized <code>Image</code> of that color. For those |
| familiar with the design of Plan 9's draw library, there is no need |
| for an explicit "repeat bit" in Go's slice-based image types; the |
| concept is subsumed by <code>Uniform</code>. |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/ZERO/` `/STOP/`}} |
| |
| <p> |
| To initialize a new image to all-blue: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/BLUE/` `/STOP/`}} |
| |
| <p> |
| To reset an image to transparent (or black, if the destination |
| image's color model cannot represent transparency), use |
| <code>image.Transparent</code>, which is an <code>image.Uniform</code>: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/RESET/` `/STOP/`}} |
| |
| <p> |
| <img src="image-2a.png"> |
| </p> |
| |
| |
| <p><b>Copying an Image</b></p> |
| |
| <p> |
| To copy from a rectangle <code>sr</code> in the source image to a rectangle |
| starting at a point <code>dp</code> in the destination, convert the source |
| rectangle into the destination image's co-ordinate space: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/RECT/` `/STOP/`}} |
| |
| <p> |
| Alternatively: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/RECT2/` `/STOP/`}} |
| |
| <p> |
| To copy the entire source image, use <code>sr = src.Bounds()</code>. |
| </p> |
| |
| <p> |
| <img src="image-2b.png"> |
| </p> |
| |
| <p><b>Scrolling an Image</b></p> |
| |
| <p> |
| Scrolling an image is just copying an image to itself, with |
| different destination and source rectangles. Overlapping |
| destination and source images are perfectly valid, just as Go's |
| built-in copy function can handle overlapping destination and |
| source slices. To scroll an image m by 20 pixels: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/SCROLL/` `/STOP/`}} |
| |
| <p><img src="image-2c.png"></p> |
| |
| <p><b>Converting an Image to RGBA</b></p> |
| |
| <p> |
| The result of decoding an image format might not be an |
| <code>image.RGBA</code>: decoding a GIF results in an <code>image.Paletted</code>, |
| decoding a JPEG results in a <code>ycbcr.YCbCr</code>, and the result of |
| decoding a PNG depends on the image data. To convert any image to |
| an <code>image.RGBA</code>: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/CONV/` `/STOP/`}} |
| |
| <p> |
| <img src="image-2d.png"> |
| </p> |
| |
| <p><b>Drawing Through a Mask</b></p> |
| |
| <p> |
| To draw an image through a circular mask with center <code>p</code> and radius |
| <code>r</code>: |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/CIRCLESTRUCT/` `/STOP/`}} |
| {{code "/doc/progs/image_draw.go" `/CIRCLE2/` `/STOP/`}} |
| |
| <p> |
| <img src="image-2e.png"> |
| </p> |
| |
| <p><b>Drawing Font Glyphs</b></p> |
| |
| <p> |
| To draw a font glyph in blue starting from a point <code>p</code>, draw with |
| an <code>image.Uniform</code> source and an <code>image.Alpha mask</code>. For |
| simplicity, we aren't performing any sub-pixel positioning or |
| rendering, or correcting for a font's height above a baseline. |
| </p> |
| |
| {{code "/doc/progs/image_draw.go" `/GLYPH/` `/STOP/`}} |
| |
| <p> |
| <img src="image-2f.png"> |
| </p> |
| |
| <p><b>Performance</b></p> |
| |
| <p> |
| The image/draw package implementation demonstrates how to provide |
| an image manipulation function that is both general purpose, yet |
| efficient for common cases. The <code>DrawMask</code> function takes arguments |
| of interface types, but immediately makes type assertions that its |
| arguments are of specific struct types, corresponding to common |
| operations like drawing one <code>image.RGBA</code> image onto another, or |
| drawing an <code>image.Alpha</code> mask (such as a font glyph) onto an |
| <code>image.RGBA</code> image. If a type assertion succeeds, that type |
| information is used to run a specialized implementation of the |
| general algorithm. If the assertions fail, the fallback code path |
| uses the generic <code>At</code> and <code>Set</code> methods. The fast-paths are purely |
| a performance optimization; the resultant destination image is the |
| same either way. In practice, only a small number of special cases |
| are necessary to support typical applications. |
| </p> |
| |
| |