Module: ChunkyPNG::Color

### Home Classes Methods

### In Files

- lib/chunky_png/color.rb

### Methods

- #a
- #alpha_decomposable?
- #b
- #blend
- #compose
- #compose_precise
- #compose_quick
- #decompose_alpha
- #decompose_alpha_component
- #decompose_alpha_components
- #decompose_color
- #euclidean_distance_rgba
- #fade
- #from_hex
- #from_hsb
- #from_hsl
- #from_hsv
- #from_rgb_stream
- #from_rgba_stream
- #fully_transparent?
- #g
- #grayscale
- #grayscale?
- #grayscale_alpha
- #grayscale_teint
- #html_color
- #int8_mult
- #interpolate_quick
- #opaque!
- #opaque?
- #parse
- #pass_bytesize
- #pixel_bitsize
- #pixel_bytesize
- #r
- #rgb
- #rgba
- #samples_per_pixel
- #scanline_bytesize
- #to_grayscale
- #to_grayscale_alpha_bytes
- #to_grayscale_bytes
- #to_hex
- #to_hsb
- #to_hsl
- #to_hsv
- #to_truecolor_alpha_bytes
- #to_truecolor_bytes

### Files

- BENCHMARKING.rdoc
- CHANGELOG.rdoc
- CONTRIBUTING.rdoc
- README.rdoc

### Class/Module Index

Quicksearch

- ChunkyPNG
- ChunkyPNG::CRCMismatch
- ChunkyPNG::Canvas
- ChunkyPNG::Canvas::Adam7Interlacing
- ChunkyPNG::Canvas::DataUrlExporting
- ChunkyPNG::Canvas::DataUrlImporting
- ChunkyPNG::Canvas::Drawing
- ChunkyPNG::Canvas::Masking
- ChunkyPNG::Canvas::Operations
- ChunkyPNG::Canvas::PNGDecoding
- ChunkyPNG::Canvas::PNGEncoding
- ChunkyPNG::Canvas::Resampling
- ChunkyPNG::Canvas::StreamExporting
- ChunkyPNG::Canvas::StreamImporting
- ChunkyPNG::Chunk
- ChunkyPNG::Chunk::Base
- ChunkyPNG::Chunk::CompressedText
- ChunkyPNG::Chunk::End
- ChunkyPNG::Chunk::Generic
- ChunkyPNG::Chunk::Header
- ChunkyPNG::Chunk::ImageData
- ChunkyPNG::Chunk::InternationalText
- ChunkyPNG::Chunk::Palette
- ChunkyPNG::Chunk::Text
- ChunkyPNG::Chunk::Transparency
- ChunkyPNG::Color
- ChunkyPNG::Datastream
- ChunkyPNG::Dimension
- ChunkyPNG::Exception
- ChunkyPNG::ExpectationFailed
- ChunkyPNG::Image
- ChunkyPNG::NotSupported
- ChunkyPNG::OutOfBounds
- ChunkyPNG::Palette
- ChunkyPNG::Point
- ChunkyPNG::RMagick
- ChunkyPNG::SignatureMismatch
- ChunkyPNG::Vector
- Enumerable
- String

No matching classes.

# ChunkyPNG::Color

The Color module defines methods for handling colors. Within the ChunkyPNG library, the concepts of pixels and colors are both used, and they are both represented by a Integer.

Pixels/colors are represented in RGBA components. Each of the four components is stored with a depth of 8 bits (maximum value = 255 = {ChunkyPNG::Color::MAX}). Together, these components are stored in a 4-byte Integer.

A color will always be represented using these 4 components in memory. When the image is encoded, a more suitable representation can be used (e.g. rgb, grayscale, palette-based), for which several conversion methods are provided in this module.

### Constants

BLACK

  @return [Integer] Black pixel/color

HEX3_COLOR_REGEXP

  @private @return [Regexp] The regexp to parse 3-digit hex color values.

HEX6_COLOR_REGEXP

  @private @return [Regexp] The regexp to parse 6- and 8-digit hex color values.

HTML_COLOR_REGEXP

  @private @return [Regexp] The regexp to parse named color values.

MAX

  @return [Integer] The maximum value of each color component.

