media9 (23sep14)

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

3 files changed, 33 insertions, 14 deletions

diff --git a/Master/texmf-dist/doc/latex/media9/ChangeLog b/Master/texmf-dist/doc/latex/media9/ChangeLog
index 6f0ee1ed1b8..991c501f777 100644
--- a/Master/texmf-dist/doc/latex/media9/ChangeLog
+++ b/Master/texmf-dist/doc/latex/media9/ChangeLog
@@ -1,3 +1,11 @@
+2014-09-23
+	* v0.47
+	* new: `width', `height', `totalheight', `keepaspectratio', `scale' added as
+	 package options; option `3Drender' accepts optional opacity values with
+	 `Transparent' and `TransparentWireframe' values; new entries in the CROSSECT
+	 section of 3D views: OPACITY, VISIBLE, INTERSECTIONVISIBLE, PLANECOLOR,
+	 INTERSECTIONCOLOR for adjusting clipping plane appearance
+
 2014-08-06
 	* v0.46
 	* fix: compilation failure in `tabular' environment; replacing deprecated l3
diff --git a/Master/texmf-dist/doc/latex/media9/media9.pdf b/Master/texmf-dist/doc/latex/media9/media9.pdf
index e98a0fb1e07..b00c029bb29 100644
--- a/Master/texmf-dist/doc/latex/media9/media9.pdf
+++ b/Master/texmf-dist/doc/latex/media9/media9.pdf
diff --git a/Master/texmf-dist/doc/latex/media9/media9.tex b/Master/texmf-dist/doc/latex/media9/media9.tex
index 5470962d4e8..0b86f6c74cd 100644
--- a/Master/texmf-dist/doc/latex/media9/media9.tex
+++ b/Master/texmf-dist/doc/latex/media9/media9.tex
@@ -42,6 +42,7 @@
   pagebordercolor={0 0 1},
   urlbordercolor={0 0 1}
 }
+\usepackage[scaled=0.85]{luximono}
 
 \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
 \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}
@@ -60,11 +61,11 @@
 \renewcommand{\topfraction}{1.0}
 \renewcommand{\bottomfraction}{1.0}
 
-%\ifpdf\else
-%  \makeatletter
-%  \@latex@error{Please use pdfLaTeX to compile this documentation}
-%  \makeatother
-%\fi
+\ifpdf\else
+  \makeatletter
+  \@latex@error{Please use pdfLaTeX to compile this documentation}
+  \makeatother
+\fi
 
 \def\parsedate#1/#2/#3\relax{
   \def\year{#1}
@@ -172,7 +173,7 @@ Except for `\verb+dvipdfmx+', `\verb+xetex+' and `\verb+bigfiles+', the options
 
 \XeLaTeX{} will be auto-detected. Therefore package option `\verb+xetex+' is optional. However, in the case of  \verb+dvipdfmx+, package option `\verb+dvipdfmx+' is mandatory because it cannot be auto-detected.
 
-\begin{animateinline}[autoplay,loop]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.
+\begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.
 
 Option `\verb+bigfiles+' is only relevant for the \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ workflow. It may be needed if large media files cause \verb+latex+ to abort with error `\verb+TeX capacity exceeded+'. See Sect.\ \ref{bugs}.
 
