Fractals/fragmentarium



Fragmentarium is an open source, cross-platform IDE by Mikael Hvidtfeldt Christensen for exploring pixel based graphics on the GPU. It is inspired by Adobe's Pixel Bender, but uses GLSL, and is created specifically with fractals and generative systems in mind."

Features:
 * Multi-tabbed IDE, with GLSL syntax highlighting
 * User widgets to manipulate parameter settings.
 * Different 'mouse to GLSL' mapping schemes
 * Modular GLSL programming - include other fragments
 * Includes simple raytracer for distance estimated systems
 * Many examples including Mandelbulb, Mandelbox, Kaleidoscopic IFS, and Julia Quaternion.

Licensed and distributed under the LPGL or GPL license.

Notice: some fragment (GLSL) shaders are copyright by other authors, and may carry other licenses. Please check the fragment file header before redistributing.

Please read the FAQ, before asking questions.

For examples of images take a look at the FF Fragmentarium galleries.

More information can be found at: FractalForums.com -> Fragmentarium and FractalForums.org -> Fragmentarium

This the unofficial wiki about it.

=Intro=

Fragmentarium comes in a few different flavors. The major differences are... -
 * Version 1.0 has only the "time" variable for animating.
 * Version 1.0.31 introduces camera position Catmull-Rom spline based keyframing, parameter morphing with easing curves, target tracking auto focus, OpenEXR format input for textures and output for images, along with German, Dutch and Russian translations.
 * Version 2.0.0 brings samplerCube textures and double precision uniform widgets.

Get v1.0
Precompiled Mac and Windows executable packages can be found at syntopia.github

or on Ubuntu Linux...

Prerequisites
cmake 3 Qt 4 C++ compiler OpenGL development libs Git (if fetching the source directly from the repository) sudo apt-get install build-essential libx11-dev mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev libxext-dev libqt4-opengl-dev git clone https://github.com/Syntopia/Fragmentarium

Build
cd Fragmentarium-master cd Fragmentarium-Source cd "Build - Linux" ( there are also build folders for Mac OSX, Windows and QCreator with build scripts. ) sh build.sh

Run
Go to the ~/Fragmentarium-master/Fragmentarium-Source directory, then run Gui program :

cd ~/Fragmentarium-master/Fragmentarium-Source ./Fragmentarium-Source

Note: at this point it would be a good idea to move the Examples, Icons and Misc folders with the Fragmentarium executable into a suitable working folder and change the name of the Fragmentarium-Source.exe file.

Get v1.0.31
Windows installer can be found at Digilanti.org

Windows users can download the 6.0M Fragmentarium Installer and run it by navigating to your Downloads folder and clicking the installer icon.

This will install the Windows Executable + Examples Includes and Misc folders + Qt 5.6.2 runtime DLLs + GUI translation files into a working folder in your home folder with startmenu shortcuts to the executable and the Maintenance program.

Source Code
Download Fragmentarium 1.0.31 sources bundled with OpenEXR sources or the smaller archive with precompiled static OpenEXR libs.

For windows the compile scripts expect to find the source in top level of C: drive so extract the archive there or adjust the pathnames in the windows bat file.

Note: the v1.0.31 sources are available on request as development is in the v2.0 branch from here on.

Prerequisites
CMake 3 + CMake-gui Qt 5.6 C++ compiler OpenGL

The above packages should be installed along with their corresponding development packages.

Git (if fetching the source directly from the repository)

Windows
After installing Qt v5.6 and MinGW v4.9.2

Start Menu/Programs/Qt Tools/5.6/MinGW 4.9.2 (32-bit)/Qt 5.6 for Desktop (MinGW 4.9.2 32 bit) cd C:/Fragmentarium-1.0.31-3Dickulus/ mkmingw

This will build OpenEXR and the Fragmentarium project and install the executable with support files to C:/Fragmentarium-1.0.31-3Dickulus/Fragmentarium folder, this folder can then be relocated to wherever you like.

Linux
The archive can be extracted anywhere and the standard development environment with Qt5 OpenGL and OpenEXR should suffice.

cd /Fragmentarium-1.0.31-3Dickulus/ sh ./mklinux.sh

This will build OpenEXR and the Fragmentarium project and install the executable and support files to  /Fragmentarium-1.0.31-3Dickulus/Fragmentarium folder, this folder can then be relocated to wherever you like.