MAX_EUCLIDEAN_DISTANCE_RGBA

  Could be simplified as MAX * 2, but this format mirrors the math in {euclidean_distance_rgba} @return [Float] The maximum Euclidean distance of two RGBA colors.

PREDEFINED_COLORS

  @return [Hash<Symbol, Integer>] All the predefined color names in HTML.

TRANSPARENT

  @return [Integer] Fully transparent pixel/color

WHITE

  @return [Integer] White pixel/color

### Public Instance Methods

a(value) click to toggle source

Returns the alpha channel value for the color value.

@param [Integer] value The color value. @return [Integer] A value between 0 and MAX.

    # File lib/chunky_png/color.rb, line 296
    def a(value)
      value & 0x000000ff
    end

alpha_decomposable?(color, mask, bg, tolerance = 1) click to toggle source

Checks whether an alpha channel value can successfully be composed given the resulting color, the mask color and a background color, all of which should be opaque.

@param [Integer] color The color that was the result of compositing. @param [Integer] mask The opaque variant of the color that was being

    composed

@param [Integer] bg The background color on which the color was composed. @param [Integer] tolerance The decomposition tolerance level, a value

    between 0 and 255.

@return [Boolean] True if the alpha component can be decomposed

    successfully.

@see decompose_alpha

    # File lib/chunky_png/color.rb, line 500
    def alpha_decomposable?(color, mask, bg, tolerance = 1)
      components = decompose_alpha_components(color, mask, bg)
      sum = components.inject(0) { |a,b| a + b }
      max = components.max * 3
      components.max <= 255 && components.min >= 0 && (sum + tolerance * 3) >= max
    end

b(value) click to toggle source

Returns the blue-component from the color value.

@param [Integer] value The color value. @return [Integer] A value between 0 and MAX.

    # File lib/chunky_png/color.rb, line 288
    def b(value)
      (value & 0x0000ff00) >> 8
    end

blend(fg, bg) click to toggle source

Blends the foreground and background color by taking the average of the components.

@param [Integer] fg The foreground color. @param [Integer] bg The foreground color. @return [Integer] The blended color.

    # File lib/chunky_png/color.rb, line 403
    def blend(fg, bg)
      (fg + bg) >> 1
    end

compose(fg, bg) click to toggle source
Alias for: compose_quick
compose_precise(fg, bg) click to toggle source

Composes two colors with an alpha channel using floating point math.

This method uses more precise floating point math, but this precision is lost when the result is converted back to an integer. Because it is slower than the version based on integer math, that version is preferred.

@param [Integer] fg The foreground color. @param [Integer] bg The background color. @return [Integer] The composited color. @see ChunkyPNG::Color#compose_quick

    # File lib/chunky_png/color.rb, line 380
    def compose_precise(fg, bg)
      return fg if opaque?(fg) || fully_transparent?(bg)
      return bg if fully_transparent?(fg)

      fg_a  = a(fg).to_f / MAX
      bg_a  = a(bg).to_f / MAX
      a_com = (1.0 - fg_a) * bg_a

      new_r = (fg_a * r(fg) + a_com * r(bg)).round
      new_g = (fg_a * g(fg) + a_com * g(bg)).round
      new_b = (fg_a * b(fg) + a_com * b(bg)).round
      new_a = ((fg_a + a_com) * MAX).round
      rgba(new_r, new_g, new_b, new_a)
    end

compose_quick(fg, bg) click to toggle source

Composes two colors with an alpha channel using integer math.

This version is faster than the version based on floating point math, so this compositing function is used by default.

@param [Integer] fg The foreground color. @param [Integer] bg The background color. @return [Integer] The composited color. @see ChunkyPNG::Color#compose_precise

    # File lib/chunky_png/color.rb, line 358
    def compose_quick(fg, bg)
      return fg if opaque?(fg) || fully_transparent?(bg)
      return bg if fully_transparent?(fg)

      a_com = int8_mult(0xff - a(fg), a(bg))
      new_r = int8_mult(a(fg), r(fg)) + int8_mult(a_com, r(bg))
      new_g = int8_mult(a(fg), g(fg)) + int8_mult(a_com, g(bg))
      new_b = int8_mult(a(fg), b(fg)) + int8_mult(a_com, b(bg))
      new_a = a(fg) + a_com
      rgba(new_r, new_g, new_b, new_a)
    end

