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.



65
66
67
68
69
70
71
72
 
# File 'lib/gd2/color.rb', line 65

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



31
32
33
 
# File 'lib/gd2/color.rb', line 31

def index
  @index
end

#palette ⇒ Object (readonly)

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



34
35
36
 
# File 'lib/gd2/color.rb', line 34

def palette
  @palette
end

#rgba ⇒ Object Also known as: to_i

:nodoc:



28
29
30
 
# File 'lib/gd2/color.rb', line 28

def rgba
  @rgba
end

Class Method Details

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

:nodoc:



78
79
80
 
# File 'lib/gd2/color.rb', line 78

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:



74
75
76
 
# File 'lib/gd2/color.rb', line 74

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

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

:nodoc:



38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/gd2/color.rb', line 38

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:



52
53
54
55
56
57
58
 
# File 'lib/gd2/color.rb', line 52

def self.pack(r, g, b, a)   #:nodoc:
  r = r.read_int if r.is_a?(FFI::Pointer)
  g = g.read_int if g.is_a?(FFI::Pointer)
  b = b.read_int if b.is_a?(FFI::Pointer)
  a = a.read_int if a.is_a?(FFI::Pointer)
  (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.



115
116
117
 
# File 'lib/gd2/color.rb', line 115

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

#===(other) ⇒ Object

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



120
121
122
 
# File 'lib/gd2/color.rb', line 120

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).



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

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.



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

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.



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

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.



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

def alpha_blend!(other)
  self.rgba = ::GD2::GD2FFI.send(:gdAlphaBlend, rgba.to_i, other.rgba.to_i)
  self
end

#blue ⇒ Object Also known as: b

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



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

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.



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

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) 


126
127
128
129
130
 
# File 'lib/gd2/color.rb', line 126

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) 


95
96
97
 
# File 'lib/gd2/color.rb', line 95

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).



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

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.



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

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

#hash ⇒ Object

:nodoc:



132
133
134
 
# File 'lib/gd2/color.rb', line 132

def hash  #:nodoc:
  rgba.hash
end

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

:nodoc:



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

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

#inspect ⇒ Object

:nodoc:



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

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

#opaque? ⇒ Boolean

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

Returns:

  • (Boolean) 


218
219
220
 
# File 'lib/gd2/color.rb', line 218

def opaque?
  alpha == ALPHA_OPAQUE
end

#red ⇒ Object Also known as: r

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



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

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.



149
150
151
152
 
# File 'lib/gd2/color.rb', line 149

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.



100
101
102
103
104
105
106
107
 
# File 'lib/gd2/color.rb', line 100

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) 


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

def transparent?
  alpha == ALPHA_TRANSPARENT
end