movie15 update (23mar09)

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

1 files changed, 133 insertions, 59 deletions

diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.tex b/Master/texmf-dist/doc/latex/movie15/movie15.tex
index 8f18cc27993..af172194d7e 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.tex
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.tex
@@ -101,7 +101,7 @@ final
 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. 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' package is required.
 
 Note that several runs may be necessary to resolve internally created cross-references. Appropriate warnings will be issued in such cases.
 
@@ -294,14 +294,6 @@ Prescribes an initial camera roll around the optical axis (in clockwise directio
 Without the above options the virtual camera sits at the origin $(0,0,0)$ of the World, looking in the positive $Y$ direction, i.\,e. default settings of \verb+3Droo=0+, \verb+3Dcoo=0 0 0+ and  \verb+3Dc2c=0 -1 0+ are assumed. (Note that $\overrightarrow{C2C}$ is the opposite of the view vector!) Thus, in order to get a `front view' of the 3D object it is sufficient to set the radius of orbit, i.\,e. the distance between camera and object appropriately. Sometimes you may want to adjust the orbital centre, i.\,e. the target of the camera as well, in particular, if the object is irregularly shaped. Fortunately, it is possible to let the values of the corresponding options be determined automatically. Simply insert a hyperlink using the \verb+\movieref+ command together with the `\verb+3Dcalculate+' option. Once the settings for `\verb+3Droo+' and `\verb+3Dcoo+' have been calculated, the hyperlink can be removed again. See section \ref{hyperlinks} for an explanation and example \ref{ex3d} in section \ref{examples}.
 
 \begin{verbatim}
-3Dviews=<views file>
-\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>}{<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>+, \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>
 \end{verbatim}
 This option sets the background colour of the canvas. Only fixed point real numbers in the range from 0 to 1 are allowed for the colour components.
@@ -315,6 +307,83 @@ Sets the default lighting scheme. The following values are honoured: `\verb+None
 \begin{flushleft}
 Sets the default render mode. The following values are honoured: `\verb+Solid+', `\verb+SolidWireframe+', `\verb+Transparent+', `\verb+TransparentWireframe+', `\verb+BoundingBox+', `\verb+TransparentBoundingBox+', `\verb+TransparentBoundingBoxOutline+', `\verb+Wireframe+', `\verb+ShadedWireframe+', `\verb+HiddenWireframe+', `\verb+Vertices+', `\verb+ShadedVertices+', `\verb+SolidOutline+', `\verb+Illustration+', `\verb+ShadedIllustration+'.
 \end{flushleft}
+
+\begin{verbatim}
+3Dviews=<views file>
+\end{verbatim}
+\emph{Deprecated}. Superseeded by the `\verb+3Dviews2+' option and a new, more flexible views file syntax (see below). File \verb+<views file>+ specifies predefined camera positions. It contains lines with the following syntax:
+\begin{verbatim}
+[<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>+, \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}
+3Dviews2=<views file>
+\end{verbatim}
+Instead of or in addition to the default view, further \emph{named views} can be set in an auxiliary file `\verb+<views file>+'. Besides the virtual camera position, it is possible to adjust the rendering attributes, such as visibility and transparency, of every single part in the scene. Moreover, background colour and scene lighting can be set individually for every view. The additional views can later be selected either from a drop down list in the tool bar that is associated with the activated 3D object in the Reader or from the context menu of the 3D object.
+
+The file \verb+<views file>+ is structured into view sections, one for every view:
+\begin{verbatim}
+  VIEW[=<optional name>]
+    COO=<coo_x> <coo_y> <coo_z>
+    C2C=<c2c_x> <c2c_y> <c2c_z>
+    ROO=<roo>
+    AAC=<aac>
+    ROLL=<roll>
+    BGCOLOR=<r> <g> <b>
+    RENDERMODE=<render mode>
+    LIGHTS=<lighting scheme>
+    PART=<part name (required) as in the Model Tree>
+      VISIBLE=true | false
+      OPACITY=<part opacity>
+      RENDERMODE=<see option `3Drender' for possible values>
+    END
+    PART=<...>
+      ...
+    END
+    etc.
+  END
+  VIEW
+    ...
+  END
+  etc.
+\end{verbatim}
+A view section starts with the keyword \verb+VIEW+, optionally followed by a name for the view, and ends with the keyword \verb+END+. If no name is given to the view, a default one is created, consisting of `View' followed by the number of the current \verb+VIEW+ section in the file. A \verb+VIEW+ section contains optional entries for setting the camera position and global rendering attributes of the scene as well as \verb+PART+ subsections for setting rendering attributes of parts individually. Table~\ref{tab:views} lists the entries in a \verb+VIEW+ section. Part sub-sections are opened by \verb+PART=<part name>+ and closed by \verb+END+. There may be as many part subsections as there are parts a 3D object is composed of. Table~\ref{tab:parts} lists the possible entries in a \verb+PART+ sub-section. All entries are optional. \verb+<part name>+ is required and must match the part name as indicated in the Model Tree of the 3D object (accessible via right-click onto the model in the Reader). In order to avoid trouble it is recommended that part names be exclusively composed of ASCII characters. You may need to load the U3D/PRC model into the authoring application and edit the part names accordingly.
+
+The views file can be commented. As usual with \LaTeX, comments start with the percent sign.
+
+To facilitate the creation of a views file, a \verb+\movieref+ link with option `\verb+3Dgetview+' can be temporarily inserted into the document. When clicked, it outputs a complete \verb+VIEW+ section corresponding to the current view of the 3D object in the Reader GUI, including camera position as well as all part and viewing options that may be set via the context (right-click) menu of the 3D object. See section \ref{hyperlinks} for details.
+
+\begin{table}
+  \centering
+  \caption{Entries in a {\tt VIEW} section}\label{tab:views}
+  \begin{tabular}[t]{llp{0.3\linewidth}}\hline
+  key & type & value\\\hline\hline
+  COO & three numbers & centre of orbit, see option `{\tt 3Dcoo}'\\ 
+  C2C & three numbers & centre of orbit to camera vector, see option `{\tt 3Dc2c}'\\ 
+  ROO & number & radius of orbit, see option `{\tt 3Droo}'\\ 
+  AAC & number & camera aperture angle, see option `{\tt 3Daac}'\\ 
+  ROLL & number & camera roll, see option `{\tt 3Droll}'\\ 
+  BGCOLOR & three numbers & canvas background colour (RGB), see option `{\tt 3Dbg}'\\ 
+  RENDERMODE & string & render mode of the 3D object, see option `{\tt 3Drender}'\\ 
+  LIGHTS & string & lighting scheme, see option `{\tt 3Dlights}'\\
+  PART & sub-section & part name as in the model tree, see Table~\ref{tab:parts} for list of possible entries\\
+  \hline
+  \end{tabular}
+\end{table}
+
+\begin{table}
+  \centering
+  \caption{Entries in a {\tt PART} sub-section}\label{tab:parts}
+  \begin{tabular}[t]{llp{0.3\linewidth}}\hline
+  key & type & value\\\hline\hline
+  VISIBLE & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of this part\\
+  OPACITY & number & a number between 0.0 and 1.0 specifying the opacity of this part\\
+  RENDERMODE & string & rendermode of this part, overrides global {\tt RENDERMODE} value in parent {\tt VIEW} section, see option `{\tt 3Drender}'\\
+  \hline
+  \end{tabular}
+\end{table}
+
 \begin{verbatim}
 3Djscript=<JavaScript file>
 \end{verbatim}
@@ -386,11 +455,11 @@ Instead of referencing an existing view of the 3D object, a new one can be defin
 \begin{verbatim}
 3Dcalculate[=<aac angle>]
 \end{verbatim}
-Mainly used during document authoring. Creates a link for calculating optimal `\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.
+Mainly used during document authoring. Creates a link for calculating optimal `\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 parameter \verb+<aac angle>+ which is the camera aperture angle $\sphericalangle AAC$ used for calculation is optional. If omitted, the one set by \verb+\includemovie+ option `\verb+3Daac+' is taken.
 \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+'.
+Mainly used during document authoring. Camera settings as well as part and scene rendering attributes that correspond to the current view are printed to a dialogue box. The output is a readily formatted \verb+VIEWS+ section to be inserted into or appended to a file of predefined views. See option `\verb+3Dviews2+'.
 \begin{verbatim}
 3Djscript=<JavaScript file>
 \end{verbatim}
@@ -493,9 +562,9 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \begin{center}
   \includemovie[
     poster,
-	label=alien,
-	text=(AlienSong.mpg),
-	repeat,
+    label=alien,
+    text=(AlienSong.mpg),
+    repeat,
     playerid=AAPL_QuickTime,
     url
   ]{\linewidth}{.75\linewidth}{http://www.linux-video.net/Samples/Mpeg1/AlienSong.mpg}\\
@@ -508,7 +577,7 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \end{center}
 \end{minipage}
 
-\newpage
+%\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 turntable.js}' disables the annoying Gimbal rotation mode.
 
 \begin{minipage}[b]{0.5\linewidth}
@@ -520,8 +589,8 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
   \phantom{xx}text=(dice.u3d),\\
   \phantom{xx}3Droo=27,\\
   \phantom{xx}3Dlights=Cube,\\
-%  \phantom{xx}3Djscript=turntable.js,\\
-  \phantom{xx}3Dviews=dice.vws\\
+  \phantom{xx}3Djscript=turntable.js,\\
+  \phantom{xx}3Dviews2=dice.vws\\
   ]\string{\\
   \phantom{xx}.5\string\linewidth\\
   \string}\string{\\
@@ -539,13 +608,13 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \begin{center}
   \includemovie[
     poster,
-	toolbar, %same as `controls'
+    toolbar, %same as `controls'
     label=dice,
     text=(dice.u3d),
     3Droo=27,
-	3Dlights=Cube,
-    3Dviews=dice.vws,
-%    3Djscript=turntable.js %a bug in Reader 8 causes the script to fail
+    3Dlights=Cube,
+    3Dviews2=dice.vws,
+    3Djscript=turntable.js
   ]{\linewidth}{\linewidth}{dice.u3d}
 \end{center}
 \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.
@@ -561,29 +630,29 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 
   {\tt%
     \string\includemovie[poster, label=my\_label]\string{\\
-	\phantom{xx}.5\string\linewidth\\
-	\string}\string{\\
-	\phantom{xx}.5\string\linewidth\\
-	\string}\string{\\
+    \phantom{xx}.5\string\linewidth\\
+    \string}\string{\\
+    \phantom{xx}.5\string\linewidth\\
+    \string}\string{\\
     \phantom{xx}my\_file.u3d\\
-	\string}\string\\\\
+    \string}\string\\\\
     \string\movieref[3Dcalculate]\string{my\_label\string}\string{Click here!\string}
   }
 
   \item Compile and recompile the document until no more `movie15' related warnings appear.
-  \item Open the PDF document in 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:
+  \item Open the PDF document in Adobe Reader and go to the page containing the 3D object. Click the link and wait for a dialogue box to pop up. Optionally, drag the object with the mouse to change the viewpoint of the camera (the dialogue must be closed beforehand) and click the link again.
+  \item Copy the settings ({\tt 3Droo=...}, {\tt 3Dcoo=...}, etc.) 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}.5\string\linewidth\\
-	\string}\string{\\
-	\phantom{xx}.5\string\linewidth\\
-	\string}\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\\
+    \string}\string{\\
     \phantom{xx}my\_file.u3d\\
-	\string}
+    \string}
   }
 
   \item Again, compile and recompile the document until no more `movie15' related warnings appear.