Also aliased as: compose
decompose_alpha(color, mask, bg) click to toggle source

Decomposes the alpha channel value given the resulting color, the mask color and a background color, all of which should be opaque.

Make sure to call {alpha_decomposable?} first to see if the alpha channel value can successfully decomposed with a given tolerance, otherwise the return value of this method is undefined.

@param [Integer] color The color that was the result of compositing. @param [Integer] mask The opaque variant of the color that was being

    composed

@param [Integer] bg The background color on which the color was composed. @return [Integer] The best fitting alpha channel, a value between 0 and

    255.

@see alpha_decomposable?

    # File lib/chunky_png/color.rb, line 521
    def decompose_alpha(color, mask, bg)
      components = decompose_alpha_components(color, mask, bg)
      (components.inject(0) { |a,b| a + b } / 3.0).round
    end

decompose_alpha_component(channel, color, mask, bg) click to toggle source

Decomposes an alpha channel for either the r, g or b color channel. @param [:r, :g, :b] channel The channel to decompose the alpha channel

    from.

@param [Integer] color The color that was the result of compositing. @param [Integer] mask The opaque variant of the color that was being

    composed

@param [Integer] bg The background color on which the color was composed. @return [Integer] The decomposed alpha value for the channel.

    # File lib/chunky_png/color.rb, line 534
    def decompose_alpha_component(channel, color, mask, bg)
      cc, mc, bc = send(channel, color), send(channel, mask), send(channel, bg)

      return 0x00 if bc == cc
      return 0xff if bc == mc
      return 0xff if cc == mc

      (((bc - cc).to_f / (bc - mc).to_f) * MAX).round
    end

decompose_alpha_components(color, mask, bg) click to toggle source

Decomposes the alpha channels for the r, g and b color channel. @param [Integer] color The color that was the result of compositing. @param [Integer] mask The opaque variant of the color that was being

    composed

@param [Integer] bg The background color on which the color was composed. @return [Array<Integer>] The decomposed alpha values for the r, g and b

    channels.

    # File lib/chunky_png/color.rb, line 551
    def decompose_alpha_components(color, mask, bg)
      [
        decompose_alpha_component(:r, color, mask, bg),
        decompose_alpha_component(:g, color, mask, bg),
        decompose_alpha_component(:b, color, mask, bg)
      ]
    end

decompose_color(color, mask, bg, tolerance = 1) click to toggle source

Decomposes a color, given a color, a mask color and a background color. The returned color will be a variant of the mask color, with the alpha channel set to the best fitting value. This basically is the reverse operation if alpha composition.

If the color cannot be decomposed, this method will return the fully transparent variant of the mask color.

@param [Integer] color The color that was the result of compositing. @param [Integer] mask The opaque variant of the color that was being

    composed

@param [Integer] bg The background color on which the color was composed. @param [Integer] tolerance The decomposition tolerance level, a value

    between 0 and 255.

@return [Integer] The decomposed color, a variant of the masked color

    with the alpha channel set to an appropriate value.

    # File lib/chunky_png/color.rb, line 479
    def decompose_color(color, mask, bg, tolerance = 1)
      if alpha_decomposable?(color, mask, bg, tolerance)
        mask & 0xffffff00 | decompose_alpha(color, mask, bg)
      else
        mask & 0xffffff00
      end
    end

euclidean_distance_rgba(pixel_after, pixel_before) click to toggle source

Compute the Euclidean distance between 2 colors in RGBA

This method simply takes the Euclidean distance between the RGBA channels of 2 colors, which gives us a measure of how different the two colors are.

Although it would be more perceptually accurate to calculate a proper Delta E in Lab colorspace, this method should serve many use-cases while avoiding the overhead of converting RGBA to Lab.

