<?xml version="1.0" encoding="utf-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
         xml:id="particles.modifiers.ambient_occlusion"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Ambient occlusion</title>

  <para>
    <informalfigure>
      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row valign="bottom">
              <entry>Input:</entry>
              <entry>Output:</entry>
            </row>
            <row valign="top">
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/ambient_occlusion_input.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/ambient_occlusion_output.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
  Performs a fast lighting calculation to shade particles based on their
  occlusion by other particles. The ambient occlusion shading model has the nice property of offering 
  a better perception of the three-dimensional shape of the structure. The algorithm 
  simulates the shading produced by a spherical light source enclosing the entire structure (similar to an overcast sky).
  OVITO uses the graphics card to quickly perform this illumination calculation.
  </para>

  <para>
  Use the ambient occlusion modifier to improve the perception of large three-dimensional structures 
  with many particles as shown in the example on the right. For even better results, and for small structures with
  only few particles, use the <link linkend="rendering.tachyon_renderer">Tachyon renderer</link> instead. Unlike 
  the ambient occlusion modifier, which computes a per-particle illumination factor, the Tachyon 
  renderer performs an ambient occlusion calculation for every output image pixel. However, only the ambient occlusion
  modifier works in near-realtime and can be used to improve the display in the interactive viewports.
  </para>

  <para>
  Note that the modifier takes the input particle colors, multiplies them with the computed illumination factors,
  and writes the modulated colors back to the <literal>Color</literal> particle property.
  Assigning new colors to particles after this modifier would overwrite
  the shading results. Therefore the ambient occlusion modifier should always be placed at the 
  very end of the modification pipeline.
  </para>  

  <simplesect>
    <title>Parameters</title>
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/ambient_occlusion_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>

    <variablelist>
      <varlistentry>
        <term>Shading intensity</term>

        <listitem>
          <para>Percentage value controlling the strength of the shading effect. The
          higher the shading intensity, the darker the occluded particles will appear.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Number of exposure samples</term>
        <listitem>
          <para>The uniform lighting produced by an overcast sky is approximated by a finite number
            of parallel light sources, which are placed evenly around the input structure. This parameter
            controls the number of light sources to compute the ambient occlusion shading. A small number of
            exposure samples reduces computation time, but can lead to cast shadow artifacts.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Render buffer resolution</term>
        <listitem>
          <para>
          To compute the illumination produced by a single light source from one direction, the modifier
          renders the particles as seen from that light source. All visible particles will receive 
          a certain amount of light while the occluded particles do not. This parameter controls 
          the resolution of the internal rendering buffer. For systems with a large number of particles it
          might be necessary to increase this value such that every particles occupies at least one
          pixel in the rendering buffer.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </simplesect>
  
 <simplesect>
    <title>Technical background information</title>
 	<para>OVITO uses the following <link xlink:href="http://en.wikipedia.org/wiki/Ambient_occlusion">ambient occlusion</link>	 algorithm to determine an illumination factor for
 	each particle, which is used to modulate its original particle color. The illumination of a sky sphere
 	enclosing the input structure is approximated by a large number of parallel light sources directed
 	at the structure. The amount of light received by a particle from one such light surface is determined
 	by rendering a projected image of the structure from the point of view of the light source to an offscreen frame buffer. 
 	All particles appearing in that image, which are not occluded by other particles, receive an amount of light 
 	that is proportional to their exposed area (i.e. the number of pixels they cover in the image). Finally, the 
 	light contributions from all light sources are added up to compute the per-particle illumination factors.</para>
  </simplesect>
  
</section>