To build Fragmentarium only, after running one of the scripts...

cd /Fragmentarium-1.0.31-3Dickulus/Fragmentarium-Source/build cmake-gui .. ( to change any paths or precompile flags like the install prefix ) cmake-gui->configure cmake-gui->generate cmake-gui->quit make install

Ubuntu
Precompiled Ubuntu 14.04.5 package at github.com requires Qt v5.7

or to compile from source on Ubuntu "trusty"

Install gcc-4.8 sudo add-apt-repository -y ppa:ubuntu-sdk-team/ppa sudo apt-get update -qq sudo apt-get -qq install g++-4.8 libc6-i386 Install Qt-5.7 sudo apt-add-repository -y ppa:beineri/opt-qt571-trusty sudo apt-get update -qq sudo apt-get install qtcreator-latest Install openexr-2.2 development + runtime sudo apt-add-repository -y ppa:thomas-schiex/blender sudo apt-get update -qq sudo apt-get install libilmbase-dev sudo apt-get install libopenexr-dev sudo apt-get install libilmbase12 sudo apt-get install libopenexr22 Install Extra-CMake-Modules for FindOpenEXR sudo apt-get install extra-cmake-modules source /opt/qt57/bin/qt57-env.sh Grab the source git clone https://github.com/3Dickulus/FragM Build and install cd FragM/Fragmentarium-Source mkdir build cd build cmake -DNVIDIAGL4PLUS=ON -DUSE_OPEN_EXR=ON -DCMAKE_INSTALL_PREFIX=~/ .. make install


 * 1) The above will install in /home/username/Fragmentarium folder with includes and support files.
 * 2) To install for all users change -DCMAKE_INSTALL_PREFIX=~/ to -DCMAKE_INSTALL_PREFIX=/usr/local and use sudo make install

SuSE Leap 42.2
Prerequisites for Linux SuSE Leap 42.2 rpm package at github.com

System Desktop OpenEXR 2.1 Qt 5.6

Build

Install git and the latest CMake and CMake-GUI programs along with ECM (Extra CMake Modules) and the standard development environment for Qt5 and OpenEXR

git clone https://github.com/3Dickulus/FragM cd FragM/Fragmentarium-Source mkdir build cd build cmake-gui .. (note: set USE_OPEN_EXR=OFF when OpenEXR is not available/desired) make -j4 make install (note: set the install prefix in cmake-gui before running make install, it will install to /usr/local by default, user home folder is OK.)

Mac OSX dmg
Prerequisites for Mac OSX (this is what was required to build on travis-ci.org) brew update brew tab homebrew/versions brew unlink gcc brew install gcc48 brew install qt5 brew install ilmbase openexr brew unlink openexr brew link --overwrite openexr brew unlink ilmbase brew link --overwrite ilmbase brew unlink cmake brew install cmake brew install git

Before calling cmake these env vars need to be set... export PATH="$QTDIR/bin:$PATH" export PATH=/usr/local/bin:$PATH export CC=/usr/local/bin/gcc-4.8 export CXX=/usr/local/bin/g++-4.8 export QTDIR="/usr/local/opt/qt" export LDFLAGS="-L/usr/local/opt/qt/lib" export CPPFLAGS="-I/usr/local/opt/qt/include"

Grab the source... git clone https://github.com/3Dickulus/FragM

Then to build, execute the following... cd FragM/Fragmentarium-Source mkdir build cd build cmake -DNVIDIAGL4PLUS=ON -DUSE_OPEN_EXR=ON -DCMAKE_INSTALL_PREFIX=../../ .. make install

And to build a dmg archive... cd ../../Fragmentarium-2.0.b     macdeployqt ./Fragmentarium-2.0.b.app -dmg mv ./Fragmentarium-2.0.b.dmg ../Fragmentarium-Source/build/Fragmentarium-2.0.b-my_build.dmg cd ../Fragmentarium-Source/build ...this should create a file named Fragmentarium-2.0.b-my_build.dmg in the build folder.

=Now that you have it installed ;) =

Open syntopia.github in your browser to learn about preprocessor commands, magical uniforms and GUI elements.

Open blog.hvidtfeldts in your browser to learn about the math behind path tracing 3D fractals and the GLSL code.

The information found at the v1.0 Syntopia links is valid for all versions of Fragmentarium.

