c9016e6488e3ad42c6f40b6dda2d303dbec63643
[xscreensaver] / local / man / man.1 / bubbles.1
1 .de EX          \"Begin example
2 .ne 5
3 .if n .sp 1
4 .if t .sp .5
5 .nf
6 .in +.5i
7 ..
8 .de EE
9 .fi
10 .in -.5i
11 .if n .sp 1
12 .if t .sp .5
13 ..
14 .TH XScreenSaver 1 "14-Dec-95" "X Version 11"
15 .SH NAME
16 bubbles - frying pan / soft drink simulation
17 .SH SYNOPSIS
18 .B bubbles
19 [\-display \fIhost:display.screen\fP] [\-foreground \fIcolor\fP] [\-background \fIcolor\fP] [\-window] [\-root] [\-mono] [\-install] [\-visual \fIvisual\fP] [\-simple] [\-broken] [\-3D] [\-file filename] [\-directory directoryname]
20 .SH DESCRIPTION
21 \fIBubbles\fP sprays lots of little random bubbles all over the window which
22 then grow until they reach their maximum size and go pop.  The inspiration
23 for this was watching little globules of oil on the bottom of a frying pan
24 and it also looks a little like bubbles in fizzy soft drink.  The default
25 mode uses fancy ray-traced bubbles but there is also a mode which just draws 
26 circles in case the default mode is too taxing on your hardware.
27 .SH OPTIONS
28 Depending on how your
29 .I bubbles
30 was compiled, it accepts the following options:
31 .TP 8
32 .B \-foreground
33 Colour of circles if \fI\-simple\fP mode is selected.
34 .TP 8
35 .B \-background
36 Colour of window background.
37 .TP 8
38 .B \-window
39 Draw on a newly-created window.  This is the default.
40 .TP 8
41 .B \-root
42 Draw on the root window.
43 .TP 8
44 .B \-mono 
45 If on a color display, pretend we're on a monochrome display.
46 .TP 8
47 .B \-install
48 Install a private colormap for the window.
49 .TP 8
50 .B \-visual \fIvisual\fP
51 Specify which visual to use.  Legal values are the name of a visual class,
52 or the id number (decimal or hex) of a specific visual.
53 .TP 8
54 .B \-delay microseconds
55 How much of a delay should be introduced between steps of the animation.
56 Default 1, or about 1 microsecond.  Actually, this is the delay between each
57 group of 15 new bubbles since such a delay between each step results in a
58 very slow animation rate.
59 .TP 8
60 .B \-nodelay
61 Same as \fI\-delay 0\fP.
62 .TP 8
63 .B \-simple
64 Don't use the default fancy pixmap bubbles.  Just draw circles instead.
65 This may give more bearable performance if your hardware wasn't made for
66 this sort of thing.
67 .TP 8
68 .B \-broken
69 Don't hide bubbles when they pop.  This was a bug during development
70 but the results were actually quite attractive.  (This option is only
71 available if you have the XPM library available and the imake generated
72 Makefile has defined HAVE_XPM).
73 .TP 8
74 .B \-3D
75 Normally, the simulation is done completely in two dimensions.  When a
76 bubble swallows up another bubble, the areas of each are added to get
77 the area of the resulting bubble.  This option changes the algorithm
78 to instead add volume (imagining each to be a sphere in 3D space).  The
79 whole thing looks more realistic but I find it attracts attention to
80 the flickering of each bubble as they are move and are redrawn.  Your
81 mileage may vary.
82 .TP 8
83 .B \-file filename
84 Use the pixmap definitions in the given file, instead of the default (if
85 one is compiled in).  This is ignored if \fI\-simple\fP is specified.  If
86 the file is compressed (either with compress or gzip), it is decompressed
87 before use.  (This option only works if you have XPM compiled into your
88 binary and you have compiled with BUBBLES_IO set in bubbles.h.  This is
89 \fBnot\fP the default).
90 .TP 8
91 .B \-directory directoryname
92 Similar to \fI-file\fP except the file is taken randomly from the
93 contents of the specified directory.  (Again, this option is only available
94 if you have XPM and BUBBLES_IO was set when compiling.  See above).
95 .TP 8
96 .B \-quiet
97 Don't print messages explaining why one or several command line options
98 were ignored.  This is disabled by default.
99 .SH NOTES
100 If you find the pace of things too slow, remember that there is a delay
101 even though you specify no \fI\-delay\fP option.  Try using \fI\-nodelay\fP
102 although beware of the effects of irritation of other users if you're on a 
103 shared system as you bleed their CPU time away.
104
105 Some tools to assist in creation of new bubbles are included in the source
106 distribution.  These can either be loaded with the \fI\-file\fP or
107 \fI\-directory\fP options (if available) or they can be used in place
108 of the distributed default bubble (bubble_default.c).
109 You might like to copy these scripts to a permanent location and
110 use them.  Read bubbles.README.
111
112 Rendered bubbles are not supported on monochrome displays.  I'm not
113 convinced that small bubbles, even dithered properly are going to look
114 like anything more than a jumble of random dots.
115 .SH BUGS
116 There is a delay before something appears on the screen when using
117 rendered bubbles.  The XPM library seems to take a \fBlong\fP time to make
118 pixmaps out of raw data.  This can be irritating on slower systems.
119
120 The movement of the bubbles looks jerky if an incomplete set of bubbles
121 is used.  
122
123 The hide/display algorithm could do with some work to avoid flickering
124 when \fI\-nodelay\fP is set.
125 .SH ENVIRONMENT
126 .PP
127 .TP 8
128 .B DISPLAY
129 to get the default host and display number.
130 .TP 8
131 .B XENVIRONMENT
132 to get the name of a resource file that overrides the global resources
133 stored in the RESOURCE_MANAGER property.
134 .SH SEE ALSO
135 .BR X (1),
136 .BR xscreensaver (1)
137 .SH DISTRIBUTION POLICY
138 This work is Copyright \(co 1995, 1996 by James Macnicol.  Distribution is
139 allowed under the terms of the GNU General Public License.  Look at the
140 sources for the legalese.
141 .SH AUTHOR
142 James Macnicol <J.Macnicol@student.anu.edu.au>.