From: dewi at dewimorgan dot com
Operating system: Windows
PHP version: 5.5.16
Package: Documentation problem
Bug Type: Documentation Problem
Bug description:GD color system poorly documented.
Description:
------------
---
From manual page: http://www.php.net/function.imagesetpixel
---
There are several undocumented GD behaviors that people are relying on
and which probably ought to be either documented as official; or
documented as "don't use, might change".
imagecolorat() is documented to return the 24-bit RGB value of the pixel
for truecolor images; that the value is in fact 31-bit ARGB is not
documented. This means there is *no* documented way to retrieve the
alpha value of a pixel.
imagecolorallocatealpha() is documented to return a color resource. That
the color returned for truecolor images is the same 31-bit ARGB value as
above is not documented.
Also undocumented is that for paletted images the value returned from
imagecolorallocatealpha() is the palette index of the color, as returned
from imagecolorat().
imagesetpixel() is documented as requiring a color resource that must be
created by imagecolorallocate; it is not documented that:
- the value from imagecolorat is OK too.
- any loaded or allocated palette index for truecolor images is OK too.
- any 31-bit ARGB value is OK for truecolor images, allocated or not.
Also not terribly well documented, though inferrable, is that GD can
only create 31-bit ARGB images (7-bit alpha), not 32-bit, so you cannot
edit true-color PNGs (with 8-bit alpha) without losing some alpha data.
Test script:
---------------
It is possible to copy a pixel as:
imagealphablending($im, false);
imagesetpixel($im, $toX, $toY, imagecolorat($im, $fromX, $fromY));
But the as-documented approach would instead be:
imagealphablending($im, false);
$inColor = imagecolorat($im, $fromX, $fromY);
if (imageistruecolor($im)) {
$r = ($color >> 16) & 0xFF;
$g = ($color >> 8) & 0xFF;
$b = ($color >> 0) & 0xFF;
$a = UndocumentedMagicHere($im, $x, $y);
}
else {
$arr = imagecolorsforindex($im, $inColor);
$r = $arr['red'];
$g = $arr['green'];
$b = $arr['blue'];
$a = $arr['alpha'];
}
$outColor = imagecolorallocatealpha($im, $r, $g, $b, $a);
imagesetpixel($im, $toX, $toY, $outColor);
Actual result:
--------------
The difference in speed for per-pixel operations, and in readability,
and in the fact that some stuff is impossible without the undocumented
bits, seem significant enough that these things *will* be relied upon
(and *are* being, even in comments to these pages), unless they are
documented as unreliable; and that if they *can* be relied upon, they
should be documented as such.
--
Edit bug report at https://bugs.php.net/bug.php?id=67900&edit=1
--