update movie15.

git-svn-id: svn://tug.org/texlive/trunk@2519 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 88 insertions, 32 deletions

diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.tex b/Master/texmf-dist/doc/latex/movie15/movie15.tex
index 18f7d208363..5a0fb60e052 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.tex
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.tex
@@ -5,7 +5,7 @@
 % for the details of that license.
 %
 \documentclass[a4paper]{article}
-
+\frenchspacing
 \usepackage[3D]{movie15}
 \usepackage{ragged2e}
 \usepackage{amssymb}
@@ -35,7 +35,7 @@
   pdftitle={The movie15 Package},
   pdfsubject={Documentation},
   pdfauthor={Alexander Grahn},
-  pdfkeywords={embed, embedded, multimedia, movie, sound, 3D, LaTeX, pdfLaTeX, PDF, Adobe},
+  pdfkeywords={embed, include, multimedia, movie, sound, video, animation, JavaScript, 3D, LaTeX, pdfLaTeX, PDF},
   citebordercolor={0 0 1},
   filebordercolor={0 0 1},
   linkbordercolor={0 0 1},
@@ -49,8 +49,9 @@
 \author{Alexander Grahn\\[1ex]\includegraphics[height=2.7ex]{mailto}}
 \maketitle
 
-\begin{abstract}
-A \LaTeX{} package for inclusion of movies, sounds and 3D objects into PDF documents with PDF-1.5/1.6 compatibility.
+\begin{abstract}\noindent
+A \LaTeX{} package for inclusion of movies, sounds and 3D objects into PDF documents with PDF-1.5/1.6 compatibility.\\[0.2\baselineskip]
+\emph{Keywords}: embed, include, multimedia, movie, sound, video, animation, JavaScript, 3D, LaTeX, pdfLaTeX, PDF
 \end{abstract}
 
 \tableofcontents
@@ -93,16 +94,14 @@ Enables the 3D feature from the PDF-1.6 specification. Inclusion of 3D files int
 \begin{verbatim}
 draft
 \end{verbatim}
-Media files are not included. Just the file name is printed in a box of size \verb+<width>+$\times$(\verb+<height>++\verb+<depth>+), see \hyperlink{lnk:widthheight}{below}.
+Media files are not included. Just the file name is printed in a box of size \verb+<width>+$\times$(\verb+<height>++\verb+<depth>+).
 \begin{verbatim}
 final
 \end{verbatim}
 The opposite of draft. Useful to override a global draft option specified
 in the \verb+\documentclass+ command.
 
