Added readme and license files and fixed example.ini

3 files changed, 87 insertions, 3 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..fddb00a
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,25 @@
+NOTE:
+This is the license of nebula2. nebula2 uses / includes the SFMT random number
+generator and the iniparser library. Both have other licenses and are property
+of their respective owners.
+
+--------------------------------------------------------------------------------
+
+Copyright (c) 2013 Kevin Chabowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.markdown b/README.markdown
new file mode 100644
index 0000000..c44053f
--- /dev/null
+++ b/README.markdown
@@ -0,0 +1,59 @@
+# nebula2
+
+A program for calculating and rendering a [Nebulabrot](http://en.wikipedia.org/wiki/Nebulabrot) image.
+
+## Dependencies / Libraries
+
+nebula2 uses these libraries:
+
+* [SFMT](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/index.html) random number generator (included).
+* [iniparser](https://github.com/ndevilla/iniparser) for parsing ini files (no, really!). (included as git submodule).
+* [pthreads](http://en.wikipedia.org/wiki/Pthreads) for parallelism. Should ship with your Linux distribution.
+
+## Building
+
+Simply run `make` in this directory.
+
+If you have a CPU that does not support SSE2 you should remove the `-DHAVE_SSE2` part of the `SFMTFLAGS` variable in the Makefile.
+
+## Running / Config file
+
+nebula2 needs a config file. It is an ini file. All parameters must belong to the section \[nebula2\].
+
+### Config parameters
+
+* **width** — The image width.
+* **height** – The image heigth.
+* **jobsize** – The size of a singe job (how many mandelbrot traces should be recorded during one job).
+* **jobs** – The number of jobs to execute. If the image quality is not good enough, you can later increase this number and rerun nebula2. It will continue where it left, if the statefile is still there.
+* **threads** – How many threads should be working?
+* **statefile** – The current calculation state is saved to this file. This allows you to abort the calculation and continue later.
+* **output** – The rendered BMP image is saved to this file.
+* **iterX** – The maximum iteration for layer X. X must start with 0 and be in ascending order (i.e. if there is a `iter0` and a `iter2`, `iter2` will be ignored).
+* **colorX** – The color for the layer/iteration X. 6 hexadecimal digits `RRGGBB`, where `R` is the red part, `G` the green part and `B` the blue part.
+
+See `example.ini` for an example.
+
+### Aborting and continuing calculation.
+
+Calculation can be aborted by sending the `SIGINT` signal to the nebula2 process (this can usually be achieved by pressing <Ctrl + C> in the terminal with the nebula2 process). Stopping the job might take a while (it needs to save the current state. Also the image is rendered).
+
+You can continue the calculation by simply executing nebula2 with the same config file again (if the statefile is still there).
+
+### Displaying progress
+
+When you send the `SIGUSR1` signal to the nebula2 process, it will display the number of jobs that still need to be calculated. It might stay pretty long at 0 open jobs, since it will render the image then (which can take some time on large images).
+
+You can use this shell snippet to display the progress continuously:
+
+	while true; do kill -SIGUSR1 <PID of nebula2 job>; sleep 1; done
+
+## Portability
+
+Only tested on Linux, might or might not work on other \*nix systems.
+
+Will definetly not work under Windows without some compatibility layer like Cygwin.
+
+## Where is nebula1?
+
+nebula1 is *very ugly* and difficult to use and will therefore not be published. Some code of it is recycled in nebula2, though.
\ No newline at end of file
diff --git a/example.ini b/example.ini
index fe42a1f..0be8fa1 100644
--- a/example.ini
+++ b/example.ini
@@ -3,7 +3,7 @@ width=800
 height=600
 
 jobsize=100000
-jobs=10000
+jobs=1000
 threads=6
 
 statefile=example.state
@@ -12,8 +12,8 @@ iter0=20
 iter1=200
 iter2=2000
 
-color0=ff0000
+color0=000088
 color1=00ff00
-color2=0000ff
+color2=ff0000
 
 output=example.bmp