This should be a pretty simple documentation addendum. I was working on transparency with images, trying to get a bit of image blending to display just right. It worked pretty well with GD 1.8.4, with a script as follows:

<?
  $baseImg = imageCreateFromPng("baseImg.png");
  $sourceImg = imageCreateFromPng("sourceImg.png");

  imageColorTransparent($sourceImg, imageColorAt($sourceImg, 0, 0));
  imageCopy($baseImg, $sourceImg, 44, 124, 8, 8, 16, 16);

  header("Content-type: image/jpeg");
  imageJpeg($baseImg);

  imageDestroy($sourceImg);
  imageDestroy($baseImg);
?>

I didn't quite like the way the colours ended up, though, and decided to try changing it to use GD 2.0.1 for true colour images. I tried it with the same script, and it didn't work. I actually ended up trying different things for several hours, along with doing several Google searches and such trying to figure out how to get it to work. The only hint I had was on the imageColorTransparent() manual page, where the note by marshall.AT.byterage.net noted that he had it working, but without specifying how...

Well, I finally figured it out (somewhat by chance). This is what's necessary:

<?
  $baseImg = imageCreateFromPng("baseImg.png");
  $sourceImg = imageCreateFromPng("sourceImg.png");

  imageColorTransparent($sourceImg, imageColorAt($sourceImg, 0, 0));
  imageCopyMerge($baseImg, $sourceImg, 44, 124, 8, 8, 16, 16, 100);

  header("Content-type: image/jpeg");
  imageJpeg($baseImg);

  imageDestroy($sourceImg);
  imageDestroy($baseImg);
?>

You'll notice that instead of imageCopy(), I used imageCopyMerge(). This actually *does* work, contrary to what it says on the imageCopyMerge() manual page: "When pct = 0, no action is taken, when 100 this function behaves identically to imagecopy()."

So, it would be great if at least two notes were added:

a) If on the imageCopyMerge() manual page, it would say that at pct = 100, it's identical to imageCopy() *for palette images only*, while it implements alpha transparency for true colour images.
b) If on the imageColorTransparent() manual page, it noted that transparency only copies with imageCopyMerge(), but not imageCopy().

Anyways, I'm filing this bug so that hopefully nobody else spends several hours trying to figure out what's going wrong. Thanks!