-If PDF is generated via DVI and Postscript by the usual \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ sequence of commands, the `graphicx' and `hyperref' packages are required and must be loaded \emph{after} `movie15'.
-
-In the case of pdf\LaTeX{}, the `graphicx' and `hyperref' packages are not required.
+If PDF is generated via DVI and Postscript by the usual \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ sequence of commands, the `graphicx' and `hyperref' packages are required. In the case of pdf\LaTeX{}, the `graphicx' and `hyperref' packages are not required.
 
 Note that several runs may be necessary to resolve internally created cross-references. Appropriate warnings will be issued in such cases.
 
@@ -112,7 +111,7 @@ Movies, sounds and 3D objects are embedded into the document using the command
 \begin{verbatim}
     \includemovie[<options>]{<width>}{<height>}{<media file>}
 \end{verbatim}
-\hypertarget{lnk:widthheight}{}Unless left empty, the \verb+<width>+ and \verb+<height>+ arguments must be given in valid \TeX{} dimensions. Horizontal and vertical dimensions of the media clip are scaled independently to fit \verb+<width>+ and \verb+<height>+ or, if the two latter are empty, to fit the size of the text box, given as argument to the `\verb+text+' option, see \hyperlink{lnk:textoption}{below}. \verb+<media file>+ specifies the file name of the media clip. If the media file is embedded as part of the final PDF output, which is the default, it may reside wherever \TeX{} or Ghostscript search for input files, depending on the PDF producing method.
+Unless left empty, the \verb+<width>+ and \verb+<height>+ arguments must be given in valid \TeX{} dimensions. Horizontal and vertical dimensions of the media clip are scaled independently to fit \verb+<width>+ and \verb+<height>+ or, if the two latter are empty, to fit the size of the text box, given as argument to the `\verb+text+' option; see \hyperlink{lnk:textoption}{below}. \verb+<media file>+ specifies the file name of the media clip. If the media file is embedded as part of the final PDF output, which is the default, it may reside wherever \TeX{} or Ghostscript search for input files, depending on the PDF producing method.
 
 Below, common options to \verb+\includemovie+ are listed. Options specific to embedding of 3D content are discussed separately in section~\ref{sec:3D}. The impatient reader may advance directly to the \hyperlink{sec:3Dtut}{3D quick-start guide}, which summarizes the basic steps for embedding 3D objects.
 \begin{verbatim}
@@ -197,7 +196,7 @@ Forces a particular media player plug-in to be used instead of the default one.
 \begin{verbatim}
 poster
 \end{verbatim}
-The first frame of the movie or the frame at the beginning of the movie section specified by the `\verb+startat+' and `\verb+endat+' options is shown.
+The first frame of the movie or the frame at the beginning of the movie section specified by the `\verb+startat+' option is shown.
 \begin{verbatim}
 poster=<image>
 \end{verbatim}
@@ -235,7 +234,7 @@ text=<text>
  \includemovie[text={\includegraphics[scale=2]{path/to/poster}}]
    {}{}{path/to/movie}
 \end{verbatim}
-In combination with the `\verb+poster+' option, where the poster image will be rendered from the movie during runtime, the PDF file size can be reduced somewhat by putting \verb+\includegraphics+ into a \verb+\phantom+ box:
+In combination with the `\verb+poster+' option, which causes the poster image to be rendered from the movie during runtime, the PDF file size can be reduced somewhat by putting \verb+\includegraphics+ into a \verb+\phantom+ box:
 \begin{verbatim}
    \includemovie[
      poster,
@@ -256,7 +255,7 @@ volume=<percentage of original volume>
 The meaning of this option should be self explaining.
 
 \subsection{Inclusion of 3D objects}\label{sec:3D}
-The PDF-1.6 specification, which was introduced with the advent of Adobe Acrobat/Reader 7, allows embedding of 3-dimensional graphic objects, such as CAD models or 3D scientific data, and lets the user interactively manipulate them. At time of writing this documentation, the only supported file format is U3D~\cite{3diforg}, and only one commercial software~\cite{dexp} for exporting into U3D format, yet from a number of CAD and 3D vector formats, including DXF and VRML, was known. Nevertheless, a try-out version of~\cite{dexp} can be downloaded without charge.
+The PDF-1.6 specification, which was introduced with the advent of Adobe Acrobat/Reader 7, allows embedding of 3-dimensional graphic objects, such as CAD models or 3D scientific data, and lets the user interactively manipulate them. At time of writing this documentation, the only supported file format was U3D~\cite{3diforg}, and only one commercial software~\cite{dexp} for exporting into the U3D format, yet from a number of CAD and 3D vector formats, including DXF and VRML, was known. Nevertheless, a try-out version of~\cite{dexp} can be downloaded without charge.
 
 Selection of the `\verb+3D+' package option enables the 3D feature. Most of the command options listed in section~\ref{usrif} do what they are supposed to do in the case of embedded 3D as well. Other options are ignored, in particular `\verb+repeat+', `\verb+palindrome+', `\verb+startat+', `\verb+endat+', `\verb+rate+' and `\verb+volume+', because they do not make sense and `\verb+mouse+', because 3D objects are interactive by definition. Options `\verb+inline=false+' and `\verb+url+' are supported, but imply option `{\tt{}externalview\-er}', because the 3D Reader plug-in handles embedded files only.
 
