summaryrefslogtreecommitdiff
path: root/Build/source/utils/asymptote/doc/asymptote.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/utils/asymptote/doc/asymptote.texi')
-rw-r--r--Build/source/utils/asymptote/doc/asymptote.texi235
1 files changed, 173 insertions, 62 deletions
diff --git a/Build/source/utils/asymptote/doc/asymptote.texi b/Build/source/utils/asymptote/doc/asymptote.texi
index b803c7cfc33..aca2cd69b35 100644
--- a/Build/source/utils/asymptote/doc/asymptote.texi
+++ b/Build/source/utils/asymptote/doc/asymptote.texi
@@ -84,7 +84,7 @@ Installation
Tutorial
* Drawing in batch mode:: Run @code{Asymptote} on a text file
-* Drawing in interactive mode:: Running @code{Asymptote} interactively
+* Drawing in interactive mode:: Running @code{Asymptote} interactively
* Figure size:: Specifying the figure size
* Labels:: Adding @code{LaTeX} labels
* Paths:: Drawing lines and curves
@@ -221,6 +221,9 @@ as @TeX{}/@code{LaTeX} is the de-facto standard for typesetting equations.
@item @code{LaTeX} typesetting of labels, for overall document consistency;
+@item the ability to generate and embed 3D vector @acronym{WebGL}
+graphics within @acronym{HTML} files;
+
@item the ability to generate and embed 3D vector @acronym{PRC}
graphics within @acronym{PDF} files;
@@ -254,7 +257,7 @@ Many of the features of @code{Asymptote} are written in the
@code{Asymptote} language itself. While the stock version of
@code{Asymptote} is designed for mathematics typesetting needs, one can
write @code{Asymptote} modules that tailor it to specific
-applications. A scientific graphing module has already been written
+applications; for example, a scientific graphing module is available
(@pxref{graph}). Examples of @code{Asymptote} code and output,
including animations, are available at
@quotation
@@ -382,7 +385,7 @@ The @code{ImageMagick} package from
@url{http://www.imagemagick.org/script/binary-releases.php}
@noindent
-is required to support output formats other than @acronym{EPS},
+is required to support output formats other than @acronym{HTML},
@acronym{PDF}, @acronym{SVG}, and @acronym{PNG} (@pxref{convert}).
The @code{Python 3} interpreter from @url{http://www.python.org} is only required
if you wish to try out the graphical user interface (@pxref{GUI}).
@@ -396,15 +399,11 @@ subdirectory of the installation directory (by default,
@section Configuring
@cindex configuring
@cindex @code{-V}
-@cindex @code{psviewer}
-@cindex @code{pdfviewer}
-@cindex @code{gs}
In interactive mode, or when given the @code{-V} option (the default
when running @code{Asymptote} on a single file under @code{MSDOS}),
@code{Asymptote} will automatically invoke the @code{PostScript}
viewer @code{gv} (under @code{UNIX}) or @code{gsview} (under
-@code{MSDOS} to display graphical output. These defaults may be
-overridden with the configuration variable @code{psviewer}.
+@code{MSDOS} to display graphical output.
The @code{PostScript} viewer should be capable of automatically
redrawing whenever the output file is updated. The default @code{UNIX}
@code{PostScript} viewer @code{gv} supports this (via a @code{SIGHUP}
@@ -418,40 +417,58 @@ Users of @code{gsview} will need to enable @code{Options/Auto Redisplay}
@code{gsview} window; under @code{UNIX} one must manually redisplay by
pressing the @code{r} key).
+@cindex @code{psviewer}
+@cindex @code{pdfviewer}
+@cindex @code{htmlviewer}
+@cindex @code{gs}
+@cindex @code{display}
+@cindex @code{animate}
@cindex @code{settings}
@cindex configuration file
Configuration variables are most easily set as @code{Asymptote}
variables in an optional configuration file @code{config.asy}
@pxref{configuration file}).
-Here are the default values of several important configuration
-variables under @code{UNIX}:
+For example, the setting @code{pdfviewer} specifies the location of
+the @acronym{PDF} viewer. Here are the default values of several
+important configuration variables under @code{UNIX}:
@noindent
@verbatim
import settings;
-psviewer="gv";
pdfviewer="acroread";
+htmlviewer="google-chrome";
+psviewer="gv";
+display="display";
+animate="animate";
gs="gs";
+libgs="";
@end verbatim
@noindent
@cindex @code{cmd}
-Under @code{MSDOS}, the (installation-dependent) default values of
-these configuration variables are determined automatically from the
-@code{Microsoft Windows} registry. Viewer settings (such as
-@code{psviewer} and @code{pdfviewer}) can be set to the string
-@code{cmd} to request the application normally associated with the
-corresponding file type.
-
-For @acronym{PDF} format output, the @code{gs} setting specifies the
-location of the @code{PostScript}-to-@acronym{PDF} processor @code{Ghostscript},
-available from @url{http://downloads.ghostscript.com/public}.
-
-The setting @code{pdfviewer} specifies the location of the @acronym{PDF}
-viewer. On @code{UNIX} systems, to support automatic document
-reloading in @code{Adobe Reader}, we recommend copying the file
-@code{reload.js} from the @code{Asymptote} system directory (by default,
-@code{@value{Datadir}/asymptote} under @code{UNIX} to
+Under @code{MSDOS}, the viewer settings
+@code{htmlviewer}, @code{pdfviewer}, @code{psviewer},
+@code{display}, and @code{animate} default to the string @code{cmd},
+requesting the application normally associated with each file type.
+The (installation-dependent) default values of @code{gs}
+and @code{libgs} are determined automatically from the @code{Microsoft
+Windows} registry. The @code{gs} setting specifies the location of the
+@code{PostScript} processor @code{Ghostscript}, available from
+@url{https://www.ghostscript.com/}.
+
+@noindent
+@cindex @code{htmlviewer}
+The configuration variable @code{htmlviewer} specifies the
+browser to use to display 3D @code{WebGL} output.
+The default setting is @code{google-chrome} under @code{UNIX} and
+@code{cmd} under @code{Microsoft Windows}. Note that @code{Internet Explorer}
+does not support @code{WebGL}; @code{Microsoft Windows} users should set their
+default html browser to @code{chrome} or @code{microsoft-edge}.
+
+On @code{UNIX} systems, to support automatic document
+reloading of @code{PDF} files in @code{Adobe Reader}, we recommend
+copying the file @code{reload.js} from the @code{Asymptote} system
+directory (by default, @code{@value{Datadir}/asymptote} under @code{UNIX} to
@code{~/.adobe/Acrobat/x.x/JavaScripts/},
where @code{x.x} represents the appropriate @code{Adobe Reader}
version number. The automatic document reload feature must then be
@@ -485,22 +502,17 @@ configuration variables @code{paperwidth} and @code{paperheight}.
@cindex @code{texcommand}
@cindex @code{dvips}
@cindex @code{dvisvgm}
-@cindex @code{libgs}
@cindex @code{convert}
-@cindex @code{display}
-@cindex @code{animate}
@cindex @code{ImageMagick}
-The following configuration variables normally do not require adjustment:
+@cindex @code{asygl}
+These additional configuration variables normally do not require adjustment:
@verbatim
config
texpath
texcommand
dvips
dvisvgm
-libgs
convert
-display
-animate
@end verbatim
@noindent
@@ -777,7 +789,7 @@ make uninstall
@menu
* Drawing in batch mode:: Run @code{Asymptote} on a text file
-* Drawing in interactive mode:: Running @code{Asymptote} interactively
+* Drawing in interactive mode:: Running @code{Asymptote} interactively
* Figure size:: Specifying the figure size
* Labels:: Adding @code{LaTeX} labels
* Paths:: Drawing lines and curves
@@ -4384,7 +4396,7 @@ type of the result:
addition
@cindex @code{-}
@item -
-subtractiona
+subtraction
@cindex @code{*}
@item *
multiplication
@@ -5585,7 +5597,7 @@ real[] A=fin;
Another useful mode is comma-separated-value mode,
@code{file csv(bool b=true)}, which causes reads to respect comma delimiters:
@verbatim
-file fin=csv(input("test.txt"));
+file fin=input("test.txt").csv();
real[] A=fin;
@end verbatim
@@ -5594,7 +5606,7 @@ To restrict the number of values read, use the @code{file dimension(int)}
function:
@verbatim
file fin=input("test.txt");
-real[] A=dimension(fin,10);
+real[] A=fin.dimension(10);
@end verbatim
This reads 10 values into A, unless end-of-file (or end-of-line in line mode)
@@ -7786,17 +7798,70 @@ for drawing optional mesh lines for each Bezier patch. The optional
@code{name} parameter is used as a prefix for naming the surface
patches in the @acronym{PRC} model tree.
Here material is a structure defined in @code{three_light.asy}:
+@cindex @code{material}
+@cindex @code{diffusepen}
+@cindex @code{emissivepen}
+@cindex @code{specularpen}
+@cindex @code{opacity}
+@cindex @code{shininess}
+@cindex @code{metallic}
+@cindex @code{freshnel0}
@verbatim
struct material {
pen[] p; // diffusepen,emissivepen,specularpen
real opacity;
real shininess;
-...
+ real metallic;
+ real fresnel0;
}
@end verbatim
@noindent
-These material properties are used to implement @code{OpenGL}-style lighting,
-based on the Phong-Blinn specular model. Sample Bezier surfaces are
+@cindex @code{PBR}
+@cindex @code{physically based rendering}
+These material properties are used to implement physically based
+rendering (PBR) using light properties defined in @code{plain_prethree.asy}
+and @code{three_light.asy}:
+@cindex @code{light}
+@cindex @code{diffuse}
+@cindex @code{specular}
+@cindex @code{background}
+@cindex @code{specularfactor}
+@cindex @code{position}
+@cindex @code{currentlight}
+@cindex @code{Viewport}
+@cindex @code{White}
+@cindex @code{Headlamp}
+@cindex @code{nolight}
+@verbatim
+struct light {
+ real[][] diffuse;
+ real[][] specular;
+ pen background=nullpen; // Background color of the 3D canvas.
+ real specularfactor;
+ triple[] position; // Only directional lights are currently implemented.
+}
+
+light Viewport=light(specularfactor=3,(0.25,-0.25,1));
+
+light White=light(new pen[] {rgb(0.38,0.38,0.45),rgb(0.6,0.6,0.67),
+ rgb(0.5,0.5,0.57)},specularfactor=3,
+ new triple[] {(-2,-1.5,-0.5),(2,1.1,-2.5),(-0.5,0,2)});
+
+light Headlamp=light(gray(0.8),specular=gray(0.7),
+ specularfactor=3,dir(42,48));
+
+currentlight=Headlamp;
+
+light nolight;
+@end verbatim
+@cindex @code{background}
+@cindex @code{transparent}
+The @code{background} pen can be use to set the 3D @code{OpenGL}
+background colour (the default is white). In the case of
+3D @code{WebGL} images one can request a completely transparent background with
+@code{currentlight.background=black+opacity(0.0);}
+
+Sample Bezier surfaces are
contained in the example files @code{@uref{http://asymptote.sourceforge.net/gallery/BezierSurface.pdf,,BezierSurface}@uref{http://asymptote.sourceforge.net/gallery/BezierSurface.asy,,.asy}}, @code{@uref{http://asymptote.sourceforge.net/gallery/teapot.pdf,,teapot}@uref{http://asymptote.sourceforge.net/gallery/teapot.asy,,.asy}},
and @code{@uref{http://asymptote.sourceforge.net/gallery/parametricsurface.pdf,,parametricsurface}@uref{http://asymptote.sourceforge.net/gallery/parametricsurface.asy,,.asy}}. The structure @code{render} contains
specialized rendering options documented at the beginning of module
@@ -7863,14 +7928,16 @@ normals or vertex colors:
@cindex @code{tessellation}
@verbatim
void draw(picture pic=currentpicture, triple[] v, int[][] vi,
- triple[] n={}, int[][] ni={}, material m=currentpen, pen[] p={},
- int[][] pi={}, light light=currentlight);
+ triple[] n={}, int[][] ni=vi, material m=currentpen, pen[] p={},
+ int[][] pi=vi, light light=currentlight);
@end verbatim
-Here, the triple array @code{v} lists the distinct vertices, while
-the array @code{vi} lists integer arrays of length 3 containing
-the indices of @code{v} corresponding to the vertices of each
+Here, the triple array @code{v} lists the (typically distinct) vertices, while
+the array @code{vi} contains integer arrays of length 3 containing
+the indices of the elements in @code{v} that form the vertices of each
triangle. Similarly, the arguments @code{n} and @code{ni} contain
-optional normal data and @code{p} and @code{pi} contain optional pen vertex data.
+optional normal data and @code{p} and @code{pi} contain optional pen
+vertex data. If more than one normal or pen is specified for a vertex, the
+last one specified is used.
An example of this tessellation facility is given in @code{@uref{http://asymptote.sourceforge.net/gallery/triangles.pdf,,triangles}@uref{http://asymptote.sourceforge.net/gallery/triangles.asy,,.asy}}.
@cindex @code{thin}
@@ -7897,18 +7964,17 @@ parameter or the setting @code{thin} is set to @code{false}. The pens
also be used to override these defaults for specific draw commands.
@noindent
-There are four choices for viewing 3D @code{Asymptote} output:
+There are five choices for viewing 3D @code{Asymptote} output:
@enumerate
+
@cindex @code{OpenGL}
@cindex @code{render}
@cindex @code{outformat}
@cindex @code{multisample}
@item Use the native @code{Asymptote} adaptive @code{OpenGL}-based
renderer (with the command-line option @code{-V} and the default settings
-@code{outformat=""} and @code{render=-1}). If you encounter warnings
-from your graphics card driver, try specifying @code{-glOptions=-indirect}
-on the command line. On @code{UNIX} systems with graphics support for
-multisampling, the sample width can be
+@code{outformat=""} and @code{render=-1}). On @code{UNIX} systems with
+graphics support for multisampling, the sample width can be
controlled with the setting @code{multisample}. An initial screen
position can be specified with the pair setting @code{position}, where
negative values are interpreted as relative to the corresponding
@@ -7945,7 +8011,7 @@ The keyboard shortcuts are:
@item y: spin about the Y axis
@item z: spin about the Z axis
@item s: stop spinning
-@item m: rendering mode (solid/mesh/patch)
+@item m: rendering mode (solid/patch/mesh)
@item e: export
@item c: show camera parameters
@item p: play animation
@@ -7961,6 +8027,40 @@ The keyboard shortcuts are:
@item Ctrl-q: exit
@end itemize
+@cindex @code{WebGL}
+@cindex @code{HTML5}
+@cindex @code{mobile browser}
+@item Generate @code{WebGL} interactive vector graphics
+output with the the command-line option and @code{-f html}
+(or the setting @code{outformat="html"}). The resulting
+3D @acronym{HTML} file can then be viewed directly in any modern desktop or
+mobile browser, or even embedded within another web page:
+@verbatim
+<div>
+<object data="logo3.html"
+ style="width:210;height:140;position:relative;top:0;left:0;">
+</object>
+</div>
+@end verbatim
+
+Normally, @code{WebGL} files generated by @code{Asymptote} are
+dynamically remeshed to fit the browser window dimensions.
+However, the setting @code{absolute=true} can be used to force the image to be
+rendered at its designed size (accounting for multiple device pixels
+per @code{css} pixel). This setting should not be used when
+embedding a @code{WebGL} file within another @acronym{HTML} document.
+
+The interactive @code{WebGL} files produced by @code{Asymptote} use the
+default mouse and (many of the same) key bindings as the @code{OpenGL}
+renderer.
+
+By default, viewing the 3D @acronym{HTML} files generated by Asymptote requires
+network access to download the @code{asygl} rendering library, which
+is normally cached by the browser for future use.
+However, the setting @code{offline=true} can be used to embed this
+small (about 42kB) library within a stand-alone @acronym{HTML} file
+that can be viewed offline.
+
@cindex @code{antialias}
@cindex @code{maxviewport}
@cindex @code{maxtile}
@@ -7985,8 +8085,6 @@ setting @code{maxviewport}, which restricts the maximum width and
height of the viewport. On @code{UNIX} systems some graphics
drivers support batch mode (@code{-noV}) rendering in an
iconified window; this can be enabled with the setting @code{iconify=true}.
-Some (broken) @code{UNIX} graphics drivers may require the command line setting
-@code{-glOptions=-indirect}, which requests (slower) indirect rendering.
@cindex @code{prc}
@cindex @code{views}
@@ -8033,7 +8131,7 @@ void size3(picture pic=currentpicture, real x, real y=x, real z=y,
@cindex margins
@cindex @code{viewportmargin}
@cindex @code{viewportsize}
-The resulting simplex linear programming problem is then solved to
+A simplex linear programming problem is then solved to
produce a 3D version of a frame (actually implemented as a 3D picture).
The result is then fit with another application of deferred drawing
to the viewport dimensions corresponding to the usual two-dimensional
@@ -9227,6 +9325,7 @@ variables may also be changed at runtime.
@cindex @code{hyperrefOptions}
@cindex @code{convertOptions}
@cindex @code{gsOptions}
+@cindex @code{htmlviewerOptions}
@cindex @code{psviewerOptions}
@cindex @code{pdfviewerOptions}
@cindex @code{pdfreloadOptions}
@@ -9234,7 +9333,8 @@ variables may also be changed at runtime.
@cindex @code{dvisvgmOptions}
The advanced configuration variables @code{dvipsOptions},
@code{hyperrefOptions}, @code{convertOptions}, @code{gsOptions},
-@code{psviewerOptions}, @code{pdfviewerOptions}, @code{pdfreloadOptions},
+@code{htmlviewerOptions}, @code{psviewerOptions},
+@code{pdfviewerOptions}, @code{pdfreloadOptions},
@code{glOptions}, and @code{dvisvgmOptions} allow specialized options
to be passed as a string to the respective applications or
libraries. The default value of @code{hyperrefOptions} is
@@ -9277,7 +9377,7 @@ produced using the @code{-f} option (or @code{outformat} setting).
@cindex @code{dvisvgm}
@cindex @code{libgs}
To produce @acronym{SVG} output, you will need @code{dvisvgm} (version
-1.5.3 or later) from @url{http://dvisvgm.sourceforge.net} and must use
+2.6.3 or later) from @url{http://dvisvgm.sourceforge.net} and must use
the @code{latex} or @code{tex} tex engine. You might need to adjust
the configuration variable @code{libgs} to point to the location of
your @code{Ghostscript} library @code{libgs.so} (or to an empty
@@ -9510,7 +9610,7 @@ pip3 install cson numpy pyqt5 PyQt5.sip
@end verbatim
Pictures are deconstructed into the @acronym{SVG} image format.
-Since @code{Qt5} does not suport @code{SVG} clipping, you will need
+Since @code{Qt5} does not support @code{SVG} clipping, you will need
the @code{rsvg-convert} utility, which is part of the
@code{librsvg2-tools} package on @code{UNIX} systems
and the @code{librsvg} package on @code{MacOS}; under
@@ -9871,7 +9971,7 @@ Martin Wiebusch, Stefan Knorr, and Supakorn ``Jamie'' Rassameemasmuang.
@c LocalWords: nonoverlapping texengine maxtimes maxheight pdb TEXMFCONFIG Jn
@c LocalWords: piecewisestraight unitrand graphmarkers antialias nolight newl
@c LocalWords: Delaunay Shewchuk convertOptions APPDATA pdfreload tempFile Yn
-@c LocalWords: pdfreloadOptions deferred OpenGL Phong Blinn renderer unitbox
+@c LocalWords: pdfreloadOptions deferred OpenGL renderer unitbox
@c LocalWords: bezulate Shardt's rasterized viewport unitdisk unitplane devel
@c LocalWords: unitcylinder unitcone solidcone unitfrustum unitsphere nslices
@c LocalWords: DPostScript YZZero externalprc nonrendered nosafe KDE
@@ -9945,10 +10045,21 @@ Martin Wiebusch, Stefan Knorr, and Supakorn ``Jamie'' Rassameemasmuang.
@c LocalWords: 5unit 144x144 aligndir smoothcontour3 's 3D 2D cmake
@c LocalWords: 'load 'asy 'lasy 'auto 5bp 1cm 4g 2S 100pt 3t nan 3x
@c LocalWords: 12pt 5mm 25cm 5x 3y 602e 2x 2y 3sin 10cm 204e 10x Ai
-@c LocalWords: Ai Ai Ai Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y nz
+@c LocalWords: Ai Ai Ai Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y nz '
@c LocalWords: 5unit Staats implicitsurface overlapedges maxdepth
@c LocalWords: through'' genustwo 144x144 0pt 1filll 's 3D 2D 'load
@c LocalWords: 'asy 'lasy 'auto 5bp 1cm 4g 2S 100pt 3t 12pt 5mm 3x
@c LocalWords: 25cm 5x 3y 602e 2x 2y 3sin 10cm 204e 10x Ai Ai Ai Ai
@c LocalWords: Ai Ai Ai Ai 5E 5cm 2N 2E 2n 100d 5z 5y 5unit 144x144
-@c LocalWords: Frohlich
+@c LocalWords: Frohlich codequoteundirected center 0pt 1filll 's 3D
+@c LocalWords: acknowledgments Colors 2D Color WebGL uref x86 dnf
+@c LocalWords: htmlviewer asygl CPPFLAGS 'load 'asy 'lasy 'auto 5bp
+@c LocalWords: 1cm labeling dotfilltype 4g color colors centered 2S
+@c LocalWords: 100pt 3t forcemath gray colorless miter 12pt 5mm 3x
+@c LocalWords: zeroTransform 25cm Python3 popcount bitreverse 5x 3y
+@c LocalWords: 602e 2x 2y 3sin 10cm 204e 10x Ai Ai Ai Ai Ai Ai Ai
+@c LocalWords: Ai findall ax 5a centers 5E 5cm 2N 2E 2n HTML5 html
+@c LocalWords: logo3 remeshed css 42kB 100d 5z 5y 5unit colored Qt5
+@c LocalWords: behavior beveled usetriangles htmlviewerOptions cson
+@c LocalWords: 144x144 pyqt5 numpy pip3 PyQt5 rsvg librsvg2
+@c LocalWords: librsvg Supakorn Jamie'' Rassameemasmuang