@param pixel_after [Integer] @param pixel_before [Integer] @return [Float]

    # File lib/chunky_png/color.rb, line 716
    def euclidean_distance_rgba(pixel_after, pixel_before)
      Math.sqrt(
        (r(pixel_after) - r(pixel_before))**2 +
        (g(pixel_after) - g(pixel_before))**2 +
        (b(pixel_after) - b(pixel_before))**2 +
        (a(pixel_after) - a(pixel_before))**2
      )
    end

fade(color, factor) click to toggle source

Lowers the intensity of a color, by lowering its alpha by a given factor. @param [Integer] color The color to adjust. @param [Integer] factor Fade factor as an integer between 0 and 255. @return [Integer] The faded color.

    # File lib/chunky_png/color.rb, line 458
    def fade(color, factor)
      new_alpha = int8_mult(a(color), factor)
      (color & 0xffffff00) | new_alpha
    end

from_hex(hex_value, opacity = nil) click to toggle source

Creates a color by converting it from a string in hex notation.

It supports colors with (rrggbbaa) or without (rrggbb) alpha channel as well as the 3-digit short format (rgb) for those without. Color strings may include the prefix "0x" or "#".

@param [String] str The color in hex notation. @return [Integer] The

    converted color value.

@param [Integer] opacity The opacity value for the color. Overrides any

    opacity value given in the hex value if given.

@return [Integer] The color value. @raise [ArgumentError] if the value given is not a hex color notation.

    # File lib/chunky_png/color.rb, line 166
    def from_hex(hex_value, opacity = nil)
      base_color = case hex_value
                   when HEX3_COLOR_REGEXP
                     $1.gsub(/([0-9a-f])/, '\1\1').hex << 8
                   when HEX6_COLOR_REGEXP
                     $1.hex << 8
                   else
                     raise ArgumentError, "Not a valid hex color notation: #{hex_value.inspect}!"
                   end
      opacity  ||= $2 ? $2.hex : 0xff
      base_color | opacity
    end

from_hsb(hue, saturation, value, alpha = 255) click to toggle source
Alias for: from_hsv
from_hsl(hue, saturation, lightness, alpha = 255) click to toggle source

Creates a new color from an HSL triple.

This implementation follows the modern convention of 0 degrees hue indicating red.

@param [Fixnum] hue The hue component (0-360) @param [Fixnum] saturation The saturation component (0-1) @param [Fixnum] lightness The lightness component (0-1) @param [Fixnum] alpha Defaults to opaque (255). @return [Integer] The newly constructed color value. @raise [ArgumentError] if the hsl triple is invalid. @see en.wikipedia.org/wiki/HSL_and_HSV

    # File lib/chunky_png/color.rb, line 217
    def from_hsl(hue, saturation, lightness, alpha = 255)
      raise ArgumentError, "Hue #{hue} was not between 0 and 360" unless (0..360).include?(hue)
      raise ArgumentError, "Saturation #{saturation} was not between 0 and 1" unless (0..1).include?(saturation)
      raise ArgumentError, "Lightness #{lightness} was not between 0 and 1" unless (0..1).include?(lightness)
      chroma = (1 - (2 * lightness - 1).abs) * saturation
      rgb    = cylindrical_to_cubic(hue, saturation, lightness, chroma)
      rgb.map! { |component| ((component + lightness - 0.5 * chroma) * 255).to_i }
      rgb << alpha
      self.rgba(*rgb)
    end

from_hsv(hue, saturation, value, alpha = 255) click to toggle source

Creates a new color from an HSV triple.

Create a new color using an HSV (sometimes also called HSB) triple. The words `value` and `brightness` are used interchangeably and synonymously in descriptions of this colorspace. This implementation follows the modern convention of 0 degrees hue indicating red.

@param [Fixnum] hue The hue component (0-360) @param [Fixnum] saturation The saturation component (0-1) @param [Fixnum] value The value (brightness) component (0-1) @param [Fixnum] alpha Defaults to opaque (255). @return [Integer] The newly constructed color value. @raise [ArgumentError] if the hsv triple is invalid. @see en.wikipedia.org/wiki/HSL_and_HSV

    # File lib/chunky_png/color.rb, line 193
    def from_hsv(hue, saturation, value, alpha = 255)
      raise ArgumentError, "Hue must be between 0 and 360" unless (0..360).include?(hue)
      raise ArgumentError, "Saturation must be between 0 and 1" unless (0..1).include?(saturation)
      raise ArgumentError, "Value/brightness must be between 0 and 1" unless (0..1).include?(value)
      chroma = value * saturation
      rgb    = cylindrical_to_cubic(hue, saturation, value, chroma)
      rgb.map! { |component| ((component + value - chroma) * 255).to_i }
      rgb << alpha
      self.rgba(*rgb)
    end

