TODO

========================================================================
 1. implement libnoise rendering: for preview rendering
========================================================================
  idea:
  - create the module tile dynamically; either colored or BW
  - fix DataAbstractModule::network(), this means: fix class_generator.py

------------------------------------
 NoiseNetworkRenderer clients are:
------------------------------------
  - preview tile per module
  - graphics exporter
  - spring map exporter
    -> current design idea is that only the heightmap is produced using libnoise while the colored image (colormap) is only
       interpolated when scaling up the heightmap. the colormap (compared to the heightmap) is of much higher resolution.
       also i currently think: the heightmap points must be interpolated linear, considering the coloring as using a
                               higher-resolution libnoise network rasterization resulted in wrongly colored heightmaps as
                               some meshes had problematic coloring.
  - libnoise-viewer like preview widget 2d and 3d (later: both started from a graphical module)

------------------------------------
 NoiseNetworkRenderer properties are:
------------------------------------
 - NoiseNetwork*, 
 - quality, 
 - pos: x,y and widht,height, 
 - coloring sheme
 - priority (preview tiles have a high priority; QGraphicsItem relatives have a high priority; libnoise-view has a low priority)

------------------------------------
 affected files
------------------------------------
 - NoiseNetwork.cpp/.h            container abstraction for the libnoise library which is passed to NoiseNetworkRenderer
 - NoiseNetworkRenderer.cpp/.h    renders tiles given a NoiseNetwork; implemented as singleton; returns raw data; implements QtConcurrent/QThreading
 - all clients (see list above)

------------------------------------
 misc
------------------------------------
 - create a LibNoiseRole which indicates that the network has changed

 - need to move the port allocation routine from Model.cpp::insertModule() to the DataAbstractModule.cpp constructor
   this is done but now the connection is not added correctly anymore

 - FIXME/incomplete class_generator.py to handle SetSourceModule and SetControlModule properly
 
 -> check that dataChanged for class Module is only called when it is needed, that is NOT every time a property changes
  -> fix dataChanged to use the LibNoiseRole
  -> filter the NoiseNetworkRendered tile from the QTreeView, as it is no property

------------------------------------
 QA
------------------------------------
 - if a network() says it is fully connected but the libnoise library is actually not, we need a mechanism to not segfault in libnoise
   - need to test this


========================================================================
 2. construct a proper backend property handler (Perlin.cpp/.h)
========================================================================
this forms the basis for step (3) (see below)



========================================================================
 3. connect the backend property with a corresponding gui delegate editor/view
========================================================================
   WARNING: a property might have several dependencies as: int 1,2,4,8 and if one set's 5 the libnoise library will create
            an exception which we most likely don't handle which will bring down the whole program.
            therefore: every property has to provide an input checker, which skips invalid input with some feedback.

-- THIS DOES NOT INCLUDE DELEGATE DEVELOPMENT (SEE NEXT POINT)--

thoughts about the makro or function call to insert a new property:
  insertProperty( type, setFunction, codeName, guiName, minValue, maxValue, description );

