<?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_property"
         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 property</title>

  <para>
    <informalfigure><screenshot><mediaobject><imageobject>
       <imagedata fileref="images/modifiers/freeze_property_panel.png" format="png" />
    </imageobject></mediaobject></screenshot></informalfigure>  
    When this modifier is inserted into a modification pipeline, it takes a snapshot of the current values of the selected particle property. 
    It will subsequently write the stored values back to the selected output particle property (which, by default, is the same as the source property), overwriting 
    the current values of that property. Thus, this modifier can be used to <emphasis>freeze</emphasis> a particle property that, otherwise, would be changing with 
    simulation time.
  </para>
  
  <para>
    The modifier automatically takes a snapshot of the current state whenever the user selects a new source property for the modifier.
    The snapshot is always taken at the current animation time. You can explicitly take a new snapshot at any later time by clicking the
    <guibutton>Take new snapshot</guibutton> button, which will replace the per-particle values stored by the modifier with the current 
    values produce by the modification pipeline.
  </para>
  
  <para>
     By default, the stored property values are written back to the same property from which the snapshot 
     was originally taken, overwriting the current values of that property. If you want to preserve the current values, you can let the modifier
     write the stored snapshot to a new property instead by entering a different name in the <guilabel>Output property</guilabel> field.
     Then both the current property values and the ones stored by the modifier will be available to other 
     modifiers following in the modification pipeline.
  </para>
  
  <simplesect>
    <title>Example 1</title>
	<para>
	<informalfigure>
      <informaltable frame="none">
        <tgroup cols="3">
          <tbody>
            <row valign="bottom">
              <entry>Initial frame:</entry>
              <entry>Without <emphasis>Freeze Property</emphasis> modifier:</entry>
              <entry>With <emphasis>Freeze Property</emphasis> modifier:</entry>
            </row>
            <row valign="top">
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/freeze_property_example1_initial.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
                <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/freeze_property_example1_without.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
              <entry>
		        <mediaobject><imageobject>
		        <imagedata fileref="images/modifiers/freeze_property_example1_with.png" format="PNG" />
		        </imageobject></mediaobject>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </informalfigure>
       The first picture shows the initial frame of a simulation sequence where the <link linkend="particles.modifiers.color_coding">Color coding</link> 
	   modifier has been used to color particles according to their position along the X axis. 
	   Then the solid is sheared and particles move (second picture).
	   This motion causes the colors of individual particles to change, because they are dynamically computed by the 
	   <link linkend="particles.modifiers.color_coding">Color coding</link> modifier on every simulation frame
	   based on the current positions.
	</para>
	<para>
	   To suppress this dynamic updating of particle colors, we can use the <emphasis>Freeze property</emphasis> modifier. 
	   It allows us the take a snapshot of the particle colors at the beginning of the simulation. Subsequently, the modifier will 
	   overwrite any new colors generated by the <emphasis>Color coding</emphasis> modifier with the stored colors 
	   (third picture). Thus, the <emphasis>Freeze property</emphasis> modifier allows us to "bake in" a dynamic particle property 
	   such as the color so that it becomes static and does not change with simulation time.
	</para>
  </simplesect>

  
  <simplesect>
    <title>Example 2</title>
	<para>
	   The modifier is also useful if we want to compare per-particle properties that change over time with their initial
	   values at the beginning of a simulation. Let's suppose, for instance, we want to determine the amount by which 
	   the charge of each particle changes during a simulation. We assume in this example that the current particle charges 
	   have been computed by our simulation code for each simulation frame and that they are stored in 
	   the particle property <literal>Charge</literal>. 
	</para>
	<para>
	   We can use the <emphasis>Freeze property</emphasis> modifier to take a snapshot of the initial particle charges at frame 0
	   by selecting <literal>Charge</literal> as the source property. In this case we do not want to overwrite the current charge 
	   values with the initial ones, because we want to compare them with each other.
	   This is why we set the modifier's <emphasis>Output property</emphasis> to the name <literal>InitialCharge</literal>. 
	   This will let the modifier write its stored values to a new property with a different name and preserve the current values
	   stored in the <literal>Charge</literal> property.
	</para>
	<para>
	  Finally, we can use the <link linkend="particles.modifiers.compute_property">Compute property</link> modifier to compute
	  the difference between the particle properties <literal>Charge</literal> (which is time-dependent) and <literal>InitialCharge</literal> 
	  (which is static thanks to the <emphasis>Freeze property</emphasis> modifier) at each frame of the simulation sequence.
	</para>
  </simplesect>
    
  <simplesect>
    <title>Example 3</title>
	  <para>
	     Another typical scenario for this modifier is described in <link linkend="howto.marker_particles">this tutorial</link>.
	  </para>
  </simplesect>  
    
  <simplesect>
    <title>Implementation note</title>
    <para>
      If the <literal>Particle Identifier</literal> property is defined, the modifier use the IDs to 
      assign the stored property values to the correct particles. If no particle IDs are defined, then the 
      number of particles and the order in which they are stored must not change in between simulation frames.
    </para>
  </simplesect>  
  
</section>
