class mrpt::gui::CDisplayWindow3D

A graphical user interface (GUI) for efficiently rendering 3D scenes in real-time.

This class always contains internally an instance of opengl::COpenGLScene, 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 COpenGLViewport).

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::COpenGLScene::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 COpenGLScene, 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::COpenGLScene::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:

Tutorial: 3D scenes

#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::COpenGLScene::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,
        const 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::COpenGLViewport::Ptr getDefaultViewport();
    void setImageView(const mrpt::img::CImage& img);
    void setImageView(mrpt::img::CImage&& img);

    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::COpenGLScene::Ptr& get3DSceneAndLock()

Gets a reference to the smart shared pointer that holds the internal scene (carefuly 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:

getLastMousePosition

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:

getLastMousePositionRay

virtual void setCursorCross(bool cursorIsCross)

Set cursor style to default (cursorIsCross=false) or to a cross (cursorIsCross=true)

See also:

getLastMousePositionRay

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:

grabImagesStop

void grabImagesStop()

Stops image grabbing started by grabImagesStart.

See also:

grabImagesStart

void captureImagesStart()

Enables the grabbing of CImage objects from screenshots of the window.

See also:

getLastWindowImage

void captureImagesStop()

Stop image grabbing.

See also:

captureImagesStart

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. 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:

grabImagesStart

void addTextMessage(
    const double x_frac,
    const double y_frac,
    const std::string& text,
    const size_t unique_index = 0,
    const mrpt::opengl::TFontParams& fontParams = mrpt::opengl::TFontParams()
    )

A shortcut for calling mrpt::opengl::COpenGLViewport::addTextMessage() in the “main” viewport of the 3D scene.

See also:

clearTextMessages, mrpt::opengl::COpenGLViewport::addTextMessage()

void clearTextMessages()

Clear all text messages created with addTextMessage().

A shortcut for calling mrpt::opengl::COpenGLViewport::clearTextMessages().

See also:

addTextMessage

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::COpenGLViewport::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::COpenGLViewport::Ptr getDefaultViewport()

A short cut for getting the “main” viewport of the scene object, it is equivalent to:

mrpt::opengl::COpenGLScene::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:

COpenGLViewport

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, COpenGLViewport

static CDisplayWindow3D::Ptr Create(
    const std::string& windowCaption,
    unsigned int initialWindowWidth = 400,
    unsigned int initialWindowHeight = 300
    )

Class factory returning a smart pointer.