From: Nigel Tao Date: Mon, 6 Feb 2012 00:04:12 +0000 (+1100) Subject: image: add package docs, rename s/UnknownFormatError/ErrFormat/ and X-Git-Tag: weekly.2012-02-07~59 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=8fc87c957c6bc9d6dbd9c74171803cd4e7384c80;p=gostls13.git image: add package docs, rename s/UnknownFormatError/ErrFormat/ and rewrite the doc comment for Repeated. Fixes #2858. R=r, rsc CC=golang-dev https://golang.org/cl/5626050 --- diff --git a/src/pkg/image/format.go b/src/pkg/image/format.go index 78fc3ed619..f93d356b04 100644 --- a/src/pkg/image/format.go +++ b/src/pkg/image/format.go @@ -10,8 +10,8 @@ import ( "io" ) -// An UnknownFormatErr indicates that decoding encountered an unknown format. -var UnknownFormatErr = errors.New("image: unknown format") +// ErrFormat indicates that decoding encountered an unknown format. +var ErrFormat = errors.New("image: unknown format") // A format holds an image format's name, magic header and how to decode it. type format struct { @@ -79,7 +79,7 @@ func Decode(r io.Reader) (Image, string, error) { rr := asReader(r) f := sniff(rr) if f.decode == nil { - return nil, "", UnknownFormatErr + return nil, "", ErrFormat } m, err := f.decode(rr) return m, f.name, err @@ -93,7 +93,7 @@ func DecodeConfig(r io.Reader) (Config, string, error) { rr := asReader(r) f := sniff(rr) if f.decodeConfig == nil { - return Config{}, "", UnknownFormatErr + return Config{}, "", ErrFormat } c, err := f.decodeConfig(rr) return c, f.name, err diff --git a/src/pkg/image/image.go b/src/pkg/image/image.go index 9dd676aced..63bfb7d59e 100644 --- a/src/pkg/image/image.go +++ b/src/pkg/image/image.go @@ -4,7 +4,20 @@ // Package image implements a basic 2-D image library. // -// See "The Go image package" for an introduction to this package: +// The fundamental interface is called Image. An Image contains colors, which +// are described in the image/color package. +// +// Values of the Image interface are created either by calling functions such +// as NewRGBA and NewPaletted, or by calling Decode on an io.Reader containing +// image data in a format such as GIF, JPEG or PNG. Decoding any particular +// image format requires the prior registration of a decoder function. +// Registration is typically automatic as a side effect of initializing that +// format's package so that, to decode a PNG image, it suffices to have +// import _ "image/png" +// in a program's main package. The _ means to import a package purely for its +// initialization side effects. +// +// See "The Go image package" for more details: // http://blog.golang.org/2011/09/go-image-package.html package image @@ -18,7 +31,8 @@ type Config struct { Width, Height int } -// Image is a finite rectangular grid of Colors drawn from a color model. +// Image is a finite rectangular grid of color.Color values taken from a color +// model. type Image interface { // ColorModel returns the Image's color model. ColorModel() color.Model @@ -42,7 +56,7 @@ type PalettedImage interface { Image } -// RGBA is an in-memory image of RGBAColor values. +// RGBA is an in-memory image whose At method returns color.RGBA values. type RGBA struct { // Pix holds the image's pixels, in R, G, B, A order. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*4]. @@ -137,7 +151,7 @@ func NewRGBA(r Rectangle) *RGBA { return &RGBA{buf, 4 * w, r} } -// RGBA64 is an in-memory image of RGBA64Color values. +// RGBA64 is an in-memory image whose At method returns color.RGBA64 values. type RGBA64 struct { // Pix holds the image's pixels, in R, G, B, A order and big-endian format. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*8]. @@ -245,7 +259,7 @@ func NewRGBA64(r Rectangle) *RGBA64 { return &RGBA64{pix, 8 * w, r} } -// NRGBA is an in-memory image of NRGBAColor values. +// NRGBA is an in-memory image whose At method returns color.NRGBA values. type NRGBA struct { // Pix holds the image's pixels, in R, G, B, A order. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*4]. @@ -340,7 +354,7 @@ func NewNRGBA(r Rectangle) *NRGBA { return &NRGBA{pix, 4 * w, r} } -// NRGBA64 is an in-memory image of NRGBA64Color values. +// NRGBA64 is an in-memory image whose At method returns color.NRGBA64 values. type NRGBA64 struct { // Pix holds the image's pixels, in R, G, B, A order and big-endian format. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*8]. @@ -448,7 +462,7 @@ func NewNRGBA64(r Rectangle) *NRGBA64 { return &NRGBA64{pix, 8 * w, r} } -// Alpha is an in-memory image of AlphaColor values. +// Alpha is an in-memory image whose At method returns color.Alpha values. type Alpha struct { // Pix holds the image's pixels, as alpha values. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*1]. @@ -536,7 +550,7 @@ func NewAlpha(r Rectangle) *Alpha { return &Alpha{pix, 1 * w, r} } -// Alpha16 is an in-memory image of Alpha16Color values. +// Alpha16 is an in-memory image whose At method returns color.Alpha64 values. type Alpha16 struct { // Pix holds the image's pixels, as alpha values in big-endian format. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*2]. @@ -627,7 +641,7 @@ func NewAlpha16(r Rectangle) *Alpha16 { return &Alpha16{pix, 2 * w, r} } -// Gray is an in-memory image of GrayColor values. +// Gray is an in-memory image whose At method returns color.Gray values. type Gray struct { // Pix holds the image's pixels, as gray values. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*1]. @@ -702,7 +716,7 @@ func NewGray(r Rectangle) *Gray { return &Gray{pix, 1 * w, r} } -// Gray16 is an in-memory image of Gray16Color values. +// Gray16 is an in-memory image whose At method returns color.Gray16 values. type Gray16 struct { // Pix holds the image's pixels, as gray values in big-endian format. The pixel at // (x, y) starts at Pix[(y-Rect.Min.Y)*Stride + (x-Rect.Min.X)*2]. diff --git a/src/pkg/image/names.go b/src/pkg/image/names.go index b830f88e1c..04616a5878 100644 --- a/src/pkg/image/names.go +++ b/src/pkg/image/names.go @@ -51,11 +51,15 @@ func NewUniform(c color.Color) *Uniform { return &Uniform{c} } -// Repeated is an infinite-sized Image that repeats another Image in both -// directions. Repeated{i, p}.At(x, y) will equal i.At(x+p.X, y+p.Y) for all -// points {x+p.X, y+p.Y} within i's Bounds. +// Repeated is an Image that is a source Image translated by -Offset and then +// repeated in all four directions to infinity. +// +// Repeated{src, off}.At(x, y) will equal src.At(x+off.X, y+off.Y) for all +// points {x+off.X, y+off.Y} within src's Bounds. type Repeated struct { - I Image + // I is the source image. + I Image + // Offset is the translation vector from result pixel to source pixel. Offset Point }