class mrpt::gui::CDisplayWindow3D
Overview
A graphical user interface (GUI) for efficiently rendering 3D scenes in real-time.
This class always contains internally an instance of opengl::Scene, which the objects, viewports, etc. to be rendered.
Images can be grabbed automatically to disk for easy creation of videos. See CDisplayWindow3D::grabImagesStart (and for creating videos, mrpt::vision::CVideoFileWriter).
A short-cut for displaying 2D images (using the OpenGL rendering hardware) is available through setImageView(). Internally, these methods call methods in the “main” viewport of the window (see Viewport).
Since the 3D rendering is performed in a detached thread, especial care must be taken when updating the 3D scene to be rendered. The process involves an internal critical section and it must always consist of these steps:
mrpt::gui::CDisplayWindow3D win("My window"); // Adquire the scene: mrpt::opengl::Scene::Ptr &ptrScene = win.get3DSceneAndLock(); // Modify the scene: ptrScene->... // or replace by another scene: ptrScene = otherScene; // Unlock it, so the window can use it for redraw: win.unlockAccess3DScene(); // Update window, if required win.forceRepaint();
An alternative way of updating the scene is by creating, before locking the 3D window, a new object of class Scene, then locking the window only for replacing the smart pointer. This may be advantageous is generating the 3D scene takes a long time, since while the window is locked it will not be responsive to the user input or window redraw.
It is safer against exceptions to use the auxiliary class CDisplayWindow3DLocker.
mrpt::gui::CDisplayWindow3D win("My window"); // ... { // The scene is adquired in this scope mrpt::opengl::Scene::Ptr ptrScene; mrpt::gui::CDisplayWindow3DLocker locker(win,ptrScene); //... // Either: // - modify ptrScene // - Or assign it a prebuilt object with: *ptrScene = *otherScene; } // scene is unlocked upon dtor of `locker`
Notice however that a copy of the smart pointer is made, so replacement of the entire scene via operator = is not possible if using this method. Instead, the content of the scene should be assigned using the operator = of the dereferenced object as illustrated with the *ptrScene = *otherScene; above.
The window can also display a set of 2D text messages overlapped to the 3D scene. See CDisplayWindow3D::addTextMessage
For a list of supported events with the observer/observable pattern, see the discussion in mrpt::gui::CBaseGUIWindow. In addition to those events, this class introduces mrpt::gui::mrptEvent3DWindowGrabImageFile
CDisplayWindow3D mouse view navigation cheatsheet
See also:
#include <mrpt/gui/CDisplayWindow3D.h> class CDisplayWindow3D: public mrpt::gui::CBaseGUIWindow { public: // typedefs typedef std::shared_ptr<CDisplayWindow3D> Ptr; typedef std::shared_ptr<const CDisplayWindow3D> ConstPtr; // construction CDisplayWindow3D( const std::string& windowCaption = std::string(), unsigned int initialWindowWidth = 400, unsigned int initialWindowHeight = 300 ); // methods mrpt::opengl::Scene::Ptr& get3DSceneAndLock(); void unlockAccess3DScene(); void forceRepaint(); void repaint(); void updateWindow(); float getFOV() const; void setMinRange(float new_min); void setMaxRange(float new_max); void setFOV(float v); virtual void resize(unsigned int width, unsigned int height); virtual void setPos(int x, int y); virtual void setWindowTitle(const std::string& str); void setCameraElevationDeg(float deg); void setCameraAzimuthDeg(float deg); void setCameraPointingToPoint(float x, float y, float z); void setCameraZoom(float zoom); void setCameraProjective(bool isProjective); float getCameraElevationDeg() const; float getCameraAzimuthDeg() const; void getCameraPointingToPoint(float& x, float& y, float& z) const; float getCameraZoom() const; bool isCameraProjective() const; void useCameraFromScene(bool useIt = true); bool getLastMousePositionRay(mrpt::math::TLine3D& ray) const; virtual bool getLastMousePosition(int& x, int& y) const; virtual void setCursorCross(bool cursorIsCross); void grabImagesStart(const std::string& grab_imgs_prefix = std::string("video_")); void grabImagesStop(); void captureImagesStart(); void captureImagesStop(); bool getLastWindowImage(mrpt::img::CImage& out_img) const; mrpt::img::CImage::Ptr getLastWindowImagePtr() const; std::string grabImageGetNextFile(); bool isCapturingImgs() const; void addTextMessage( const double x_frac, const double y_frac, const std::string& text, size_t unique_index = 0, const mrpt::opengl::TFontParams& fontParams = mrpt::opengl::TFontParams() ); void clearTextMessages(); bool updateTextMessage(const size_t unique_index, const std::string& text); double getRenderingFPS() const; mrpt::opengl::Viewport::Ptr getDefaultViewport(); void setImageView(const mrpt::img::CImage& img); void setImageView(mrpt::img::CImage&& img); void sendFunctionToRunOnGUIThread(const std::function<void(void)>& f); bool is_GL_context_created() const; bool wait_for_GL_context(const double timeout_seconds = 1.0) const; static CDisplayWindow3D::Ptr Create( const std::string& windowCaption, unsigned int initialWindowWidth = 400, unsigned int initialWindowHeight = 300 ); };
Inherited Members
public: // methods void* getWxObject(); void notifyChildWindowDestruction(); void notifySemThreadReady(); bool isOpen(); virtual void resize(unsigned int width, unsigned int height) = 0; virtual void setPos(int x, int y) = 0; virtual void setWindowTitle(const std::string& str) = 0; virtual bool getLastMousePosition(int& x, int& y) const = 0; virtual void setCursorCross(bool cursorIsCross) = 0; int waitForKey(bool ignoreControlKeys = true, mrptKeyModifier* out_pushModifier = nullptr); bool keyHit() const; void clearKeyHitFlag(); int getPushedKey(mrptKeyModifier* out_pushModifier = nullptr);
Construction
CDisplayWindow3D( const std::string& windowCaption = std::string(), unsigned int initialWindowWidth = 400, unsigned int initialWindowHeight = 300 )
Constructor.
Methods
mrpt::opengl::Scene::Ptr& get3DSceneAndLock()
Gets a reference to the smart shared pointer that holds the internal scene (carefully read introduction in gui::CDisplayWindow3D before use!) This also locks the critical section for accessing the scene, thus the window will not be repainted until it is unlocked.
It is safer to use mrpt::gui::CDisplayWindow3DLocker instead.
void unlockAccess3DScene()
Unlocks the access to the internal 3D scene.
It is safer to use mrpt::gui::CDisplayWindow3DLocker instead. Typically user will want to call forceRepaint after updating the scene.
void forceRepaint()
Repaints the window.
forceRepaint, repaint and updateWindow are all aliases of the same method
void repaint()
Repaints the window.
forceRepaint, repaint and updateWindow are all aliases of the same method
void updateWindow()
Repaints the window.
forceRepaint, repaint and updateWindow are all aliases of the same method
float getFOV() const
Return the camera field of view (in degrees) (used for gluPerspective)
void setMinRange(float new_min)
Changes the camera min clip range (z) (used for gluPerspective).
The window is not updated with this method, call “forceRepaint” to update the 3D view.
void setMaxRange(float new_max)
Changes the camera max clip range (z) (used for gluPerspective.
The window is not updated with this method, call “forceRepaint” to update the 3D view.
void setFOV(float v)
Changes the camera field of view (in degrees) (used for gluPerspective).
The window is not updated with this method, call “forceRepaint” to update the 3D view.
virtual void resize(unsigned int width, unsigned int height)
Resizes the window, stretching the image to fit into the display area.
virtual void setPos(int x, int y)
Changes the position of the window on the screen.
virtual void setWindowTitle(const std::string& str)
Changes the window title.
void setCameraElevationDeg(float deg)
Changes the camera parameters programmatically.
void setCameraAzimuthDeg(float deg)
Changes the camera parameters programmatically.
void setCameraPointingToPoint(float x, float y, float z)
Changes the camera parameters programmatically.
void setCameraZoom(float zoom)
Changes the camera parameters programmatically.
void setCameraProjective(bool isProjective)
Sets the camera as projective, or orthogonal.
float getCameraElevationDeg() const
Get camera parameters programmatically.
float getCameraAzimuthDeg() const
Get camera parameters programmatically.
void getCameraPointingToPoint(float& x, float& y, float& z) const
Get camera parameters programmatically.
float getCameraZoom() const
Get camera parameters programmatically.
bool isCameraProjective() const
Sets the camera as projective, or orthogonal.
void useCameraFromScene(bool useIt = true)
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.
bool getLastMousePositionRay(mrpt::math::TLine3D& ray) const
Gets the 3D ray for the direction line of the pixel where the mouse cursor is at.
Returns:
False if the window is closed.
See also:
virtual bool getLastMousePosition(int& x, int& y) const
Gets the last x,y pixel coordinates of the mouse.
Returns:
False if the window is closed.
See also:
virtual void setCursorCross(bool cursorIsCross)
Set cursor style to default (cursorIsCross=false) or to a cross (cursorIsCross=true)
See also:
void grabImagesStart(const std::string& grab_imgs_prefix = std::string("video_"))
Start to save rendered images to disk.
Images will be saved independently as png files, depending on the template path passed to this method. For example, the path_prefix ./video_ will generate ./video_000001.png, etc.
If this feature is enabled, the window will emit events of the type mrpt::gui::mrptEvent3DWindowGrabImageFile() which you can subscribe to.
See also:
void grabImagesStop()
Stops image grabbing started by grabImagesStart.
See also:
void captureImagesStart()
Enables the grabbing of CImage objects from screenshots of the window.
See also:
void captureImagesStop()
Stop image grabbing.
See also:
bool getLastWindowImage(mrpt::img::CImage& out_img) const
Retrieve the last captured image from the window.
You MUST CALL FIRST captureImagesStart to enable image grabbing.
Returns:
false if there was no time yet for grabbing any image (then, the output image is undefined).
See also:
captureImagesStart, getLastWindowImagePtr
mrpt::img::CImage::Ptr getLastWindowImagePtr() const
Retrieve the last captured image from the window, as a smart pointer.
This method is more efficient than getLastWindowImage since only a copy of the pointer is performed, while getLastWindowImage would copy the entire image.
You MUST CALL FIRST captureImagesStart to enable image grabbing. Note If there was no time yet for grabbing any image, an empty smart pointer will be returned.
See also:
captureImagesStart, getLastWindowImage
std::string grabImageGetNextFile()
Increments by one the image counter and return the next image file name (Users normally don’t want to call this method).
See also:
void addTextMessage( const double x_frac, const double y_frac, const std::string& text, size_t unique_index = 0, const mrpt::opengl::TFontParams& fontParams = mrpt::opengl::TFontParams() )
A shortcut for calling mrpt::opengl::Viewport::addTextMessage() in the “main” viewport of the 3D scene.
See also:
clearTextMessages, mrpt::opengl::Viewport::addTextMessage()
void clearTextMessages()
Clear all text messages created with addTextMessage().
A shortcut for calling mrpt::opengl::Viewport::clearTextMessages().
See also:
bool updateTextMessage(const size_t unique_index, const std::string& text)
Just updates the text of a given text message, without touching the other parameters.
A shortcut for calling mrpt::opengl::Viewport::updateTextMessage()
Returns:
false if given ID doesn’t exist.
double getRenderingFPS() const
Get the average Frames Per Second (FPS) value from the last 250 rendering events.
mrpt::opengl::Viewport::Ptr getDefaultViewport()
A short cut for getting the “main” viewport of the scene object, it is equivalent to:
mrpt::opengl::Scene::Ptr &scene = win3D.get3DSceneAndLock(); viewport = scene->getViewport("main"); win3D.unlockAccess3DScene();
void setImageView(const mrpt::img::CImage& img)
Set the “main” viewport into “image view”-mode, where an image is efficiently drawn (fitting the viewport area) using an OpenGL textured quad.
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). Internally, the texture is drawn using a mrpt::opengl::CTexturedPlane The viewport can be reverted to behave like a normal viewport by calling setNormalMode() This method already locks/unlocks the 3D scene of the window, so the user must NOT call get3DSceneAndLock() / unlockAccess3DScene() before/after calling it.
See also:
Viewport
void setImageView(mrpt::img::CImage&& img)
Just like setImageView but moves the internal image memory instead of making a copy, so it’s faster but empties the input image.
This method already locks/unlocks the 3D scene of the window, so the user must NOT call get3DSceneAndLock() / unlockAccess3DScene() before/after calling it.
See also:
setImageView, Viewport
static CDisplayWindow3D::Ptr Create( const std::string& windowCaption, unsigned int initialWindowWidth = 400, unsigned int initialWindowHeight = 300 )
Class factory returning a smart pointer, equivalent to std::make_shared<>(...)