@@ -594,47 +663,52 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 
 \begin{enumerate}
   \setcounter{enumi}{\lastcount}
-  \item Associate a JavaScript with the 3D object:
+  \item Create a file with predefined views of the 3D object and attach it to the latter using the `{\tt{}3Dviews2}' option:
 
   {\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}..., label=my\_label, 3Dviews2=my\_views.vws\\
+    ]\string{\\
+    \phantom{xx}.5\string\linewidth\\
+    \string}\string{\\
+    \phantom{xx}.5\string\linewidth\\
+    \string}\string{\\
     \phantom{xx}my\_file.u3d\\
-	\string}
+    \string}
   }
 
-  JavaScript is \emph{not} required to make use of \emph{embedded} keyframe animation. Just click the `Play' button in the 3D toolbar of the 3D annotation. However, the example file `{\tt{}animation.js}' in the `{\tt{}doc/javascript}' directory provides additional controls (accessible via the context menu of the 3D annotation) that can be used to change the speed of a running animation. The `Up', `Down' and `Home' keys of the keyboard can also be used.
+  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 using the mouse and any of the `Part' and `Viewing' options from the 3D context menu in the Reader. Visibility, lighting, transparency, render mode etc. of individual parts or of the object as a whole can be changed this way. Sometimes you may wish to move the camera target into the centre of a single part or of a group of visible parts. The context menu items `Part Options$\rightarrow$Zoom to Part' and `Part Options$\rightarrow$Fit Visible' can be used for this purpose.
   