@@ -255,7 +256,7 @@ Decides on how to de-activate the media annotation. `\verb+deactivate=pageclose+
 draft
 final
 \end{verbatim}
-With `\verb+draft+' the media is not embedded. Instead, a box is inserted that has the dimensions of \verb+<poster text>+, subject to the resizing options `\verb+width+', `\verb+height+', `\verb+depth+' and `\verb+scale+'. Option `\verb+final+' does the opposite as it forces the media to be embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the media annotation that is currently worked on. After the document has been finished, the global `\verb+draft+' option can be removed.
+With `\verb+draft+' the media is not embedded. Instead, a box is inserted that has the dimensions of \verb+<poster text>+, subject to the resizing options `\verb+width+', `\verb+height+', `\verb+totalheight+' and `\verb+scale+'. Option `\verb+final+' does the opposite as it forces the media to be embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the media annotation that is currently worked on. After the document has been finished, the global `\verb+draft+' option can be removed.
 \begin{verbatim}
 playbutton[= fancy | plain | none]
 noplaybutton
@@ -322,7 +323,7 @@ Mainly used during document authoring. Adds three entries, `\emph{\sffamily Gene
 
 `\emph{\sffamily Generate Default View}' computes optimal camera settings such that the visible parts of the 3D scene fit tightly into the viewing area. The result is printed, formatted as a list of \verb+\includemedia+ options, into the JavaScript console. The calculation is based on the 3D object size and its position in the World coordinate system as well as the current viewing mode (perspective or orthographic).
 
-`\emph{\sffamily Cross Section}' is a toggle switch to add or remove a cross section to or from the current view. If a part of the 3D scene was previously selected, the central rotating point of the section plane is put into the part's centre, otherwise into the target point of the camera. The section plane can be rotated around the vertical axis and tilted against its upright position using the arrow keys \keys{\arrowkeyleft}, \keys{\arrowkeyright}, \keys{\arrowkeyup} and \keys{\arrowkeydown}. Keys \keys{X}, \keys{\shift+X}, \keys{Y}, \keys{\shift+Y}, \keys{Z}, \keys{\shift+Z} move the section plane along the World axes, and \keys{S}, \keys{\shift+S} scale its size.
+`\emph{\sffamily Cross Section}' is a toggle switch to add or remove a cross section to or from the current view. If a part of the 3D scene was previously selected, the central rotating point of the cutting plane is put into the part's centre, otherwise into the target point of the camera. The cutting plane can be rotated around the vertical axis and tilted against its upright position using the arrow keys \keys{\arrowkeyleft}, \keys{\arrowkeyright}, \keys{\arrowkeyup} and \keys{\arrowkeydown}. Keys \keys{X}, \keys{\shift+X}, \keys{Y}, \keys{\shift+Y}, \keys{Z}, \keys{\shift+Z} move the cutting plane along the World axes, and \keys{S}, \keys{\shift+S} scale its size.
 
 `\emph{\sffamily Get Current View}' writes camera settings, any part alterations, an optional cross section as well as part and scene rendering attributes of the current view into the JavaScript console. The output is a readily formatted \verb+VIEW+ section to be inserted into or appended to a file of predefined views. See option `\verb+3Dviews+'. All settings reachable via the `\emph{\sffamily Part Options}' and `\emph{\sffamily Viewing Options}' context menu items are written to the \verb+VIEW+ section.
 \begin{verbatim}
@@ -334,10 +335,10 @@ This option sets the background colour of the 3D scene. Only fixed point real nu
 \end{verbatim}
 Sets the default lighting scheme. The following values are honoured: `\verb+None+', `\verb+White+', `\verb+Day+', `\verb+Night+', `\verb+Hard+', `\verb+Primary+', `\verb+Blue+', `\verb+Red+', `\verb+Cube+', `\verb+CAD+', `\verb+HeadLamp+'. The default is to use the lighting scheme as specified within the 3D artwork.
 \begin{verbatim}
-3Drender=<render mode>
+3Drender=Solid | Transparent[:<opacity>] | ...
 \end{verbatim}
 \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+'.
+Sets the default render mode of the scene. 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+'. Options `\verb+Transparent+' and `\verb+TransparentWireframe+' take an optional value between 0 and 1 that controls the opacity of the rendered 3D object.
 \end{flushleft}
 \begin{verbatim}
 3Dpartsattrs=restore | keep
@@ -367,6 +368,11 @@ The file \verb+<views file>+ is structured into view sections, one for every vie
     CROSSSECT
       CENTER=<x> <y> <z>
       NORMAL=<x> <y> <z>
+      OPACITY=<cutting plane opacity>
+      VISIBLE=true | false
+      PLANECOLOR=<r> <g> <b>
+      INTERSECTIONVISIBLE=true | false
+      INTERSECTIONCOLOR=<r> <g> <b>
     END
     PARTSATTRS=keep
     PART=<part name  as in the Model Tree (required, optional if UTF16NAME present)>
@@ -392,7 +398,7 @@ A view section starts with the keyword \verb+VIEW+, optionally followed by a nam
 
 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 in a 3D scene. Table~\ref{tab:parts} lists the possible entries in a \verb+PART+ sub-section. All entries are optional. However, a \verb+UTF16NAME+ entry is recommended, as the part name may contain non-ASCII characters. The value of the \verb+UTF16NAME+ key is the part name as a hex-encoded Unicode string. If \verb+UTF16NAME+ is not used, the part name in the 3D file must be entirely composed of ASCII characters. In that case, \verb+<part name>+ is mandatory and must match the part name as indicated in the \Acrobatmenu{ShowHideModelTree}{3D Model Tree} of the 3D object (accessible via right-click onto the model in the Reader). The part can be scaled and repositioned by means of a \verb+TRANSFORM+ entry which takes a 12-element transformation matrix as its value. Remaining entries in a part sub-section control the visual appearance of the part.
 
-A view section may contain at most one \verb+CROSSSECT+ sub-section. It inserts a section plane at a definite position and orientation in the 3D space, controlled by optional \verb+CENTER+ and \verb+NORMAL+ entries. See Table~\ref{tab:crosss} for explanation.
+A view section may contain at most one \verb+CROSSSECT+ sub-section. It inserts a cutting plane at a definite position and orientation in the 3D space, controlled by optional \verb+CENTER+ and \verb+NORMAL+ entries. The appearance characteristics of the cutting plane and the intersection of the plane with the 3D geometry are controlled by optional \verb+OPACITY+, \verb+VISIBLE+, \verb+PLANECOLOR+, \verb+INTERSECTIONVISIBLE+, \verb+INTERSECTIONCOLOR+ entries. See Table~\ref{tab:crosss} for explanation.
 
 The views file can be commented. As usual, comments start with the percent sign.
 
@@ -440,7 +446,7 @@ Things like animation, lighting, background of 3D objects etc. may also be scrip
   {\tt ORTHO} & number (optional) & enables orthographic view, see option `{\tt 3Dortho}'\\
   {\tt PSOB} & string & expert setting, see option `{\tt 3Dpsob}'\\
   {\tt ROLL} & number & camera roll, see option `{\tt 3Droll}'\\
-  {\tt BGCOLOR} & three numbers & 3D scene background colour (RGB), see option `{\tt 3Dbg}'\\
+  {\tt BGCOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the 3D scene background colour (RGB), see option `{\tt 3Dbg}'\\
   {\tt RENDERMODE} & string & render mode of the 3D object, see option `{\tt 3Drender}'\\
   {\tt LIGHTS} & string & lighting scheme, see option `{\tt 3Dlights}'\\
   {\tt PARTSATTRS} & string & allowed values are `{\tt keep}' and `{\tt restore}'; decides on whether to restore or not original part attributes before applying new ones from this view; see option `{\tt 3Dpartsattrs}'\\
@@ -469,8 +475,13 @@ Things like animation, lighting, background of 3D objects etc. may also be scrip
   \caption{Entries in a {\tt CROSSSECT} sub-section.}\label{tab:crosss}
   \begin{tabular}[t]{llp{0.5\linewidth}}\hline
   key & type & remarks\\\hline\hline
-  {\tt CENTER} & three numbers & central point coordinates of the section plane\\
-  {\tt NORMAL} & three numbers & normal vector coordinates of the section plane pointing into the cut-off region\\
+  {\tt CENTER} & three numbers & central point coordinates of the cutting plane\\
+  {\tt NORMAL} & three numbers & normal vector coordinates of the cutting plane pointing into the cut-off region\\
+  {\tt OPACITY} & number & a number between 0.0 and 1.0 specifying the opacity of the cutting plane\\
+  {\tt VISIBLE} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of the cutting plane\\
+  {\tt PLANECOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the colour (RGB) of the cutting plane\\
+  {\tt INTERSECTIONVISIBLE} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of the intersection of the cutting plane with any 3D geometry\\
+  {\tt INTERSECTIONCOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the colour (RGB) for the cutting plane's intersection with the 3D geometry\\
   \hline
   \end{tabular}
 \end{table}