color.go

Documentation: image/color

		 1  // Copyright 2011 The Go Authors. All rights reserved.
		 2  // Use of this source code is governed by a BSD-style
		 3  // license that can be found in the LICENSE file.
		 4  
		 5  // Package color implements a basic color library.
		 6  package color
		 7  
		 8  // Color can convert itself to alpha-premultiplied 16-bits per channel RGBA.
		 9  // The conversion may be lossy.
		10  type Color interface {
		11  	// RGBA returns the alpha-premultiplied red, green, blue and alpha values
		12  	// for the color. Each value ranges within [0, 0xffff], but is represented
		13  	// by a uint32 so that multiplying by a blend factor up to 0xffff will not
		14  	// overflow.
		15  	//
		16  	// An alpha-premultiplied color component c has been scaled by alpha (a),
		17  	// so has valid values 0 <= c <= a.
		18  	RGBA() (r, g, b, a uint32)
		19  }
		20  
		21  // RGBA represents a traditional 32-bit alpha-premultiplied color, having 8
		22  // bits for each of red, green, blue and alpha.
		23  //
		24  // An alpha-premultiplied color component C has been scaled by alpha (A), so
		25  // has valid values 0 <= C <= A.
		26  type RGBA struct {
		27  	R, G, B, A uint8
		28  }
		29  
		30  func (c RGBA) RGBA() (r, g, b, a uint32) {
		31  	r = uint32(c.R)
		32  	r |= r << 8
		33  	g = uint32(c.G)
		34  	g |= g << 8
		35  	b = uint32(c.B)
		36  	b |= b << 8
		37  	a = uint32(c.A)
		38  	a |= a << 8
		39  	return
		40  }
		41  
		42  // RGBA64 represents a 64-bit alpha-premultiplied color, having 16 bits for
		43  // each of red, green, blue and alpha.
		44  //
		45  // An alpha-premultiplied color component C has been scaled by alpha (A), so
		46  // has valid values 0 <= C <= A.
		47  type RGBA64 struct {
		48  	R, G, B, A uint16
		49  }
		50  
		51  func (c RGBA64) RGBA() (r, g, b, a uint32) {
		52  	return uint32(c.R), uint32(c.G), uint32(c.B), uint32(c.A)
		53  }
		54  
		55  // NRGBA represents a non-alpha-premultiplied 32-bit color.
		56  type NRGBA struct {
		57  	R, G, B, A uint8
		58  }
		59  
		60  func (c NRGBA) RGBA() (r, g, b, a uint32) {
		61  	r = uint32(c.R)
		62  	r |= r << 8
		63  	r *= uint32(c.A)
		64  	r /= 0xff
		65  	g = uint32(c.G)
		66  	g |= g << 8
		67  	g *= uint32(c.A)
		68  	g /= 0xff
		69  	b = uint32(c.B)
		70  	b |= b << 8
		71  	b *= uint32(c.A)
		72  	b /= 0xff
		73  	a = uint32(c.A)
		74  	a |= a << 8
		75  	return
		76  }
		77  
		78  // NRGBA64 represents a non-alpha-premultiplied 64-bit color,
		79  // having 16 bits for each of red, green, blue and alpha.
		80  type NRGBA64 struct {
		81  	R, G, B, A uint16
		82  }
		83  
		84  func (c NRGBA64) RGBA() (r, g, b, a uint32) {
		85  	r = uint32(c.R)
		86  	r *= uint32(c.A)
		87  	r /= 0xffff
		88  	g = uint32(c.G)
		89  	g *= uint32(c.A)
		90  	g /= 0xffff
		91  	b = uint32(c.B)
		92  	b *= uint32(c.A)
		93  	b /= 0xffff
		94  	a = uint32(c.A)
		95  	return
		96  }
		97  
		98  // Alpha represents an 8-bit alpha color.
		99  type Alpha struct {
	 100  	A uint8
	 101  }
	 102  
	 103  func (c Alpha) RGBA() (r, g, b, a uint32) {
	 104  	a = uint32(c.A)
	 105  	a |= a << 8
	 106  	return a, a, a, a
	 107  }
	 108  
	 109  // Alpha16 represents a 16-bit alpha color.
	 110  type Alpha16 struct {
	 111  	A uint16
	 112  }
	 113  
	 114  func (c Alpha16) RGBA() (r, g, b, a uint32) {
	 115  	a = uint32(c.A)
	 116  	return a, a, a, a
	 117  }
	 118  
	 119  // Gray represents an 8-bit grayscale color.
	 120  type Gray struct {
	 121  	Y uint8
	 122  }
	 123  
	 124  func (c Gray) RGBA() (r, g, b, a uint32) {
	 125  	y := uint32(c.Y)
	 126  	y |= y << 8
	 127  	return y, y, y, 0xffff
	 128  }
	 129  
	 130  // Gray16 represents a 16-bit grayscale color.
	 131  type Gray16 struct {
	 132  	Y uint16
	 133  }
	 134  
	 135  func (c Gray16) RGBA() (r, g, b, a uint32) {
	 136  	y := uint32(c.Y)
	 137  	return y, y, y, 0xffff
	 138  }
	 139  
	 140  // Model can convert any Color to one from its own color model. The conversion
	 141  // may be lossy.
	 142  type Model interface {
	 143  	Convert(c Color) Color
	 144  }
	 145  
	 146  // ModelFunc returns a Model that invokes f to implement the conversion.
	 147  func ModelFunc(f func(Color) Color) Model {
	 148  	// Note: using *modelFunc as the implementation
	 149  	// means that callers can still use comparisons
	 150  	// like m == RGBAModel. This is not possible if
	 151  	// we use the func value directly, because funcs
	 152  	// are no longer comparable.
	 153  	return &modelFunc{f}
	 154  }
	 155  
	 156  type modelFunc struct {
	 157  	f func(Color) Color
	 158  }
	 159  
	 160  func (m *modelFunc) Convert(c Color) Color {
	 161  	return m.f(c)
	 162  }
	 163  
	 164  // Models for the standard color types.
	 165  var (
	 166  	RGBAModel		Model = ModelFunc(rgbaModel)
	 167  	RGBA64Model	Model = ModelFunc(rgba64Model)
	 168  	NRGBAModel	 Model = ModelFunc(nrgbaModel)
	 169  	NRGBA64Model Model = ModelFunc(nrgba64Model)
	 170  	AlphaModel	 Model = ModelFunc(alphaModel)
	 171  	Alpha16Model Model = ModelFunc(alpha16Model)
	 172  	GrayModel		Model = ModelFunc(grayModel)
	 173  	Gray16Model	Model = ModelFunc(gray16Model)
	 174  )
	 175  
	 176  func rgbaModel(c Color) Color {
	 177  	if _, ok := c.(RGBA); ok {
	 178  		return c
	 179  	}
	 180  	r, g, b, a := c.RGBA()
	 181  	return RGBA{uint8(r >> 8), uint8(g >> 8), uint8(b >> 8), uint8(a >> 8)}
	 182  }
	 183  
	 184  func rgba64Model(c Color) Color {
	 185  	if _, ok := c.(RGBA64); ok {
	 186  		return c
	 187  	}
	 188  	r, g, b, a := c.RGBA()
	 189  	return RGBA64{uint16(r), uint16(g), uint16(b), uint16(a)}
	 190  }
	 191  
	 192  func nrgbaModel(c Color) Color {
	 193  	if _, ok := c.(NRGBA); ok {
	 194  		return c
	 195  	}
	 196  	r, g, b, a := c.RGBA()
	 197  	if a == 0xffff {
	 198  		return NRGBA{uint8(r >> 8), uint8(g >> 8), uint8(b >> 8), 0xff}
	 199  	}
	 200  	if a == 0 {
	 201  		return NRGBA{0, 0, 0, 0}
	 202  	}
	 203  	// Since Color.RGBA returns an alpha-premultiplied color, we should have r <= a && g <= a && b <= a.
	 204  	r = (r * 0xffff) / a
	 205  	g = (g * 0xffff) / a
	 206  	b = (b * 0xffff) / a
	 207  	return NRGBA{uint8(r >> 8), uint8(g >> 8), uint8(b >> 8), uint8(a >> 8)}
	 208  }
	 209  
	 210  func nrgba64Model(c Color) Color {
	 211  	if _, ok := c.(NRGBA64); ok {
	 212  		return c
	 213  	}
	 214  	r, g, b, a := c.RGBA()
	 215  	if a == 0xffff {
	 216  		return NRGBA64{uint16(r), uint16(g), uint16(b), 0xffff}
	 217  	}
	 218  	if a == 0 {
	 219  		return NRGBA64{0, 0, 0, 0}
	 220  	}
	 221  	// Since Color.RGBA returns an alpha-premultiplied color, we should have r <= a && g <= a && b <= a.
	 222  	r = (r * 0xffff) / a
	 223  	g = (g * 0xffff) / a
	 224  	b = (b * 0xffff) / a
	 225  	return NRGBA64{uint16(r), uint16(g), uint16(b), uint16(a)}
	 226  }
	 227  
	 228  func alphaModel(c Color) Color {
	 229  	if _, ok := c.(Alpha); ok {
	 230  		return c
	 231  	}
	 232  	_, _, _, a := c.RGBA()
	 233  	return Alpha{uint8(a >> 8)}
	 234  }
	 235  
	 236  func alpha16Model(c Color) Color {
	 237  	if _, ok := c.(Alpha16); ok {
	 238  		return c
	 239  	}
	 240  	_, _, _, a := c.RGBA()
	 241  	return Alpha16{uint16(a)}
	 242  }
	 243  
	 244  func grayModel(c Color) Color {
	 245  	if _, ok := c.(Gray); ok {
	 246  		return c
	 247  	}
	 248  	r, g, b, _ := c.RGBA()
	 249  
	 250  	// These coefficients (the fractions 0.299, 0.587 and 0.114) are the same
	 251  	// as those given by the JFIF specification and used by func RGBToYCbCr in
	 252  	// ycbcr.go.
	 253  	//
	 254  	// Note that 19595 + 38470 + 7471 equals 65536.
	 255  	//
	 256  	// The 24 is 16 + 8. The 16 is the same as used in RGBToYCbCr. The 8 is
	 257  	// because the return value is 8 bit color, not 16 bit color.
	 258  	y := (19595*r + 38470*g + 7471*b + 1<<15) >> 24
	 259  
	 260  	return Gray{uint8(y)}
	 261  }
	 262  
	 263  func gray16Model(c Color) Color {
	 264  	if _, ok := c.(Gray16); ok {
	 265  		return c
	 266  	}
	 267  	r, g, b, _ := c.RGBA()
	 268  
	 269  	// These coefficients (the fractions 0.299, 0.587 and 0.114) are the same
	 270  	// as those given by the JFIF specification and used by func RGBToYCbCr in
	 271  	// ycbcr.go.
	 272  	//
	 273  	// Note that 19595 + 38470 + 7471 equals 65536.
	 274  	y := (19595*r + 38470*g + 7471*b + 1<<15) >> 16
	 275  
	 276  	return Gray16{uint16(y)}
	 277  }
	 278  
	 279  // Palette is a palette of colors.
	 280  type Palette []Color
	 281  
	 282  // Convert returns the palette color closest to c in Euclidean R,G,B space.
	 283  func (p Palette) Convert(c Color) Color {
	 284  	if len(p) == 0 {
	 285  		return nil
	 286  	}
	 287  	return p[p.Index(c)]
	 288  }
	 289  
	 290  // Index returns the index of the palette color closest to c in Euclidean
	 291  // R,G,B,A space.
	 292  func (p Palette) Index(c Color) int {
	 293  	// A batch version of this computation is in image/draw/draw.go.
	 294  
	 295  	cr, cg, cb, ca := c.RGBA()
	 296  	ret, bestSum := 0, uint32(1<<32-1)
	 297  	for i, v := range p {
	 298  		vr, vg, vb, va := v.RGBA()
	 299  		sum := sqDiff(cr, vr) + sqDiff(cg, vg) + sqDiff(cb, vb) + sqDiff(ca, va)
	 300  		if sum < bestSum {
	 301  			if sum == 0 {
	 302  				return i
	 303  			}
	 304  			ret, bestSum = i, sum
	 305  		}
	 306  	}
	 307  	return ret
	 308  }
	 309  
	 310  // sqDiff returns the squared-difference of x and y, shifted by 2 so that
	 311  // adding four of those won't overflow a uint32.
	 312  //
	 313  // x and y are both assumed to be in the range [0, 0xffff].
	 314  func sqDiff(x, y uint32) uint32 {
	 315  	// The canonical code of this function looks as follows:
	 316  	//
	 317  	//	var d uint32
	 318  	//	if x > y {
	 319  	//		d = x - y
	 320  	//	} else {
	 321  	//		d = y - x
	 322  	//	}
	 323  	//	return (d * d) >> 2
	 324  	//
	 325  	// Language spec guarantees the following properties of unsigned integer
	 326  	// values operations with respect to overflow/wrap around:
	 327  	//
	 328  	// > For unsigned integer values, the operations +, -, *, and << are
	 329  	// > computed modulo 2n, where n is the bit width of the unsigned
	 330  	// > integer's type. Loosely speaking, these unsigned integer operations
	 331  	// > discard high bits upon overflow, and programs may rely on ``wrap
	 332  	// > around''.
	 333  	//
	 334  	// Considering these properties and the fact that this function is
	 335  	// called in the hot paths (x,y loops), it is reduced to the below code
	 336  	// which is slightly faster. See TestSqDiff for correctness check.
	 337  	d := x - y
	 338  	return (d * d) >> 2
	 339  }
	 340  
	 341  // Standard colors.
	 342  var (
	 343  	Black			 = Gray16{0}
	 344  	White			 = Gray16{0xffff}
	 345  	Transparent = Alpha16{0}
	 346  	Opaque			= Alpha16{0xffff}
	 347  )
	 348
View as plain text