Uniform color management in imageapi

A general (and backward compatible) way to manage colors in ImageAPI

Motivation

There are numerous ways to represent RGB colors today. ImageAPI pretty much leaves the parsing of colors to the underlying toolkit and this leads to situations where e.g. imagemagick will accept one (maybe user entered) color, whereas gd will not.

The proposal

This patch is the first step in an attempt to uniform color management in ImageAPI by introduction to a new function imageapi_color_convert(). This accepts RGB(A) colors in several formats and return the same color in another. So far, accepted colors are 24 bit integers, arrays with rgba values and strings with hex representations just like imageapi_hex2rgba(). The intended use is whenever a toolkit needs to use colors entered by users or modules and the toolkits needs this in a different formats.

The algorithm is simple: Split the color into each separate channel and output the color in the desired format. It's a generalization of imageapi_hex2rgba().

Discussion, comments

The values for the parameter $format probably need work. If it should be possible to output colors as a CSS rgb() function we have a collision, or one could add the formats 'css_rgb'.

Another question is whether it should be possible to enter HSL (hue-saturation-lightness) color values. This might add the need for another parameter, specifying if it is a RGB or HSL color we got.

This implementation triggers a bug in imageapi_gd due to the fact that alpha channels in GD are from 0 (full opacity) to 127 (full transparency). The norm elsewhere is that 0 is full transparency and MAX (1.0, 100%, 255) is full opacity. So is the case with this implementation. Depending on the outcome of this patch, another issue will address this bug.

Colors specified as integers only accept the 24 least significant bits and leaves no room for alpha channel. If you use 32 bits and specify a integer literal above 0x7fffffff, PHP treats this as a double. This leaves no room for four 8-bit channels in an integer.

I still haven't looked into simpletest, but here is a snippet that tests a series of different colors:

function _imageapi_color_convert_test()
{
  $colors = array(
     0xFFFFFF, 0xFF00FF, 0xB0A090, -1,
     0xABC,    0xAABBCC, 0xABCD,   0x112233,
     0x003,    0x000033, 0x003f,   0x0033ff,

     array(255,255,255), array(-1, 300, -200, 5000),
     array(255,255,0), array(0xaa, 0xaa, 0, 0x33),
     array(0x80,0x7f,0x0f), array(0xa, 0xa, 0xaa, 0),
     array('255','255','0'), array('aa', 'aa', '0', '33'),

      'abc',   'aabbcc',   'abcd',   'aabbccdd',
     '#abc',  '#aabbcc',  '#abcd',  '#aabbccdd',
    '0xabc', '0xaabbcc', '0xabcd', '0xaabbccdd',
      '123',   '112233',   '1234',   '11223344',
     '#123',  '#112233',  '#1234',  '#11223344',
    '0x123', '0x112233', '0x1234', '0x11223344',
  );
  $ret = "<pre>\n";
  $ret .= "src         web     array                  rgb    rgba    \n";
  $ret .= "==========================================================\n";
  foreach($colors as $color) {
    $web = imageapi_color_convert($color, 'web');
    $array = imageapi_color_convert($color, 'array');
    $rgb   = imageapi_color_convert($color, 'rgb');
    $rgba  = imageapi_color_convert($color, 'rgba');
    $ret .= sprintf("%-10s: %7s array(%3d,%3d,%3d,%3d) %s %s\n", $color, $web, $array[0], $array[1], $array[2], $array[3], $rgb, $rgba);
  }
  return $ret ."</pre>\n";
}

Please review.