movie15 update

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

1 files changed, 135 insertions, 39 deletions

diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.tex b/Master/texmf-dist/doc/latex/movie15/movie15.tex
index 7c2f32ee3d6..7bae57c9ecb 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.tex
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.tex
@@ -4,27 +4,16 @@
 %    http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
 % for the details of that license.
 %
-
 \documentclass[a4paper]{article}
 
-%please use pdfLaTeX
-\usepackage{ifthen}
-\ifthenelse{\isundefined{\pdfoutput}}{%
-  \errmessage{Use pdfLaTeX, please!}
-}{%
-  \ifthenelse{\number\pdfoutput<1}{%
-    \errmessage{Use pdfLaTeX, please!}
-  }{}
-}
-
 \usepackage[3D]{movie15}
-
 \usepackage{ragged2e}
 \usepackage{amssymb}
 \usepackage[UKenglish]{babel}
 \usepackage{color}
 \usepackage{graphicx}
 \usepackage{hyperref}
+\usepackage{textcomp}
 \pdfpagewidth595bp
 \pdfpageheight842bp
 \parindent0pt
@@ -80,7 +69,7 @@ If PDF is generated via DVI and Postscript by the usual \verb+latex+ $\rightarro
 
 In the case of pdf\LaTeX{}, the `graphicx' and `hyperref' packages are not required.
 
-Note, that more than one run may be necessary to resolve internally created cross-references. Appropriate warnings will be emitted in such cases.
+Note that more than one run may be necessary to resolve internally created cross-references. Appropriate warnings will be issued in such cases.
 
 \section{Requirements}
 pdf\LaTeX{}, version $\ge1.20$, is needed for direct PDF output.
@@ -95,13 +84,13 @@ Movies, sounds and 3D objects are embedded into the document using the command
 \begin{verbatim}
     \includemovie[<options>]{<width>}{<height>}{<media file>}
 \end{verbatim}
