class GD2::Palette

Description

Palette objects are associated with an Image and hold the selection of pixel colors available to the Image. This is primarily a concern for Image::IndexedColor images, but their use with Image::TrueColor images is supported for consistency.

Obtaining

Obtain a Palette object from the associated Image:

palette = image.palette

Attributes

image[R]

The Image associated with this Palette

Public Instance Methods

<<(color) click to toggle source

Ensure the given color is present in this palette, allocating it if necessary. Returns the palette so calls may be stacked.

# File lib/gd2/palette.rb, line 140
def <<(color)
  exact(color) or allocate(color)
  self
end
[](index) click to toggle source

Return the color allocated to the specified index, or nil if the entry is unallocated.

# File lib/gd2/palette.rb, line 56
def [](index)
  index = size + index if index < 0
  raise RangeError unless (0...size).include? index
  return nil unless allocated?(index)
  get_color(index)
end
[]=(index, color) click to toggle source

Assign (allocate) the given color to the palette entry identified by index. If the entry was previously allocated to a different color, every pixel in the image having the given color index will effectively be changed to the new color. This method cannot be used with Image::TrueColor palettes.

# File lib/gd2/palette.rb, line 68
def []=(index, color)
  raise RangeError unless (0...MAX_COLORS).include? index
  if color.nil?
    deallocate(self[index] ||
      Color.new_from_palette(0, 0, 0, 0, index, self))
  else
    ptr = @image.image_ptr
    ptr[:red][index] = color.red
    ptr[:green][index] = color.green
    ptr[:blue][index] = color.blue
    ptr[:alpha][index] = color.alpha
    ptr[:open][index] = 0
  end
end
allocate(color) click to toggle source

Assign the given color to an unoccupied entry in this palette and return it. Does not check whether the color is already allocated, and raises an error for Image::IndexedColor palettes if the palette is full.

# File lib/gd2/palette.rb, line 130
def allocate(color)
  raise TypeError unless color.kind_of? Color
  c = ::GD2::GD2FFI.send(:gdImageColorAllocateAlpha, @image.image_ptr,
    color.red.to_i, color.green.to_i, color.blue.to_i, color.alpha.to_i)
  c == -1 ? raise(Palette::PaletteFullError, 'Palette is full') :
    get_color(c)
end
available() click to toggle source

Return the number of palette entries available to be allocated for new colors.

# File lib/gd2/palette.rb, line 50
def available
  size - used
end
closest(color) click to toggle source

Return the color in this palette that is closest to the given color according to Euclidian distance.

# File lib/gd2/palette.rb, line 111
def closest(color)
  raise TypeError unless color.kind_of? Color
  c = ::GD2::GD2FFI.send(:gdImageColorClosestAlpha, @image.image_ptr,
    color.red.to_i, color.green.to_i, color.blue.to_i, color.alpha.to_i)
  c == -1 ? nil : get_color(c)
end
closest_hwb(color) click to toggle source

Return the color in this palette that is closest to the given color according to hue, whiteness, and blackness.

# File lib/gd2/palette.rb, line 120
def closest_hwb(color)
  raise TypeError unless color.kind_of? Color
  c = ::GD2::GD2FFI.send(:gdImageColorClosestHWB, @image.image_ptr,
    color.red.to_i, color.green.to_i, color.blue.to_i)
  c == -1 ? nil : get_color(c)
end
deallocate(color) click to toggle source

Remove the given color from this palette.

# File lib/gd2/palette.rb, line 146
def deallocate(color)
  color = exact(color) unless color.index
  return nil if color.nil? || color.index.nil?
  ::GD2::GD2FFI.send(:gdImageColorDeallocate, @image.image_ptr, color.index.to_i)
  nil
end
deallocate_unused() click to toggle source

Remove all colors from this palette that are not currently in use by the associated Image. This is an expensive operation. Returns the number of palette entries deallocated.

# File lib/gd2/palette.rb, line 156
def deallocate_unused
  # implemented by subclass
end
exact(color) click to toggle source

Locate the given color in this palette and return it. Returns nil if the color is not presently in the palette.

# File lib/gd2/palette.rb, line 95
def exact(color)
  raise TypeError unless color.kind_of? Color
  c = ::GD2::GD2FFI.send(:gdImageColorExactAlpha, @image.image_ptr,
    color.red.to_i, color.green.to_i, color.blue.to_i, color.alpha.to_i)
  c == -1 ? nil : get_color(c)
end
exact!(color) click to toggle source

Like Palette#exact except an error is raised if the color is not presently in the palette.

# File lib/gd2/palette.rb, line 104
def exact!(color)
  exact(color) or raise Palette::ColorNotFoundError,
    "Color #{color} is not in the palette"
end
length()
Alias for: size
resolve(color) click to toggle source

Locate the given color in this palette and return it if found; otherwise try to allocate the color, or if the palette is full, return a color from the palette that is closest to it.

# File lib/gd2/palette.rb, line 86
def resolve(color)
  raise TypeError unless color.kind_of? Color
  c = ::GD2::GD2FFI.send(:gdImageColorResolveAlpha, @image.image_ptr,
    color.red.to_i, color.green.to_i, color.blue.to_i, color.alpha.to_i)
  c == -1 ? nil : get_color(c)
end
size() click to toggle source

Return the maximum number of colors this palette can hold.

# File lib/gd2/palette.rb, line 31
def size
  MAX_COLORS
end
Also aliased as: length
used() click to toggle source

Return the number of colors presently allocated in this palette.

# File lib/gd2/palette.rb, line 42
def used
  (0...size).inject(0) do |sum, i|
    sum + (allocated?(i) ? 1 : 0)
  end
end