X-Git-Url: http://git.hungrycats.org/cgi-bin/gitweb.cgi?p=xscreensaver;a=blobdiff_plain;f=hacks%2Fglx%2Fromanboy.man;fp=hacks%2Fglx%2Fromanboy.man;h=2957a0ec4b71a1c6423dd35f7464ed38d4eb12cd;hp=0000000000000000000000000000000000000000;hb=d1ae2829ff0fd2a96c16a0c8c5420efaa47d7b30;hpb=7edd66e6bd3209013ee059819747b10b5835635b diff --git a/hacks/glx/romanboy.man b/hacks/glx/romanboy.man new file mode 100644 index 00000000..2957a0ec --- /dev/null +++ b/hacks/glx/romanboy.man @@ -0,0 +1,390 @@ +.TH XScreenSaver 1 "" "X Version 11" +.SH NAME +romanboy - Draws a 3d immersion of the real projective plane that +smoothly deforms between the Roman surface and the Boy surface. +.SH SYNOPSIS +.B romanboy +[\-display \fIhost:display.screen\fP] +[\-install] +[\-visual \fIvisual\fP] +[\-window] +[\-root] +[\-delay \fIusecs\fP] +[\-fps] +[\-mode \fIdisplay-mode\fP] +[\-wireframe] +[\-surface] +[\-transparent] +[\-appearance \fIappearance\fP] +[\-solid] +[\-distance-bands] +[\-direction-bands] +[\-colors \fIcolor-scheme\fP] +[\-twosided-colors] +[\-distance-colors] +[\-direction-colors] +[\-view-mode \fIview-mode\fP] +[\-walk] +[\-turn] +[\-no-deform] +[\-deformation-speed \fIfloat\fP] +[\-initial-deformation \fIfloat\fP] +[\-roman] +[\-boy] +[\-surface-order \fInumber\fP] +[\-orientation-marks] +[\-projection \fImode\fP] +[\-perspective] +[\-orthographic] +[\-speed-x \fIfloat\fP] +[\-speed-y \fIfloat\fP] +[\-speed-z \fIfloat\fP] +[\-walk-direction \fIfloat\fP] +[\-walk-speed \fIfloat\fP] +.SH DESCRIPTION +The \fIromanboy\fP program shows a 3d immersion of the real projective +plane that smoothly deforms between the Roman surface and the Boy +surface. You can walk on the projective plane or turn in 3d. The +smooth deformation (homotopy) between these two famous immersions of +the real projective plane was constructed by François Apéry. +.PP +The real projective plane is a non-orientable surface. To make this +apparent, the two-sided color mode can be used. Alternatively, +orientation markers (curling arrows) can be drawn as a texture map on +the surface of the projective plane. While walking on the projective +plane, you will notice that the orientation of the curling arrows +changes (which it must because the projective plane is +non-orientable). +.PP +The real projective plane is a model for the projective geometry in 2d +space. One point can be singled out as the origin. A line can be +singled out as the line at infinity, i.e., a line that lies at an +infinite distance to the origin. The line at infinity is +topologically a circle. Points on the line at infinity are also used +to model directions in projective geometry. The origin can be +visualized in different manners. When using distance colors, the +origin is the point that is displayed as fully saturated red, which is +easier to see as the center of the reddish area on the projective +plane. Alternatively, when using distance bands, the origin is the +center of the only band that projects to a disk. When using direction +bands, the origin is the point where all direction bands collapse to a +point. Finally, when orientation markers are being displayed, the +origin the the point where all orientation markers are compressed to a +point. The line at infinity can also be visualized in different ways. +When using distance colors, the line at infinity is the line that is +displayed as fully saturated magenta. When two-sided colors are used, +the line at infinity lies at the points where the red and green +"sides" of the projective plane meet (of course, the real projective +plane only has one side, so this is a design choice of the +visualization). Alternatively, when orientation markers are being +displayed, the line at infinity is the place where the orientation +markers change their orientation. +.PP +Note that when the projective plane is displayed with bands, the +orientation markers are placed in the middle of the bands. For +distance bands, the bands are chosen in such a way that the band at +the origin is only half as wide as the remaining bands, which results +in a disk being displayed at the origin that has the same diameter as +the remaining bands. This choice, however, also implies that the band +at infinity is half as wide as the other bands. Since the projective +plane is attached to itself (in a complicated fashion) at the line at +infinity, effectively the band at infinity is again as wide as the +remaining bands. However, since the orientation markers are displayed +in the middle of the bands, this means that only one half of the +orientation markers will be displayed twice at the line at infinity if +distance bands are used. If direction bands are used or if the +projective plane is displayed as a solid surface, the orientation +markers are displayed fully at the respective sides of the line at +infinity. +.PP +The immersed projective plane can be projected to the screen either +perspectively or orthographically. When using the walking modes, +perspective projection to the screen will be used. +.PP +There are three display modes for the projective plane: mesh +(wireframe), solid, or transparent. Furthermore, the appearance of +the projective plane can be as a solid object or as a set of +see-through bands. The bands can be distance bands, i.e., bands that +lie at increasing distances from the origin, or direction bands, i.e., +bands that lie at increasing angles with respect to the origin. +.PP +When the projective plane is displayed with direction bands, you will +be able to see that each direction band (modulo the "pinching" at the +origin) is a Moebius strip, which also shows that the projective plane +is non-orientable. +.PP +Finally, the colors with with the projective plane is drawn can be set +to two-sided, distance, or direction. In two-sided mode, the +projective plane is drawn with red on one "side" and green on the +"other side". As described above, the projective plane only has one +side, so the color jumps from red to green along the line at infinity. +This mode enables you to see that the projective plane is +non-orientable. In distance mode, the projective plane is displayed +with fully saturated colors that depend on the distance of the points +on the projective plane to the origin. The origin is displayed in +red, the line at infinity is displayed in magenta. If the projective +plane is displayed as distance bands, each band will be displayed with +a different color. In direction mode, the projective plane is +displayed with fully saturated colors that depend on the angle of the +points on the projective plane with respect to the origin. Angles in +opposite directions to the origin (e.g., 15 and 205 degrees) are +displayed in the same color since they are projectively equivalent. +If the projective plane is displayed as direction bands, each band +will be displayed with a different color. +.PP +The rotation speed for each of the three coordinate axes around which +the projective plane rotates can be chosen. +.PP +Furthermore, in the walking mode the walking direction in the 2d base +square of the projective plane and the walking speed can be chosen. +The walking direction is measured as an angle in degrees in the 2d +square that forms the coordinate system of the surface of the +projective plane. A value of 0 or 180 means that the walk is along a +circle at a randomly chosen distance from the origin (parallel to a +distance band). A value of 90 or 270 means that the walk is directly +from the origin to the line at infinity and back (analogous to a +direction band). Any other value results in a curved path from the +origin to the line at infinity and back. +.PP +By default, the immersion of the real projective plane smoothly +deforms between the Roman and Boy surfaces. It is possible to choose +the speed of the deformation. Furthermore, it is possible to switch +the deformation off. It is also possible to determine the initial +deformation of the immersion. This is mostly useful if the +deformation is switched off, in which case it will determine the +appearance of the surface. +.PP +As a final option, it is possible to display generalized versions of +the immersion discussed above by specifying the order of the surface. +The default surface order of 3 results in the immersion of the real +projective described above. The surface order can be chosen between 2 +and 9. Odd surface orders result in generalized immersions of the +real projective plane, while even numbers result in a immersion of a +topological sphere (which is orientable). The most interesting even +case is a surface order of 2, which results in an immersion of the +halfway model of Morin's sphere eversion (if the deformation is +switched off). +.PP +This program is inspired by François Apéry's book "Models of the Real +Projective Plane", Vieweg, 1987. +.SH OPTIONS +.I romanboy +accepts the following options: +.TP 8 +.B \-window +Draw on a newly-created window. This is the default. +.TP 8 +.B \-root +Draw on the root window. +.TP 8 +.B \-install +Install a private colormap for the window. +.TP 8 +.B \-visual \fIvisual\fP +Specify which visual to use. Legal values are the name of a visual +class, or the id number (decimal or hex) of a specific visual. +.TP 8 +.B \-delay \fImicroseconds\fP +How much of a delay should be introduced between steps of the +animation. Default 10000, or 1/100th second. +.TP 8 +.B \-fps +Display the current frame rate, CPU load, and polygon count. +.PP +The following four options are mutually exclusive. They determine how +the projective plane is displayed. +.TP 8 +.B \-mode random +Display the projective plane in a random display mode (default). +.TP 8 +.B \-mode wireframe \fP(Shortcut: \fB\-wireframe\fP) +Display the projective plane as a wireframe mesh. +.TP 8 +.B \-mode surface \fP(Shortcut: \fB\-surface\fP) +Display the projective plane as a solid surface. +.TP 8 +.B \-mode transparent \fP(Shortcut: \fB\-transparent\fP) +Display the projective plane as a transparent surface. +.PP +The following four options are mutually exclusive. They determine the +appearance of the projective plane. +.TP 8 +.B \-appearance random +Display the projective plane with a random appearance (default). +.TP 8 +.B \-appearance solid \fP(Shortcut: \fB\-solid\fP) +Display the projective plane as a solid object. +.TP 8 +.B \-appearance distance-bands \fP(Shortcut: \fB\-distance-bands\fP) +Display the projective plane as see-through bands that lie at +increasing distances from the origin. +.PP +.TP 8 +.B \-appearance direction-bands \fP(Shortcut: \fB\-direction-bands\fP) +Display the projective plane as see-through bands that lie at +increasing angles with respect to the origin. +.PP +The following four options are mutually exclusive. They determine how +to color the projective plane. +.TP 8 +.B \-colors random +Display the projective plane with a random color scheme (default). +.TP 8 +.B \-colors twosided \fP(Shortcut: \fB\-twosided-colors\fP) +Display the projective plane with two colors: red on one "side" and +green on the "other side." Note that the line at infinity lies at the +points where the red and green "sides" of the projective plane meet, +i.e., where the orientation of the projective plane reverses. +.TP 8 +.B \-colors distance \fP(Shortcut: \fB\-distance-colors\fP) +Display the projective plane with fully saturated colors that depend +on the distance of the points on the projective plane to the origin. +The origin is displayed in red, the line at infinity is displayed in +magenta. If the projective plane is displayed as distance bands, each +band will be displayed with a different color. +.TP 8 +.B \-colors direction \fP(Shortcut: \fB\-direction-colors\fP) +Display the projective plane with fully saturated colors that depend +on the angle of the points on the projective plane with respect to the +origin. Angles in opposite directions to the origin (e.g., 15 and 205 +degrees) are displayed in the same color since they are projectively +equivalent. If the projective plane is displayed as direction bands, +each band will be displayed with a different color. +.PP +The following three options are mutually exclusive. They determine +how to view the projective plane. +.TP 8 +.B \-view-mode random +View the projective plane in a random view mode (default). +.TP 8 +.B \-view-mode turn \fP(Shortcut: \fB\-turn\fP) +View the projective plane while it turns in 3d. +.TP 8 +.B \-view-mode walk \fP(Shortcut: \fB\-walk\fP) +View the projective plane as if walking on its surface. +.PP +The following options determine whether the surface is being deformed. +.TP 8 +.B \-deform +Deform the surface smoothly between the Roman and Boy surfaces +(default). +.TP 8 +.B \-no-deform +Don't deform the surface. +.PP +The following option determines the deformation speed. +.TP 8 +.B \-deformation-speed \fIfloat\fP +The deformation speed is measured in percent of some sensible maximum +speed (default: 10.0). +.PP +The following options determine the initial deformation of the +surface. As described above, this is mostly useful if +\fB\-no-deform\fP is specified. +.TP 8 +.B \-initial-deformation \fIfloat\fP +The initial deformation is specified as a number between 0 and 1000. +A value of 0 corresponds to the Roman surface, while a value of 1000 +corresponds to the Boy surface. The default value is 1000. +.TP 8 +.B \-roman +This is a shortcut for \fB\-initial-deformation 0\fP. +.TP 8 +.B \-boy +This is a shortcut for \fB\-initial-deformation 1000\fP. +.PP +The following option determines the order of the surface to be +displayed. +.TP 8 +.B \-surface-order \fInumber\fP +The surface order can be set to values between 2 and 9 (default: 3). +As described above, odd surface orders result in generalized +immersions of the real projective plane, while even numbers result in +a immersion of a topological sphere. +.PP +The following options determine whether orientation marks are shown on +the projective plane. +.TP 8 +.B \-orientation-marks +Display orientation marks on the projective plane. +.TP 8 +.B \-no-orientation-marks +Don't display orientation marks on the projective plane (default). +.PP +The following three options are mutually exclusive. They determine +how the projective plane is projected from 3d to 2d (i.e., to the +screen). +.TP 8 +.B \-projection random +Project the projective plane from 3d to 2d using a random projection +mode (default). +.TP 8 +.B \-projection perspective \fP(Shortcut: \fB\-perspective\fP) +Project the projective plane from 3d to 2d using a perspective +projection. +.TP 8 +.B \-projection orthographic \fP(Shortcut: \fB\-orthographic\fP) +Project the projective plane from 3d to 2d using an orthographic +projection. +.PP +The following three options determine the rotation speed of the +projective plane around the three possible axes. The rotation speed +is measured in degrees per frame. The speeds should be set to +relatively small values, e.g., less than 4 in magnitude. In walk +mode, all speeds are ignored. +.TP 8 +.B \-speed-x \fIfloat\fP +Rotation speed around the x axis (default: 1.1). +.TP 8 +.B \-speed-y \fIfloat\fP +Rotation speed around the y axis (default: 1.3). +.TP 8 +.B \-speed-z \fIfloat\fP +Rotation speed around the z axis (default: 1.5). +.PP +The following two options determine the walking speed and direction. +.TP 8 +.B \-walk-direction \fIfloat\fP +The walking direction is measured as an angle in degrees in the 2d +square that forms the coordinate system of the surface of the +projective plane (default: 83.0). A value of 0 or 180 means that the +walk is along a circle at a randomly chosen distance from the origin +(parallel to a distance band). A value of 90 or 270 means that the +walk is directly from the origin to the line at infinity and back +(analogous to a direction band). Any other value results in a curved +path from the origin to the line at infinity and back. +.TP 8 +.B \-walk-speed \fIfloat\fP +The walking speed is measured in percent of some sensible maximum +speed (default: 20.0). +.SH INTERACTION +If you run this program in standalone mode in its turn mode, you can +rotate the projective plane by dragging the mouse while pressing the +left mouse button. This rotates the projective plane in 3d. To +examine the projective plane at your leisure, it is best to set all +speeds to 0. Otherwise, the projective plane will rotate while the +left mouse button is not pressed. This kind of interaction is not +available in the walk mode. +.SH ENVIRONMENT +.PP +.TP 8 +.B DISPLAY +to get the default host and display number. +.TP 8 +.B XENVIRONMENT +to get the name of a resource file that overrides the global resources +stored in the RESOURCE_MANAGER property. +.SH SEE ALSO +.BR X (1), +.BR xscreensaver (1) +.SH COPYRIGHT +Copyright \(co 2013-2014 by Carsten Steger. Permission to use, copy, +modify, distribute, and sell this software and its documentation for +any purpose is hereby granted without fee, provided that the above +copyright notice appear in all copies and that both that copyright +notice and this permission notice appear in supporting documentation. +No representations are made about the suitability of this software for +any purpose. It is provided "as is" without express or implied +warranty. +.SH AUTHOR +Carsten Steger , 03-oct-2014.