-Unless left empty (cf. option `\verb+text+') 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>+. \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{3dtut}.
 \begin{verbatim}
 attach[=false]
 \end{verbatim}
-By default, the embedded data stream is re-used as embedded file attachment. This makes `movie15' a little more portable to PDF Readers which do not have a multimedia plugin because it gives the user the opportunity to extract the media file and to save it to disk for later playback with an external player. However, support of file attachments is required. Re-use as file attachment can be suppressed with option `\verb+attach=false+'. Note, that `\verb+attach=false+' is a poor method to prevent the user from obtaining a copy of the media file. There are several (free) tools for decompressing and extracting stream objects from PDF files.
+By default, the embedded data stream is re-used as embedded file attachment. This makes `movie15' a little more portable to PDF Readers which do not have a multimedia plugin because it gives the user the opportunity to extract the media file and to save it to disk for later playback with an external player. However, support of file attachments is required. Re-use as file attachment can be suppressed with option `\verb+attach=false+'. Note that `\verb+attach=false+' is a poor method to prevent the user from obtaining a copy of the media file. There are several (free) tools for decompressing and extracting stream objects from PDF files.
 \begin{verbatim}
 autopause
 \end{verbatim}
@@ -142,7 +131,7 @@ This can be suppressed with option `\verb+inline=false+'.
 \begin{verbatim}
 label=<label spec>
 \end{verbatim}
-The media is labelled with \verb+<label spec>+ such that it can be referenced by the \verb+\movieref+ command elsewhere in the document. The \verb+\movieref+ command creates a hyperlink to either stop, pause, resume the media, to play it with different settings, such as frame rate or volume, or to show a different part of it. \verb+<label spec>+ may consist of any sequence of letters, digits or punctuation characters.
+The media is labelled with \verb+<label spec>+ such that it can be referenced by the \verb+\movieref+ command elsewhere in the document. The \verb+\movieref+ command creates a hyperlink to either stop, pause, resume the media, to play it with different settings, such as frame rate or volume, or to show a different part of it. See section~\ref{hyperlinks} for details. \verb+<label spec>+ may consist of any sequence of letters, digits or punctuation characters.
 \begin{verbatim}
 mimetype=<mimetype>
 \end{verbatim}
@@ -156,6 +145,16 @@ palindrome[=true|false]
 \end{verbatim}
 The media is played forward and backward, if supported by the media player. In combination with option `\verb+repeat+' this forward-and-reverse playback repeats as many times as specified. Each complete forward and reverse playback counts as one repeat.
 \begin{verbatim}
+playerid=<playerid>
+\end{verbatim}
+Forces a particular media player plugin to be used instead of the default one. Currently, the following values are recognized:\\[1ex]
+{\tt\phantom{xxxx}AAPL\_QuickTime\\
+\phantom{xxxx}MACR\_FlashPlayer\\
+\phantom{xxxx}RNWK\_RealPlayer\\
+\phantom{xxxx}MSFT\_WindowsMediaPlayer\\
+\phantom{xxxx}ADBE\_MCI} (Adobe builtin player)
+
+\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.
@@ -187,14 +186,22 @@ Some \verb+<offset>+ examples:
     frame:100
     {marker:"Chapter 1", time:60}
 \end{verbatim}
+\hypertarget{lnk:textoption}{}
 \begin{verbatim}
 text=<text>
 \end{verbatim}
-\verb+<text>+ is typeset onto and centred within the media display area which has been specified by the \verb+<width>+ and \verb+<height>+ arguments as well as the `\verb+depth+' option. If either or both of the \verb+<width>+ and \verb+<height>+ arguments are left empty, any unspecified dimension of the media display is scaled to match the corresponding dimension, i.\,e. width and height, of \verb+<text>+. Likewise, the depth of the media display is adjusted to the depth of \verb+<text>+ if the optional `\verb+depth+' has not been given. Therefore, option `\verb+text+' can be used to scale the media display to the natural or scaled dimensions of a poster image file, such as (requires package `graphicx'):
+\verb+<text>+ is typeset onto and centred within the media display area which has been specified by the \verb+<width>+ and \verb+<height>+ arguments as well as the `\verb+depth+' option. If either or both of the \verb+<width>+ and \verb+<height>+ arguments are left empty, any unspecified dimension of the media display is scaled to match the corresponding dimension, i.\,e. width and height, of \verb+<text>+. Likewise, the depth of the media display is adjusted to the depth of \verb+<text>+ if the optional `\verb+depth+' has not been given. Therefore, option `\verb+text+' can be used to scale the media display to the natural or scaled dimensions of a poster image file, such as (requires package `graphicx'; \emph{also note the empty {\tt<width>} and  {\tt<height>} arguments!}):
 \begin{verbatim}
  \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:
+\begin{verbatim}
+   \includemovie[
+     poster,
+     text={\phantom{\includegraphics[scale=2]{path/to/poster}}}
+   ]{}{}{path/to/movie}
+\end{verbatim}
 \begin{verbatim}
 textoverposter[=false]
 \end{verbatim}
@@ -209,11 +216,11 @@ volume=<percentage of original volume>
 The meaning of this option should be self explaining.
 
 \subsection{Inclusion of 3D objects}\label{3dtut}
-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. However, a tryout version of~\cite{dexp} can be downloaded from the Web site.
+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 tryout version of~\cite{dexp} can be downloaded from the Web site.
 
-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+open+', `\verb+repeat+', `\verb+palindrome+', `\verb+startat+', `\verb+endat+', `\verb+rate+' and `\verb+volume+', because they do not make sense, `\verb+inline+' and `\verb+url+', because 3D files are always fully embedded and finally `\verb+mouse+', because 3D objects are interactive by definition.
+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 plugin handles embedded files only.
 
-There are a few options to \verb+\includemovie+ which define how the 3D object is positioned within the viewport of a virtual camera, or conversely, how the virtual camera is positioned and oriented within a coordinate system, called `The World', which bears the 3D object at a fixed position. Fig.~\ref{3dscene} should help to visualise the scenery: The virtual camera is orbiting at a distance of $ROO$ around the centre of orbit, specified by the position vector $\overrightarrow{COO}$; $\sphericalangle AAC$ is the camera's aperture angle. In addition, the direction vector $\overrightarrow{C2C}$ is needed to specify the initial camera position.
+There are a few options to \verb+\includemovie+ which define how the 3D object is positioned within the viewport of a virtual camera, or conversely, how the virtual camera is positioned and oriented within a coordinate system, called `The World', which bears the 3D object at a fixed position. Fig.~\ref{3dscene} should help to visualize the scenery: The virtual camera is orbiting at a distance of $ROO$ around the centre of orbit, specified by the position vector $\overrightarrow{COO}$; $\sphericalangle AAC$ is the camera's aperture angle. In addition, the direction vector $\overrightarrow{C2C}$ is needed to specify the initial camera position.
 \begin{figure}[ht]
   \resizebox{\linewidth}{!}{\input{3dsystem}}
   \caption{Camera and 3D object in the World System $XYZ$; centre of orbit position vector $\vec{COO}$, centre of orbit to camera direction vector $\vec{C2C}$, radius of orbit $ROO$, aperture angle of camera $\sphericalangle AAC$.}\label{3dscene}
@@ -223,30 +230,37 @@ The \emph{default view}, i. e. the view that is shown initially after activating
 \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 preset by default. Larger values can be used to achieve wide-angle or fish-eye effects, cf. example 2 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 preset 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}
-\verb+<x> <y> <z>+ specify a direction vector $\overrightarrow{C2C}$ of arbitrary length, originating in the centre of orbit and pointing to the virtual camera; cf. option `\verb+3Dcoo+' for the number format of \verb+<x> <y> <z>+. Note, that \emph{top} ({\tt 3Dc2c=0 0 1}) and \emph{bottom views} ({\tt 3Dc2c=0 0 -1}) as well as views with \emph{very small but larger than zero inclination angles} relative to the world axes should be avoided when going the {\tt latex} $\rightarrow$ {\tt dvips} $\rightarrow$ {\tt ps2pdf} route. Due to a bug in Ghostscript they lead to unusable 3D inclusions. This restriction does not apply to pdf\LaTeX!
+\verb+<x> <y> <z>+ specify a direction vector $\overrightarrow{C2C}$ of arbitrary length, originating in the centre of orbit and pointing to the virtual camera. Only fixed point numbers in the range from\\[1ex]
+\phantom{xxxx}$-999999999999999999.999999999999999999$\\
+to\\
+\phantom{xxxx}$+999999999999999999.999999999999999999$\\[1ex]
+are allowed.
+%Note that views with \emph{very small but larger than zero} inclination angles relative to the world axes \emph{may} lead to broken 3D inclusions when going the {\tt latex} $\rightarrow$ {\tt dvips} $\rightarrow$ {\tt ps2pdf} route. If this happens chances are great that a Ghostscript version prior to 8.53 has been used for PS to PDF conversion. This issue has been resolved since version 8.53.
 \begin{verbatim}
 3Dcoo=<x> <y> <z>
 \end{verbatim}
-\verb+<x> <y> <z>+ specify the positional vector $\overrightarrow{COO}$ of the centre of orbit. Only fixed point numbers in the range from -999999999999999999.999999999999999999 to +999999999999999999.999999999999999999 are allowed.
+\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}
 3Droo=<r>
 \end{verbatim}
-\verb+<r>+ (always positive!) specifies the radius of orbit $ROO$ of the virtual camera; cf. option `\verb+3Dcoo+' for the number format
+\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>+.
 
-Without the above options the immovable camera sits at the origin $(0,0,0)$ of the World, and looks 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!)
+Without the above options the immovable 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!)
 
-Therefore, in order to get a `front view' of the 3D object it would be sufficient to gradually increase the radius $ROO$ from \LaTeX{} run to \LaTeX{} run until the object or group of objects can be fully seen in the viewport. Since the object size in terms of world coordinate units may differ in orders of magnitude between U3D files, the optimal `\verb+3Droo+' setting might be found by experimenting with a series of geometrically increasing numbers, such as 1, 10, 100, 1000, 10000, 100000 etc. to get a rough approximation and by a subsequent fine tuning using smaller changes.
+Thus, in order to get a `front view' of the 3D object it is sufficient to gradually increase the radius $ROO$ from \LaTeX{} run to \LaTeX{} run until the object or group of objects can be fully seen in the viewport. Since the object size in terms of world coordinate units may differ in orders of magnitude between U3D files, the optimal `\verb+3Droo+' setting might be found by experimenting with a series of geometrically increasing numbers, such as 1, 10, 100, 1000, 10000 etc. to get a rough approximation and by subsequent fine tuning using smaller changes.
 
-Ideally, there should be no need for changing the default setting of \verb+3Dcoo=0 0 0+ for the centre of orbit. However, this requires that the 3D object or group of objects be centred around the world origin $(0,0,0)$ during file export into the U3D format. (This is the default setting with~\cite{dexp}.) If the 3D object apparently pivots around an orbital centre that lies outside of the object's cubature, either the file export could be repeated with appropriate settings or the centre of orbit could be moved into the object centre using the `\verb+3Dcoo+' option. Regarding the latter method, this can be easily achieved if the object is examined from two different directions, say from left (\verb+3Dc2c=-1 0 0+) in order to adjust the \verb+<y>+ and \verb+<z>+ coordinates of `\verb+3Dcoo+' and from front (\verb+3Dc2c=0 -1 0+) in order to adjust the remaining \verb+<x>+ coordinate.
+Ideally, there should be no need for changing the default setting of \verb+3Dcoo=0 0 0+ for the centre of orbit. However, this requires that the 3D object or group of objects be centred around the world origin $(0,0,0)$ during file export into U3D format. (This is the default setting with~\cite{dexp}.) If the 3D object apparently pivots around an orbital centre that lies outside of the object's cubature, either the file export could be repeated with appropriate settings or the centre of orbit could be moved into the object centre using the `\verb+3Dcoo+' option. Regarding the latter method, this can be easily achieved if the object is examined from two different directions, say from left (\verb+3Dc2c=-1 0 0+) in order to adjust the \verb+<y>+ and \verb+<z>+ coordinates of `\verb+3Dcoo+' and from front (\verb+3Dc2c=0 -1 0+) in order to adjust the remaining \verb+<x>+ coordinate.
+
+Alternatively, good values for the `\verb+3Droo+' and `\verb+3Dcoo+' options can be found easily by temporarily inserting a hyperlink using the \verb+\movieref+ command together with the `\verb+3Dcalculate+' option. See section \ref{hyperlinks} for an explanantion 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, predefined views} can be set in an auxiliary file specified by the `\verb+3Dviews+' option. The predefined 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:
+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>}
 \end{verbatim}
@@ -260,16 +274,16 @@ This option sets the background colour of the canvas. Only fixed point real numb
 \begin{verbatim}
 3Djscript=<JavaScipt file>
 \end{verbatim}
-Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates a \verb+<JavaScipt file>+ with the 3D object. The script will be executed upon activation of the object. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript} for details.
+Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates a \verb+<JavaScipt 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.
 
-\subsection{Media hyperlinks}
-A movie or sound may serve as the destination of hyperlinks, which are inserted into the document using the command
+\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
 \begin{verbatim}
   \movieref[<options>]{<label spec>}{<text>}
 \end{verbatim}
-It makes \verb+<text>+ a hyperlink to a movie or sound that has been labelled with \verb+<label spec>+ using the `\verb+label+' option of the \verb+\includemovie+ command. Media hyperlinks can be inserted at any location within the document. Clicking onto the hyperlink causes the Reader to open the page containing the media it is pointing to. Referencing of 3D objects has not been implemented yet.
+It makes \verb+<text>+ a hyperlink to the media that has been labelled with \verb+<label+ \verb+spec>+ using the `\verb+label+' option of the \verb+\includemovie+ command. Media hyperlinks can be inserted at any location within the document. Clicking onto the hyperlink causes the Reader to open the page containing the media it is pointing to. The primary purpose of media hyperlinks, however, is to provide a means to control the playback.
 
-The primary purpose of media hyperlinks, however, is to provide a means to control the playback of media. Depending on the \verb+<options>+ being in effect, clicking onto the hyperlink causes the media to stop, pause or resume, or to restart at different settings, such as frame rate, volume, starting and ending positions.
+\emph{In 2D context}, clicking onto the hyperlink causes the media to stop, pause or resume, or to restart at different settings, such as frame rate, volume, starting and ending positions, depending on the \verb+<options>+ being in effect.
 
 Options that control the playback \emph{characteristics} are: `\verb+controls+', `\verb+endat+', `\verb+mouse+', `\verb+palindrome+', `\verb+rate+', `\verb+repeat+', `\verb+startat+' and `\verb+volume+'. Their meaning is the same as for the \verb+\includemovie+ command and can be looked up in section~\ref{usrif}. They take effect in combination with the `\verb+play+' option only.
 
@@ -299,6 +313,34 @@ close
 \end{verbatim}
 Immediately closes the media player.
 
+\emph{In 3D context}, \verb+\movieref+ can be used to define an additional view of the object, to access a particular view from the list of predefined views or to run a JavaScript. Moreover, a link can be created for calculating the camera settings `\verb+3Droo+' and `\verb+3Dcoo+', instead of finding them manually. The following options are recognized:
+\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.
+
+\begin{verbatim}
+3Daac=<angle>
+3Dc2c=<x> <y> <z>
+3Dcoo=<x> <y> <z>
+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{3dtut}.
+
+\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 dialog 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}
+3Djscript=<JavaScipt file>
+\end{verbatim}
+Runs the script \verb+<JavaScipt file>+ after clicking the link. Unlike the script that has been associated with the 3D annotation during object embedding, this JavaScript is not directly run by the JavaScript engine of the 3D plugin, but is run by Acrobat's own scripting engine. However, full access to the API of the 3D script engine is provided through the `\verb+context3D+' property of the `\verb+Annot3D+' object. For convenience, an associative array `\verb+annot3D+' has been provided for use within \verb+<JavaScipt file>+, in order to easily access the `\verb+Annot3D+' object of the annotation the enclosing link is pointing to. The particular element of the array is referenced by the annotation's label \verb+<label spec>+, enclosed in quotation marks. As an example, the `\verb+scene+' object can be referenced within \verb+<JavaScipt file>+ by
+\begin{verbatim}
+  annot3D["<label spec>"].context3D.scene
+\end{verbatim}
+For details about Acrobat JavaScript and its Annot3D object, see \cite{jscript}.
+
 \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}