@@ -270,7 +269,7 @@ The \emph{default view}, i.\,e. the view that is shown initially after activatin
 \begin{verbatim}
 3Daac=<angle>
 \end{verbatim}
-This option sets the aperture angle of the camera, measured in degrees. Fixed point real numbers between 0 and 180 are admissible. A sensible value of 30 is pre-set by default. Larger values can be used to achieve wide-angle or fish-eye effects, see example~\ref{ex3d} in section~\ref{examples}.
+This option sets the aperture angle of the camera, measured in degrees. Fixed point real numbers between 0 and 180 are admissible. A sensible value of 30 is pre-set by default. Larger values can be used to achieve wide-angle or fish-eye effects. See example~\ref{ex3d} in section~\ref{examples}.
 \begin{verbatim}
 3Dc2c=<x> <y> <z>
 \end{verbatim}
@@ -284,6 +283,10 @@ are allowed.
 \end{verbatim}
 \verb+<x> <y> <z>+ specify the positional vector $\overrightarrow{COO}$ of the centre of orbit. See option `\verb+3Dc2c+' for the number format of \verb+<x> <y> <z>+.
 \begin{verbatim}
+3Droll=<roll>
+\end{verbatim}
+Prescribes an initial camera roll around the optical axis (in clockwise direction, if \verb+<roll>+ is greater that zero); measured in degrees.
+\begin{verbatim}
 3Droo=<r>
 \end{verbatim}
 \verb+<r>+ (always positive!) specifies the radius of orbit $ROO$ of the virtual camera. See option `\verb+3Dc2c+' for the number format of \verb+<r>+.
@@ -295,9 +298,9 @@ Without the above options the virtual camera sits at the origin $(0,0,0)$ of the
 \end{verbatim}
 Instead of or in addition to the default view, further \emph{named views} can be set in an auxiliary file specified by the `\verb+3Dviews+' option. The additional views can later be selected from a drop down list in the tool bar that is associated with every activated 3D object in the Reader. The file \verb+<views file>+ contains lines which obey the syntax:
 \begin{verbatim}
-[<name>]{<coo_x> <coo_y> <coo_z>}{<c2c_x> <c2c_y> <c2c_z>}{<roo>}{<aac>}
+[<name>]{<coo_x> <coo_y> <coo_z>}{<c2c_x> <c2c_y> <c2c_z>}{<roo>}{<roll>}{<aac>}
 \end{verbatim}
-The \verb+<name>+ entry is optional. If \verb+<name>+ is not given, a default name consisting of `View' followed by the number of the current entry in the list is formed. For \verb+<coo_x>+, \verb+<coo_y>+, \verb+<coo_z>+, \verb+<c2c_x>+, \verb+<c2c_y>+, \verb+<c2c_z>+, \verb+<roo>+ and \verb+<aac>+ the same rules as for the corresponding options `\verb+3Dcoo+', `\verb+3Dc2c+', `\verb+3Droo+' and `\verb+3Daac+' apply. Empty braces, \verb+{}+, are possible and cause default values to be used. Trailing spaces or comment signs (\%) are allowed. Reading of the file stops either at its end, at the first empty line encountered or at the first line containing nothing but spaces and/or a comment sign followed by arbitrary stuff.
+The \verb+<name>+ entry is optional. If \verb+<name>+ is not given, a default name consisting of `View' followed by the number of the current entry in the list is formed. For \verb+<coo_x>+, \verb+<coo_y>+, \verb+<coo_z>+, \verb+<c2c_x>+, \verb+<c2c_y>+, \verb+<c2c_z>+, \verb+<roo>+, \verb+<roll>+ and \verb+<aac>+ the same rules as for the corresponding options `\verb+3Dcoo+', `\verb+3Dc2c+', `\verb+3Droo+', `\verb+3Droll+' and `\verb+3Daac+' apply. Empty braces, \verb+{}+, are possible and cause default values to be used. Trailing spaces or comment signs (\%) are allowed. Reading of the file stops either at its end, at the first empty line encountered or at the first line containing nothing but spaces and/or a comment sign followed by arbitrary stuff. See option `\verb+3Dgetview+' of \verb+\movieref+ on how to get the camera settings of the current view in the Reader, which can be used to populate a file of additional views.
 
 \begin{verbatim}
 3Dbg=<r> <g> <b>
@@ -307,7 +310,7 @@ This option sets the background colour of the canvas. Only fixed point real numb
 \begin{verbatim}
 3Djscript=<JavaScript file>
 \end{verbatim}
-Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates a \verb+<JavaScript file>+ with the 3D object. The script will be executed upon activation of the object. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details.
+Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates \verb+<JavaScript file>+ with the 3D object. The script will be executed upon activation of the object. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details. Directory `\verb+doc/javascript+' contains JavaScript example files for animation and rotation control. The files work off-the-shelf with any 3D file and may be concatenated to combine their effects.
 
 \subsection{Media hyperlinks}\label{hyperlinks}
 A movie, sound or 3D object may serve as the destination of hyperlinks, which are inserted into the document using the command
