<?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="display_objects.particles"
         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>Particle display</title>

  <para>
      
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/display_objects/particles_panel.png" format="PNG" />
    </imageobject></mediaobject></screenshot></informalfigure>
    
    This <link linkend="display_objects">display object</link> is responsible for rendering particles, and its parameters control the visual appearance
    of particles. You can open this parameter panel
    by selecting the <emphasis>Particles</emphasis> entry in the <link linkend="usage.modification_pipeline.pipeline_listbox">pipeline editor</link>.  
  </para>

   <simplesect>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>Shape</term>
        <listitem>
          <para>Selects the visual shape of particles.
          Note that spherical particles can be turned into <link linkend="howto.aspherical_particles">ellipsoidal particles</link>
          by setting the <literal>Aspherical Shape</literal> particle property. Similarly,
          the size of box-shaped particles can be controlled with the same property.
          </para>
          <para>
          The size of cylindrical and spherocylindrical particles is also controlled by the 
          <literal>Aspherical Shape</literal> property. Here, the component <literal>Aspherical Shape.X</literal>
          determines the radius of the cylinder, and <literal>Aspherical Shape.Z</literal> determines its
          length. The vector component <literal>Aspherical Shape.Y</literal> is ignored.
          </para>
          <para>
          The orientation of ellipsoidal, box, and cylindrical particles can be controlled 
          using the <literal>Orientation</literal> particle property. With this property,
          a quaternion can be specified for each particle which determines its orientation in space.
          If the <literal>Orientation</literal> property is not defined, all particles
          will be aligned with the global simulation coordinate axes.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Default particle radius</term>
        <listitem>
          <para>Specifies the display size of particles that have an otherwise unspecified size. 
          This size value is only used for particles for which <emphasis>none</emphasis> of the following applies:
          <itemizedlist>
            <listitem><para>The <literal>Radius</literal> property has been set.</para></listitem>
            <listitem><para>A non-zero type-specific radius has been set for the particle's type.</para></listitem>
          </itemizedlist>
          In other words, this parameter provides a fallback value if no display size has been set on a 
          per-particle basis or on a per-type basis.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Rendering quality</term>
        <listitem>
          <para>This parameter controls the method used to render the particles. The following modes are available and affect only the rendering of spherical particles:
		    <variablelist>
		      <varlistentry>
		        <term>Low</term>
		        <listitem><para>Particles are rendered as texture-mapped imposters facing the viewer. Particles do not have depth in this mode, 
		        and intersections between spherical particles may not be displayed correctly. This mode is the fastest.</para></listitem>
		      </varlistentry>
		      <varlistentry>
		        <term>Medium</term>
		        <listitem><para>Particles are rendered as texture-mapped imposters facing the viewer. An OpenGL fragment shader is used
		        to compute depth information for each rendered pixel to produce reasonable looking sphere-sphere intersections for overlapping particles.</para></listitem>
		      </varlistentry>
		      <varlistentry>
		        <term>High</term>
		        <listitem><para>Particles are rendered as true spheres using an OpenGL fragment shader, which computes the ray-sphere intersection for every
		        rendered pixel.</para></listitem>
		      </varlistentry>
		      <varlistentry>
		        <term>Automatic</term>
		        <listitem><para>OVITO automatically switches between the three quality levels above depending on the number of particles to render in the interactive viewports. For
		        less than 4,000 particles, the high-quality method is used. For more than 400,000 particles, the lowest quality mode is used. Irrespective of the
		        particle number, high-quality mode is always used to produce a final output image.</para></listitem>
		      </varlistentry>
		    </variablelist>
          </para>
        </listitem>
      </varlistentry>
  	</variablelist>
    </simplesect>
    
</section>
