update movie15.

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

10 files changed, 426 insertions, 129 deletions

diff --git a/Master/texmf-dist/doc/latex/movie15/README b/Master/texmf-dist/doc/latex/movie15/README
index bfe5f779188..a71172392df 100644
--- a/Master/texmf-dist/doc/latex/movie15/README
+++ b/Master/texmf-dist/doc/latex/movie15/README
@@ -207,6 +207,10 @@ Usage:
                               +999999999999999999.999999999999999999 are
                               allowed.
 
+   3Droll=<roll>              prescribes an initial camera roll around the
+                              optical axis (in clockwise direction, if <roll>
+                              is greater than zero); measured in degrees.
+
    3Droo=<r>                  Radius of orbit ROO of the virtual camera; cf.
                               option `3Dcoo' for the number format.
 
@@ -215,7 +219,7 @@ Usage:
                               The file <views file> contains lines which obey
                               the syntax:
 
-        [<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>}
 
                               The <name> entry is optional. For <coo_x>,
                               <coo_y>, <coo_z>, <c2c_x>, <c2c_y>, <c2c_z>, <roo>
@@ -268,6 +272,11 @@ Usage:
                               calculation unless an optional <aac angle> has
                               been provided.
 
+   3Dgetview                  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 `3Dviews'.
+
 
 Known file name extensions:
 
diff --git a/Master/texmf-dist/doc/latex/movie15/animation.js b/Master/texmf-dist/doc/latex/movie15/animation.js
new file mode 100644
index 00000000000..7c870a1b498
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/movie15/animation.js
@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////
+//
+// animation.js
+//
+// JavaScript for use with `3Djscript' option of \includemovie
+//
+// * Activates animation embedded in the u3d file.
+// * Arrow keys `Down', `Up' can be used for speeding up and slowing
+//   down a running animation, key `Home' for reverting to the default
+//   speed.
+//
+///////////////////////////////////////////////////////////////////////
+
+///////////////////////////////////////////////////////
+// adjustable parameters
+///////////////////////////////////////////////////////
+var rate = 1; // 1 --> use original speed as default
+var palindrome = true; // true --> play forth and back
+///////////////////////////////////////////////////////
+
+//get the first animation in the scene
+var myAnim = scene.animations.getByIndex(0);
+rate = Math.abs(rate);
+myAnim.speed = rate;
+myAnim.forward = true;
+scene.activateAnimation(myAnim);
+
+//menu items
+runtime.addCustomMenuItem(
+  "faster", "Faster (Key Up)", "default", 0
+);
+runtime.addCustomMenuItem(
+  "slower", "Slower (Key Down)", "default", 0
+);
+runtime.addCustomMenuItem(
+  "default", "Default Speed (Key Home)", "default", 0
+);
+
+//menu handler to control speed
+menuEventHandler = new MenuEventHandler();
+menuEventHandler.onEvent = function(e) {
+  if (e.menuItemName == "faster") {
+    myAnim.speed *= 1.25;
+  }
+  else if (e.menuItemName == "slower") {
+    myAnim.speed /= 1.25;
+  }
+  else if (e.menuItemName == "default") {
+    myAnim.speed = rate;
+  }
+};
+runtime.addEventHandler(menuEventHandler);
+
+//key handler to control speed
+keyEventHandler = new KeyEventHandler();
+keyEventHandler.onKeyDown = true;
+keyEventHandler.onEvent = function(e) {
+  switch(e.characterCode) {
+    case 30: //key up
+      myAnim.speed *= 1.05;
+      break;
+
+    case 31: //key down
+      myAnim.speed /= 1.05;
+      break;
+
+    case 4: //key home
+      myAnim.speed = rate;
+      break;
+  }
+};
+runtime.addEventHandler(keyEventHandler);
+
+//run the animation using a TimeEventHandler
+myTimer = new TimeEventHandler();
+myTimer.onTimeChange = true;
+myTimer.onEvent = function(e) {
+  if (myAnim.forward) {
+    myAnim.currentTime += e.deltaTime * myAnim.speed;
+    if (myAnim.currentTime > myAnim.endTime) {
+      if (palindrome == true) {
+        myAnim.currentTime = myAnim.endTime;
+        myAnim.forward = false;
+      }
+      else {
+        myAnim.currentTime = myAnim.startTime;
+      }
+    }
+  }
+  else {
+    myAnim.currentTime -= e.deltaTime * myAnim.speed;
+    if (myAnim.currentTime < myAnim.startTime) {
+      myAnim.currentTime = myAnim.startTime;
+      myAnim.forward = true;
+    }
+  }
+};
+runtime.addEventHandler(myTimer);
diff --git a/Master/texmf-dist/doc/latex/movie15/dice.js b/Master/texmf-dist/doc/latex/movie15/dice.js
index e5561194c32..2050fbcf536 100644
--- a/Master/texmf-dist/doc/latex/movie15/dice.js
+++ b/Master/texmf-dist/doc/latex/movie15/dice.js
@@ -1,98 +1,119 @@
-//////////////////////////
-// add our own lights
-//////////////////////////
+////////////////////////////////////////////////////////////////////////
+//
+// This JavaScript file is a simple concatenation of the files
+// `lights.js' and `turntable.js' from the `doc/javascript' directory.
+//
+////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////
+//
+// lights.js
+//
+// example JavaScript for use with `3Djscript' option of \includemovie
+//
+// * Adds light sources around the object for better illumination.
+//
+////////////////////////////////////////////////////////////////////////
+
 //first remove any scene lights
 for (var i = scene.lights.count - 1; i >= 0; i--) {
   scene.lights.removeByIndex(i);
 }
 