Also aliased as: from_hsb
from_rgb_stream(stream, pos = 0) click to toggle source

Creates a color by unpacking an rgb triple from a string.

@param [String] stream The string to load the color from. It should be

    at least 3 + pos bytes long.

@param [Integer] pos The position in the string to load the triple from. @return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 140
    def from_rgb_stream(stream, pos = 0)
      rgb(*stream.unpack("@#{pos}C3"))
    end

from_rgba_stream(stream, pos = 0) click to toggle source

Creates a color by unpacking an rgba triple from a string

@param [String] stream The string to load the color from. It should be

    at least 4 + pos bytes long.

@param [Integer] pos The position in the string to load the triple from. @return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 150
    def from_rgba_stream(stream, pos = 0)
      rgba(*stream.unpack("@#{pos}C4"))
    end

fully_transparent?(value) click to toggle source

Returns true if this color is fully transparent.

@param [Integer] value The color to test. @return [true, false] True if the alpha channel equals 0.

    # File lib/chunky_png/color.rb, line 327
    def fully_transparent?(value)
      a(value) == 0x00000000
    end

g(value) click to toggle source

Returns the green-component from the color value.

@param [Integer] value The color value. @return [Integer] A value between 0 and MAX.

    # File lib/chunky_png/color.rb, line 280
    def g(value)
      (value & 0x00ff0000) >> 16
    end

grayscale(teint) click to toggle source

Creates a new color using a grayscale teint. @param [Integer] teint The grayscale teint (0-255), will be used as r, g,

    and b value.

@return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 117
    def grayscale(teint)
      teint << 24 | teint << 16 | teint << 8 | 0xff
    end

grayscale?(value) click to toggle source

Returns true if this color is fully transparent.

@param [Integer] value The color to test. @return [true, false] True if the r, g and b component are equal.

    # File lib/chunky_png/color.rb, line 319
    def grayscale?(value)
      r(value) == b(value) && b(value) == g(value)
    end

grayscale_alpha(teint, a) click to toggle source

Creates a new color using a grayscale teint and alpha value. @param [Integer] teint The grayscale teint (0-255), will be used as r, g,

    and b value.

@param [Integer] a The opacity (0-255) @return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 126
    def grayscale_alpha(teint, a)
      teint << 24 | teint << 16 | teint << 8 | a
    end

grayscale_teint(color) click to toggle source

Calculates the grayscale teint of an RGB color.

@param [Integer] color The color to convert. @return [Integer] The grayscale teint of the input color, 0-255.

    # File lib/chunky_png/color.rb, line 435
    def grayscale_teint(color)
      (r(color) * 0.3 + g(color) * 0.59 + b(color) * 0.11).round
    end

html_color(color_name, opacity = nil) click to toggle source

Gets a color value based on a HTML color name.

The color name is flexible. E.g. `'yellowgreen'`, `'Yellow green'`, `'YellowGreen'`, `'YELLOW_GREEN'` and `:yellow_green` will all return the same color value.

You can include a opacity level in the color name (e.g. `'red @ 0.5'`) or give an explicit opacity value as second argument. If no opacity value is given, the color will be fully opaque.

@param [Symbol, String] color_name The color name. It may include an

    opacity specifier like <tt>@ 0.8</tt> to set the color's opacity.

@param [Integer] opacity The opacity value for the color between 0 and

    255. Overrides any opacity value given in the color name.

