OpenWalnut  1.4.0
WGEColormapping.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WGECOLORMAPPING_H
26 #define WGECOLORMAPPING_H
27 
28 #include <map>
29 #include <string>
30 #include <algorithm>
31 #include <functional>
32 #include <vector>
33 
34 #ifndef Q_MOC_RUN
35 #include <boost/signals2/signal.hpp>
36 #endif
37 #ifndef Q_MOC_RUN
38 #include <boost/function.hpp>
39 #endif
40 
41 #include <osg/Node>
42 
43 #include "../common/WBoundingBox.h"
44 #include "../common/WSharedSequenceContainer.h"
45 #include "../common/WSharedAssociativeContainer.h"
46 
47 #include "callbacks/WGEFunctorCallback.h"
48 
49 #include "WGETexture.h"
50 #include "shaders/WGEShader.h"
51 
52 
53 /**
54  * Class implements a manager for multiple 3D textures. They can be applied to arbitrary osg::Node. This allows very comfortable use of dataset
55  * based colormapping. The only requirement is that your geometry/node needs to specify texture coordinates in Object Space. That means: the
56  * texture coordinates equal the regular 3D grid of the texture.
57  */
58 class WGEColormapping // NOLINT
59 {
60 public:
61  /**
62  * The alias for a shared container.
63  */
65 
66  /**
67  * Iterator to access the texture list.
68  */
70 
71  /**
72  * Const iterator to access the texture list.
73  */
75 
76  /**
77  * The type of handler used for being notified about added textures.
78  */
79  typedef boost::function< void ( osg::ref_ptr< WGETexture3D > ) > TextureRegisterHandler;
80 
81  /**
82  * The type of handler used for being notified about removed textures.
83  */
85 
86  /**
87  * The type of handler used for being notified about replaced textures.
88  */
89  typedef boost::function< void ( osg::ref_ptr< WGETexture3D >, osg::ref_ptr< WGETexture3D > ) > TextureReplaceHandler;
90 
91  /**
92  * The type of handler called whenever the texture list got resorted.
93  */
94  typedef boost::function< void ( void ) > TextureSortHandler;
95 
96  /**
97  * Destructor.
98  */
99  virtual ~WGEColormapping();
100 
101  /**
102  * Returns instance of the module factory to use to create modules.
103  *
104  * \return the running module factory.
105  */
106  static boost::shared_ptr< WGEColormapping > instance();
107 
108  /**
109  * a bunch of nodes.
110  */
111  typedef std::vector< osg::ref_ptr< osg::Node > > NodeList;
112 
113  /**
114  * Apply the colormapping to the specified node.
115  *
116  * \param node the node.
117  * \param shader the shader to use for colormapping. Provide your own shader here to let WGEColormap set some defines needed. If not
118  * specified, a default shader is used.
119  * \param preTransform Transformation matrix getting applied to your texture coordinates before applying texture matrices. This allows you to
120  * specify any kind of texture coordinates as long as you use this matrix to transform them to the right space.
121  * \param startTexUnit the first texture unit allowed to be used
122  */
123  static void apply( osg::ref_ptr< osg::Node > node, WMatrix4d preTransform = WMatrix4d::identity(),
124  osg::ref_ptr< WGEShader > shader = osg::ref_ptr< WGEShader >(), size_t startTexUnit = 0 );
125 
126  /**
127  * Apply the colormapping to a list of nodes using the same shader.
128  *
129  * \param nodes the node-list.
130  * \param shader the shader to use for colormapping. Provide your own shader here to let WGEColormap set some defines needed. If not
131  * specified, a default shader is used.
132  * \param preTransform Transformation matrix getting applied to your texture coordinates before applying texture matrices. This allows you to
133  * specify any kind of texture coordinates as long as you use this matrix to transform them to the right space.
134  * \param startTexUnit the first texture unit allowed to be used
135  */
136  static void apply( NodeList nodes, WMatrix4d preTransform = WMatrix4d::identity(),
137  osg::ref_ptr< WGEShader > shader = osg::ref_ptr< WGEShader >(), size_t startTexUnit = 0 );
138 
139  /**
140  * Apply the colormapping to the specified node.
141  *
142  * \param node the node.
143  * \param shader the shader to use for colormapping. Provide your own shader here to let WGEColormap set some defines needed. If not
144  * specified, a default shader is used.
145  * \param startTexUnit the first texture unit allowed to be used
146  */
147  static void apply( osg::ref_ptr< osg::Node > node, osg::ref_ptr< WGEShader > shader = osg::ref_ptr< WGEShader >(), size_t startTexUnit = 0 );
148 
149  /**
150  * Apply the colormapping to a list of nodes which all use the same shader.
151  *
152  * \param nodes the node list.
153  * \param shader the shader to use for colormapping. Provide your own shader here to let WGEColormap set some defines needed. If not
154  * specified, a default shader is used.
155  * \param startTexUnit the first texture unit allowed to be used
156  */
157  static void apply( NodeList nodes,
158  osg::ref_ptr< WGEShader > shader = osg::ref_ptr< WGEShader >(), size_t startTexUnit = 0 );
159 
160  /**
161  * Register the specified texture to the colormapper. The registered texture is the automatically applied to all users of WGEColormapping.
162  * The texture gets inserted at the beginning of the texture list.
163  *
164  * \param texture the texture to add
165  * \param name the name of the texture to add
166  */
167  static void registerTexture( osg::ref_ptr< WGETexture3D > texture, std::string name = "" );
168 
169  /**
170  * De-register the specified texture to the colormapper. The texture is the automatically removed from all users of WGEColormapping. If the
171  * texture is not in the list, nothing happens.
172  *
173  * \param texture the texture to remove
174  */
175  static void deregisterTexture( osg::ref_ptr< WGETexture3D > texture );
176 
177  /**
178  * Replaces the specified texture with the given new one. If the old texture does not exist, the new one gets inserted at the front of the
179  * list as \ref registerTexture does.
180  *
181  * \param old the texture to remove
182  * \param newTex the new texture to put at the position of the old one
183  * \param name the name of the texture.
184  */
185  static void replaceTexture( osg::ref_ptr< WGETexture3D > old, osg::ref_ptr< WGETexture3D > newTex, std::string name = "" );
186 
187  /**
188  * Resorts the texture list using the specified comparator.
189  *
190  * \tparam Comparator the comparator type. Usually a boost::function or class providing the operator().
191  * \param comp the comparator
192  */
193  template < typename Comparator >
194  void sort( Comparator comp );
195 
196  /**
197  * Resorts the texture list using the specified comparator using a stable sorting algorithm.
198  *
199  * \tparam Comparator the comparator type. Usually a boost::function or class providing the operator().
200  * \param comp the comparator
201  */
202  template < typename Comparator >
203  void stableSort( Comparator comp );
204 
205  /**
206  * Sort the texture list by the indices that have been stored in each texture's sortIndex.
207  */
208  void sortByIndex();
209 
210  /**
211  * This function sets the index of a texture in the list to this texture's WGETexture::sortIndex(). This can be used later using
212  * sortByIndex().
213  */
214  void setSortIndices();
215 
216  /**
217  * Reset all sort indices. This can be useful when loading new project files with new sort indices.
218  */
219  void resetSortIndices();
220 
221  /**
222  * Move the specified texture up in the list, directly to the top. Causes the sort signal to fire.
223  *
224  * \param texture the texture swapped with its ascendant
225  * \return true if swap was successful. False if not (texture not found, texture already at beginning).
226  */
227  bool moveToTop( osg::ref_ptr< WGETexture3D > texture );
228 
229  /**
230  * Move the specified texture down in the list, directly to the bottom. Causes the sort signal to fire.
231  *
232  * \param texture the texture swapped with its descendant
233  * \return true if swap was successful. False if not (texture not found, texture already at end).
234  */
235  bool moveToBottom( osg::ref_ptr< WGETexture3D > texture );
236 
237  /**
238  * Move the specified texture one item up in the list. Causes the sort signal to fire.
239  *
240  * \param texture the texture swapped with its ascendant
241  * \return true if swap was successful. False if not (texture not found, texture already at beginning).
242  */
243  bool moveUp( osg::ref_ptr< WGETexture3D > texture );
244 
245  /**
246  * Move the specified texture one item down in the list. Causes the sort signal to fire.
247  *
248  * \param texture the texture swapped with its descendant
249  *
250  * \return true if swap was successful. False if not (texture not found, texture already at end).
251  */
252  bool moveDown( osg::ref_ptr< WGETexture3D > texture );
253 
254  /**
255  * Move the texture to the specified index. If the texture is not in the list, nothing happens.
256  *
257  * \param texture the texture to move
258  * \param idx the target index
259  *
260  * \return true if the operation was successful.
261  */
262  bool moveTo( osg::ref_ptr< WGETexture3D > texture, size_t idx );
263 
264  /**
265  * Counts the number of textures in the colormapper.
266  *
267  * \return the number of textures.
268  */
269  size_t size() const;
270 
271  /**
272  * Possible signals that can be subscribed for being notified about texture list changes.
273  */
274  typedef enum
275  {
276  Registered = 0, //!< texture got added
277  Deregistered, //!< texture got removed
278  Replaced, //!< texture got replaced
279  Sorted //!< texture list was resorted
280  }
282 
283  /**
284  * Subscribe to the specified signal. See \ref TextureListSignal for details about their meaning.
285  *
286  * \param signal the signal to subscribe
287  * \param notifier the notifier
288  *
289  * \return the connection. Keep this and disconnect it properly!
290  */
291  boost::signals2::connection subscribeSignal( TextureListSignal signal, TextureRegisterHandler notifier );
292 
293  /**
294  * Subscribe to the specified signal. See \ref TextureListSignal for details about their meaning.
295  *
296  * \param signal the signal to subscribe
297  * \param notifier the notifier
298  *
299  * \return the connection. Keep this and disconnect it properly!
300  */
301  boost::signals2::connection subscribeSignal( TextureListSignal signal, TextureReplaceHandler notifier );
302 
303  /**
304  * Subscribe to the specified signal. See \ref TextureListSignal for details about their meaning.
305  *
306  * \param signal the signal to subscribe
307  * \param notifier the notifier
308  *
309  * \return the connection. Keep this and disconnect it properly!
310  */
311  boost::signals2::connection subscribeSignal( TextureListSignal signal, TextureSortHandler notifier );
312 
313  /**
314  * Returns a read ticket to the texture array. Useful to iterate the textures.
315  *
316  * \return the read ticket
317  */
319 
320  /**
321  * This returns the bounding box of all the data textures. This is very useful if you implement an universal color-mapped exploration tool.
322  * It returns a copy of the current bounding box. Please note that this can change any moment.
323  *
324  * \return the bounding box.
325  */
327 
328  /**
329  * Returns the condition firing if the texture list changes (sort, replace, add or remove). If you are interested in a certain event only,
330  * use \ref subscribeSignal.
331  *
332  * \return the change condition
333  */
335 
336 protected:
337  /**
338  * Default constructor.
339  */
340  WGEColormapping();
341 
342  /**
343  * Apply the colormapping to the specified nodes.
344  *
345  * \param nodes the nodes.
346  * \param preTransform Transformation matrix getting applied to your texture coordinates before applying texture matrices. This allows you to
347  * specify any kind of texture coordinates as long as you use this matrix to transform them to the right space.
348  * \param shader the shader to use for colormapping. Provide your own shader here to let WGEColormap set some defines needed. If not
349  * specified, a default shader is used.
350  * \param startTexUnit the first texture unit allowed to be used
351  */
352  void applyInst( NodeList nodes, WMatrix4d preTransform = WMatrix4d::identity(),
353  osg::ref_ptr< WGEShader > shader = osg::ref_ptr< WGEShader >(), size_t startTexUnit = 0 );
354 
355  /**
356  * Register the specified texture to the colormapper. The registered texture is the automatically applied to all users of WGEColormapping.
357  *
358  * \param texture the texture to add
359  * \param name the name of the texture.
360  */
361  void registerTextureInst( osg::ref_ptr< WGETexture3D > texture, std::string name );
362 
363  /**
364  * De-register the specified texture to the colormapper. The texture is the automatically removed from all users of WGEColormapping.
365  *
366  * \param texture the texture to remove
367  */
368  void deregisterTextureInst( osg::ref_ptr< WGETexture3D > texture );
369 
370  /**
371  * Replaces the specified texture with the given new one. If the old texture does not exist, the new one gets inserted at the front of the
372  * list as \ref registerTexture does.
373  *
374  * \param old the texture to remove
375  * \param newTex the new texture to put at the position of the old one
376  * \param name the name of the texture.
377  */
378  void replaceTextureInst( osg::ref_ptr< WGETexture3D > old, osg::ref_ptr< WGETexture3D > newTex, std::string name = "" );
379 
380  /**
381  * This callback handles all the updates needed. It is called by the callback instance every update cycle for each node using this
382  * WGEColormapping instance.
383  *
384  * \param node
385  */
386  void callback( osg::Node* node );
387 
388  /**
389  * Called whenever the texture list is updated.
390  */
391  void textureUpdate();
392 
393 private:
394  /**
395  * Singleton instance of WGEColormapping
396  */
397  static boost::shared_ptr< WGEColormapping > m_instance;
398 
399  /**
400  * The textures managed by this instance.
401  */
402  TextureContainerType m_textures;
403 
404  /**
405  * Simple structure to store some additional node-related info like texture units and so on.
406  */
407  struct NodeInfo
408  {
409  bool m_rebind; //!< true if the node has not been callback'ed before
410  size_t m_texUnitStart; //!< the start index of the texture unit to use
411  WMatrix4d m_preTransform; //!< matrix used for transforming arbitrary texture coordinates to the proper space.
412  };
413 
414  /**
415  * The alias for a shared container with a set of node-nodeInfo pairs
416  */
418 
419  /**
420  * This map is needed to keep track of several node specific settings
421  */
422  NodeInfoContainerType m_nodeInfo;
423 
424  /**
425  * Called whenever a texture got registered.
426  */
427  boost::signals2::signal< void( osg::ref_ptr< WGETexture3D > ) > m_registerSignal;
428 
429  /**
430  * Called whenever a texture got removed.
431  */
432  boost::signals2::signal< void( osg::ref_ptr< WGETexture3D > ) > m_deregisterSignal;
433 
434  /**
435  * Called whenever a texture got replaced.
436  */
437  boost::signals2::signal< void( osg::ref_ptr< WGETexture3D >, osg::ref_ptr< WGETexture3D > ) > m_replaceSignal;
438 
439  /**
440  * Called whenever the texture list got resorted
441  */
442  boost::signals2::signal< void( void ) > m_sortSignal;
443 
444  /**
445  * The bounding box of all the textures.
446  */
448 
449  /**
450  * Updates the bounding box information. This is called for every write-update in m_textures.
451  */
452  void updateBounds();
453 };
454 
455 template < typename Comparator >
456 void WGEColormapping::sort( Comparator comp )
457 {
458  m_textures.sort< Comparator >( comp );
459 }
460 
461 template < typename Comparator >
462 void WGEColormapping::stableSort( Comparator comp )
463 {
464  m_textures.stableSort< Comparator >( comp );
465 }
466 
467 #endif // WGECOLORMAPPING_H
468 
TextureContainerType::Iterator TextureIterator
Iterator to access the texture list.
bool moveUp(osg::ref_ptr< WGETexture3D > texture)
Move the specified texture one item up in the list.
TextureContainerType m_textures
The textures managed by this instance.
void sort(Comparator comp)
Resorts the texture list using the specified comparator.
WGEColormapping()
Default constructor.
static void registerTexture(osg::ref_ptr< WGETexture3D > texture, std::string name="")
Register the specified texture to the colormapper.
size_t size() const
Counts the number of textures in the colormapper.
boost::function< void(void) > TextureSortHandler
The type of handler called whenever the texture list got resorted.
void sort(Comparator comp)
Resorts the container using the specified comparator from its begin to its end.
TextureRegisterHandler TextureDeregisterHandler
The type of handler used for being notified about removed textures.
void deregisterTextureInst(osg::ref_ptr< WGETexture3D > texture)
De-register the specified texture to the colormapper.
This class provides a common interface for thread-safe access to sequence containers (list...
size_t m_texUnitStart
the start index of the texture unit to use
static void deregisterTexture(osg::ref_ptr< WGETexture3D > texture)
De-register the specified texture to the colormapper.
boost::function< void(osg::ref_ptr< WGETexture3D >, osg::ref_ptr< WGETexture3D >) > TextureReplaceHandler
The type of handler used for being notified about replaced textures.
void stableSort(Comparator comp)
Resorts the texture list using the specified comparator using a stable sorting algorithm.
void sortByIndex()
Sort the texture list by the indices that have been stored in each texture's sortIndex.
void registerTextureInst(osg::ref_ptr< WGETexture3D > texture, std::string name)
Register the specified texture to the colormapper.
void callback(osg::Node *node)
This callback handles all the updates needed.
boost::signals2::connection subscribeSignal(TextureListSignal signal, TextureRegisterHandler notifier)
Subscribe to the specified signal.
WCondition::SPtr getChangeCondition() const
Returns the condition firing if the texture list changes (sort, replace, add or remove).
NodeInfoContainerType m_nodeInfo
This map is needed to keep track of several node specific settings.
WSharedObject< WBoundingBox > m_boundingBox
The bounding box of all the textures.
std::vector< osg::ref_ptr< WGETexture3D > >::const_iterator ConstIterator
A typedef for the correct const iterator useful to traverse this sequence container.
TextureContainerType::ConstIterator TextureConstIterator
Const iterator to access the texture list.
boost::signals2::signal< void(void) > m_sortSignal
Called whenever the texture list got resorted.
Simple structure to store some additional node-related info like texture units and so on...
texture list was resorted
boost::signals2::signal< void(osg::ref_ptr< WGETexture3D >) > m_deregisterSignal
Called whenever a texture got removed.
bool moveDown(osg::ref_ptr< WGETexture3D > texture)
Move the specified texture one item down in the list.
virtual ~WGEColormapping()
Destructor.
static void replaceTexture(osg::ref_ptr< WGETexture3D > old, osg::ref_ptr< WGETexture3D > newTex, std::string name="")
Replaces the specified texture with the given new one.
WMatrix4d m_preTransform
matrix used for transforming arbitrary texture coordinates to the proper space.
void textureUpdate()
Called whenever the texture list is updated.
Wrapper around an object/type for thread safe sharing of objects among multiple threads.
Definition: WSharedObject.h:43
TextureContainerType::ReadTicket getReadTicket()
Returns a read ticket to the texture array.
static boost::shared_ptr< WGEColormapping > instance()
Returns instance of the module factory to use to create modules.
static MatrixType identity()
Returns an identity matrix.
Definition: WMatrixFixed.h:314
bool m_rebind
true if the node has not been callback'ed before
WBoundingBox getBoundingBox() const
This returns the bounding box of all the data textures.
boost::signals2::signal< void(osg::ref_ptr< WGETexture3D >, osg::ref_ptr< WGETexture3D >) > m_replaceSignal
Called whenever a texture got replaced.
bool moveToTop(osg::ref_ptr< WGETexture3D > texture)
Move the specified texture up in the list, directly to the top.
void resetSortIndices()
Reset all sort indices.
std::vector< osg::ref_ptr< osg::Node > > NodeList
a bunch of nodes.
This class provides a common interface for thread-safe access to associative containers (set...
void setSortIndices()
This function sets the index of a texture in the list to this texture's WGETexture::sortIndex().
Class implements a manager for multiple 3D textures.
void replaceTextureInst(osg::ref_ptr< WGETexture3D > old, osg::ref_ptr< WGETexture3D > newTex, std::string name="")
Replaces the specified texture with the given new one.
static void apply(osg::ref_ptr< osg::Node > node, WMatrix4d preTransform=WMatrix4d::identity(), osg::ref_ptr< WGEShader > shader=osg::ref_ptr< WGEShader >(), size_t startTexUnit=0)
Apply the colormapping to the specified node.
void updateBounds()
Updates the bounding box information.
WSharedSequenceContainer< std::vector< osg::ref_ptr< WGETexture3D > > > TextureContainerType
The alias for a shared container.
boost::function< void(osg::ref_ptr< WGETexture3D >) > TextureRegisterHandler
The type of handler used for being notified about added textures.
boost::shared_ptr< WCondition > SPtr
Shared pointer type for WCondition.
Definition: WCondition.h:54
void applyInst(NodeList nodes, WMatrix4d preTransform=WMatrix4d::identity(), osg::ref_ptr< WGEShader > shader=osg::ref_ptr< WGEShader >(), size_t startTexUnit=0)
Apply the colormapping to the specified nodes.
std::vector< osg::ref_ptr< WGETexture3D > >::iterator Iterator
A typedef for the correct iterator to traverse this sequence container.
boost::shared_ptr< WSharedObjectTicketRead< std::vector< osg::ref_ptr< WGETexture3D > > > > ReadTicket
Type for read tickets.
Definition: WSharedObject.h:64
static boost::shared_ptr< WGEColormapping > m_instance
Singleton instance of WGEColormapping.
WSharedAssociativeContainer< std::map< osg::Node *, NodeInfo *, std::less< osg::Node * > > > NodeInfoContainerType
The alias for a shared container with a set of node-nodeInfo pairs.
bool moveToBottom(osg::ref_ptr< WGETexture3D > texture)
Move the specified texture down in the list, directly to the bottom.
bool moveTo(osg::ref_ptr< WGETexture3D > texture, size_t idx)
Move the texture to the specified index.
texture got replaced
void stableSort(Comparator comp)
Resorts the container using the specified comparator from its begin to its end.
boost::signals2::signal< void(osg::ref_ptr< WGETexture3D >) > m_registerSignal
Called whenever a texture got registered.
TextureListSignal
Possible signals that can be subscribed for being notified about texture list changes.