-lights = new Object();
-lights.init = function() {
-  //from left
-  l1 = scene.createLight();
-  l1.color.set3(1,1,1);
-  l1.brightness = .4;
-  l1.direction.set3(1,0,0); //NB: direction, not source!
-
-  //from right
-  l2 = scene.createLight();
-  l2.color.set3(1,1,1);
-  l2.brightness = .4;
-  l2.direction.set3(-1,0,0);
-
-  //from bottom
-  l3 = scene.createLight();
-  l3.color.set3(1,1,1);
-  l3.brightness = .4;
-  l3.direction.set3(0,0,1);
-
-  //from top
-  l4 = scene.createLight();
-  l4.color.set3(1,1,1);
-  l4.brightness = .4;
-  l4.direction.set3(0,0,-1);
-
-  //from front
-  l5 = scene.createLight();
-  l5.color.set3(1,1,1);
-  l5.brightness = .4;
-  l5.direction.set3(0,1,0);
-
-  //from back
-  l6 = scene.createLight();
-  l6.color.set3(1,1,1);
-  l6.brightness = .4;
-  l6.direction.set3(0,-1,0);
-}
+//new lights
+//from left
+l1 = scene.createLight();
+l1.color.set(1,1,1);
+l1.brightness = .4;
+l1.direction.set(1,0,0);
 
-lights.init();
+//from right
+l2 = scene.createLight();
+l2.color.set(1,1,1);
+l2.brightness = .4;
+l2.direction.set(-1,0,0);
 
-////////////////////////////////////////////////////////////////////////
-// get rid of Gimbal rotation; as a result the z-axis will always be up;
-// this part of the script should work off the shelf with _any_ 3D model
-////////////////////////////////////////////////////////////////////////
-var max_theta = 88; // maximum pitch (degrees from horizontal) of the camera
-var sin_max_theta = Math.sin(max_theta * Math.PI/180);
-var tan_max_theta = Math.tan(max_theta * Math.PI/180);
+//from bottom
+l3 = scene.createLight();
+l3.color.set(1,1,1);
+l3.brightness = .4;
+l3.direction.set(0,0,1);
+
+//from top
+l4 = scene.createLight();
+l4.color.set(1,1,1);
+l4.brightness = .4;
+l4.direction.set(0,0,-1);
+
+//from front
+l5 = scene.createLight();
+l5.color.set(1,1,1);
+l5.brightness = .4;
+l5.direction.set(0,1,0);
 