GUI Usage
Run from the desktop by clicking the icon for the executable file. You can drag and drop .frag, .fragparams and .png screenshot files onto the main window and Fragmentarium will open a new tab for a .frag file or apply the parameter settings to the current fragment. Settings are stored in screen shot png files in a chunk named "frAg" and are automatically recognized by Fragmentarium.

Commandline Usage
./Fragmentarium-2.0.b [options] [filename.frag] Output: Fragmentarium is a cross-platform IDE for exploring pixel based GPU graphics. Options: -h, --help                Displays this help. -v, --version             Displays version information. --style           sets the application GUI style. Possible values are 'Breeze','Windows','GTK+','Fusion'. -l, --language sets the application language. Possible values are 'en','de','ru','nl'. -s, --script     Fragmentarium command script file to load. Arguments: filename.frag             initial fragment to open.

OpenGL version mismatch
FragM 2 expects an OpenGL 4.1 Compatibility Profile context. Some drivers provide a lower version in Compatibility Profile, reserving higher versions for Core Profile.

Check it : Unfortunately if FragM gets a lower version, it can crash on startup with a segmentation fault.

Mesa
Check if you are using MESA: If using Mesa for OpenGL (most commonly on Linux with Free/Libre Open Source drivers) you can force Mesa to lie about its capabilities by setting an environment variable in the shell before launching FragM:

This may however merely postpone crashes until unsupported features are invoked. Use at your own risk.

=Files & Folders=

Examples
Contains 233 files in 16 sub-folders, this tree is duplicated in the Examples menu, just select one and it will be loaded into a new tab.

Examples/Tutorials
Contains 19 tutorial frags that demonstrate specific features or techniques.

The rest of the folders in Examples/ contain frags from a number of contributors, see Acknowledgements

fqScript
Contains some example Fragmentarium Qt Script files that can be loaded, edited, executed and saved from within Fragmentarium.

Misc
Contains options files for the video encoders, this folder is also intended for tool scripts like mkcombined.sh and the glsl.xml that describes highlighting for the code editor, at the end of glsl.xml there are places for user selectable colors and style hints so one can customize the highlighting to their own tastes.

Languages
Contains GUI translation files for Dutch, German and Russian contributed by Sabine, Crist-JRoger and SCORPION.

=Main Window= Top, Program Menus and dynamic menus Tool Bar, Buffer size, Build, Progressive/Animation stop start rewind, Subframe setting and readout, Current time setting and readout. Left, Fragment editor, hide by dragging the splitter bar all the way to the left Middle, GL rendering area Right, Variable widgets (uniforms) dock window, can float or be hidden Bottom, Log dock window, can float or be hidden Status Bar, relays info messages, has XYZ readout for cursor pos, rendered frames per second.

=Menus=

File
New : Creates a new tab with a simple DE function. Open : Creates a new tab and loads the selected fragment file. Save : Writes the currently active tab to file. Save As : Writes the currently active tab to filename selected by user. Recent files list : History. Close Tab : Closes the currently active tab and associated windows. Exit Application : Quits Framentarium, user will be prompted if there are unsaved changes.

Edit
Cut : Cuts selected text to clipboard. Copy : Copies selected text to clipboard. Paste : Pastes current clipboard contents. Find : Locate selected text, if no selected text request user input. Shader Asm : Displays GPU assembler code for currently active shaders. (nVidia only) Indent Script : Indent selected text. Insert Command -> Preprocessor Commands : Inserts the selected preprocessor command at the cursor or replaces selected text. Special Uniforms : Inserts the selected uniform variable at the cursor or replaces selected text. Include File (from Preferences Path) : Creates an #include fileName statement at the current cursor position. Insert Preset (from Current Settings) : Appends a new named preset to the text editor. Add Easing Curve : Creates easingcurve settings for the currently selected slider. Add Key Frame : Appends a preset with only camera position information. Select Key Frame : Highlights the text associated with the currently listed keyframe from the variable editor pulldown menu. Preferencess : Global program settings.

Render
Build Systems : Compiles the shaders. High Resolution and Animation Render : Opens the rendering dialog. Output Preprocessed Script (debug) : Creates a new tab with the main fragment script after parsing all included files. Full Screen (ESC key toggle) : Switch to full screen mode. Save Screen Shot : Saves the current GL area. When image format is png the settings are saved in the "fRAg" chunk, Fragmentarium will recognize this chunk if the screen shot png file is dragged and dropped onto the main window and will attempt to apply those settings to the current fragment. Edit Command Script : Opens a simple editor and allows creating, loading and running a .fqs file, see fqScript folder for examples. Video Encoding : Opens a dialog where the user can select mencoder or ffmpeg to create videos from a folder of generated images.