@@ -336,8 +378,9 @@ Start playback at the specified temporal offset. The trailing `\verb+s+' is mand
 \begin{verbatim}
 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 `startat' from \verb+\includemovie+. The following options can be combined in order to define a media segment: `\verb+startat+'/`\verb+endat+', `\verb+start+'/`\verb+endat+', `\verb+start+'/`\verb+duration+'.
+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
 \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/}
@@ -362,12 +405,46 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \end{center}
 \end{minipage}
 
-\item 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}. A file `{\tt dice.vws}' that provides predefined views and a JavaScript `{\tt dice.js}' defining light sources have been associated with the 3D object.
+%\enlargethispage{15ex}\thispagestyle{empty}
+\item Another MPEG movie, loaded on the fly from \href{http://www.linux-video.net/Samples/}{\tt http://www.linux-video} \href{http://www.linux-video.net/Samples/}{\tt .net/Samples/}. Hence, a working Internet connection is required. This time, we force the QuickTime plugin to be used instead of MediaPlayer (Windows boxes only). Well, the latter seems to be bugged. Quod erat expectandum.
 
 \begin{minipage}{0.5\linewidth}
 {\tt%
   \string\includemovie[\\
   \phantom{xx}poster,\\
+  \phantom{xx}label=alien,\\
+  \phantom{xx}text=(AlienSong.mpg),\\
+  \phantom{xx}url,\\
+  \phantom{xx}playerid=AAPL\_QuickTime,\\
+  \phantom{xx}repeat\\
+  ]\string{\\
+  \phantom{xx}.5\string\linewidth\\
+  \string}\string{\\
+  \phantom{xx}.375\string\linewidth\\
+  \string}\string{http://www.linux-video.net/Samples/Mpeg1/AlienSong.mpg\string}\\
+  \string\movieref[rate=0.5]\string{alien\string}\string{Slow\string}\\
+  \string\movieref\string{alien\string}\string{Normal\string}\\
+  \string\movieref[rate=2]\string{alien\string}\string{Fast\string}\\
+  \string\movieref[pause]\string{alien\string}\string{Pause/Resume\string}
+}
+\end{minipage}%
+\begin{minipage}{0.5\linewidth}
+\begin{center}
+  \includemovie[poster, label=alien, text=(AlienSong.mpg), url, playerid=AAPL_QuickTime, repeat]{\linewidth}{.75\linewidth}{http://www.linux-video.net/Samples/Mpeg1/AlienSong.mpg}\\
+\movieref[rate=0.5]{alien}{Slow}\hfill
+\movieref{alien}{Normal}\hfill
+\movieref[rate=2]{alien}{Fast}\hfill
+\movieref[pause]{alien}{Pause/Resume}\vspace{19 ex}
+\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}. A file `{\tt dice.vws}' that provides additional views and a JavaScript `{\tt dice.js}' defining light sources have been associated with the 3D object.
+
+\begin{minipage}{0.5\linewidth}
+{\tt%
+  \string\includemovie[\\
+  \phantom{xx}poster,\\
+  \phantom{xx}label=dice,\\
   \phantom{xx}text=(dice.u3d),\\
   \phantom{xx}3Droo=28,\\
   \phantom{xx}3Dc2c=1 -1 1,\\
@@ -378,21 +455,39 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
   \phantom{xx}.5\string\linewidth\\
   \string}\string{\\
   \phantom{xx}.5\string\linewidth\\
-  \string}\string{dice.u3d\string}%
+  \string}\string{dice.u3d\string}\\
+  \string\movieref[\\
+  \phantom{xx}3Dviewindex=N\\
+  ]\string{dice\string}\string{Click here\string} \dots\\
+  \string\movieref[\\
+  \phantom{xx}3Dcalculate=60\\
+  ]\string{dice\string}\string{This link\string} \dots
 }
 \end{minipage}%
 \begin{minipage}{0.5\linewidth}
 \begin{center}
-  \includemovie[poster, text=(dice.u3d), 3Droo=28, 3Dc2c=1 -1 1, 3Dbg=1 1 1, 3Dviews=dice.vws, 3Djscript=dice.js]{\linewidth}{\linewidth}{dice.u3d}
+  \includemovie[
+    poster,
+    label=dice,
+    text=(dice.u3d),
+    3Droo=28,
+    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.
+
 \end{minipage}
+
 \end{enumerate}
 
 \begin{thebibliography}{9}
   \bibitem{pdfspec} Adobe Systems Inc.: \emph{PDF Reference, fifth edition: Adobe Portable Document Format version 1.6}, 2004, Implementation note 144, Appendix H.3, available at: \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/pdf_creation_apis_and_specs/PDFReference.pdf}{\tt http://partners.adobe.com/public/developer/en/acrobat/sdk/} \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/pdf_creation_apis_and_specs/PDFReference.pdf}{\tt pdf/pdf\_creation\_apis\_and\_specs/PDFReference.pdf}.
   \bibitem{3diforg} \href{http://www.3dif.org/}{\tt http://www.3dif.org/}
   \bibitem{dexp} \href{http://www.righthemisphere.com/products/dexp/}{\tt http://www.righthemisphere.com/products/dexp/}
-  \bibitem{jscript}  Adobe Systems Inc.: \emph{Adobe Acrobat 7.0 3D JavaScript Reference}, 2005, available at \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/Acro3DJS.pdf}{\tt http://partners.adobe.com/public/developer/en/ac} \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/Acro3DJS.pdf}{\tt robat/sdk/pdf/javascript/Acro3DJS.pdf}
+  \bibitem{jscript3D}  Adobe Systems Inc.: \emph{Adobe Acrobat 7.0 3D JavaScript Reference}, 2005, available at \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/Acro3DJS.pdf}{\tt http://partners.adobe.com/public/developer/en/ac} \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/Acro3DJS.pdf}{\tt robat/sdk/pdf/javascript/Acro3DJS.pdf}
+  \bibitem{jscript}  Adobe Systems Inc.: \emph{Adobe Acrobat 7.0.5 JavaScript Scripting Reference}, 2005, available at \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/AcroJS.pdf}{\tt http://partners.adobe.com/public/developer/en/ac} \href{http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/AcroJS.pdf}{\tt robat/sdk/pdf/javascript/AcroJS.pdf}
 \end{thebibliography}
 
 \begin{table}[h]
@@ -403,11 +498,12 @@ Extension & MIME type & Description\\\hline\hline\\[-2.5ex]
 aif, aifc, aiff & audio/aiff & Audio Interchange File Format\\
 au, snd         & audio/basic & NeXT/Sun Audio Format\\
 avi             & video/avi & Audio/Video Interleaved\\
+gif             & image/gif & (animated) GIF\\
 mid, rmi        & audio/midi & Musical Instrument Digital Interface\\
 mov, qt         & video/quicktime & Apple QuickTime\\
 mp3, m3u        & audio/x-mp3 & MPEG Audio Layer-3\\
 mp4             & video/mp4 & MPEG-4 Video/Audio\\
-mpeg, mpg       & video/mpeg & MPEG-2 Video\\
+mpeg, mpg       & video/mpeg & MPEG-1 \& 2 Video\\
 ra, ram, rm     & audio/x-pn-realaudio & Real Media\\
 smil            & application/smil & Synchronized Multimedia Integration Language\\
 swf             & application/x-shockwave-flash & (Adobe?) Macromedia Flash\\