-mouseEventHandler = new MouseEventHandler();
+//from back
+l6 = scene.createLight();
+l6.color.set(1,1,1);
+l6.brightness = .4;
+l6.direction.set(0,-1,0);
+
+/////////////////////////////////////////////////////////////////////
+//
+// turntable.js
+//
+// JavaScript for use with `3Djscript' option of \includemovie
+//
+// * Greatly improves the rotational behaviour of the 3D object,
+//   prevents it from tilting to the side while dragging the mouse.
+//   This is achieved by suppressing the rolling of the camera about
+//   its optical axis.
+//
+/////////////////////////////////////////////////////////////////////
+
+// maximum pitch (degrees from horizontal) of the camera
+var max_alpha = 88;
+var min_beta = 90 - max_alpha; // the complement
+var cos_min_beta = Math.cos(min_beta * Math.PI/180);
+var tan_min_beta = Math.tan(min_beta * Math.PI/180);
+
+var camera = scene.cameras.getByIndex(0);
+
+//updates the vertical axis of rotation whenever a predefined view
+//is selected from the drop down list in the 3D toolbar
+var cameraEventHandler = new CameraEventHandler();
+cameraEventHandler.onEvent = function (e) {
+  camera.axis_up = camera.up.subtract(camera.position);
+  camera.axis_up.normalize();
+}
+runtime.addEventHandler(cameraEventHandler);
+
+//suppresses camera rolling and limits camera pitch
+var mouseEventHandler = new MouseEventHandler();
 mouseEventHandler.onMouseMove = true;