@@ -350,20 +353,26 @@ Immediately closes the media player.
 \begin{verbatim}
 3Dviewindex=<index>
 \end{verbatim}
-Go to a predefined view of the 3D object. \verb+<index>+ can take `\verb+F+', `\verb+L+', `\verb+N+' or `\verb+P+' to access the first, last, next or previous element of the list of additional views, cf. option `\verb+3Dviews+' of {\tt \string\include\-movie}, or an integer specifying an index into the list. In the case of `\verb+N+' and `\verb+P+', repeated clicking onto the hyperlink allows to cycle through the list in forward or backward direction. `\verb+D+' gives access to the default view.
+Go to a predefined view of the 3D object. \verb+<index>+ can take `\verb+F+', `\verb+L+', `\verb+N+' or `\verb+P+' to access the first, last, next or previous element of the list of additional views, see option `\verb+3Dviews+' of {\tt \string\include\-movie}, or an integer specifying an index into the list. In the case of `\verb+N+' and `\verb+P+', repeated clicking onto the hyperlink allows to cycle through the list in forward or backward direction. `\verb+D+' gives access to the default view.
 
 \begin{verbatim}
 3Daac=<angle>
 3Dc2c=<x> <y> <z>
 3Dcoo=<x> <y> <z>
+3Droll=<roll>
 3Droo=<r>
 \end{verbatim}
-Instead of referencing an existing view of the 3D object, a new one can be defined using any of these options, cf. section~\ref{sec:3D}.
+Instead of referencing an existing view of the 3D object, a new one can be defined using any of these options. See section~\ref{sec:3D}.
 
 \begin{verbatim}
 3Dcalculate[=<aac angle>]
 \end{verbatim}
-Creates a link for calculating `\verb+3Droo+' and `\verb+3Dcoo+' settings of the virtual camera. Clicking the link opens a dialogue box from which the settings can be copied to the clipboard for later insertion into the option list of \verb+\includemovie+. The default aperture angle of $30$\textdegree{} is used for the calculation unless an optional \verb+<aac angle>+ has been provided.
+Mainly used during document authoring. Creates a link for calculating `\verb+3Droo+' and `\verb+3Dcoo+' settings of the virtual camera, which may be used to define a default view. Clicking the link opens a dialogue box from which the settings can be copied to the clipboard for later insertion into the option list of \verb+\includemovie+. The default aperture angle of $30$\textdegree{} is used for the calculation unless an optional \verb+<aac angle>+ has been provided.
+
+\begin{verbatim}
+3Dgetview
+\end{verbatim}
+Mainly used during document authoring. Camera settings corresponding to the current view in the Reader are printed to a dialogue box. The output is readily formatted to be inserted into a file of predefined views. See option `\verb+3Dviews+'.
 
 \begin{verbatim}
 3Djscript=<JavaScript file>
@@ -374,7 +383,7 @@ Runs the script \verb+<JavaScript file>+ after clicking the link. Unlike the scr
 \end{verbatim}
 For details about Acrobat JavaScript and its Annot3D object, see \cite{jscript}.
 
-\newpage
+%\newpage
 \subsection{Compatibility commands}
 Two user commands have been provided that make `movie15' a replacement for the `multimedia' package which is part of Till Tantau's `Beamer' Class:
 \begin{verbatim}
