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.



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

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:



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

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:



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

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
73
74
75
76
 
# File 'lib/gd2/color.rb', line 70

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.



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

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

#===(other) ⇒ Object

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



138
139
140
 
# File 'lib/gd2/color.rb', line 138

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



202
203
204
 
# File 'lib/gd2/color.rb', line 202

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.



209
210
211
212
 
# File 'lib/gd2/color.rb', line 209

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.



225
226
227
 
# File 'lib/gd2/color.rb', line 225

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.



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

def alpha_blend!(other)
  self.rgba = 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).



188
189
190
 
# File 'lib/gd2/color.rb', line 188

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.



195
196
197
198
 
# File 'lib/gd2/color.rb', line 195

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) 


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

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) 


113
114
115
 
# File 'lib/gd2/color.rb', line 113

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



174
175
176
 
# File 'lib/gd2/color.rb', line 174

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.



181
182
183
184
 
# File 'lib/gd2/color.rb', line 181

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

#hash ⇒ Object

:nodoc:



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

def hash  #:nodoc:
  rgba.hash
end

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

:nodoc:



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

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

#inspect ⇒ Object

:nodoc:



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

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

#opaque? ⇒ Boolean

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

Returns:

  • (Boolean) 


236
237
238
 
# File 'lib/gd2/color.rb', line 236

def opaque?
  alpha == ALPHA_OPAQUE
end

#red ⇒ Object Also known as: r

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



160
161
162
 
# File 'lib/gd2/color.rb', line 160

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.



167
168
169
170
 
# File 'lib/gd2/color.rb', line 167

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.



118
119
120
121
122
123
124
125
 
# File 'lib/gd2/color.rb', line 118

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) 


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

def transparent?
  alpha == ALPHA_TRANSPARENT
end