-mouseEventHandler.onEvent = function(event) {
-  if(event.currentTool == runtime.TOOL_NAME_ROTATE) {
-    var camera = scene.cameras.getByIndex(0);
-    var c2c = camera.position.subtract(camera.targetPosition);
-    var roo = c2c.length;
-
-    try {
-      var sin_theta = c2c.z / roo;
-      if(sin_theta == 1) {//top view
-        c2c.z = roo * sin_max_theta;
-        c2c.y = -c2c.z / tan_max_theta;
-        c2c.x = 0
-      }
-      else if(sin_theta == -1) {//bottom view
-        c2c.z = -roo * sin_max_theta;
-        c2c.y = c2c.z / tan_max_theta;
-        c2c.x = 0
-      }
-      else if(sin_max_theta < sin_theta){//camera too high
-        c2c.z = Math.sqrt(c2c.x * c2c.x + c2c.y * c2c.y) * tan_max_theta;
-        c2c.normalize();
-        c2c.scaleInPlace(roo);
-      }
-      else if(sin_theta < -sin_max_theta){//camera too low
-        c2c.z = -Math.sqrt(c2c.x * c2c.x + c2c.y * c2c.y) * tan_max_theta;
-        c2c.normalize();
-        c2c.scaleInPlace(roo);
-      }
-
-      //corrected camera position
-      camera.position.set(camera.targetPosition.add(c2c));
-    }
-    catch(e) {}
-
-    camera.roll=0; //z-axis always up
+mouseEventHandler.onEvent = function (e) {
+  var c2c = camera.position.subtract(camera.targetPosition);
+  var roo = c2c.length;
+  c2c.normalize();
+  cos_beta = c2c.dot(camera.axis_up); //cos of enclosed angle
+
+  //correct the camera position if it is too high or too low
+  if(Math.abs(cos_beta) > cos_min_beta) {
+    //auxiliary vectors a & b
+    var a = camera.axis_up.scale(cos_beta);
+    var b = c2c.subtract(a);
+    b.normalize();
+    b.scaleInPlace(tan_min_beta * a.length);
+
+    c2c.set(a.add(b));
+    c2c.normalize();
+
+    camera.position.set(camera.targetPosition.add(c2c.scale(roo)));
+    cos_beta = c2c.dot(camera.axis_up);
   }
-}
 
+  //suppress rolling
+  camera.up.set(
+    camera.position.add(camera.axis_up).add(c2c.scale(-cos_beta))
+  );
+};
 runtime.addEventHandler(mouseEventHandler);
diff --git a/Master/texmf-dist/doc/latex/movie15/dice.vws b/Master/texmf-dist/doc/latex/movie15/dice.vws
index 06a7e496061..bfd7f35ec83 100644
--- a/Master/texmf-dist/doc/latex/movie15/dice.vws
+++ b/Master/texmf-dist/doc/latex/movie15/dice.vws
@@ -1,7 +1,7 @@
-[Front]{}{0 -1 0}{27}{}% using defaults coo=0 0 0 (arg #2) and aac=30 (arg #5)
-[Back]{}{0 1 0}{27}{}
-[Left]{}{-1 0 0}{27}{}
-[Right]{}{1 0 0}{27}{}
-[Top]{}{0 0 1}{27}{}
-[Bottom]{}{0 0 -1}{27}{}
-[Fish Eye at Centre]{}{0 -1 0}{}{130}% using defaults coo=0 0 0 (arg #2) and roo=0 (arg #4)
+[Front]{}{}{27}{}{}% using defaults: coo=0 0 0 (arg #2), c2c=0 -1 0 (arg #3), roll=0 (arg #5) and aac=30 (arg #6)
+[Back]{}{0 1 0}{27}{}{}
+[Left]{}{-1 0 0}{27}{}{}
+[Right]{}{1 0 0}{27}{}{}
+[Top]{}{0 0 1}{27}{}{}
+[Bottom]{}{0 0 -1}{27}{}{}
+[Fish Eye at Centre]{}{}{}{}{130}% using defaults: coo=0 0 0 (arg #2), c2c=0 -1 0 (arg #3), roo=0 (arg #4), roll=0 (arg #5)
diff --git a/Master/texmf-dist/doc/latex/movie15/lights.js b/Master/texmf-dist/doc/latex/movie15/lights.js
new file mode 100644
index 00000000000..97c6175336f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/movie15/lights.js
@@ -0,0 +1,51 @@
+////////////////////////////////////////////////////////////////////////
+//
+// lights.js
+//
+// example JavaScript for use with `3Djscript' option of \includemovie
+//
+// * Adds light sources around the object for better illumination.
+//
+////////////////////////////////////////////////////////////////////////
+
+//first remove any scene lights
+for (var i = scene.lights.count - 1; i >= 0; i--) {
+  scene.lights.removeByIndex(i);
+}
+
+//new lights
+//from left
+l1 = scene.createLight();
+l1.color.set(1,1,1);
+l1.brightness = .4;
+l1.direction.set(1,0,0);
+
+//from right
+l2 = scene.createLight();
+l2.color.set(1,1,1);
+l2.brightness = .4;
+l2.direction.set(-1,0,0);
+
+//from bottom
+l3 = scene.createLight();
+l3.color.set(1,1,1);
+l3.brightness = .4;
+l3.direction.set(0,0,1);
+
+//from top
+l4 = scene.createLight();
+l4.color.set(1,1,1);
+l4.brightness = .4;
+l4.direction.set(0,0,-1);
+
+//from front
+l5 = scene.createLight();
+l5.color.set(1,1,1);
+l5.brightness = .4;
+l5.direction.set(0,1,0);
+
+//from back
+l6 = scene.createLight();
+l6.color.set(1,1,1);
+l6.brightness = .4;
+l6.direction.set(0,-1,0);
diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.pdf b/Master/texmf-dist/doc/latex/movie15/movie15.pdf
index 27cd89c2953..e55f511fe30 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.pdf
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.pdf
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}
diff --git a/Master/texmf-dist/doc/latex/movie15/overlay-example.pdf b/Master/texmf-dist/doc/latex/movie15/overlay-example.pdf
index 845bbbaab89..8c7635481bd 100644
--- a/Master/texmf-dist/doc/latex/movie15/overlay-example.pdf
+++ b/Master/texmf-dist/doc/latex/movie15/overlay-example.pdf
diff --git a/Master/texmf-dist/doc/latex/movie15/overlay-example.tex b/Master/texmf-dist/doc/latex/movie15/overlay-example.tex
index 5aa70abc012..92348d42247 100644
--- a/Master/texmf-dist/doc/latex/movie15/overlay-example.tex
+++ b/Master/texmf-dist/doc/latex/movie15/overlay-example.tex
@@ -6,7 +6,7 @@
 %
 \documentclass{beamer}
 \setbeamertemplate{navigation symbols}{}
-\usepackage{movie15}
+\usepackage[3D]{movie15}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 % Some hints on using movie15 with /presentation/ packages
@@ -31,10 +31,12 @@
       \includemovie[
         poster,
         autopause, autoresume,
-        text=(AlienSong.mpg),
+        text={\parbox{0.4\linewidth}{\tiny
+          http://www.linux-video.net/\\Samples/Mpeg1/AlienSong.mpg%
+        }},
         playerid=AAPL_QuickTime,
         url
-      ]{0.5\linewidth}{0.375\linewidth}{%
+      ]{0.4\linewidth}{0.3\linewidth}{%
         http://www.linux-video.net/Samples/Mpeg1/AlienSong.mpg%
       }
       \end{center}
diff --git a/Master/texmf-dist/doc/latex/movie15/turntable.js b/Master/texmf-dist/doc/latex/movie15/turntable.js
new file mode 100644
index 00000000000..d8f5bd93fd1
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/movie15/turntable.js
@@ -0,0 +1,60 @@
+/////////////////////////////////////////////////////////////////////
+//
+// turntable.js
+//
+// JavaScript for use with `3Djscript' option of \includemovie
+//
+// * Greatly improves the rotational behaviour of the 3D object,
+//   prevents it from tilting to the side while dragging the mouse.
+//   This is achieved by suppressing the rolling of the camera about
+//   its optical axis.
+//
+/////////////////////////////////////////////////////////////////////
+
+// maximum pitch (degrees from horizontal) of the camera
+var max_alpha = 88;
+var min_beta = 90 - max_alpha; // the complement
+var cos_min_beta = Math.cos(min_beta * Math.PI/180);
+var tan_min_beta = Math.tan(min_beta * Math.PI/180);
+
+var camera = scene.cameras.getByIndex(0);
+
+//updates the vertical axis of rotation whenever a predefined view
+//is selected from the drop down list in the 3D toolbar
+var cameraEventHandler = new CameraEventHandler();
+cameraEventHandler.onEvent = function (e) {
+  camera.axis_up = camera.up.subtract(camera.position);
+  camera.axis_up.normalize();
+}
+runtime.addEventHandler(cameraEventHandler);
+
+//suppresses camera rolling and limits camera pitch
+var mouseEventHandler = new MouseEventHandler();
+mouseEventHandler.onMouseMove = true;
+mouseEventHandler.onEvent = function (e) {
+  var c2c = camera.position.subtract(camera.targetPosition);
+  var roo = c2c.length;
+  c2c.normalize();
+  cos_beta = c2c.dot(camera.axis_up); //cos of enclosed angle
+
+  //correct the camera position if it is too high or too low
+  if(Math.abs(cos_beta) > cos_min_beta) {
+    //auxiliary vectors a & b
+    var a = camera.axis_up.scale(cos_beta);
+    var b = c2c.subtract(a);
+    b.normalize();
+    b.scaleInPlace(tan_min_beta * a.length);
+
+    c2c.set(a.add(b));
+    c2c.normalize();
+
+    camera.position.set(camera.targetPosition.add(c2c.scale(roo)));
+    cos_beta = c2c.dot(camera.axis_up);
+  }
+
+  //suppress rolling
+  camera.up.set(
+    camera.position.add(camera.axis_up).add(c2c.scale(-cos_beta))
+  );
+};
+runtime.addEventHandler(mouseEventHandler);