@return [Integer] The color value. @raise [ChunkyPNG::Exception] If the color name was not recognized.

    # File lib/chunky_png/color.rb, line 901
    def html_color(color_name, opacity = nil)
      if color_name.to_s =~ HTML_COLOR_REGEXP
        opacity ||= $2 ? ($2.to_f * 255.0).round : 0xff
        base_color_name = $1.gsub(/[^a-z]+/, '').downcase.to_sym
        return PREDEFINED_COLORS[base_color_name] | opacity if PREDEFINED_COLORS.has_key?(base_color_name)
      end
      raise ArgumentError, "Unknown color name #{color_name}!"
    end

int8_mult(a, b) click to toggle source

Multiplies two fractions using integer math, where the fractions are stored using an integer between 0 and 255. This method is used as a helper method for compositing colors using integer math.

This is a quicker implementation of ((a * b) / 255.0).round.

@param [Integer] a The first fraction. @param [Integer] b The second fraction. @return [Integer] The result of the multiplication.

    # File lib/chunky_png/color.rb, line 344
    def int8_mult(a, b)
      t = a * b + 0x80
      ((t >> 8) + t) >> 8
    end

interpolate_quick(fg, bg, alpha) click to toggle source

Interpolates the foreground and background colors by the given alpha value. This also blends the alpha channels themselves.

A blending factor of 255 will give entirely the foreground, while a blending factor of 0 will give the background.

@param [Integer] fg The foreground color. @param [Integer] bg The background color. @param [Integer] alpha The blending factor (fixed 8bit) @param [Integer] The interpolated color.

    # File lib/chunky_png/color.rb, line 417
    def interpolate_quick(fg, bg, alpha)
      return fg if alpha >= 255
      return bg if alpha <= 0

      alpha_com = 255 - alpha

      new_r = int8_mult(alpha, r(fg)) + int8_mult(alpha_com, r(bg))
      new_g = int8_mult(alpha, g(fg)) + int8_mult(alpha_com, g(bg))
      new_b = int8_mult(alpha, b(fg)) + int8_mult(alpha_com, b(bg))
      new_a = int8_mult(alpha, a(fg)) + int8_mult(alpha_com, a(bg))

      rgba(new_r, new_g, new_b, new_a)
    end

opaque!(value) click to toggle source

Returns the opaque value of this color by removing the alpha channel. @param [Integer] value The color to transform. @return [Integer] The opaque color

    # File lib/chunky_png/color.rb, line 311
    def opaque!(value)
      value | 0x000000ff
    end

opaque?(value) click to toggle source

Returns true if this color is fully opaque.

@param [Integer] value The color to test. @return [true, false] True if the alpha channel equals MAX.

    # File lib/chunky_png/color.rb, line 304
    def opaque?(value)
      a(value) == 0x000000ff
    end

parse(source) click to toggle source

Parses a color value given a numeric or string argument.

It supports color numbers, colors in hex notation and named HTML colors.

@param [Integer, String] The color value. @return [Integer] The color value, with the opacity applied if one was

    given.

    # File lib/chunky_png/color.rb, line 84
    def parse(source)
      return source if source.kind_of?(Integer)
      case source.to_s
        when /^\d+$/; source.to_s.to_i
        when HEX3_COLOR_REGEXP, HEX6_COLOR_REGEXP; from_hex(source.to_s)
        when HTML_COLOR_REGEXP; html_color(source.to_s)
        else raise ArgumentError, "Don't know how to create a color from #{source.inspect}!"
      end
    end

pass_bytesize(color_mode, depth, width, height) click to toggle source

Returns the number of bytes used for an image pass @param [Integer] color_mode The color mode in which the pixels are

    stored.

@param [Integer] depth The color depth of the pixels. @param [Integer] width The width of the image pass. @param [Integer] width The height of the image pass. @return [Integer] The number of bytes used per scanline in a datastream.

    # File lib/chunky_png/color.rb, line 976
    def pass_bytesize(color_mode, depth, width, height)
      return 0 if width == 0 || height == 0
      (scanline_bytesize(color_mode, depth, width) + 1) * height
    end

pixel_bitsize(color_mode, depth = 8) click to toggle source

Returns the size in bits of a pixel when it is stored using a given color mode.

@param [Integer] color_mode The color mode in which the pixels are

    stored.

