<?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.freeze_selection"
         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>Freeze selection</title>

  <para>This modifier can be used to preserve a particle selection over time. 
  At the time the modifier is first inserted into the modification pipeline, it records the current selection state
  of all particles. During an evaluation of the modification pipeline, it will subsequently 
  override any other selection state
  (generated by preceding modifiers in the pipeline) with its stored 
  selection set. Thus, this modifier allows to freeze a particle selection state that,
  otherwise, would change with animation time.</para>

  <simplesect>
    <title>Usage example</title>
	  <para>A typical application of this modifier is to make 
	  the motion of (tracer) particles visible. For this, one first selects
	  the group of tracer particles (for instance, using the <link
	  linkend="particles.modifiers.slice">Slice modifier</link>, which allows to select particles within a thin slab). 
	  This initial selection is performed at the first frame of the simulation. One then applies the <emphasis>Freeze selection</emphasis> 
	  modifier to preserve this selection for all times. When jumping to a different simulation frame,
	  the same set of particles remains selected, independent of where the tracer particles have moved.
	  </para>
	  <para>
	  Hint: If you want to preserve an arbitrary particle property over time (and not just the selection state),
	  you can use the <link linkend="particles.modifiers.freeze_property">Freeze property</link> modifier.
	  </para>
  </simplesect>
  
  <simplesect>
    <title>Implementation note</title>
    <para>
    The modifier can store the selection of particles in two ways: It either keeps a list of 
    selected particle indices or a list of particle identifiers.
      <informaltable>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Index-based selection mode</entry>
              <entry>Identifier-based selection mode</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry valign="top">In this mode, the modifier stores a Boolean value for each particle index indicating 
              the selection state. The number of input particles and their storage order must not change.
              Otherwise the modifier cannot apply the stored selection state to the particle dataset or 
              may even assign it to the wrong particles.</entry>
              
              <entry valign="top"><para>This selection storage method is preferred and will automatically be used when the 
              input dataset contains particle identifiers. The modifier stores the identifiers of all selected particles. 
              When the modifier applies the stored selection state to the input particles during an evaluation of the modification pipeline,
              it checks for each input particle if its identifier is contained in the stored selection set.</para>
              <para>
              Note that this selection mode requires that particles have unique identifiers.
              </para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </para>
  </simplesect>  
  
</section>