Parameters
Reset All : Resets all uniforms to their specified default values. Copy Settings : Copies all variable settings to the clipboard. Copy Group : Copies a single group (variable editor tab) to the clipboard. Paste from Clipboard : Pastes clipbaord contents into variable editor. Paste Selected Text : Pastes the selected text (usually from a preset in the code window) into the variable editor. Save to File : Creates a parameters file. Load from File : Loads a parameters file.

Examples
This menu is populated dynamically at runtime from the contents of the currently active Examples folder. Selecting a fragment will load the file into a new tab and execute build.

Windows
These are parts of the main window that can be displayed or hidden. Right mouse button click in the empty part of the menu bar will show this menu as a popup. Log Variable Editor (uniforms) File Toolbar Edit Toolbar Buffer Dimensions Render Toolbar Rendering Mode Zappa Tools Time

Help
These should be self explanitory. About Show Welcome Note Mouse and Keyboard Help Scripting General Help Scripting Parameter Help Scripting Image Anim Dialog Help Scripting Control Help Clear Texture Cache Project Homepage (web link) Fragmentarium@FractalForums (web link) Fragmentarium 3Dickulus (web link) Flickr Fragmentarium Group (web link) GLSL Specifications (web link) Introduction to Distance Estimated Fractals (web link) Fragmentarium FAQ (web link)

EXR Tools
When OpenEXR is installed on your system this menu should be populated with these commands. Selecting a command from this menu will display a usage help dialog, these are all commandline programs and only information about the command is shown here. exrenvmap exrheader exrmakepreview exrmaketiled exrmultipart exrmultiview exrstdattr If the EXR Tools menu exists but shows no entries you can set the EXR binaries path via Preferences... from the Edit menu.

=Main Window Dialogs=

=Scripting=

Fragmentarium can be controlled via scripting commands available in fqscript files.

General commands
void setFrame(int); Sets the current frame number.

int getFrame; Returns the current frame number.

void loadFragFile(String); Opens a new editor tab, loads the named fragment file, initializes default preset, initializes keyframes and easing curves if the file contains these settings.

bool initializeFragment; Returns success or fail. Must be called after altering a locked variable before rendering an image.

Parameter commands
void setParameter(String); Set a parameter from String in the form of "parameter = value" also accepts parameter file formated string.

void setParameter(String, bool); Sets a boolean parameter where String is the parameter name and bool is TRUE or FALSE

void setParameter(String, int); Sets an integer parameter where String is the parameter name and int is any integer.

void setParameter(String, x); Sets a float parameter where String is the parameter name and x is any floating point number.

void setParameter(String, x, y); Sets a float2 parameter where String is the parameter name and x,y are any floating point numbers.

void setParameter(String, x, y, z); Sets a float3 parameter where String is the parameter name and x,y,z are any floating point numbers.

void setParameter(String, x, y, z, w); Sets a float4 parameter where String is the parameter name and x,y,z,w are any floating point numbers.

String getParameter(String); Returns a string representing the value(s) for the named parameter, user must parse this into usable values.

void applyPresetByName(String); Applies the named preset.

Hires image and animation dialog commands
void setAnimationLength(int); Sets the total animation duration in seconds.

void setTileWidth(int); void setTileHeight(int); Sets the tile width and height.

void setTileMax(int); Sets the number of row and column tiles, this value squared = total tiles.

void setSubFrames(int); Sets the number of frames to accumulate.

void setOutputBaseFileName(String); Sets the filename for saved image, if script has total control this must be set by the script for every frame, if animation is using frag file settings, keyframes etc., then this only needs to be set once to basename and Fragmentarium will add an index padded to 5 digits.

void setFps(int); Sets the frames per second for rendering.

void setStartFrame(int); Sets the start frame number for rendering a range of frames.

void setEndFrame(int); Sets the end frame number for rendering a range of frames.

void setAnimation(bool); FALSE sets animation to script control exclusively. TRUE enables control from keyframes and easing curves.

void setPreview(bool); TRUE will preview frames in a window on the desktop instead of saving image files.

