Main MRPT website > C++ reference for MRPT 1.3.2
CDisplayWindow3D.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2015, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 #ifndef CDisplayWindow3D_H
10 #define CDisplayWindow3D_H
11 
16 #include <mrpt/utils/CImage.h>
17 
18 /*---------------------------------------------------------------
19  Class
20  ---------------------------------------------------------------*/
21 namespace mrpt
22 {
23  namespace gui
24  {
25  class C3DWindowDialog;
26  class CMyGLCanvas_DisplayWindow3D;
27 
29 
30  /** A graphical user interface (GUI) for efficiently rendering 3D scenes in real-time.
31  * This class always contains internally an instance of opengl::COpenGLScene, which
32  * the objects, viewports, etc. to be rendered.
33  *
34  * Images can be grabbed automatically to disk for easy creation of videos.
35  * See CDisplayWindow3D::grabImagesStart (and for creating videos, mrpt::vision::CVideoFileWriter).
36  *
37  * A short-cut for displaying 2D images (using the OpenGL rendering hardware) is available
38  * through \a setImageView() and \a setImageView_fast(). Internally, these methods call methods
39  * in the "main" viewport of the window (see \a COpenGLViewport).
40  *
41  * Since the 3D rendering is performed in a detached thread, especial care must be taken
42  * when updating the 3D scene to be rendered. The process involves an internal critical section
43  * and it must always consist of these steps:
44  *
45  * \code
46  * CDisplayWindow3D win("My window");
47  *
48  * // Adquire the scene:
49  * opengl::COpenGLScenePtr &ptrScene = win.get3DSceneAndLock();
50  *
51  * // Modify the scene:
52  * ptrScene->...
53  * // or replace by another scene:
54  * ptrScene = otherScene;
55  *
56  * // Unlock it, so the window can use it for redraw:
57  * win.unlockAccess3DScene();
58  *
59  * // Update window, if required
60  * win.forceRepaint();
61  * \endcode
62  *
63  * An alternative way of updating the scene is by creating, before locking the 3D window, a new object
64  * of class COpenGLScene, then locking the window only for replacing the smart pointer. This may be
65  * advantageous is generating the 3D scene takes a long time, since while the window
66  * is locked it will not be responsive to the user input or window redraw.
67  *
68  * The window can also display a set of 2D text messages overlapped to the 3D scene.
69  * See CDisplayWindow3D::addTextMessage
70  *
71  * For a list of supported events with the observer/observable pattern, see the discussion in mrpt::gui::CBaseGUIWindow.
72  * In addition to those events, this class introduces mrpt::gui::mrptEvent3DWindowGrabImageFile
73  *
74  *
75  * \sa The example /samples/display3D, the <a href="http://www.mrpt.org/Tutorial_3D_Scenes" > tutorial only</a>.
76  * \ingroup mrpt_gui_grp
77  */
79  {
80  // This must be added to any CObject derived class:
82 
83  protected:
84  friend class C3DWindowDialog;
85  friend class CMyGLCanvas_DisplayWindow3D;
86  /** Internal OpenGL object (see general discussion in about usage of this object)
87  */
88  opengl::COpenGLScenePtr m_3Dscene;
89 
90  /** Critical section for accesing m_3Dscene
91  */
92  synch::CCriticalSection m_csAccess3DScene;
93 
94  /** Throws an exception on initialization error
95  */
96  void createOpenGLContext();
97 
98  mrpt::utils::void_ptr_noncopy m_DisplayDeviceContext;
99  mrpt::utils::void_ptr_noncopy m_GLRenderingContext;
100 
101  std::string m_grab_imgs_prefix;
102  unsigned int m_grab_imgs_idx;
103 
104  bool m_is_capturing_imgs;
105  mrpt::utils::CImagePtr m_last_captured_img;
106  synch::CCriticalSection m_last_captured_img_cs;
107 
108  void doRender();
109 
110  mrpt::system::TTimeStamp m_lastFullScreen;
111 
112  double m_last_FPS; //!< \sa getRenderingFPS
113 
114  void internalSetMinMaxRange();
115 
116  public:
117  /** Constructor
118  */
120  const std::string &windowCaption = std::string(),
121  unsigned int initialWindowWidth = 400,
122  unsigned int initialWindowHeight = 300 );
123 
124  /** Class factory returning a smart pointer */
125  static CDisplayWindow3DPtr Create(
126  const std::string &windowCaption,
127  unsigned int initialWindowWidth = 400,
128  unsigned int initialWindowHeight = 300 );
129 
130  /** Destructor
131  */
132  virtual ~CDisplayWindow3D();
133 
134  /** Gets a reference to the smart shared pointer that holds the internal scene (carefuly read introduction in gui::CDisplayWindow3D before use!)
135  * This also locks the critical section for accesing the scene, thus the window will not be repainted until it is unlocked.
136  */
137  opengl::COpenGLScenePtr & get3DSceneAndLock( );
138 
139  /** Unlocks the access to the internal 3D scene.
140  * Typically user will want to call forceRepaint after updating the scene.
141  */
142  void unlockAccess3DScene();
143 
144  /** Repaints the window.
145  * forceRepaint, repaint and updateWindow are all aliases of the same method.
146  */
147  void forceRepaint();
148 
149  /** Repaints the window.
150  * forceRepaint, repaint and updateWindow are all aliases of the same method.
151  */
152  void repaint() { forceRepaint(); }
153 
154  /** Repaints the window.
155  * forceRepaint, repaint and updateWindow are all aliases of the same method.
156  */
157  void updateWindow() { forceRepaint(); }
158 
159  /** Return the camera field of view (in degrees) (used for gluPerspective). */
160  float getFOV() const;
161 
162  /** Changes the camera min clip range (z) (used for gluPerspective).
163  * The window is not updated with this method, call "forceRepaint" to update the 3D view.
164  */
165  void setMinRange(double new_min);
166 
167  /** Changes the camera max clip range (z) (used for gluPerspective).
168  * The window is not updated with this method, call "forceRepaint" to update the 3D view.
169  */
170  void setMaxRange(double new_max);
171 
172  /** Changes the camera field of view (in degrees) (used for gluPerspective).
173  * The window is not updated with this method, call "forceRepaint" to update the 3D view.
174  */
175  void setFOV(float v);
176 
177  /** Resizes the window, stretching the image to fit into the display area.
178  */
179  void resize( unsigned int width, unsigned int height );
180 
181  /** Changes the position of the window on the screen.
182  */
183  void setPos( int x, int y );
184 
185  /** Changes the window title.
186  */
187  void setWindowTitle( const std::string &str );
188 
189  /** Changes the camera parameters programatically
190  */
191  void setCameraElevationDeg( float deg );
192 
193  /** Changes the camera parameters programatically
194  */
195  void setCameraAzimuthDeg( float deg );
196 
197  /** Changes the camera parameters programatically
198  */
199  void setCameraPointingToPoint( float x,float y, float z );
200 
201  /** Changes the camera parameters programatically
202  */
203  void setCameraZoom( float zoom );
204 
205  /** Sets the camera as projective, or orthogonal. */
206  void setCameraProjective( bool isProjective );
207 
208 
209  /** Get camera parameters programatically */
210  float getCameraElevationDeg() const;
211 
212  /** Get camera parameters programatically */
213  float getCameraAzimuthDeg() const;
214 
215  /** Get camera parameters programatically */
216  void getCameraPointingToPoint( float &x,float &y, float &z ) const;
217 
218  /** Get camera parameters programatically */
219  float getCameraZoom() const;
220 
221  /** Sets the camera as projective, or orthogonal. */
222  bool isCameraProjective() const;
223 
224  /** If set to true (default = false), the mouse-based scene navigation will be disabled and the camera position will be determined by the opengl viewports in the 3D scene.
225  */
226  void useCameraFromScene(bool useIt = true);
227 
228  /** Gets the 3D ray for the direction line of the pixel where the mouse cursor is at. \return False if the window is closed. \sa getLastMousePosition */
229  bool getLastMousePositionRay(mrpt::math::TLine3D &ray) const;
230 
231  /** Gets the last x,y pixel coordinates of the mouse. \return False if the window is closed. \sa getLastMousePositionRay */
232  virtual bool getLastMousePosition(int &x, int &y) const;
233 
234  /** Set cursor style to default (cursorIsCross=false) or to a cross (cursorIsCross=true) \sa getLastMousePositionRay */
235  virtual void setCursorCross(bool cursorIsCross);
236 
237  /** Start to save rendered images to disk.
238  * Images will be saved independently as png files, depending on
239  * the template path passed to this method. For example:
240  *
241  * path_prefix: "./video_"
242  *
243  * Will generate "./video_000001.png", etc.
244  *
245  * If this feature is enabled, the window will emit events of the type mrpt::gui::mrptEvent3DWindowGrabImageFile() which you can subscribe to.
246  *
247  * \sa grabImagesStop
248  */
249  void grabImagesStart( const std::string &grab_imgs_prefix = std::string("video_") );
250 
251  /** Stops image grabbing started by grabImagesStart
252  * \sa grabImagesStart
253  */
254  void grabImagesStop();
255 
256  /** Enables the grabbing of CImage objects from screenshots of the window.
257  * \sa getLastWindowImage
258  */
259  void captureImagesStart();
260 
261  /** Stop image grabbing
262  * \sa captureImagesStart
263  */
264  void captureImagesStop();
265 
266  /** Retrieve the last captured image from the window.
267  * You MUST CALL FIRST captureImagesStart to enable image grabbing.
268  * \return false if there was no time yet for grabbing any image (then, the output image is undefined).
269  * \sa captureImagesStart, getLastWindowImagePtr
270  */
271  bool getLastWindowImage( mrpt::utils::CImage &out_img) const;
272 
273  /** Retrieve the last captured image from the window, as a smart pointer.
274  * This method is more efficient than getLastWindowImage since only a copy of the pointer is performed, while
275  * getLastWindowImage would copy the entire image.
276  *
277  * You MUST CALL FIRST captureImagesStart to enable image grabbing.
278  * \Note If there was no time yet for grabbing any image, an empty smart pointer will be returned.
279  * \sa captureImagesStart, getLastWindowImage
280  */
281  mrpt::utils::CImagePtr getLastWindowImagePtr() const;
282 
283  /** Increments by one the image counter and return the next image file name (Users normally don't want to call this method).
284  * \sa grabImagesStart
285  */
286  std::string grabImageGetNextFile();
287 
288  bool isCapturingImgs() const { return m_is_capturing_imgs; }
289 
290 
291  /** Add 2D text messages overlapped to the 3D rendered scene. The string will remain displayed in the 3D window
292  * until it's changed with subsequent calls to this same method, or all the texts are cleared with clearTextMessages().
293  *
294  * \param x The X position, interpreted as absolute pixels from the left if X>=1, absolute pixels from the left if X<0 or as a width factor if in the range [0,1[.
295  * \param y The Y position, interpreted as absolute pixels from the bottom if Y>=1, absolute pixels from the top if Y<0 or as a height factor if in the range [0,1[.
296  * \param text The text string to display.
297  * \param color The text color. For example: TColorf(1.0,1.0,1.0)
298  * \param unique_index An "index" for this text message, so that subsequent calls with the same index will overwrite this text message instead of creating new ones.
299  *
300  * You'll need to refresh the display manually with forceRepaint().
301  *
302  * \sa clearTextMessages
303  */
304  void addTextMessage(
305  const double x,
306  const double y,
307  const std::string &text,
308  const mrpt::utils::TColorf &color = mrpt::utils::TColorf(1.0,1.0,1.0),
309  const size_t unique_index = 0,
311  );
312 
313  /** \overload with more font parameters - refer to mrpt::opengl::gl_utils::glDrawText()
314  * Available fonts are enumerated at mrpt::opengl::gl_utils::glSetFont() */
315  void addTextMessage(
316  const double x_frac,
317  const double y_frac,
318  const std::string &text,
319  const mrpt::utils::TColorf &color,
320  const std::string &font_name,
321  const double font_size,
323  const size_t unique_index = 0,
324  const double font_spacing = 1.5,
325  const double font_kerning = 0.1,
326  const bool draw_shadow = false,
327  const mrpt::utils::TColorf &shadow_color = mrpt::utils::TColorf(0,0,0)
328  );
329 
330  /** Clear all text messages created with addTextMessage().
331  * You'll need to refresh the display manually with forceRepaint().
332  * \sa addTextMessage
333  */
334  void clearTextMessages();
335 
336  /** Get the average Frames Per Second (FPS) value from the last 250 rendering events */
337  double getRenderingFPS() const { return m_last_FPS; }
338 
339  /** A short cut for getting the "main" viewport of the scene object, it is equivalent to:
340  * \code
341  * mrpt::opengl::COpenGLScenePtr &scene = win3D.get3DSceneAndLock();
342  * viewport = scene->getViewport("main");
343  * win3D.unlockAccess3DScene();
344  * \endcode
345  */
346  mrpt::opengl::COpenGLViewportPtr getDefaultViewport();
347 
348  /** Set the "main" viewport into "image view"-mode, where an image is efficiently drawn (fitting the viewport area) using an OpenGL textured quad.
349  * Call this method with the new image to update the displayed image (but recall to first lock the parent openglscene's critical section, then do the update, then release the lock, and then issue a window repaint).
350  * Internally, the texture is drawn using a mrpt::opengl::CTexturedPlane
351  * The viewport can be reverted to behave like a normal viewport by calling setNormalMode()
352  * \sa setImageView_fast, COpenGLViewport
353  */
354  void setImageView(const mrpt::utils::CImage &img);
355 
356  /** Just like \a setImageView but moves the internal image memory instead of making a copy, so it's faster but empties the input image.
357  * \sa setImageView, COpenGLViewport
358  */
359  void setImageView_fast(mrpt::utils::CImage &img);
360 
361 
362  protected:
363  void internal_setRenderingFPS(double FPS); //!< Set the rendering FPS (users don't call this, the method is for internal MRPT objects only) \sa getRenderingFPS
364  void internal_emitGrabImageEvent(const std::string &fil); //!< called by CMyGLCanvas_DisplayWindow3D::OnPostRenderSwapBuffers
365 
366  }; // End of class def.
368 
369 
370  /** @name Events specific to CDisplayWindow3D
371  @{ */
372 
373  /** An event sent by a CDisplayWindow3D window when an image is saved after enabling this feature with CDisplayWindow3D::grabImagesStart()
374  *
375  * IMPORTANTE NOTICE: Event handlers in your observer class will be invoked from the wxWidgets internal MRPT thread,
376  * so all your code in the handler must be thread safe.
377  */
378  class GUI_IMPEXP mrptEvent3DWindowGrabImageFile : public mrpt::utils::mrptEvent
379  {
380  protected:
381  virtual void do_nothing() { } //!< Just to allow this class to be polymorphic
382  public:
384  CDisplayWindow3D *obj,
385  const std::string &_img_file
386  ) : source_object(obj), img_file(_img_file) { }
387 
389  const std::string &img_file; //!< The absolute path of the file that has been just saved.
390  }; // End of class def.
391 
392  /** @} */
393 
394 
395  } // End of namespace
396 } // End of namespace
397 
398 #endif
uint64_t TTimeStamp
A system independent time type, it holds the the number of 100-nanosecond intervals since January 1...
Definition: datetime.h:30
An event sent by a CDisplayWindow3D window when an image is saved after enabling this feature with CD...
A class for storing images as grayscale or RGB bitmaps.
Definition: CImage.h:101
STL namespace.
const std::string & img_file
The absolute path of the file that has been just saved.
TOpenGLFont
Existing fonts for 2D texts in mrpt::opengl methods.
Definition: opengl_fonts.h:26
TOpenGLFontStyle
Different style for vectorized font rendering.
Definition: opengl_fonts.h:37
#define DEFINE_MRPT_OBJECT(class_name)
This declaration must be inserted in all CObject classes definition, within the class declaration...
Definition: CObject.h:167
#define DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_)
Definition: CObject.h:172
double getRenderingFPS() const
Get the average Frames Per Second (FPS) value from the last 250 rendering events. ...
#define DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_)
Definition: CObject.h:171
non_copiable_ptr_basic< void > void_ptr_noncopy
mrptEvent3DWindowGrabImageFile(CDisplayWindow3D *obj, const std::string &_img_file)
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
renders glyphs filled with antialiased outlines
Definition: opengl_fonts.h:40
A RGB color - floats in the range [0,1].
Definition: TColor.h:52
void updateWindow()
Repaints the window.
virtual void do_nothing()
Just to allow this class to be polymorphic.
The base class for GUI window classes.
A graphical user interface (GUI) for efficiently rendering 3D scenes in real-time.
3D line, represented by a base point and a director vector.



Page generated by Doxygen 1.8.11 for MRPT 1.3.2 SVN:Unversioned directory at Sun May 1 08:45:24 UTC 2016