Class: GD2::Color

Inherits:
Object
  • Object
show all
Defined in:
lib/gd2/color.rb

Overview

Description

Color objects hold the red, green, blue, and alpha components for a pixel color. Color objects may also be linked to a particular palette index associated with an image.

Creating

Color objects are created by specifying the individual components:

red   = Color[1.0, 0.0, 0.0]
green = Color[0.0, 1.0, 0.0]
blue  = Color[0.0, 0.0, 1.0]

transparent_yellow = Color[1.0, 1.0, 0.0, 0.5]

The components may be specified as a percentage, as an explicit value between 0..RGB_MAX or 0..ALPHA_MAX, or as another color from which the associated component will be extracted.

Constant Summary collapse

BLACK = 
Color[0.0, 0.0, 0.0].freeze
WHITE = 
Color[1.0, 1.0, 1.0].freeze
TRANSPARENT = 
Color[0.0, 0.0, 0.0, ALPHA_TRANSPARENT].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(r, g, b, a = ALPHA_OPAQUE) ⇒ Color

Create a new Color object with the given component values.



79
80
81
82
83
84
85
86
 
# File 'lib/gd2/color.rb', line 79

def initialize(r, g, b, a = ALPHA_OPAQUE)
  r = self.class.normalize(r, RGB_MAX, :red)
  g = self.class.normalize(g, RGB_MAX, :green)
  b = self.class.normalize(b, RGB_MAX, :blue)
  a = self.class.normalize(a, ALPHA_MAX, :alpha)

  init_with_rgba(self.class.pack(r, g, b, a))
end

Instance Attribute Details

#index ⇒ Object (readonly)

The palette index of this color, if associated with an image palette



49
50
51
 
# File 'lib/gd2/color.rb', line 49

def index
  @index
end

#palette ⇒ Object (readonly)

The palette of this color, if associated with an image palette



52
53
54
 
# File 'lib/gd2/color.rb', line 52

def palette
  @palette
end

#rgba ⇒ Object Also known as: to_i

:nodoc:



46
47
48
 
# File 'lib/gd2/color.rb', line 46

def rgba
  @rgba
end

Class Method Details

.new_from_palette(r, g, b, a, index, palette) ⇒ Object

:nodoc:



92
93
94
 
# File 'lib/gd2/color.rb', line 92

def self.new_from_palette(r, g, b, a, index, palette)   #:nodoc:
  allocate.init_with_rgba(pack(r, g, b, a), index, palette)
end

.new_from_rgba(rgba) ⇒ Object

:nodoc:



88
89
90
 
# File 'lib/gd2/color.rb', line 88

def self.new_from_rgba(rgba)  #:nodoc:
  allocate.init_with_rgba(rgba)
end

.normalize(value, max, component = nil) ⇒ Object

:nodoc:



56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/gd2/color.rb', line 56

def self.normalize(value, max, component = nil)   #:nodoc:
  case value
  when Integer
    (value < 0) ? 0 : (value > max) ? max : value
  when Float
    normalize((value * max).round, max, component)
  when Color
    value.send(component)
  else
    return normalize(value.to_i, max) if value.respond_to?(:to_i)
    raise TypeError
  end
end

.pack(r, g, b, a) ⇒ Object

:nodoc:



70
71
72
 
# File 'lib/gd2/color.rb', line 70

def self.pack(r, g, b, a)   #:nodoc:
  (a << 24) + (r << 16) + (g << 8) + b
end

Instance Method Details

#==(other) ⇒ Object

Compare this color with another color. Returns true if the associated red, green, blue, and alpha components are identical.



129
130
131
 
# File 'lib/gd2/color.rb', line 129

def ==(other)
  other.kind_of?(Color) && rgba == other.rgba
end

#===(other) ⇒ Object

Return true if this color is visually identical to another color.



134
135
136
 
# File 'lib/gd2/color.rb', line 134

def ===(other)
  self == other || (self.transparent? && other.transparent?)
end

#alpha ⇒ Object Also known as: a

Return the alpha component of this color (0..ALPHA_MAX).



198
199
200
 
# File 'lib/gd2/color.rb', line 198

def alpha
  (rgba & 0x7F000000) >> 24
end

#alpha=(value) ⇒ Object Also known as: a=

Modify the alpha component of this color. If this color is associated with a palette entry, this also modifies the palette.



205
206
207
208
 
# File 'lib/gd2/color.rb', line 205

def alpha=(value)
  self.rgba = (rgba & ~0xFF000000) |
    (self.class.normalize(value, ALPHA_MAX, :alpha) << 24)
end

#alpha_blend(other) ⇒ Object

