<refentry id="{@id}">
  <refnamediv>
    <refname>Using PEL in applications</refname>
    <refpurpose>Learn how to load, edit, and save images</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <authorblurb>
      <para>
        <author>
          <firstname>Martin</firstname>
          <surname>Geisler</surname>
        </author>
        {@link mailto:mgeisler@users.sourceforge.net
        mgeisler@users.sourceforge.net}
      </para>
    </authorblurb>
  </refsynopsisdiv>

  {@toc}

  <refsect1 id="{@id jpeg}">
    <title>Loading a JPEG image</title>

    <para>The typical use for PEL is to read and write data from JPEG
    images.  Such an image is represented in PEL using an object of
    the <classname>PelJpeg</classname> class.  With the filename of a
    JPEG image stored in the variable <varname>$filename</varname>,
    then it is a simple matter of creating a {@link PelJpeg}
    object:</para>

    <programlisting role="php">
      <![CDATA[
$jpeg = new PelJpeg($filename);
      ]]>
    </programlisting>

    <para>If this succeeded without any exceptions being thrown, one
    can proceed to find the Exif data itself. The Exif data is
    retrieved using the {@link PelJpeg::getExif()} method:</para>

    <programlisting role="php">
      <![CDATA[
$exif = $jpeg->getExif();
      ]]>
    </programlisting>

    <para>The section stored in <varname>$exif</varname> is now a
    {@link PelExif} object.</para>

    <warning>
      <para>If the JPEG image does not contain Exif information, then
      the <varname>$exif</varname> variable will be
      <literal>null</literal>.</para>
    </warning>

  </refsect1>


  <refsect1 id="{@id tiff}">
    <title>Obtaining the TIFF data</title>

    <para>The Exif data is not stored directly in this object, instead
    it is stored in a {@link PelTiff} object, which can be retrieved
    using the {@link PelExif::getTiff() getTiff()} method:</para>

    <programlisting role="php">
      <![CDATA[
$tiff = $exif->getTiff();
      ]]>
    </programlisting>

    <para>This peculiar step is necessary because what one normally
    thinks of as Exif data is really just an extension of the TIFF
    standard.  PEL models this by having the {@link PelExif} object
    contain a {@link PelTiff} object.</para>

    <para>TIFF data is organized as a chain of Image File Directories
    (IFDs), each represented by a {@link PelIfd} object.  Each IFD has
    a number of entries ({@link PelEntry} objects) which one can get
    hold of using the {@link PelIfd::getEntry() getEntry()}
    method.</para>

    <para>The first IFD, number zero, will normally contain the
    {@link PelTag::IMAGE_DESCRIPTION IMAGE_DESCRIPTION} tag. The
    following code will initialize <varname>$ifd0</varname> with the
    first IFD, and <varname>$desc</varname> with the
    description:</para>

    <programlisting role="php">
      <![CDATA[
$ifd0 = $tiff->getIfd();
$desc = $ifd0->getEntry(PelTag::IMAGE_DESCRIPTION);
      ]]>
    </programlisting>

    <para>Now <varname>$desc</varname> will contain a
    {@link PelEntryAscii} object holding the description.  Each entry
    is represented using an object of a class descendent of
    {@link PelEntry}.  There are classes for numbers such as
    {@link PelEntryShort} for small numbers and {@link PelEntryLong}
    for big numbers, and more specialized classes, such as
    {@link PelEntryVersion} for version numbers, {@link PelEntryTime}
    for date and time, and so on.</para>

  </refsect1>

  <refsect1 id="{@id reading}">
    <title>Reading Values</title>

    <para>The value of any entry can be retrieved by calling the
    {@link PelEntry::getValue() getValue()} method on the object.
    Doing this on <varname>$desc</varname> will return a string, while
    doing it on a {@link PelEntryShort} will normally return an
    integer (see {@link PelEntryNumber::getValue() the documentation}
    for the full story).  So to echo the description one simply
    does:</para>

    <programlisting role="php">
      <![CDATA[
echo 'The description: ' . $desc->getValue();
      ]]>
    </programlisting>

  </refsect1>

  <refsect1 id="{@id writing}">

    <title>Writing Values</title>

    <para>Writing new values (changing values) to an entry is just as
    easy as reading values, one just uses the
    {@link PelEntry::setValue() setValue()} method on the entry in
    question.</para>

    <para>Continuing on our example from before where
    <varname>$desc</varname> contains a {@link PelEntryAscii} object
    with the description for the image, one changes the description
    with:</para>

    <programlisting role="php">
      <![CDATA[
$desc->setValue('The new description.');
      ]]>
    </programlisting>

    <para>The object is now updated and is ready to be turned back
    into bytes, so that the image can be saved with the new, updated
    description.</para>

  </refsect1>

  <refsect1 id="{@id saving}">

    <title>Saving an Image</title>

    <para>After having changed an image, one would probably want to
    save it to keep the changes.</para>

    <para>{@link PelJpeg} objects (and {@link PelTiff} objects) can be
    turned back into bytes with the {@link PelJpeg::getBytes()
    getBytes} method.  This will turn the object and all the objects
    within it into bytes, which can then be saved in a file to produce
    a JPEG image.</para>

    <para>With the image loaded into <varname>$jpeg</varname> it is a
    simple matter to write the new JPEG file:</para>

    <programlisting role="php">
      <![CDATA[
$jpeg->saveFile('new-' . $filename);
      ]]>
    </programlisting>

  </refsect1>

</refentry>