Source file src/pkg/image/color/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