@param [Integer] depth The color depth of the pixels. @return [Integer] The number of bytes used per pixel in a datastream.

    # File lib/chunky_png/color.rb, line 955
    def pixel_bitsize(color_mode, depth = 8)
      samples_per_pixel(color_mode) * depth
    end

pixel_bytesize(color_mode, depth = 8) click to toggle source

Returns the size in bytes of a pixel when it is stored using a given color mode.

@param [Integer] color_mode The color mode in which the pixels are

    stored.

@return [Integer] The number of bytes used per pixel in a datastream.

    # File lib/chunky_png/color.rb, line 943
    def pixel_bytesize(color_mode, depth = 8)
      return 1 if depth < 8
      (pixel_bitsize(color_mode, depth) + 7) >> 3
    end

r(value) click to toggle source

Returns the red-component from the color value.

@param [Integer] value The color value. @return [Integer] A value between 0 and MAX.

    # File lib/chunky_png/color.rb, line 272
    def r(value)
      (value & 0xff000000) >> 24
    end

rgb(r, g, b) click to toggle source

Creates a new color using an r, g, b triple. @param [Integer] r The r-component (0-255) @param [Integer] g The g-component (0-255) @param [Integer] b The b-component (0-255) @return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 109
    def rgb(r, g, b)
      r << 24 | g << 16 | b << 8 | 0xff
    end

rgba(r, g, b, a) click to toggle source

Creates a new color using an r, g, b triple and an alpha value. @param [Integer] r The r-component (0-255) @param [Integer] g The g-component (0-255) @param [Integer] b The b-component (0-255) @param [Integer] a The opacity (0-255) @return [Integer] The newly constructed color value.

    # File lib/chunky_png/color.rb, line 100
    def rgba(r, g, b, a)
      r << 24 | g << 16 | b << 8 | a
    end

samples_per_pixel(color_mode) click to toggle source

Returns the number of sample values per pixel. @param [Integer] color_mode The color mode being used. @return [Integer] The number of sample values per pixel.

    # File lib/chunky_png/color.rb, line 926
    def samples_per_pixel(color_mode)
      case color_mode
        when ChunkyPNG::COLOR_INDEXED;         1
        when ChunkyPNG::COLOR_TRUECOLOR;       3
        when ChunkyPNG::COLOR_TRUECOLOR_ALPHA; 4
        when ChunkyPNG::COLOR_GRAYSCALE;       1
        when ChunkyPNG::COLOR_GRAYSCALE_ALPHA; 2
        else raise ChunkyPNG::NotSupported, "Don't know the number of samples for this colormode: #{color_mode}!"
      end
    end

scanline_bytesize(color_mode, depth, width) click to toggle source

Returns the number of bytes used per scanline. @param [Integer] color_mode The color mode in which the pixels are

    stored.

@param [Integer] depth The color depth of the pixels. @param [Integer] width The number of pixels per scanline. @return [Integer] The number of bytes used per scanline in a datastream.

    # File lib/chunky_png/color.rb, line 965
    def scanline_bytesize(color_mode, depth, width)
      ((pixel_bitsize(color_mode, depth) * width) + 7) >> 3
    end

to_grayscale(color) click to toggle source

Converts a color to a fiting grayscale value. It will conserve the alpha channel.

This method will return a full color value, with the R, G, and B value set to the grayscale teint calcuated from the input color's R, G and B values.

@param [Integer] color The color to convert. @return [Integer] The input color, converted to the best fitting

    grayscale.

@see grayscale_teint

    # File lib/chunky_png/color.rb, line 450
    def to_grayscale(color)
      grayscale_alpha(grayscale_teint(color), a(color))
    end

to_grayscale_alpha_bytes(color) click to toggle source

Returns an array with the grayscale teint and alpha channel values for this color.

This method expects the color to be grayscale, i.e. r, g, and b value to be equal and uses only the B channel. If you need to convert a color to grayscale first, see {to_grayscale}.

@param [Integer] color The grayscale color to convert. @return [Array<Integer>] An array with 2 Integer elements. @see to_grayscale

    # File lib/chunky_png/color.rb, line 695
    def to_grayscale_alpha_bytes(color)
      [b(color), a(color)] # assumption r == g == b
    end