Control commands
bool scriptRunning; Returns FALSE when the user selects the [Stop] button in the script editor. For user implemented test in script to break out of the script control loop.

void stopScript; For user implemented test in script to break out of the script control loop or error like file not found, initialization fail etc.

void tileBasedRender; Begins rendering the current frame or range of frames applying the current state for keyframes and active easing settings.

=Preprocessor Commands= (from syntopia.github.io) Fragmentarium adds a few additional preprocessor commands.

Simply includes the referenced file. If the filename is a relative filename, Fragmentarium first searches for the file relative to the location of the current executing file (if it is saved), otherwise the paths specified in the 'include path' preference are searched.
 * 1) include "some.frag"

Tells Fragmentarium to setup a 3D camera model, making it possible to adjust the camera using the mouse on the canvas.
 * 1) camera 3D

Tells Fragmentarium to setup a 2D camera model.
 * 1) camera 2D

Makes it possible to order GUI elements in groups.
 * 1) group parameter group name

Outputs info when compiling the fragment. Useful for attributions.
 * 1) info "hello there"

Experimental. Includes 'some.frag', but will ignore any 'include' commands in that file.
 * 1) includeonly "some.frag"

Experimental. Replaces the given patterns in all subsequent read lines (not in previously parsed lines).
 * 1) replace "before" "after"

Tells Fragmentarium that it should not attempt to run this file - it is meant be included from another file.
 * 1) donotrun

Marks the beginning of a section with parameter settings. These will appear in a drop-down combobox in the parameter editor window.
 * 1) preset name

Marks the end of a section with parameter settings.
 * 1) endpreset

=Uniform Widgets= The line: uniform float Angle; slider[45.00,0,360] in the GLSL editor will make a simple variable editor widget appear.

To create widgets for other types of uniforms...

uniform type name ; widget[min,default,max] locktype

The keyword uniform must always be present at the beginning of the line. locktype can be one of locked notlocked notlockable alwayslocked defaults to notlocked In the Menu/Edit/Preferences dialog you can select the behavior of lock handling. "Locked" uniforms can be interpreted as "#define"s or as "const"s in the final GLSL code that gets sent to the GPU.

type and  widget can be one of these GLSL valid types and corresponding Fragmentarium widgets...

v2.0
All of v1.0 - v1.0.31 plus these...

All float type sliders have 7 decimal places while double types have 14.

=Tutorials=

=Acknowledgements=

Much of the inspiration and formulas for Fragmentarium came from the community at FractalForums.com, including Tom Beddard, Jan Kadlec, Iñigo Quilez, Buddhi, Jesse, and others. Special thanks goes out to Knighty and Kali for their great fragments. All fragments should include information about their origins - please notify me, if I made any mis-attributions.

The icons used are part of the Everaldo: Crystal project.

Fragmentarium is built using the Qt cross-platform GUI framework.

Translations by Fractal Forums users:
 * Russian SCORPION
 * Russian Crist-JRoger
 * German Sabine
 * Dutch Sabine

Contributors, This means allmost everyone at FractalForums.com over the last 7 years? This list is not complete.
 * 1) 3Dickulus
 * 2) Adam Majewski
 * 3) bermarte
 * 4) Buddhi
 * 5) cKleinhuis
 * 6) Claude
 * 7) Crist-JRodger
 * 8) DarkBeam
 * 9) Eiffie
 * 10) Íñigo Quílez
 * 11) Jesse
 * 12) Kali
 * 13) Knighty
 * 14) M Benesi
 * 15) mclarekin
 * 16) Patryk Kizny
 * 17) Stefan Gustavson
 * 18) Sabine
 * 19) SCORPION
 * 20) Syntopia
 * 21) SubBlue
 * 22) tglad
 * 23) Tryptophan
 * 24) Vinz
 * 25) _revers_

...just to name a few, if anyone can add to this list it would be a great help. If you contributed an idea or fix to the GUI or source code then I think your user/name deserves mention here too.

=Other Docs=
 * official pages :
 * home page
 * github Syntopia page
 * blog
 * faq
 * FragM wiki
 * Fractalforums :
 * program page
 * programming page
 * gallery
 * flicker group
 * deviantart
 * search
 * Fragmentarium group
 * commons : Category:Fragmentarium
 * git forks
 * github by Claude : Fragmentarium

=References=

|