@@ -414,7 +423,7 @@ duration=<duration in seconds>s
 \end{verbatim}
 The duration of the media segment to be played. The trailing `\verb+s+' is mandatory. Note that `\verb+duration+' cannot be used together with option `\verb+startat+' from \verb+\includemovie+. In order to define a media segment options can be combined as follows: `\verb+startat+'/`\verb+endat+', `\verb+start+'/`\verb+endat+', `\verb+start+'/`\verb+duration+'.
 
-\newpage
+%\newpage
 \section{Examples}\label{examples}
 \begin{enumerate}
 \item A short circular MPEG movie, taken from \href{http://www.linux-video.net/Samples/}{\tt http://www.linux-video.net/} \href{http://www.linux-video.net/Samples/}{\tt Samples/}
@@ -472,8 +481,8 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \end{center}
 \end{minipage}
 
-\newpage
-\item\label{ex3d} Embedded U3D file. It is based on a VRML model by Peter Whitehouse \href{mailto:pwhitehouse@optusnet.com.au}{\tt <pwhitehouse@optusnet.com.au>}. Conversion to U3D has been made with DeepExploration\textsuperscript{\scriptsize\textregistered}\cite{dexp}. The file `{\tt dice.vws}' provides additional views to be selected from the 3D toolbar or by right click. The JavaScript `{\tt dice.js}' defines light sources and disables the annoying Gimbal rotation mode.
+%\newpage
+\item\label{ex3d} Embedded U3D file. It is based on a VRML model by Peter Whitehouse, \href{http://www.wonko.info/vrml/index.htm}{\tt http://www.wonko.info/vrml/index.htm}. Conversion to U3D has been made with DeepExploration\textsuperscript{\scriptsize\textregistered}\cite{dexp}. The file `{\tt dice.vws}' provides predefined views to be selected from the 3D toolbar or by right click. The JavaScript `{\tt dice.js}' defines light sources and disables the annoying Gimbal rotation mode.
 
 \begin{minipage}{0.5\linewidth}
 {\tt%
@@ -482,8 +491,7 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
   \phantom{xx}label=dice,\\
   \phantom{xx}text=(dice.u3d),\\
   \phantom{xx}3Droo=27,\\
-  \phantom{xx}3Dc2c=1 -1 1,\\
-  \phantom{xx}3Dbg=1 1 1,\\
+%  \phantom{xx}3Dc2c=1 -1 1,\\
   \phantom{xx}3Dviews=dice.vws,\\
   \phantom{xx}3Djscript=dice.js\\
   ]\string{\\
@@ -506,13 +514,11 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
     label=dice,
     text=(dice.u3d),
     3Droo=27,
-    3Dc2c=1 -1 1,
-    3Dbg=1 1 1,
     3Dviews=dice.vws,
     3Djscript=dice.js
   ]{\linewidth}{\linewidth}{dice.u3d}
 \end{center}
-\movieref[3Dviewindex=N]{dice}{Click here} to cycle through the list of additional views. \movieref[3Dcalculate=60]{dice}{This link} calculates 3D option settings for a 60\textdegree{} aperture angle of the virtual camera.
+\movieref[3Dviewindex=N]{dice}{Click here} to cycle through the list of predefined views. \movieref[3Dcalculate=60]{dice}{This link} calculates 3D option settings for a 60\textdegree{} aperture angle of the virtual camera.
 \end{minipage}
 
 \end{enumerate}
@@ -533,14 +539,14 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
     \string\movieref[3Dcalculate]\string{my\_label\string}\string{Click here!\string}
   }
 
-  \item Compile and recompile the document source until no more `movie15' related warnings appear.
+  \item Compile and recompile the document until no more `movie15' related warnings appear.
   \item Open the PDF document with Adobe Reader and go to the page containing the 3D object. Click the link and wait for a dialogue box to pop up.
   \item Copy the settings ({\tt 3Droo=...}, {\tt 3Dcoo=...}) from the dialogue box into the option list of {\tt \string\include\-movie}. Remove the link from the document source:
 
   {\tt%
     \string\includemovie[\\
-	\phantom{xx}poster, 3Droo=33.3333, 3Dcoo=1.2345 9.8765 0
-	\\]\string{\\
+	\phantom{xx}poster, 3Droo=33.3333, 3Dcoo=1.2345 9.8765 0\\
+	]\string{\\
 	\phantom{xx}.5\string\linewidth\\
 	\string}\string{\\
 	\phantom{xx}.5\string\linewidth\\
@@ -549,9 +555,59 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 	\string}
   }
 
-  \item Again, compile and recompile the document source until no more `movie15' related warnings appear.
+  \item Again, compile and recompile the document until no more `movie15' related warnings appear.
+  \xdef\lastcount{\theenumi}
 \end{enumerate}
 
+\emph{Optional steps:}
+
+\begin{enumerate}
+  \setcounter{enumi}{\lastcount}
+  \item Associate a JavaScript with the 3D object:
+
+  {\tt%
+    \string\includemovie[\\
+	\phantom{xx}..., 3Djscript=my\_script.js\\
+	]\string{\\
+	\phantom{xx}.5\string\linewidth\\
+	\string}\string{\\
+	\phantom{xx}.5\string\linewidth\\
+	\string}\string{\\
+    \phantom{xx}my\_file.u3d\\
+	\string}
+  }
+
+  JavaScript is required if you want to make use of embedded animation. The example file `{\tt{}animation.js}' in the `{\tt{}doc/javascript}' directory may serve as a starting point.
+  
+  Another useful example file you should definitely experiment with is `{\tt{}turn\-table.js}'. It improves the rotational behaviour of the 3D object, because it prevents the object from tilting to the side while dragging the mouse.
+
+  All files in `{\tt{}doc/javascript}' work off-the-shelf and can be copied into a single file in order to combine their effects.
+
+  \item Create a file with predefined views of the 3D object and attach it to the latter using the `{\tt{}3Dviews}' option:
+
+  {\tt%
+    \string\includemovie[\\
+	\phantom{xx}..., label=my\_label, 3Dviews=my\_views.vws\\
+	]\string{\\
+	\phantom{xx}.5\string\linewidth\\
+	\string}\string{\\
+	\phantom{xx}.5\string\linewidth\\
+	\string}\string{\\
+    \phantom{xx}my\_file.u3d\\
+	\string}
+  }
+
+  The views file can easily be populated using a temporarily inserted {\tt \string\movie\-ref} link:
+
+  {\tt%
+    \string\movieref[3Dgetview]\string{my\_label\string}\string{Click here!\string}
+  }
+
+  Manipulate the 3D object in the Reader by means of the `Rotate', `Pan', `Zoom' and `Walk' tools as well as the `Zoom to Part' action (to be selected from the context menu items `Tools' and `Part Options'). A line, readily formatted for insertion into the views file, that contains the settings according to the current view can be copied from a dialogue box which pops up after clicking the link.
+\end{enumerate}
+
+
+
 \section{Media formats}
 \begin{table}[H]
 \caption{Media formats for use with Adobe Reader (partially from \cite{pdfspec})}\label{table:mime}