-  Another useful example file you may want to 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.
+  When you are done, click the link to get the {\tt VIEW} section, readily formatted for insertion into the views file. Repeat this procedure to get any number of views you want to predefine. The views file can be edited manually to give meaningful names to the views (change the value of the {\tt VIEW} entry) or to further tweak camera settings, opacity etc.
 
-  All files in `{\tt{}doc/javascript}' work off-the-shelf and can be copied into a single file in order to combine their effects.
+  If you are satisfied with the predefined views in the views file, the default view first specified through the options of {\tt\string\includemovie} can be deleted. The first view in the views file becomes the default view then.
 
-  \item Create a file with predefined views of the 3D object and attach it to the latter using the `{\tt{}3Dviews}' option:
+  \item Associate a JavaScript with the 3D object:
 
   {\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}..., 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}
+    \string}
   }
 
-  The views file can easily be populated using a temporarily inserted {\tt \string\movie\-ref} link:
+  JavaScript is \emph{not} required to make use of \emph{embedded} keyframe animation. Just click the `Play' button in the 3D toolbar of the 3D annotation. However, the example file `{\tt{}animation.js}' in the `{\tt{}doc/javascript}' directory provides additional controls (accessible via the context menu of the 3D annotation) that can be used to change the speed of a running animation. The `Up', `Down' and `Home' keys of the keyboard can also be used.
+  
+  Another useful example file you may want to 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.
 
-  {\tt%
-    \string\movieref[3Dgetview]\string{my\_label\string}\string{Click here!\string}
-  }
+  All files in `{\tt{}doc/javascript}' work off-the-shelf and can be copied into a single file in order to combine their effects.
 
-  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}