Like Color#alpha_blend! except returns a new Color without modifying the receiver.



221
222
223
 
# File 'lib/gd2/color.rb', line 221

def alpha_blend(other)
  dup.alpha_blend!(other)
end

#alpha_blend!(other) ⇒ Object Also known as: <<

Alpha blend this color with the given color. If this color is associated with a palette entry, this also modifies the palette.



213
214
215
216
 
# File 'lib/gd2/color.rb', line 213

def alpha_blend!(other)
  self.rgba = SYM[:gdAlphaBlend].call(rgba, other.rgba)[0]
  self
end

#blue ⇒ Object Also known as: b

Return the blue component of this color (0..RGB_MAX).



184
185
186
 
# File 'lib/gd2/color.rb', line 184

def blue
  rgba & 0x0000FF
end

#blue=(value) ⇒ Object Also known as: b=

Modify the blue component of this color. If this color is associated with a palette entry, this also modifies the palette.



191
192
193
194
 
# File 'lib/gd2/color.rb', line 191

def blue=(value)
  self.rgba = (rgba & ~0x0000FF) |
    self.class.normalize(value, RGB_MAX, :blue)
end

#eql?(other) ⇒ Boolean

Compare this color with another color in a manner that takes into account palette identities.

Returns:

  • (Boolean) 


140
141
142
143
144
 
# File 'lib/gd2/color.rb', line 140

def eql?(other)
  self == other &&
    (palette.nil? || other.palette.nil? ||
      (palette == other.palette && index == other.index))
end

#from_palette?(palette = nil) ⇒ Boolean

Return true if this color is associated with the specified palette, or with any palette if nil is given.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/gd2/color.rb', line 109

def from_palette?(palette = nil)
  @palette && @index && (palette.nil? || palette.equal?(@palette))
end

#green ⇒ Object Also known as: g

Return the green component of this color (0..RGB_MAX).



170
171
172
 
# File 'lib/gd2/color.rb', line 170

def green
  (rgba & 0x00FF00) >> 8
end

#green=(value) ⇒ Object Also known as: g=

Modify the green component of this color. If this color is associated with a palette entry, this also modifies the palette.



177
178
179
180
 
# File 'lib/gd2/color.rb', line 177

def green=(value)
  self.rgba = (rgba & ~0x00FF00) |
    (self.class.normalize(value, RGB_MAX, :green) << 8)
end

#hash ⇒ Object

:nodoc:



146
147
148
 
# File 'lib/gd2/color.rb', line 146

def hash  #:nodoc:
  rgba.hash
end

#init_with_rgba(rgba, index = nil, palette = nil) ⇒ Object

:nodoc:



96
97
98
99
100
101
 
# File 'lib/gd2/color.rb', line 96

def init_with_rgba(rgba, index = nil, palette = nil)  #:nodoc:
  @rgba = rgba
  @index = index
  @palette = palette
  self
end

#inspect ⇒ Object

:nodoc:



123
124
125
 
# File 'lib/gd2/color.rb', line 123

def inspect   #:nodoc:
  "<#{to_s}>"
end

#opaque? ⇒ Boolean

Return true if the alpha channel of this color is completely opaque.

Returns:

  • (Boolean) 


232
233
234
 
# File 'lib/gd2/color.rb', line 232

def opaque?
  alpha == ALPHA_OPAQUE
end

#red ⇒ Object Also known as: r

Return the red component of this color (0..RGB_MAX).



156
157
158
 
# File 'lib/gd2/color.rb', line 156

def red
  (rgba & 0xFF0000) >> 16
end

#red=(value) ⇒ Object Also known as: r=

Modify the red component of this color. If this color is associated with a palette entry, this also modifies the palette.



163
164
165
166
 
# File 'lib/gd2/color.rb', line 163

def red=(value)
  self.rgba = (rgba & ~0xFF0000) |
    (self.class.normalize(value, RGB_MAX, :red) << 16)
end

#to_s ⇒ Object

Return a string description of this color.



114
115
116
117
118
119
120
121
 
# File 'lib/gd2/color.rb', line 114

def to_s
  s  = 'RGB'
  s += "A" if alpha != ALPHA_OPAQUE
  s += "[#{@index}]" if @index
  s += '#' + [red, green, blue].map { |e| '%02X' % e }.join('')
  s += '%02X' % alpha if alpha != ALPHA_OPAQUE
  s
end

#transparent? ⇒ Boolean

Return true if the alpha channel of this color is completely transparent.

Returns:

  • (Boolean) 


227
228
229
 
# File 'lib/gd2/color.rb', line 227

def transparent?
  alpha == ALPHA_TRANSPARENT
end