Document imageconvolution()

imagecolorallocate* return FALSE on error since 5.1.3


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@227941 c90b9560-bf6c-de11-be94-00142212c4b1

reference/image/functions/imagecolorallocate.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <refentry id="function.imagecolorallocate">
  <refnamediv>
   <refname>imagecolorallocate</refname>
@@ -68,7 +68,30 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   A color identifier or -1 if the allocation failed.
+   A color identifier or &false; if the allocation failed.
+  </para>
+ </refsect1>
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>Prior to 5.1.3</entry>
+       <entry>
+        Returns -1 if the allocation failed.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
   </para>
  </refsect1>
  <refsect1 role="examples">

reference/image/functions/imagecolorallocatealpha.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <refentry id="function.imagecolorallocatealpha">
  <refnamediv>
   <refname>imagecolorallocatealpha</refname>
@@ -71,6 +71,29 @@
    A color identifier or &false; if the allocation failed.
   </para>
  </refsect1>
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>Prior to 5.1.3</entry>
+       <entry>
+        Returns -1 if the allocation failed.
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
  <refsect1 role="examples">
   &reftitle.examples;
   <para>

reference/image/functions/imageconvolution.xml

@@ -1,20 +1,23 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <refentry id="function.imageconvolution">
  <refnamediv>
   <refname>imageconvolution</refname>
-  <refpurpose>Apply a 3x3 convolution matrix, using coefficient div and offset</refpurpose>
+  <refpurpose>Apply a 3x3 convolution matrix, using coefficient and offset</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>imageconvolution</methodname>
    <methodparam><type>resource</type><parameter>image</parameter></methodparam>
-   <methodparam><type>array</type><parameter>matrix3x3</parameter></methodparam>
+   <methodparam><type>array</type><parameter>matrix</parameter></methodparam>
    <methodparam><type>float</type><parameter>div</parameter></methodparam>
    <methodparam><type>float</type><parameter>offset</parameter></methodparam>
   </methodsynopsis>
-  &warn.undocumented.func;
+  <para>
+   Applies a convolution matrix on the image, using the given coefficient and
+   offset.
+  </para>
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;
@@ -22,9 +25,10 @@
    <variablelist>
     &gd.image.description;
     <varlistentry>
-     <term><parameter>matrix3x3</parameter></term>
+     <term><parameter>matrix</parameter></term>
      <listitem>
       <para>
+       A 3x3 matrix: an array of three arrays of three floats.
       </para>
      </listitem>
     </varlistentry>
@@ -32,6 +36,7 @@
      <term><parameter>div</parameter></term>
      <listitem>
       <para>
+       The divisor of the result of the convolution, used for normalization.
       </para>
      </listitem>
     </varlistentry>
@@ -51,10 +56,68 @@
    &return.success;
   </para>
  </refsect1>
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Embossing the PHP.net logo</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$image = imagecreatefromgif('http://www.php.net/images/php.gif');
+
+$emboss = array(array(2, 0, 0), array(0, -1, 0), array(0, 0, -1));
+imageconvolution($image, $emboss, 1, 127);
+
+header('Content-Type: image/png');
+imagepng($image, null, 9);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screenshot>
+     <graphic fileref="figures/image.imageconvolution_emboss.png" />
+    </screenshot>
+   </example>
+   <example>
+    <title>Gaussian blur</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$image = imagecreatetruecolor(180,40);
+
+// Writes the text and apply a gaussian blur on the image
+imagestring($image, 5, 10, 8, 'Gaussian Blur Text', 0x00ff00);
+$gaussian = array(array(1.0, 2.0, 1.0), array(2.0, 4.0, 2.0), array(1.0, 2.0, 1.0));
+imageconvolution($image, $gaussian, 16, 0);
+
+// Rewrites the text for comparison
+imagestring($image, 5, 10, 18, 'Gaussian Blur Text', 0x00ff00);
+
+header('Content-Type: image/png');
+imagepng($image, null, 9);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screenshot>
+     <graphic fileref="figures/image.imageconvolution_gaussian.png" />
+    </screenshot>
+   </example>
+  </para>
+ </refsect1>
  <refsect1 role="notes">
   &reftitle.notes;
   &note.bundled.gd;
  </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>imagefilter</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file

reference/image/functions/imagefilter.xml

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry id="function.imagefilter">
  <refnamediv>
   <refname>imagefilter</refname>
@@ -200,6 +200,14 @@ imagedestroy($im);
   &reftitle.notes;
   &note.bundled.gd;
  </refsect1>
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>imageconvolution</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file