Fractals/fragmentarium

From Wikibooks, open books for an open world
< Fractals
Jump to: navigation, search
Screen shot of Fragmentarium

"Fragmentarium is an open source, cross-platform IDE by Mikael Hvidtfeldt Christensen [1] 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."
This in unofficial wiki about it.

Intro[edit]

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[edit]

Precompiled Mac and Windows executable packages can be found at syntopia.github[2]

or on Ubuntu Linux...

Prerequisites[edit]

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[edit]

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[edit]

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[edit]

Precompiled SuSE Leap 42.2 , Mac and Windows packages can be found at Digilanti.org[3]

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[edit]

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.

Prerequisites[edit]

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)

Build[edit]

Windows[edit]

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[edit]

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

cd <wherever>/Fragmentarium-1.0.31-3Dickulus/
sh ./mklinux.sh

This will build OpenEXR and the Fragmentarium project and install the executable and support files to <wherever>/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 <wherever>/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

Get v2.0.0[edit]

Required Libraries for Linux SuSE Leap 42.2 rpm package at Digilanti.org[4]

libGL.so.1()(64bit)
libGLU.so.1()(64bit)
libc.so.6()(64bit)
libgcc_s.so.1()(64bit)
libm.so.6()(64bit)
libpthread.so.0()(64bit)
libstdc++.so.6()(64bit)
libz.so.1()(64bit)

openexr(x86-64) >= 2.1.0
    libHalf.so.11()(64bit)
    libIex-2_1.so.11()(64bit)
    libIexMath-2_1.so.11()(64bit)
    libIlmImf-Imf_2_1.so.21()(64bit)
    libIlmThread-2_1.so.11()(64bit)
    libImath-2_1.so.11()(64bit)

libQt5Core.so.5(Qt_5)(64bit)
libQt5Gui.so.5(Qt_5)(64bit)
libQt5OpenGL.so.5(Qt_5)(64bit)
libQt5Script.so.5(Qt_5)(64bit)
libQt5Widgets.so.5(Qt_5)(64bit)
libQt5Xml.so.5(Qt_5)(64bit)

Build[edit]

This should work for Linux, Mac and Windows(Qt5+MinGW)

Install git and the latest CMake and CMake-GUI programs 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 ..
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.) 

Now that you have it installed ;)[edit]

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

Open blog.hvidtfeldts[6] 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[edit]

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[edit]

./Fragmentarium-2.0.b [options] [filename.frag] <enter>

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 <style>            sets the application GUI style.
                            Possible values are
                            'Breeze','Windows','GTK+','Fusion'.
-l, --language <language>  sets the application language.
                            Possible values are 'en','de','ru','nl'.
-s, --script <script>      Fragmentarium command script file to load.

Arguments:
filename.frag              initial fragment to open.

Files & Folders[edit]

Examples[edit]

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[edit]

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[edit]

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

Misc[edit]

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[edit]

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

Main Window[edit]

Screenshot

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[edit]

Dialogs[edit]

Scripting[edit]

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

General commands[edit]

   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[edit]

   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[edit]

   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[edit]

   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[edit]

Uniform Widgets[edit]

The line: uniform float Angle; slider[45.00,0,360] in the GLSL editor will make a simple 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 the gets sent to the GPU.

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

v1.0 - v1.0.31[edit]

Type Widget
uniform int name; slider[min,default,max]
uniform bool name; false]
uniform float name; slider[min,default,max]
uniform vec2 name; slider[(min,min),(default,default),(max,max)]
uniform vec3 name; slider[(min,min,min),(default,default,default),(max,max,max)]
uniform vec4 name; slider[(min,min,min,min),(default,default,default,default),(max,max,max,max)]
uniform vec3 name; color[R,G,B] color selector only
uniform vec4 name; color[min,default,max, R, G, B] slider with color selector
uniform sampler2D name; file[imageFileName] can be any supported format


v2.0[edit]

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

Type Widget
uniform samplerCube name; file[cubemap.png]
uniform double name; slider[min,default,max]
uniform dvec2 name; slider[(min,min),(default,default),(max,max)]
uniform dvec3 name; slider[(min,min,min),(default,default,default),(max,max,max)]
uniform dvec4 name; slider[(min,min,min,min),(default,default,default,default),(max,max,max,max)]
uniform dvec3 name; color[R,G,B] color selector only
uniform dvec4 name; color[min,default,max, R, G, B] slider with color selector


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

Examples[edit]

Acknowledgements[edit]

Contributors, bermarte, Buddhi, cKleinhuis, Claude, Crist-JRodger, DarkBeam, Eiffie, Íñigo Quílez, Jesse, Kali, Knighty, M Benesi, mclarekin, Patryk Kizny, Stefan Gustavson, Sabine, SCORPION, Syntopia, SubBlue, tglad, Tryptophan, Vinz, _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[edit]

References[edit]

  1. Mikael Hvidtfeldt Christensen
  2. v1.0 github
  3. v1.0.31 Digilanti.org
  4. v2.0.0 Digilanti.org
  5. Fragmentarium usage
  6. Fragmentarium blog
  7. Fragmentarium home page
  8. github page
  9. Fragmentarium blog
  10. Fragmentarium official FAQ
  11. Fractal Forums page
  12. programming page
  13. FF gallery
  14. flicker group
  15. deviantart search
  16. Fragmentarium deviantart group