git.hungrycats.org Git - xscreensaver/blob - hacks/glx/romanboy.man

   1 .TH XScreenSaver 1 "" "X Version 11"
   2 .SH NAME
   3 romanboy \- Draws a 3d immersion of the real projective plane that
   4 smoothly deforms between the Roman surface and the Boy surface.
   5 .SH SYNOPSIS
   6 .B romanboy
   7 [\-\-display \fIhost:display.screen\fP]
   8 [\-\-install]
   9 [\-\-visual \fIvisual\fP]
  10 [\-\-window]
  11 [\-\-root]
  12 [\-\-window\-id \fInumber\fP]
  13 [\-\-delay \fIusecs\fP]
  14 [\-\-fps]
  15 [\-\-mode \fIdisplay-mode\fP]
  16 [\-\-wireframe]
  17 [\-\-surface]
  18 [\-\-transparent]
  19 [\-\-appearance \fIappearance\fP]
  20 [\-\-solid]
  21 [\-\-distance-bands]
  22 [\-\-direction-bands]
  23 [\-\-colors \fIcolor-scheme\fP]
  24 [\-\-onesided-colors]
  25 [\-\-twosided-colors]
  26 [\-\-distance-colors]
  27 [\-\-direction-colors]
  28 [\-\-change-colors]
  29 [\-\-view-mode \fIview-mode\fP]
  30 [\-\-walk]
  31 [\-\-turn]
  32 [\-\-no-deform]
  33 [\-\-deformation-speed \fIfloat\fP]
  34 [\-\-initial-deformation \fIfloat\fP]
  35 [\-\-roman]
  36 [\-\-boy]
  37 [\-\-surface-order \fInumber\fP]
  38 [\-\-orientation-marks]
  39 [\-\-projection \fImode\fP]
  40 [\-\-perspective]
  41 [\-\-orthographic]
  42 [\-\-speed-x \fIfloat\fP]
  43 [\-\-speed-y \fIfloat\fP]
  44 [\-\-speed-z \fIfloat\fP]
  45 [\-\-walk-direction \fIfloat\fP]
  46 [\-\-walk-speed \fIfloat\fP]
  47 .SH DESCRIPTION
  48 The \fIromanboy\fP program shows a 3d immersion of the real projective
  49 plane that smoothly deforms between the Roman surface and the Boy
  50 surface.  You can walk on the projective plane or turn in 3d.  The
  51 smooth deformation (homotopy) between these two famous immersions of
  52 the real projective plane was constructed by François Apéry.
  53 .PP
  54 The real projective plane is a non-orientable surface.  To make this
  55 apparent, the two-sided color mode can be used.  Alternatively,
  56 orientation markers (curling arrows) can be drawn as a texture map on
  57 the surface of the projective plane.  While walking on the projective
  58 plane, you will notice that the orientation of the curling arrows
  59 changes (which it must because the projective plane is
  60 non-orientable).
  61 .PP
  62 The real projective plane is a model for the projective geometry in 2d
  63 space.  One point can be singled out as the origin.  A line can be
  64 singled out as the line at infinity, i.e., a line that lies at an
  65 infinite distance to the origin.  The line at infinity, like all lines
  66 in the projective plane, is topologically a circle.  Points on the
  67 line at infinity are also used to model directions in projective
  68 geometry.  The origin can be visualized in different manners.  When
  69 using distance colors (and using static colors), the origin is the
  70 point that is displayed as fully saturated red, which is easier to see
  71 as the center of the reddish area on the projective plane.
  72 Alternatively, when using distance bands, the origin is the center of
  73 the only band that projects to a disk.  When using direction bands,
  74 the origin is the point where all direction bands collapse to a point.
  75 Finally, when orientation markers are being displayed, the origin the
  76 the point where all orientation markers are compressed to a point.
  77 The line at infinity can also be visualized in different ways.  When
  78 using distance colors (and using static colors), the line at infinity
  79 is the line that is displayed as fully saturated magenta.  When
  80 two-sided (and static) colors are used, the line at infinity lies at
  81 the points where the red and green "sides" of the projective plane
  82 meet (of course, the real projective plane only has one side, so this
  83 is a design choice of the visualization).  Alternatively, when
  84 orientation markers are being displayed, the line at infinity is the
  85 place where the orientation markers change their orientation.
  86 .PP
  87 Note that when the projective plane is displayed with bands, the
  88 orientation markers are placed in the middle of the bands.  For
  89 distance bands, the bands are chosen in such a way that the band at
  90 the origin is only half as wide as the remaining bands, which results
  91 in a disk being displayed at the origin that has the same diameter as
  92 the remaining bands.  This choice, however, also implies that the band
  93 at infinity is half as wide as the other bands.  Since the projective
  94 plane is attached to itself (in a complicated fashion) at the line at
  95 infinity, effectively the band at infinity is again as wide as the
  96 remaining bands.  However, since the orientation markers are displayed
  97 in the middle of the bands, this means that only one half of the
  98 orientation markers will be displayed twice at the line at infinity if
  99 distance bands are used.  If direction bands are used or if the
 100 projective plane is displayed as a solid surface, the orientation
 101 markers are displayed fully at the respective sides of the line at
 102 infinity.
 103 .PP
 104 The immersed projective plane can be projected to the screen either
 105 perspectively or orthographically.  When using the walking modes,
 106 perspective projection to the screen will be used.
 107 .PP
 108 There are three display modes for the projective plane: mesh
 109 (wireframe), solid, or transparent.  Furthermore, the appearance of
 110 the projective plane can be as a solid object or as a set of
 111 see-through bands.  The bands can be distance bands, i.e., bands that
 112 lie at increasing distances from the origin, or direction bands, i.e.,
 113 bands that lie at increasing angles with respect to the origin.
 114 .PP
 115 When the projective plane is displayed with direction bands, you will
 116 be able to see that each direction band (modulo the "pinching" at the
 117 origin) is a Moebius strip, which also shows that the projective plane
 118 is non-orientable.
 119 .PP
 120 Finally, the colors with with the projective plane is drawn can be set
 121 to one-sided, two-sided, distance, or direction.  In one-sided mode,
 122 the projective plane is drawn with the same color on both "sides."  In
 123 two-sided mode (using static colors), the projective plane is drawn
 124 with red on one "side" and green on the "other side."  As described
 125 above, the projective plane only has one side, so the color jumps from
 126 red to green along the line at infinity.  This mode enables you to see
 127 that the projective plane is non-orientable.  If changing colors are
 128 used in two-sided mode, changing complementary colors are used on the
 129 respective "sides."  In distance mode, the projective plane is
 130 displayed with fully saturated colors that depend on the distance of
 131 the points on the projective plane to the origin.  If static colors
 132 are used, the origin is displayed in red, while the line at infinity
 133 is displayed in magenta.  If the projective plane is displayed as
 134 distance bands, each band will be displayed with a different color.
 135 In direction mode, the projective plane is displayed with fully
 136 saturated colors that depend on the angle of the points on the
 137 projective plane with respect to the origin.  Angles in opposite
 138 directions to the origin (e.g., 15 and 205 degrees) are displayed in
 139 the same color since they are projectively equivalent.  If the
 140 projective plane is displayed as direction bands, each band will be
 141 displayed with a different color.
 142 .PP
 143 The rotation speed for each of the three coordinate axes around which
 144 the projective plane rotates can be chosen.
 145 .PP
 146 Furthermore, in the walking mode the walking direction in the 2d base
 147 square of the projective plane and the walking speed can be chosen.
 148 The walking direction is measured as an angle in degrees in the 2d
 149 square that forms the coordinate system of the surface of the
 150 projective plane.  A value of 0 or 180 means that the walk is along a
 151 circle at a randomly chosen distance from the origin (parallel to a
 152 distance band).  A value of 90 or 270 means that the walk is directly
 153 from the origin to the line at infinity and back (analogous to a
 154 direction band).  Any other value results in a curved path from the
 155 origin to the line at infinity and back.
 156 .PP
 157 By default, the immersion of the real projective plane smoothly
 158 deforms between the Roman and Boy surfaces.  It is possible to choose
 159 the speed of the deformation.  Furthermore, it is possible to switch
 160 the deformation off.  It is also possible to determine the initial
 161 deformation of the immersion.  This is mostly useful if the
 162 deformation is switched off, in which case it will determine the
 163 appearance of the surface.
 164 .PP
 165 As a final option, it is possible to display generalized versions of
 166 the immersion discussed above by specifying the order of the surface.
 167 The default surface order of 3 results in the immersion of the real
 168 projective described above.  The surface order can be chosen between 2
 169 and 9.  Odd surface orders result in generalized immersions of the
 170 real projective plane, while even numbers result in a immersion of a
 171 topological sphere (which is orientable).  The most interesting even
 172 case is a surface order of 2, which results in an immersion of the
 173 halfway model of Morin's sphere eversion (if the deformation is
 174 switched off).
 175 .PP
 176 This program is inspired by François Apéry's book "Models of the Real
 177 Projective Plane", Vieweg, 1987.
 178 .SH OPTIONS
 179 .I romanboy
 180 accepts the following options:
 181 .TP 8
 182 .B \-\-window
 183 Draw on a newly-created window.  This is the default.
 184 .TP 8
 185 .B \-\-root
 186 Draw on the root window.
 187 .TP 8
 188 .B \-\-window\-id \fInumber\fP
 189 Draw on the specified window.
 190 .TP 8
 191 .B \-\-install
 192 Install a private colormap for the window.
 193 .TP 8
 194 .B \-\-visual \fIvisual\fP
 195 Specify which visual to use.  Legal values are the name of a visual
 196 class, or the id number (decimal or hex) of a specific visual.
 197 .TP 8
 198 .B \-\-delay \fImicroseconds\fP
 199 How much of a delay should be introduced between steps of the
 200 animation.  Default 10000, or 1/100th second.
 201 .TP 8
 202 .B \-\-fps
 203 Display the current frame rate, CPU load, and polygon count.
 204 .PP
 205 The following four options are mutually exclusive.  They determine how
 206 the projective plane is displayed.
 207 .TP 8
 208 .B \-\-mode random
 209 Display the projective plane in a random display mode (default).
 210 .TP 8
 211 .B \-\-mode wireframe \fP(Shortcut: \fB\-\-wireframe\fP)
 212 Display the projective plane as a wireframe mesh.
 213 .TP 8
 214 .B \-\-mode surface \fP(Shortcut: \fB\-\-surface\fP)
 215 Display the projective plane as a solid surface.
 216 .TP 8
 217 .B \-\-mode transparent \fP(Shortcut: \fB\-\-transparent\fP)
 218 Display the projective plane as a transparent surface.
 219 .PP
 220 The following four options are mutually exclusive.  They determine the
 221 appearance of the projective plane.
 222 .TP 8
 223 .B \-\-appearance random
 224 Display the projective plane with a random appearance (default).
 225 .TP 8
 226 .B \-\-appearance solid \fP(Shortcut: \fB\-\-solid\fP)
 227 Display the projective plane as a solid object.
 228 .TP 8
 229 .B \-\-appearance distance-bands \fP(Shortcut: \fB\-\-distance-bands\fP)
 230 Display the projective plane as see-through bands that lie at
 231 increasing distances from the origin.
 232 .PP
 233 .TP 8
 234 .B \-\-appearance direction-bands \fP(Shortcut: \fB\-\-direction-bands\fP)
 235 Display the projective plane as see-through bands that lie at
 236 increasing angles with respect to the origin.
 237 .PP
 238 The following four options are mutually exclusive.  They determine how
 239 to color the projective plane.
 240 .TP 8
 241 .B \-\-colors random
 242 Display the projective plane with a random color scheme (default).
 243 .TP 8
 244 .B \-\-colors onesided \fP(Shortcut: \fB\-\-onesided-colors\fP)
 245 Display the projective plane with a single color.
 246 .TP 8
 247 .B \-\-colors twosided \fP(Shortcut: \fB\-\-twosided-colors\fP)
 248 Display the projective plane with two colors: one color one "side" and
 249 the complementary color on the "other side."  For static colors, the
 250 colors are red and green.  Note that the line at infinity lies at the
 251 points where the red and green "sides" of the projective plane meet,
 252 i.e., where the orientation of the projective plane reverses.
 253 .TP 8
 254 .B \-\-colors distance \fP(Shortcut: \fB\-\-distance-colors\fP)
 255 Display the projective plane with fully saturated colors that depend
 256 on the distance of the points on the projective plane to the origin.
 257 For static colors, the origin is displayed in red, while the line at
 258 infinity is displayed in magenta.  If the projective plane is
 259 displayed as distance bands, each band will be displayed with a
 260 different color.
 261 .TP 8
 262 .B \-\-colors direction \fP(Shortcut: \fB\-\-direction-colors\fP)
 263 Display the projective plane with fully saturated colors that depend
 264 on the angle of the points on the projective plane with respect to the
 265 origin.  Angles in opposite directions to the origin (e.g., 15 and 205
 266 degrees) are displayed in the same color since they are projectively
 267 equivalent.  If the projective plane is displayed as direction bands,
 268 each band will be displayed with a different color.
 269 .PP
 270 The following options determine whether the colors with which the
 271 projective plane is displayed are static or are changing dynamically.
 272 .TP 8
 273 .B \-\-change-colors
 274 Change the colors with which the projective plane is displayed
 275 dynamically.
 276 .TP 8
 277 .B \-\-no-change-colors
 278 Use static colors to display the projective plane (default).
 279 .PP
 280 The following three options are mutually exclusive.  They determine
 281 how to view the projective plane.
 282 .TP 8
 283 .B \-\-view-mode random
 284 View the projective plane in a random view mode (default).
 285 .TP 8
 286 .B \-\-view-mode turn \fP(Shortcut: \fB\-\-turn\fP)
 287 View the projective plane while it turns in 3d.
 288 .TP 8
 289 .B \-\-view-mode walk \fP(Shortcut: \fB\-\-walk\fP)
 290 View the projective plane as if walking on its surface.
 291 .PP
 292 The following options determine whether the surface is being deformed.
 293 .TP 8
 294 .B \-\-deform
 295 Deform the surface smoothly between the Roman and Boy surfaces
 296 (default).
 297 .TP 8
 298 .B \-\-no-deform
 299 Don't deform the surface.
 300 .PP
 301 The following option determines the deformation speed.
 302 .TP 8
 303 .B \-\-deformation-speed \fIfloat\fP
 304 The deformation speed is measured in percent of some sensible maximum
 305 speed (default: 10.0).
 306 .PP
 307 The following options determine the initial deformation of the
 308 surface.  As described above, this is mostly useful if
 309 \fB\-\-no-deform\fP is specified.
 310 .TP 8
 311 .B \-\-initial-deformation \fIfloat\fP
 312 The initial deformation is specified as a number between 0 and 1000.
 313 A value of 0 corresponds to the Roman surface, while a value of 1000
 314 corresponds to the Boy surface.  The default value is 1000.
 315 .TP 8
 316 .B \-\-roman
 317 This is a shortcut for \fB\-\-initial-deformation 0\fP.
 318 .TP 8
 319 .B \-\-boy
 320 This is a shortcut for \fB\-\-initial-deformation 1000\fP.
 321 .PP
 322 The following option determines the order of the surface to be
 323 displayed.
 324 .TP 8
 325 .B \-\-surface-order \fInumber\fP
 326 The surface order can be set to values between 2 and 9 (default: 3).
 327 As described above, odd surface orders result in generalized
 328 immersions of the real projective plane, while even numbers result in
 329 a immersion of a topological sphere.
 330 .PP
 331 The following options determine whether orientation marks are shown on
 332 the projective plane.
 333 .TP 8
 334 .B \-\-orientation-marks
 335 Display orientation marks on the projective plane.
 336 .TP 8
 337 .B \-\-no-orientation-marks
 338 Don't display orientation marks on the projective plane (default).
 339 .PP
 340 The following three options are mutually exclusive.  They determine
 341 how the projective plane is projected from 3d to 2d (i.e., to the
 342 screen).
 343 .TP 8
 344 .B \-\-projection random
 345 Project the projective plane from 3d to 2d using a random projection
 346 mode (default).
 347 .TP 8
 348 .B \-\-projection perspective \fP(Shortcut: \fB\-\-perspective\fP)
 349 Project the projective plane from 3d to 2d using a perspective
 350 projection.
 351 .TP 8
 352 .B \-\-projection orthographic \fP(Shortcut: \fB\-\-orthographic\fP)
 353 Project the projective plane from 3d to 2d using an orthographic
 354 projection.
 355 .PP
 356 The following three options determine the rotation speed of the
 357 projective plane around the three possible axes.  The rotation speed
 358 is measured in degrees per frame.  The speeds should be set to
 359 relatively small values, e.g., less than 4 in magnitude.  In walk
 360 mode, all speeds are ignored.
 361 .TP 8
 362 .B \-\-speed-x \fIfloat\fP
 363 Rotation speed around the x axis (default: 1.1).
 364 .TP 8
 365 .B \-\-speed-y \fIfloat\fP
 366 Rotation speed around the y axis (default: 1.3).
 367 .TP 8
 368 .B \-\-speed-z \fIfloat\fP
 369 Rotation speed around the z axis (default: 1.5).
 370 .PP
 371 The following two options determine the walking speed and direction.
 372 .TP 8
 373 .B \-\-walk-direction \fIfloat\fP
 374 The walking direction is measured as an angle in degrees in the 2d
 375 square that forms the coordinate system of the surface of the
 376 projective plane (default: 83.0).  A value of 0 or 180 means that the
 377 walk is along a circle at a randomly chosen distance from the origin
 378 (parallel to a distance band).  A value of 90 or 270 means that the
 379 walk is directly from the origin to the line at infinity and back
 380 (analogous to a direction band).  Any other value results in a curved
 381 path from the origin to the line at infinity and back.
 382 .TP 8
 383 .B \-\-walk-speed \fIfloat\fP
 384 The walking speed is measured in percent of some sensible maximum
 385 speed (default: 20.0).
 386 .SH INTERACTION
 387 If you run this program in standalone mode in its turn mode, you can
 388 rotate the projective plane by dragging the mouse while pressing the
 389 left mouse button.  This rotates the projective plane in 3d.  To
 390 examine the projective plane at your leisure, it is best to set all
 391 speeds to 0.  Otherwise, the projective plane will rotate while the
 392 left mouse button is not pressed.  This kind of interaction is not
 393 available in the walk mode.
 394 .SH ENVIRONMENT
 395 .PP
 396 .TP 8
 397 .B DISPLAY
 398 to get the default host and display number.
 399 .TP 8
 400 .B XENVIRONMENT
 401 to get the name of a resource file that overrides the global resources
 402 stored in the RESOURCE_MANAGER property.
 403 .TP 8
 404 .B XSCREENSAVER_WINDOW
 405 The window ID to use with \fI\-\-root\fP.
 406 .SH SEE ALSO
 407 .BR X (1),
 408 .BR xscreensaver (1)
 409 .SH COPYRIGHT
 410 Copyright \(co 2013-2020 by Carsten Steger.  Permission to use, copy,
 411 modify, distribute, and sell this software and its documentation for
 412 any purpose is hereby granted without fee, provided that the above
 413 copyright notice appear in all copies and that both that copyright
 414 notice and this permission notice appear in supporting documentation.
 415 No representations are made about the suitability of this software for
 416 any purpose.  It is provided "as is" without express or implied
 417 warranty.
 418 .SH AUTHOR
 419 Carsten Steger <carsten@mirsanmir.org>, 06-jan-2020.