color.go

     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