In situations where true randomness would lead to visually unappealing
-displays, this program provides random selection from curated lists. For
+displays, this program provides random selection from curated lists. As one
example, to avoid randomly selecting visually indistinguishable colors like
`dark red` and `brown` to depict on/off cells, the program includes a
pre-selected list of color pairs that complement each other and chooses
-randomly from this list when the `-random-color` flag is passed. Similarly, to
-avoid the visually uninteresting rules like rule 0, a rule which simply turns
-every cell off and keeps it off, the program includes a list of rulesets and
-starting seeds which are visually appealing, selecting randomly from this list
-when the `-random-rule` flag is passed.
+randomly from this list.
Status
simulation completes or after resizing the window.
+CLI: Rule Selection
+-------------------
+
+If neither of the following two options are passed, rules are randomly selected
+from `curated_ruleset_list[]` in `WolframAutomata.c`.
+
+ - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
+ from a curated list. Note that many rules are visually uninteresting.
+
+ - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
+ from 0-255 inclusive are valid.
+
+
CLI: Simulation Seed
--------------------
-If none of the following options are specified, the starting seed will contain
-randomly interspersed active/inactive cells at a 30/70, 50/50, or 70/30 ratio,
-itself also randomly selected.
+The following seed related CLI flags apply only when using the
+`-true-random-rule` or `-rule N` flags. Without these flags, the program draws
+rules from `curated_ruleset_list[]` which also includes curated seeds, all of
+which override any seed related CLI flags.
+
+If the curated rule list is not in use and none of the following options are
+specified, the starting seed will contain randomly interspersed active/inactive
+cells at a 30/70, 50/50, or 70/30 ratio, itself also randomly selected.
- **`-seed-left`**: Seeds a single active cell on the left side of the
display. All other cells are inactive.
- **`-seed-density N`**: Generates random seed with `N` percent active cells.
-CLI: Rule Selection
--------------------
+CLI: Simulation Length
+----------------------
-If neither of the following two options are passed, rules are randomly selected
-from `curated_ruleset_list[]` in `WolframAutomata.c`.
+If neither of the following two options are passed, the simulation runs as
+thought `-length 5000` was passed.
- - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
- from a curated list. Note that many rules are visually uninteresting.
+ - **`-random-length`**: A random length smaller than 10,000 generations but
+ large enough to fill the screen is selected.
- - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
- from 1-255 inclusive are valid.
+ - **`-length N`**: Request `N` generations be simulated on each run.
-Note that, although Rule 0 is a valid set of rules, it is reused as a null
-value by the program and thus is ignored if passed as `-rule 0`. If you want to
-see Rule 0, choose any starting conditions you desire, then turn off your
-monitor and enjoy the resulting simulation.
+Note that an upper limit of 10,000 generations is enforced in order to avoid
+`BadAlloc` errors from some X servers. For more details, read
+`WolframAutomata.c` starting around the comment, "The maximum number of
+generations is cell_size dependent. This is a soft limit and may be increased
+if ..."
CLI: Simulation Speed
well respected.
-CLI: Simulation Length
-----------------------
-
-If neither of the following two options are passed, the simulation runs as
-thought `-length 5000` was passed.
-
- - **`-random-length`**: A random length smaller than 10,000 generations but
- large enough to fill the screen is selected.
-
- - **`-length N`**: Request `N` generations be simulated on each run.
-
-Note that an upper limit of 10,000 generations is enforced in order to avoid
-`BadAlloc` errors from some X servers. For more details, read
-`WolframAutomata.c` starting around the comment, "The maximum number of
-generations is cell_size dependent. This is a soft limit and may be increased
-if ..."
-
-
CLI: Cell Dimensions
--------------------
2x2, etc). Increasing the cell size may help with flickering on high DPI
monitors displaying chaotic rulesets.
-If neither of the following two options are passed, the simulation selects
-whatever cell size it feels appropriate for the current simulation speed.
+If neither of the following two options are passed, the simulation behaves as
+though `-cell-size 2` was passed.
- - **`-random-cell-size`**: Selects cell size of 2^N pixels for an `N`
- randomly chosen in the inclusive range `0`-`5`.
+ - **`-random-cell-size`**: Randomly selects 1, 2, 4, 8, 16, or 32 as the cell
+ size on each reset of the simulation.
- **`-cell-size N`**: Display each individual cell as an `N`x`N` square of
pixels on the screen.
CLI: Admiration
---------------
-When the simulation reaches its end as determined by flags like `-length N`, it
+When the simulation reaches its end as determined by flags like `-length N` it
will pause for a period of time, allowing the viewer to examine it without
interference from scrolling. By default, this 'admiration window' is five
seconds long.
- **`-admiration-delay N`**: At the end of a simulation, pause for `N`
seconds before resetting for the next simulation.
+
+
+XScreensaver Integration
+========================
+
+In addition to running as a standalone program, WolframAutomata can be
+integrated into the XScreensaver framework.
+
+To accomplish this integration, begin by installing and configuring
+XScreensaver via whatever method is appropriate for your operating system. The
+following instructions assume the filesystem paths used by FreeBSD packages and
+ports; your paths may differ. After XScreensaver installation, ensure all
+pertinent config files are created by running `xscreensaver-demo` and
+configuring XScreensaver for your system.
+
+After XScreensaver is configured and working on your system, ensure that
+WolframAutomata runs in standalone mode on your system. If you can `make clean run`
+in the `screensavers/hacks/WolframAutomata/` folder and see the hack's visual
+output, you're ready to move on.
+
+At this point, copy the hack into your XScreensaver hack directory. For
+example, with prerequisite steps spelled out:
+
+ git clone git://git.subgeniuskitty.com/screensavers
+ cd screensavers/hacks/WolframAutomata
+ make clean all
+ cp WolframAutomata /usr/local/bin/xscreensaver-hacks/
+
+Now create the file `WolframAutomata.xml` wherever your system stores
+XScreensaver config files and populate it with the contents shown below. For
+example, on FreeBSD:
+
+ vi /usr/local/share/xscreensaver/config/WolframAutomata.xml
+
+ TODO: Finish writing this file after the command line options are finalized.
+
+The next step integrates WolframAutomata into an individual user's XScreensaver
+config via the file `~/.xscreensaver`. If preferred, it could instead be done
+in the global XScreensaver config.
+
+In the `~/.xscreensaver` file, create a WolframAutomata entry under the
+`programs:` label in the same list as all the other hacks. Position in the
+list is irrelevant, but ensure you don't paste WolframAutomata's entry into the
+middle of pre-existing, multi-line entries. For context, the example below
+includes a multi-line entry, a GL entry and a plain entry. All that is needed
+is to insert the WolframAutomata line somewhere in the `programs:` list, as
+demonstrated.
+
+ vi ~/.xscreensaver
+
+ <snip>
+ programs: \
+ xplanet -vroot -wait 1 -timewarp 400 \
+ -label -origin moon \n\
+ GL: fireflies -root \n\
+ WolframAutomata -root \n\
+ blitspin -root \n\
+ <snip>
+
+That's all. Now you can run `xscreensaver-demo` and select WolframAutomata just
+like any other hack.
+
+
+Screen Tearing
+==============
+
+Certain combinations of rules and display settings lead to full screen vertical
+scrolling of alternating light and dark pixels, or other difficult to display
+patterns. If your display doesn't include some type of vertical refresh
+synchronization, such output will look terrible.
+
+If stuck in this situation, changing the output of WolframAutomata to scroll
+horizontally may help, or simply increasing the cell size.
+
projects / screensavers / blobdiff