php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #67900 GD color system poorly documented.
Submitted: 2014-08-25 02:54 UTC Modified: 2016-08-21 11:29 UTC
From: dewi at dewimorgan dot com Assigned:
Status: Verified Package: GD related
PHP Version: 5.5.16 OS: Windows
Private report: No CVE-ID: None
View Add Comment Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
You can add a comment by following this link or if you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: dewi at dewimorgan dot com
New email:
PHP Version: OS:

 

 [2014-08-25 02:54 UTC] dewi at dewimorgan dot com
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.

Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2014-08-25 02:57 UTC] dewi at dewimorgan dot com
"- any loaded or allocated palette index for truecolor images is OK too."
above should be:
"- any of a paletted image's loaded or allocated palette indexes is OK too."
 [2016-06-14 16:26 UTC] cmb@php.net
-Package: Documentation problem +Package: GD related
 [2016-08-21 11:29 UTC] cmb@php.net
-Status: Open +Status: Verified
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Thu Dec 12 18:01:24 2019 UTC