A CUDA renderer for the Buddhabrot fractal
This project contains a small CUDA program for rendering the Buddhabrot fractal using a CUDA-capable GPU.
I'm aware that there are at least two other github projects named "cudabrot", but both of them render the Mandelbrot set rather than the Buddhabrot. The Buddhabrot set is a variant of the Mandelbrot set similar to an attractor, and is generally more processor-intensive to render. Therefore, rendering high-resolution Buddhabrot images is an excellent application of GPU computing.
For more information on how the Buddhabrot set is rendered, see the Wikipedia article for information about the algorithm and the relationship to the Mandelbrot set.
To compile and run this program, you need to be using a Linux system with CUDA installed (the more recent the version, the better), and a CUDA-capable GPU. See below for instructions on AMD, using HIP.
Compile the program simply by running make
. Run it by running ./cudabrot
.
A summary of command-line arguments can be obtained by running
./cudabrot --help
. Running the program will produce a single grayscale image.
Typically, a colored Buddhabrot image is created by rendering several single-
channel images with different parameters, then combining the results by
assigning each single-channel image to a color in the output image.
This program has also been built and tested using ROCm 3.7 (but older versions
probably work) on AMD GPUs. To use this, you'll need to have
installed ROCm, including hip
,
rocRAND
, and hipRAND
(these should be installed by default if you just
follow the main ROCm installation instructions). Additionally, you'll need to
ensure that hipcc
and hipify-perl
are on your PATH
. The makefile also
expects to be able to find rocRAND
and hipRAND
under /opt/rocm/rocrand
and /opt/rocm/hiprand
, respectively.
If you satisfy all of the above requirements, then you should be able to
compile the program by running make hip
. This will produce a cudabrot
binary that behaves the same way as the CUDA version. (Don't be intimidated by
these instructions--check the makefile, it's actually very simple!)
All examples below were rendered using an NVIDIA GTX 970 with 4GB of GPU RAM.
-d <device number>
: Example: ./cudabrot -d 0
. If you have more than one
GPU, providing the -d
flag along with a device number allows you to run
computations on a GPU of your choosing. If the -d
flag isn't specified,
the program defaults to using GPU 0.
-o <output file name>
: Example: ./cudabrot -o image.pgm
. This program is
capable only of saving .pgm
-format images, which are a simple grayscale
bitmap format. Output images always use 16-bit grayscale. If left
unspecified, the program will save the image to a file named output.pgm
by
default.
-w <image width>
: Example: ./cudabrot -w 500 -h 500
. This flag controls
the horizontal resolution of the output image, in pixels. Note that neither
this nor -h
(for controlling vertical resolution) affects resolution at
which the complex plane is actually sampled. Image resolution doesn't
directly affect computation speed, but it will have an impact on GPU and
CPU memory required. For example, rendering a 20000x20000 image
(-w 20000 -h 20000
) takes at least 3 GB of GPU memory, so higher
resolutions may only be possible on more-capable GPUs.
-h <image height>
: Example: ./cudabrot -w 500 -h 500
. This is like -w
,
except it controls vertical resolution rather than horizontal resolution.
-s <save/load file>
: If provided, this must be the name of a file into
which the rendering buffer will be saved, for future continuation. If the
file already exists when the program starts, it will be loaded (and then
updated again before the program exits). This can be helpful if you need to
"pause" long-running renders and resume them later. If already present, the
file's size must match the expected internal size of the image buffer, but
otherwise the file has no specified format.
--min-real <minimum real value>
: Example: ./cudabrot -w 200 -h 100 --min-real 0.0 --max-real 1.0 --min-imag 0.0 --max-imag 0.5
.
This, along with --max-real
, --min-imag
, and --max-imag
control the
borders of the output-image "canvas" on the complex plane. The rectangle
specified must be well-formed (e.g. --min-real
must be less than
--max-real
, etc.). If you want to set the canvas to something that isn't a
square, then you'll also need manually adjust the output width and height to
match the aspect ratio. For example, the above "example" command produces
this image: . Note that
"zooming in" will not necessarily speed up rendering, since points must
still be sampled from across the entire Mandelbrot-set domain (from -2.0 to
2.0, and -2.0i to 2.0i). However, these settings can still be used for
saving memory if you want to zoom in on finer details without rendering an
ultra-high-resolution image. --min-real
defaults to -2.0.
--max-real <maximum real value>
. See the note about --min-real
.
--max-real
defaults to 2.0.
--min-imag <minimum imaginary value>
. See the note about --min-real
.
--min-imag
defaults to -2.0.
--max-imag <maximum imaginary value>
. See the note about --min-real
.
--max-imag
defaults to 2.0.
-t <time to run (in seconds)>
: Example: ./cudabrot -t 60
. This option
specifies the amount of time, in seconds, to run the rendering on the GPU.
The longer the time, the sharper the image will appear (especially at high
resolutions or number of iterations). Passing a special value of -1 to -t
will cause the program to run until it is interrupted by the user (using
kill
or CTRL+C on Linux, for example). Example: ./cudabrot -t -1
. If the
program is run with -t -1
and killed by the user, it will save the
currently-rendered output image. This is the recommended way to run the
program, if, for example, you want to render an image overnight. This option
defaults to 10 seconds.
-g <gamma correction>
: Example: ./cudabrot -g 2.0
. This option specifies
the amount of gamma correction to be applied post-rendering. Gamma
correction brightens darker areas of the image, which enhances the
visibility of some details. In most cases, it may be easier to apply gamma
correction post-rendering using a separate image editor (where changes can
be previewed), but this option is available for convenience and scripting.
This option defaults to 1.0 (no gamma correction).
Example images:
./cudabrot -w 200 -h 200 -m 10000 -c 8000 -t 30 -g 1.0 |
./cudabrot -w 200 -h 200 -m 10000 -c 8000 -t 30 -g 1.5 |
./cudabrot -w 200 -h 200 -m 10000 -c 8000 -t 30 -g 2.2 |
---|---|---|
-m <max escape iterations>
: Example: ./cudabrot -m 10000
. This option
specifies the maximum iterations to follow each particle before determining
whether it remains in the Mandelbrot set (meaning that its path is included
in the Buddhabrot set). In short, increasing this value will include more
fine details in the resulting image. This value defaults to 100, which is a
fairly low value. See these examples:
./cudabrot -w 200 -h 200 -t 10 -c 20 -m 100 |
./cudabrot -w 200 -h 200 -t 10 -c 20 -m 1000 |
./cudabrot -w 200 -h 200 -t 10 -c 20 -m 20000 |
---|---|---|
-c <min escape iterations>
: Example: ./cudabrot -m 5000 -c 4000
. This
option specifies the minimum cutoff for the number of iterations for which
points must remain in the Mandelbrot set if they are to be included in
the Buddhabrot. Increasing the minimum cutoff iterations will therefore
reduce the "cloudiness" of the generated image, enhancing the visibility of
the details produced using higher -m
values. This value defaults to 20,
which will produce a cloudy, nebulous image. See these examples:
./cudabrot -w 200 -h 200 -t 30 -g 1.8 -m 20000 -c 20 |
./cudabrot -w 200 -h 200 -t 30 -g 1.8 -m 20000 -c 2000 |
./cudabrot -w 200 -h 200 -t 30 -g 1.8 -m 20000 -c 10000 |
---|---|---|
The Buddhabrot rendering maps most easily to grayscale images, so coloring is
left to post-processing. The "traditional" way to color a Buddhabrot is to
generate several grayscale images using different minimum and maximum iteration
values (the -m
and -c
options in this program). The grayscale images can
then be combined into a single output image, with each grayscale image
contributing to a different color channel in the output.
A free program that can be used to combine grayscale images into a single color image exists in a separate repository.
Here's an example of how to create a color image, using the image_combiner
tool linked above:
./cudabrot -g 2.0 -w 1000 -h 1000 -m 100 -c 20 -t 20 -o low_iterations.pgm
./cudabrot -g 2.0 -w 1000 -h 1000 -m 2000 -c 600 -t 20 -o mid_iterations.pgm
./cudabrot -g 2.5 -w 1000 -h 1000 -m 10000 -c 9000 -t 40 -o high_iterations.pgm
./image_combiner \
low_iterations.pgm blue \
mid_iterations.pgm lime \
high_iterations.pgm red \
color_output.jpg
Alternatively, I've found that mapping grayscale images to H, S, and L
components of an HSL-color image results in a wide range of colors. I've
included a script, generate_hires_color_image.sh
, that uses this program to
generate a nice looking, high-resolution (20k x 15x pixels) result. See the
comments in the script for notes about additional requirements and operation.
The following image is a cropped portion of the full-resolution output: