From: Carl Hetherington <cth@carlh.net>
Date: Wed, 6 Nov 2013 23:07:41 +0000 (+0000)
Subject: Various manual bits.
X-Git-Tag: v2.0.48~1191
X-Git-Url: https://git.carlh.net/gitweb/?p=dcpomatic.git;a=commitdiff_plain;h=a44238ce4ce8f0ba29e093de92067b708454a876

Various manual bits.
---

diff --git a/.gitignore b/.gitignore
index 0fd802092..3dc9f50fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,9 @@ doc/design/*.log
 doc/design/*.aux
 doc/manual/diagrams/*.pdf
 doc/manual/diagrams/*.png
+doc/manual/colour.pdf
+doc/manual/colour.log
+doc/manual/colour.aux
 .be/id-cache
 *.pyc
 GPATH
diff --git a/doc/manual/Makefile b/doc/manual/Makefile
index 991af212c..8be93db19 100644
--- a/doc/manual/Makefile
+++ b/doc/manual/Makefile
@@ -6,7 +6,9 @@ DIAGRAMS := file-structure.svg 3d-left-right.svg
 
 SCREENSHOTS := file-new.png video-new-film.png still-new-film.png video-select-content-file.png \
                still-select-content-file.png examine-thumbs.png examine-content.png timing-tab.png \
-               calculate-audio-gain.png prefs.png making-dcp.png filters.png video-tab.png audio-tab.png subtitles-tab.png \
+               calculate-audio-gain.png \
+               prefs-kdm-email.png prefs-colour-conversions.png prefs-metadata.png prefs-misc.png prefs-tms.png \
+               making-dcp.png filters.png video-tab.png audio-tab.png subtitles-tab.png \
                audio-plot.png audio-map-eg1.png audio-map-eg2.png audio-map-eg3.png kdm.png
 
 XML := dcpomatic.xml
diff --git a/doc/manual/colour.tex b/doc/manual/colour.tex
new file mode 100644
index 000000000..a742788fc
--- /dev/null
+++ b/doc/manual/colour.tex
@@ -0,0 +1,59 @@
+\documentclass{article}
+
+\pagestyle{empty}
+\usepackage{amsmath,mathtools}
+\title{Colour conversion in DCP-o-matic}
+\author{}
+\date{}
+\begin{document}
+\maketitle
+
+Conversion from an RGB pixel $(r, g, b)$ is done in three steps.
+First, the input gamma $\gamma_i$ is applied.  This is done in one of
+two ways, depending on the setting of the ``linearise input gamma
+curve for low values'' option.  If linearisation is disabled, we use:
+
+\begin{align*}
+r' &= r^{\gamma_i} \\
+g' &= g^{\gamma_i} \\
+b' &= b^{\gamma_i}
+\end{align*}
+
+otherwise, with linearisation enabled, we use:
+
+\begin{align*}
+r' &= \begin{dcases}
+\frac{r}{12.92} & r \leq 0.04045 \\
+\left(\frac{r + 0.055}{1.055}\right)^{\gamma_i} & r > 0.04045
+\end{dcases}
+\end{align*}
+
+Next, the colour transformation matrix is used to convert to XYZ:
+
+\begin{align*}
+\left[\begin{array}{c}
+x \\
+y \\
+z
+\end{array}\right] &=
+\left[\begin{array}{ccc}
+m_{11} & m_{12} & m_{13} \\
+m_{21} & m_{22} & m_{23} \\
+m_{31} & m_{32} & m_{33}
+\end{array}\right]
+\left[\begin{array}{c}
+r' \\
+g' \\
+b'
+\end{array}\right]
+\end{align*}
+
+Finally, the output gamma $\gamma_o$ is applied to give our final XYZ values $(x', y', z')$:
+
+\begin{align*}
+x' &= x^{1/\gamma_o} \\
+y' &= y^{1/\gamma_o} \\
+z' &= z^{1/\gamma_o} \\
+\end{align*}
+
+\end{document}
diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index 29c69b443..3ff9cc155 100644
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -8,7 +8,7 @@
 <!ENTITY % extensions SYSTEM "extensions.ent">
 %extensions;
 ]>
-<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<book xmlns="http://docbook.org/ns/docbook" xmlns:mml="http://www.w3.org/1998/Math/MathML" version="5.0" xml:lang="en">
 
 <!-- By good luck or good management, the scale parameter to imagedata
      appears only to affect PDF output.  HTML scaling is done in the
@@ -1163,7 +1163,7 @@ behaviour.  This chapter explains those options.
 <para>
 The preferences dialogue is opened by choosing
 <guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu.  The dialogue is split into four tabs.
+menu.  The dialogue is split into five tabs.
 </para>
 
 <section>
@@ -1205,8 +1205,21 @@ read about how to contribute a translation.
 <para>
 When DCP-o-matic is encoding DCPs it can use multiple parallel threads
 to speed things up.  Set this value to the number of threads
-DCP-o-matic should use.  This would typically be set to the number of
-processors (or processor cores) in your machine.
+DCP-o-matic should use.  This should normally be the number of
+processors (or processor cores) in your machine.  DCP-o-matic will try
+to set this up correctly when you run it for the first time.
+</para>
+
+</section>
+
+<section>
+<title>KDM emails</title>
+
+<para>
+DCP-o-matic can send KDMs (see <xref linkend="ch-encryption"/>) to
+cinemas (or anywhere else) via email.  To make this work, enter a
+suitable outgoing mail (SMTP) server and &lsquo;from&rsquo; address
+for these emails.
 </para>
 
 </section>
@@ -1222,30 +1235,36 @@ properties of new films that you create.
 </section>
 </section>
 
-<section xml:id="sec-prefs-servers">
-<title>Encoding servers</title>
+<section>
+<title>Colour conversions</title>
 
 <para>
-The encoding servers tab is shown in <xref linkend="fig-prefs-servers"/>.
+The colour conversions tab is shown in <xref linkend="fig-prefs-colour-conversions"/>.
 </para>
 
-<figure id="fig-prefs-servers"> 
-  <title>Encoding servers preferences</title> 
+<figure id="fig-prefs-colour-conversions">
+  <title>Colour conversions preferences</title> 
   <mediaobject>
     <imageobject> 
-      <imagedata fileref="screenshots/prefs-servers&scs;"/>
+      <imagedata fileref="screenshots/prefs-colour-conversions&scs;"/>
     </imageobject> 
   </mediaobject>
 </figure>
 
 <para>
-If you have spare machines sitting around on your network not doing
-much, they can be pressed into service to speed up DCP encodes.  This
-is done by running a small server program on the machine, which will
-encode video sent to it by the &lsquo;master&rsquo; DCP-o-matic.  This
-option is described in more detail in <xref linkend="ch-servers"/>.
-Use these preferences to specify the encoding servers that should be
-used.
+As part of the encoding process, DCP-o-matic has to convert the colour
+space of the source files that you use into XYZ, the colour space used
+by the DCI standard.
+</para>
+
+<para>
+Colour conversion is discussed in more detail in a separate document
+<ulink url="http://dcpomatic.com/manual/colour.pdf">colour.pdf</a>.
+</para>
+
+<para>
+These preferences control a list of presets which are suitable for
+converting from common input colour spaces to XYZ.
 </para>
 
 </section>
@@ -1303,8 +1322,32 @@ credentials required to log into the TMS via SSH.
 </para>
 </section>
 
+<section>
+<title>KDM email</title>
+
+<para>
+The KDM email is shown in <xref linkend="fig-prefs-kdm-email"/>.
+</para>
+
+<figure id="fig-prefs-kdm-email"> 
+  <title>KDM email preferences</title> 
+  <mediaobject>
+    <imageobject> 
+      <imagedata fileref="screenshots/prefs-kdm-email&scs;"/>
+    </imageobject> 
+  </mediaobject>
+</figure>
+
+<para>
+This is a template for the email that is used to send KDMs out to
+cinemas.  You can change it to say whatever you like.  The
+&lsquo;magic&rsquo; string <code>$CPL_NAME</code> will be replaced by
+DCP's title.
+</para>
 
 </section>
+</section>
+
 </chapter>
 
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-frame-rates">
@@ -1421,7 +1464,12 @@ than one machine at the same time.  An instance of DCP-o-matic can
 offload some of the time-consuming JPEG2000 encoding to any number of
 other machines on a network.  To do this, one &lsquo;master&rsquo;
 machine runs DCP-o-matic, and the &lsquo;server&rsquo; machines run
-a small program called &lsquo;dcpomatic_server&rsquo;.
+a small program called <code>dcpomatic_server</code>.
+</para>
+
+<para>
+The master and server machines do not need to be the same type, so you
+can mix Windows PCs, Macs and Linux machines as you wish.
 </para>
 
 <section>
@@ -1465,24 +1513,28 @@ tray; right-click it to open a menu from whence you can quit the
 server or open a window to show its status.
 </para>
 
+<para>If you would rather not bother installing DCP-o-matic on your
+server computers, the other option is to use the live-CD
+image that you can download from the <ulink
+url="http://dcpomatic.com/">DCP-o-matic web site.</ulink></para>
+
+<para>Either burn the image to CD, or write it to a USB stick (using
+something like <ulink
+url="http://unetbootin.sourceforge.net/">unetbootin</ulink>).  Boot a
+PC from the CD or USB stick and it becomes a DCP-o-matic server
+without touching your standard operating system install.
+</para>
+
 </section>
 <section>
 <title>Setting up DCP-o-matic</title>
 
 <para>
-Once your servers are running, you need to tell your master
-DCP-o-matic instance about them.  Start DCP-o-matic and open the
-<guilabel>Preferences</guilabel> dialog from the
-<guilabel>Edit</guilabel> menu.  At the bottom of this dialog is a
-section where you can add, edit and remove encoding servers.  For each
-encoding server you need only specify its IP address and the number of
-threads that it is running, so that DCP-o-matic knows how many
-parallel encode jobs to send to the server.
-</para>
-
-<para>
-Once this is done, any encodes that you start will split the workload
-up between the master machine and the servers.
+DCP-o-matic periodically looks on the local network for servers.  Any
+that it finds are given work to do during encodes.  Selecting
+<guilabel>Encoding Servers</guilabel> from the
+<guilabel>Tools</guilabel> menu brings up a window which shows that
+servers that DCP-o-matic has found.
 </para>
 
 </section>
@@ -1500,13 +1552,28 @@ You will probably find that using a 1Gb/s or faster network will
 provide a significant speed-up compared to a 100Mb/s network.
 </para>
 
+</section>
+
+</chapter>
+
+<chapter xml:id="ch-colour-conversions" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Colour conversions</title>
+
+<para>
+As part of the encoding process, DCP-o-matic has to convert the colour
+space of the source files that you use into XYZ, the colour space used
+by the DCI standard.
+</para>
+
 <para>
-Making changes to the server configuration in the master DCP-o-matic
-will have no effect while an encode is running; the changes will only
-be noticed when a new encode is started.
+In order to do this, source colour is converted in three steps:
 </para>
 
-</section>
+<itemizedlist>
+<listitem>Input gamma correction.</listitem>
+<listitem>Multiplication by a conversion matrix.</listitem>
+<listitem>Output gamma correction.</listitem>
+</itemizedlist>
 
 </chapter>
 
diff --git a/doc/manual/screenshots/prefs-colour-conversions.png b/doc/manual/screenshots/prefs-colour-conversions.png
new file mode 100644
index 000000000..4ac4dc1d1
Binary files /dev/null and b/doc/manual/screenshots/prefs-colour-conversions.png differ
diff --git a/doc/manual/screenshots/prefs-kdm-email.png b/doc/manual/screenshots/prefs-kdm-email.png
new file mode 100644
index 000000000..26ab5c044
Binary files /dev/null and b/doc/manual/screenshots/prefs-kdm-email.png differ
diff --git a/doc/manual/screenshots/prefs-metadata.png b/doc/manual/screenshots/prefs-metadata.png
index bcfc19e98..c2492c7f3 100644
Binary files a/doc/manual/screenshots/prefs-metadata.png and b/doc/manual/screenshots/prefs-metadata.png differ
diff --git a/doc/manual/screenshots/prefs-misc.png b/doc/manual/screenshots/prefs-misc.png
index ce6e85ee9..7e3a45a39 100644
Binary files a/doc/manual/screenshots/prefs-misc.png and b/doc/manual/screenshots/prefs-misc.png differ
diff --git a/doc/manual/screenshots/prefs-servers.png b/doc/manual/screenshots/prefs-servers.png
deleted file mode 100644
index 3b7e8e7c1..000000000
Binary files a/doc/manual/screenshots/prefs-servers.png and /dev/null differ
diff --git a/doc/manual/screenshots/prefs-tms.png b/doc/manual/screenshots/prefs-tms.png
index ed3878303..effc3ad71 100644
Binary files a/doc/manual/screenshots/prefs-tms.png and b/doc/manual/screenshots/prefs-tms.png differ
diff --git a/doc/manual/screenshots/prefs.png b/doc/manual/screenshots/prefs.png
deleted file mode 100644
index a1e0e083e..000000000
Binary files a/doc/manual/screenshots/prefs.png and /dev/null differ