to_grayscale_bytes(color) click to toggle source

Returns an array with the grayscale teint value for this color.

This method expects the r, g, and b value to be equal, and the alpha channel will be discarded.

@param [Integer] color The grayscale color to convert. @return [Array<Integer>] An array with 1 Integer element.

    # File lib/chunky_png/color.rb, line 681
    def to_grayscale_bytes(color)
      [b(color)] # assumption r == g == b
    end

to_hex(color, include_alpha = true) click to toggle source

Returns a string representing this color using hex notation (i.e. rrggbbaa).

@param [Integer] value The color to convert. @return [String] The color in hex notation, starting with a pound sign.

    # File lib/chunky_png/color.rb, line 568
    def to_hex(color, include_alpha = true)
      include_alpha ? ('#%08x' % color) : ('#%06x' % [color >> 8])
    end

to_hsb(color, include_alpha = false) click to toggle source
Alias for: to_hsv
to_hsl(color, include_alpha = false) click to toggle source

Returns an array with the separate HSL components of a color.

Because ChunkyPNG internally handles colors as Integers for performance reasons, some rounding occurs when importing or exporting HSL colors whose coordinates are float-based. Because of this rounding, to_hsl and from_hsl may not be perfect inverses.

This implementation follows the modern convention of 0 degrees hue indicating red.

@param [Integer] color The ChunkyPNG color to convert. @param [Boolean] include_alpha Flag indicates whether a fourth element

    representing alpha channel should be included in the returned array.

@return [Array] The hue of the color (0-360) @return [Array] The saturation of the color (0-1) @return [Array] The lightness of the color (0-1) @return [Array] Optional fourth element for alpha, included if

    include_alpha=true (0-255)

@see en.wikipedia.org/wiki/HSL_and_HSV

    # File lib/chunky_png/color.rb, line 619
    def to_hsl(color, include_alpha = false)
      hue, chroma, max, min = hue_and_chroma(color)
      lightness  = 0.5 * (max + min)
      saturation = chroma.zero? ? 0.0 : chroma.fdiv(1 - (2 * lightness - 1).abs)

      include_alpha ? [hue, saturation, lightness, a(color)] :
                      [hue, saturation, lightness]
    end

to_hsv(color, include_alpha = false) click to toggle source

Returns an array with the separate HSV components of a color.

Because ChunkyPNG internally handles colors as Integers for performance reasons, some rounding occurs when importing or exporting HSV colors whose coordinates are float-based. Because of this rounding, to_hsv and from_hsv may not be perfect inverses.

This implementation follows the modern convention of 0 degrees hue indicating red.

@param [Integer] color The ChunkyPNG color to convert. @param [Boolean] include_alpha Flag indicates whether a fourth element

    representing alpha channel should be included in the returned array.

@return [Array] The hue of the color (0-360) @return [Array] The saturation of the color (0-1) @return [Array] The value of the color (0-1) @return [Array] Optional fourth element for alpha, included if

    include_alpha=true (0-255)

@see en.wikipedia.org/wiki/HSL_and_HSV

    # File lib/chunky_png/color.rb, line 591
    def to_hsv(color, include_alpha = false)
      hue, chroma, max, min = hue_and_chroma(color)
      value      = max
      saturation = chroma.zero? ? 0.0 : chroma.fdiv(value)

      include_alpha ? [hue, saturation, value, a(color)] :
                      [hue, saturation, value]
    end

Also aliased as: to_hsb
to_truecolor_alpha_bytes(color) click to toggle source

Returns an array with the separate RGBA values for this color.

@param [Integer] color The color to convert. @return [Array<Integer>] An array with 4 Integer elements.

    # File lib/chunky_png/color.rb, line 661
    def to_truecolor_alpha_bytes(color)
      [r(color), g(color), b(color), a(color)]
    end

to_truecolor_bytes(color) click to toggle source

Returns an array with the separate RGB values for this color. The alpha channel will be discarded.

@param [Integer] color The color to convert. @return [Array<Integer>] An array with 3 Integer elements.

    # File lib/chunky_png/color.rb, line 670
    def to_truecolor_bytes(color)
      [r(color), g(color), b(color)]
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.