modules="""                               properties
Utils NoiseMapBuilderPlane      1 0 0     ?
Utils RendererImage             1 0 0     ?
Utils Image                     1 0 0     ?

Generator Billow                0 0 1     
 double, SetFrequency, m_frequency, Frequency, min, max, "Sets the frequency of the first octave" 
 double, SetLacunarity, m_lacunarity, Lacunarity, min, max, "Sets the lacunarity of the billowy noise"
 int, SetNoiseQuality, m_noisequality, Noise Quality, min, max, "Sets the quality of the billowy noise"      // GetNoiseQuality (FAST/STD/BEST)
 int, SetOctaveCount, m_octavecount, Octave Count, 1, noise::module::BILLOW_MAX_OCTAVE, "Sets the number of octaves that generate the billowy noise"
 double, SetPersistence, m_persistence, 0.0, 1.0 , "Sets the persistence value of the billowy noise"
 int, SetSeed, m_seed, Seed, min, max, "Sets the seed value used by the billowy-noise function"

Generator Checkerboard          0 0 1     -

Generator Const                 0 0 1     
 double constvalue

Generator Cylinders             0 0 1     
 double frequency

Generator Perlin                0 0 1     
 double frequency, 
 double lacunarity,  
 GetNoiseQuality (FAST/STD/BEST), 
 int octavecount, 
 double persistence (), 
 int seed, 

Generator RidgedMulti           0 0 1     
 double frequency, 
 double lacunarity,  
 GetNoiseQuality (FAST/STD/BEST), 
 int octavecount, 
 int seed, 

Generator Spheres               0 0 1     
 double frequency, 

Generator Voronoi               0 0 1     
 bool distance, 
 double displacement, 
 double frequency, 
 int seed, 

Combiner Add                    2 0 1     -
Combiner Max                    2 0 1     -
Combiner Min                    2 0 1     -
Combiner Multiply               2 0 1     -
Combiner Power                  2 0 1     -

Modifier Abs                    1 0 1     -
Modifier Clamp                  1 0 1     -
Modifier Curve                  1 0 1     several: AddControlPoint (double inputValue, double outputValue) / void   ClearAllControlPoints ()
Modifier Exponent               1 0 1     double 0.0 to 1.0; setExponent, getExponent
Modifier Invert                 1 0 1     -
Modifier ScaleBias              1 0 1     several: double GetBias/SetBias, GetScale, SetScale
Modifier Terrace                1 0 1     bool  InvertTerraces; addControlPoint(double), getControlPoint(..)

Selector Blend                  2 1 1     -
Selector Select                 2 1 1     double edgefalloff, double lowerbound, double upperbound, 

Transformer Displace            1 3 1     -
Transformer RotatePoint         1 0 1     double xangle, double yangle, double zangle
Transformer ScalePoint          1 0 1     double scale, double xscale, double yscale, double zscale
Transformer TranslatePoint      1 0 1     double translation, double xtranslation, double ytranslation, double ztranslation,
Transformer Turbulence          1 0 1     double frequency, double power, int RoughnessCount, int seed, 

Spring Mapgenerator             1 0 0     qpoint position, mapsize x,y (spring map sizetype)

second backend object factory to build the libnoise chain:
 - registers required properties at the Graphical Representation
 - is able to collect properties from the Graphical Representation and uses them to build the libnoise-chain
 - should not mix GraphicsScene coordinates with libnoise-properties as "Position" for instance, we need a 
   gui string and an internal string, so that both 'could' be named/called "Position" but one uses gui_position to store it while the
   other uses libnoise_position

========================================================================
  DELEGATES, optimizing the QTreeView
========================================================================
- see 'Delegate Classes' in assistant, then create delegates for the module properties
- rethink the 'delegate' role of the QGraphicsItems which 'act' as delegates for my GraphicsView...
- if a property changes(a child), the parent (module) should get updated in the GraphicsScene
   SEE: void GraphicsScene::dataChanged(const QModelIndex&, const QModelIndex&)  FIXME: not implemented yet for PROPERTY 
- properties:
 - properties need an interface to be accessed via the model
 - property may be registered only once, fail with exit(1) on the second attempt!
 - properties should use type::int instead of "QString" as identifier - faster processing
- if setData did not work, because the validator discarded the value for any reason, the QStatusBar should be used to display why

- concept: see assistant, the QTreeView there is basically what i want to clone
  - QTreeView editor for pos should split QPoint up into x and y component as it is done in assistant. is that compilicated?

- fix this:
  MainWidget.cpp:
    //void QTreeView::setFirstColumnSpanned ( int row, const QModelIndex & parent, bool span )
    treeView->setFirstColumnSpanned(0, QModelIndex(), 1);
 -> but i want that be retrieved by data(..) but span is not used yet!

20:27 < qknight> i wonder how to set a QAbstractItemDelegate* for a single QModelIndex in a QTreeView
20:28 <+zbenjamin> !f delegate
20:28 < qtassistant> zbenjamin: [delegates] http://doc.trolltech.com/latest/model-view-introduction.html#delegates
20:28 <+zbenjamin> !rtfm setDelegate
20:28 < qtassistant> zbenjamin: Qt 4.6: QFileDialog Class Reference - QFileDialog::setItemDelegate - http://doc.qt.nokia.com/qfiledialog.html#setItemDelegate
20:28 < special> you can't.
20:28 <+zbenjamin> !rtfm QAbstractItemView::setDelegate
20:28 < special> you can set delegates for everything, for rows, or for columns, but not for individual indexes
20:28 < qtassistant> zbenjamin: Qt 4.6: QAbstractItemView Class Reference - QAbstractItemView::setItemDelegate - 
                     http://doc.qt.nokia.com/qabstractitemview.html#setItemDelegate
20:29 < special> and row/column are by integer, not by QModelIndex, so in a heirarchical model, they apply to *every* row 2
20:29 < special> seriously :|
20:29 <+zbenjamin> you can
20:29 <+zbenjamin> reimplement QAbstractItemDelegate * QAbstractItemView::itemDelegate ( const QModelIndex & index ) const
20:29 <+zbenjamin> argh its not virtual
20:29 <+zbenjamin> ok you cant
20:29 < special> I was about to be excited, that would be a perfect solution
20:30 <+zbenjamin> yeah :)
20:30 < special> damn you, binary compatibility.
20:30 <+zbenjamin> you could patch your own qt version if you ship it with your project :)
20:31 < special> except that you have to deal with the LGPL requirements
20:31 < qknight> so i could assign 'one' delegate for _all_ items. then within the context of that delegate i can find out about the type of the object and based on that i 
                 can change the backend used for that delegate? is that right?
20:31 < special> qknight: Yes. I've done that before.
20:32 < qknight> special, zbenjamin: thanks very much
20:32 < qknight> i think that is a good solution
20:32 < qknight> isn't qt doing that? using one delegate for all editing things (in the default setup)
20:33 <+zbenjamin> i was about to say the same
20:33 < qknight> hehe! thanks a lot!
20:33 <+zbenjamin> reimplement your own delegate and make the delegate change for every modelindex
20:34 <+zbenjamin> s/change/behave different

*yepee*
[1] http://qt.nokia.com/products/appdev/add-on-products/catalog/4/Widgets/qtpropertybrowser/

Q: how does [1] work?
A: all examples seem to have their own model implementation for their properties, which is: in short - "bad".
   one registers a QtGroupPropertyManager with various childs as:
    QtProperty *item0 = groupManager->addProperty("QObject");
   and these managers do have their own guis

   QtPointPropertyManager::setValue works like this:
    0. the data structure: typedef QMap<const QtProperty *, Data> PropertyValueMap;
    1. a property is probably unique as find is used on a ValueMap and the item found first is used and changed
    2. then two signals are fired: propertyChanged and valueChanged
   internally two m_intPropertyManager- are used

Q: why is this bad?
A: - this managers can't be used with my model (as they have their own data structure)
   - they use their own widgets, no QTreeView stuff

Q: which delegates does the 'srmg' require?
A: basically: 
   - float
   - int 
   - QPoint
   - QPointF
   - QStringDropdownList for GetNoiseQuality
   - QList<ControlPoint>

-> editors should be generated automatically based on the type given:
  - QTreeView will use delegates
  - GraphicsScene will provide it's own editor (a graphical modular approach)
  - QGraphicsItem's additional editor/view: doubleclicking will open a new QWidget with an appropriate view/editor:
    - libnoise-view                   mainly viewer, but also editor as it alters the module source position using transform
    - Modifier::Terrace controllPoint editor
    - Modifier::Curve   controllPoint editor
    - Spring::mapgen                  editor

Q: can i copy the delegates at least partially to use them with a QTreeView cell?
A:

Q: how to implement a delegate for a QTreeView at all?
A: current guess: one delegate is assigned to all cells, on certain cells the delegate changes it's representation.. somehow

Q: implementation of PropertyComponent, where int a, int b are two components of QPoint, is that complicated to write?
A: a DataItemType::PROPERTY needs to insert two childs both with an int delegate, that can be done in two ways:
   a) when inserting a property with setProperty("identifier", type);, the insert function uses type and adds two childs
   b) such an item knows that and adds two childs itself somehow?!








===========================================================================
   REFACTORING
===========================================================================
- check if all the in/mod/out put roles are needed in Model.cpp anymore 
- bug: if a module makes doubleuse of a outgoing port, one can NOT connect new connections to any input port of that module!
       however: if the second output usage is removed one can connect the input ports as expected, later the second output
                can be connected again...?!
       - this fails silently, create a debug message
       - this bug is in Model::insertConnection(..) for sure
       to reproduce:
       insert perlin p1; selector s1, selector s2; connect s1.out1 to s2.in1 and s1.out1 to s2.in2, then try to connect p1 to 
              s1.in1 and s2.put1 as well, will not work. will work if no double use of s1.out1 is made!
       FIX is: first find similar connections as (s1.out1 - s2.in1) AND (s1.out1 - s2.in2), and then only process one of these
       IMPORTANT: add a qDebug() statement why it does fail

- check the specification for QAbstractItemModel: 
 - Q: what must be implemented, is reset and layout changes mandatory?
   A: yes, this important, implement it!
      -> if someone uses load (not implemented yet) one can assign a new rootItem to the model. now reset needs to be called in order to make the
         view aware of the new data. reset is used as the data has fundamentally changed.
 - Q: does a Model have to know that a view is attached?
   A: no, but when removing the Model using ~Model it's better to have no view using that model anymore

- QTreeView did not show anything lately:
  see FilterProxyModel changes.
  this bug didn't show up before as DataItemType::ROOT was actually 0. but now it is not anymore!
  so i've added some code when having an invalid QModelIndex it simply retuns true...? and now it's working again...
  what special role did have a invalid QModelIndex have in a model?!
- FIXME: - have a look at Model::removeRows and Model::parent, there is some strange things going on, 
           especially with the handling of rootItem and QModelIndex()
         - the rootItem should return a valid QModelIndex() and rootItem->parent() should return QModelIndex()

- considering the next bug it would be wise to refactore DataAbstractItem to create new objects not using
       DataConnection* dc = new DataConnection( abstractItemA, abstractItemB );
   but instead do:
       DataPort* p; p->insertConnection( abstractItemA, abstractItemB );
   -> that way one could _NOT_ create dc objects externally
   -> DataConnection should register the object and the reference automatically
     -> also if the reference OR the connection is removed also the respectively object is removed 
- bug: 'virtual void DataPort::removeChild(unsigned int) this should not happen' does show up with this configuration:
  Billow::out0 - connection - select::modput0 
  then exit the program using alt+f4
 -> the problem is a cyclic dependency (not implemented) because calling removeReference must also remove the connection and vice versa
   WARNING: current fix is to disable the deletion of connections/references in DataPort::~DataPort() {

=================================================================================
  Model related: Adding, selecting, changing, removing of single/multiple items:
=================================================================================
- implement QSettings for QTreeView column width
    MainWidget::changeActiveDocument() -> replace by QSettings... treeView->setColumnWidth(0, 230);
- QTreeView: add tooltips -> Model::data()

========================================================================
  Fixing QGraphicsItem(s) and the behaviour of the QGraphicsView:
========================================================================
usability:
- hovering over an QGraphicsItem should:
 - highlight the entry in the 'list on the right'
 - highlight all used connections in a blinking fashion for 3 toggles
- selecting an QGraphicsItem should set a filter on the list on the right to only show selected items
- items in the list on the right should be sorted based on the view position on the screen
- hovering over an item in the list on the right should animate an QGraphisItem on the right
- item list on the right should have a string filter textbox
- middle click should drag the view as well as cursor keys
- QGraphicsItems should not have a QGraphicsView context menu
  - instead a menu covering: 
    - libnoiseview
    - libnoiseview3d

- fixme: when selecting an module, and while hoovering&moving it: delete it using 'del'-key. 
         the next item will instantly port to 'x,y=0,0', when moving it, using a drag'n'drop operation
         issue might be: when the item is removed, there is still some pos() thing going on and when the next item is moved it is
                         moved to the previous item's position, which is QVariant().toPoint(), so 0,0
- cubic_to may be hardware accelerated if i enable opengl in src/CMakeLists.txt as well as for the QGraphicsScene/*View
- Connection drawing could be nicer
 - drawing of the connection path: if x1 and x2 from the different coordinates are the same and y1 and y2 differ much then the
   path looks somehow broken. it should have a nice arc or bow like shape
 - z value tuning, should it be drawn behind a module?
- creating a connection currently is done clicking a port with a drag'n'drop operation:
  this should be changed: clicking once will change the mousecursor to a port draw operation cursor, next the line will always follow from
  the source port to the mouse cursor (basically what it does currently) until the next click which then checks if a valid port was clicked.
  this would enable connecting two ports which are not in the same view as the scene might be bigger than the current view port
- QStatusBar should receive messages, especially when loops are formed or connection attemps are done the wrong way
- creat 'visual indication' like a red ball behind the port to represent various PortType(s)
- also add a little 'x' button on the top right side of the module (similar to widgets)
- make items selectable with:
 - boundingbox selection
  - set bounding box selection using a modifier key, say ctrl
- clicking an item in the right list should focus the view of the graphicsscene over the respective item
- FIXME: insert modules at 'out of sight' will create strange view relocations...
         this happens when items (not connections) are inserted via Document.cpp
- QGraphicsItem(s) should be a QWidget (for module preview) so that one can scroll the view port of a noisegen right from there.
  + this would be cool as it would make editing much faster and more interactive
  + also resizing could be implemented, so one could increase the area which is viewed
- adding a connection (when no connection was added before whill relocate the view quite far away?!)
- using Document.cpp::Document()'s insertConnection will add scrollbars to the QGraphicsView... ;P
 - so i have to fix my QGraphicsView code once again
 - it's funny that clicking a item in the right side will now focus over the respecitive QGraphicsItem (didn't work before)
 - scrollbars should always be there
- softscroll to item instead of immediate focus
- fix regression: QTreeView modules can't be clicked to focus the QGraphicsView over it anymore
- implement singleselection:
  > if an item in the graphicsview is selected, the QTreeView should only show the respective properties of that item
  + if more items are selected, diplay all selected items
  + if no item is selected anymore, show all items in the QTreeView

GraphicsView:
 - zoomin/zoomout (mwheel or +/-) and zoomfit (gui button)
 - move selected items should 'move the view' if moved towards the border of the view (or beyond)
 - connection snapping, as indication when creating a new connection
 - modput needs some redesigning, see modules which use more than one modput: transformer::displace
 - scrollbars in GraphicsView are currently disabled by the resizeEvent(..) implementation, maybe
   they should indicated the document width()/height() and making it work might be by using
   POSSIBLE FIX: centerOn(..) or scroll(..)
 - when selecting a GraphicsItem using a click on the respecitive QTreeView item, the item should be animated for some time

========================================================================
  Timeline...
========================================================================
- integrate xml save/load functionality (add an object serializer to all nodes in the graph)
  - load+save viewport-position in document

- integrate libNoise-view (first refactore it)
- integrate spring map exporter (smf or s3m)
- concept: each item MUST be able to host one/many QWidget(s) as for instance: an editor or a libnoise-view

- integrate height-colorizer and height-texturizer
  the height-colorizer is easy to implement and gives a basic look&feel for the heightmap
  the height-texturizer is basically the same but instead of applying a color it inserts
  textures, the textures do have a fixed orientation. later this might be adapted to reflect
  the gradient of the landscape and other parameters as wind-pressure artefacts in sand dunes...

- new moduels which might be nice:
 - rain simulation (also known as erosion)
 - blur filter (imagemagick filters in general, if they are arch-independant say 32vs64bit should output
                the same image, the same goes for intel vs spark)

- think about cuda/openCL integration <---> libnoise or filtering

- create an icon for this project
- documentation: include a qwebkit browser with some html documentation about the modules

- integrate 3d viewer (adapted/copied from qtlobby)

- doxygen (adapt the libnoise-doc Doxygen script)

- FIX all TODO/FIXME/BUG lines

- official release of 'the source as package'