From d6da6ad11e81e7588c0875a47d431520bf6fd159 Mon Sep 17 00:00:00 2001
From: Chris Wright <daverandom@php.net>
Date: Tue, 22 Oct 2013 11:25:50 +0000
Subject: [PATCH] Added description and examples for Imagick::setImageDelay()
 and Imagick::setImageTicksPerSecond()

--
Provided by anonymous 33522 (Danack@Basereality.com)

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@331913 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/imagick/imagick/setimagedelay.xml   | 43 +++++++++++-
 .../imagick/setimagetickspersecond.xml        | 68 ++++++++++++++++++-
 2 files changed, 107 insertions(+), 4 deletions(-)

diff --git a/reference/imagick/imagick/setimagedelay.xml b/reference/imagick/imagick/setimagedelay.xml
index 33b62859ac..1239477df2 100644
--- a/reference/imagick/imagick/setimagedelay.xml
+++ b/reference/imagick/imagick/setimagedelay.xml
@@ -13,7 +13,12 @@
    <methodparam><type>int</type><parameter>delay</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Sets the image delay.
+   Sets the image delay. For an animated image this is the amount of time that
+   this frame of the image should be displayed for, before displaying the next
+   frame.
+  </para>
+  <para>
+   The delay can be set individually for each frame in an image.
   </para>
  </refsect1>
 
@@ -25,6 +30,9 @@
      <term><parameter>delay</parameter></term>
      <listitem>
       <para>
+       The amount of time expressed in 'ticks' that the image should be
+       displayed for. For animated GIFs there are 100 ticks per second, so a
+       value of 20 would be 20/100 of a second aka 1/5th of a second.
       </para>
      </listitem>
     </varlistentry>
@@ -46,6 +54,39 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Modify animated Gif with <function>Imagick::setImageDelay</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+// Modify an animated Gif so that it's frames are played at a variable speed,
+// varying between being shown for 50ms down to 0ms, which will cause the frame
+// to be skipped in most browsers.
+$imagick = new Imagick(realpath("Test.gif"));
+$imagick = $imagick->coalesceImages();
+
+$frameCount = 0;
+
+foreach ($imagick as $frame) {
+    $imagick->setImageDelay((($frameCount % 11) * 5));
+    $frameCount++;
+}
+
+$imagick = $imagick->deconstructImages();
+
+$imagick->writeImages("/path/to/save/output.gif", true);
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/imagick/imagick/setimagetickspersecond.xml b/reference/imagick/imagick/setimagetickspersecond.xml
index f3e8ed0ace..d85e932565 100644
--- a/reference/imagick/imagick/setimagetickspersecond.xml
+++ b/reference/imagick/imagick/setimagetickspersecond.xml
@@ -10,11 +10,26 @@
   &reftitle.description;
   <methodsynopsis>
    <type>bool</type><methodname>Imagick::setImageTicksPerSecond</methodname>
-   <methodparam><type>int</type><parameter>ticks_per-second</parameter></methodparam>
+   <methodparam><type>int</type><parameter>ticks_per_second</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Sets the image ticks-per-second.
+   Adjust the amount of time that a frame of an animated image is displayed for.
   </para>
+  <note>
+   <para>
+    For animated GIFs, this function does not change the number of 'image ticks'
+    per second, which is always defined as 100. Instead it adjusts the amount of
+    time that the frame is displayed for to simulate the change in 'ticks per
+    second'.
+   </para>
+   <para>
+    For example, for an animated GIF where each frame is displayed for 20 ticks
+    (1/5 of a second) when this method is called on each frame of that image
+    with an argument of <literal>50</literal> the frames are adjusted to be
+    displayed for 40 ticks (2/5 of a second) and the animation will play at half
+    the original speed.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -22,9 +37,11 @@
   <para>
    <variablelist>
     <varlistentry>
-     <term><parameter>ticks_per-second</parameter></term>
+     <term><parameter>ticks_per_second</parameter></term>
      <listitem>
       <para>
+       The duration for which an image should be displayed expressed in ticks
+       per second.
       </para>
      </listitem>
     </varlistentry>
@@ -39,6 +56,51 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+    &reftitle.examples;
+  <para>
+   <example>
+    <title>Modify animated Gif with <function>Imagick::setImageTicksPerSecond</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+// Modify an animated gif so the first half of the gif is played at half the
+// speed it currently is, and the second half to be played at double the speed
+// it currently is
+
+$imagick = new Imagick(realpath("Test.gif"));
+$imagick = $imagick->coalesceImages();
+
+$totalFrames = $imagick->getNumberImages();
+
+$frameCount = 0;
+
+foreach ($imagick as $frame) {
+    $imagick->setImageTicksPerSecond(50);
+    
+    if ($frameCount < ($totalFrames / 2)) {
+        // Modify the frame to be displayed for twice as long as it currently is
+        $imagick->setImageTicksPerSecond(50);
+    } else {
+        // Modify the frame to be displayed for half as long as it currently is
+        $imagick->setImageTicksPerSecond(200);
+    }
+
+    $frameCount++;
+}
+
+$imagick = $imagick->deconstructImages();
+
+$imagick->writeImages("/path/to/save/output.gif", true);
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file