Class CDisplayWindow3D

Defined in File CDisplayWindow3D.h

Inheritance Relationships

Base Type

public mrpt::gui::CBaseGUIWindow (Class CBaseGUIWindow)

Class Documentation

class CDisplayWindow3D : public mrpt::gui::CBaseGUIWindow 

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::img::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::viz::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::viz::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

../../output_staging/generated/doxygen/xml/preview_CDisplayWindow3D.png

See also

tutorial_3D_scenes

Public Types

using Ptr = std::shared_ptr<CDisplayWindow3D>

using ConstPtr = std::shared_ptr<const CDisplayWindow3D>

Public Functions

CDisplayWindow3D(const std::string &windowCaption = std::string(), unsigned int initialWindowWidth = 400, unsigned int initialWindowHeight = 300): Constructor

~CDisplayWindow3D() override: Destructor

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

Note

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

inline void repaint(): Repaints the window. forceRepaint, repaint and updateWindow are all aliases of the same method

inline 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) override: Resizes the window, stretching the image to fit into the display area.

virtual void setPos(int x, int y) override: Changes the position of the window on the screen.

virtual void setWindowTitle(const std::string &str) override: 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 setProjectiveModel(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

std::optional<mrpt::math::TLine3D> getLastMousePositionRay() const

Gets the 3D ray for the direction line of the pixel where the mouse cursor is at.

See also

getLastMousePosition

Returns:: False if the window is closed.

virtual std::optional<mrpt::img::TPixelCoord> getLastMousePosition() const override

Gets the last x,y pixel coordinates of the mouse.

Returns:: nullopt if the window is closed.

virtual void setCursorCross(bool cursorIsCross) override

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

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

grabImagesStart

inline bool isCapturingImgs() const

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

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

inline void clearTextMessages()

Clear all text messages created with addTextMessage(). A shortcut for calling mrpt::viz::Viewport::clearTextMessages().

See also

addTextMessage

inline 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::viz::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::viz::Viewport::Ptr getDefaultViewport()

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

mrpt::viz::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::viz::CTexturedPlane The viewport can be reverted to behave like a normal viewport by calling setNormalMode()

See also

Viewport

Note

This method already locks/unlocks the 3D scene of the window, so the user must NOT call get3DSceneAndLock() / unlockAccess3DScene() before/after calling it.

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.

See also

setImageView, Viewport

Note

This method already locks/unlocks the 3D scene of the window, so the user must NOT call get3DSceneAndLock() / unlockAccess3DScene() before/after calling it.

void sendFunctionToRunOnGUIThread(const std::function<void(void)> &f)

void sendFunctionWithShaderManager(const std::function<void(mrpt::opengl::ShaderProgramManager&)> &f): Runs f on the GUI/OpenGL thread, passing the active ShaderProgramManager. Use this to override or install custom shaders after the GL context is ready. If the compiled scene does not exist yet, f is not called.

Note

Must only be called once the window is fully open (after wait_for_GL_context()).

bool is_GL_context_created() const

bool wait_for_GL_context(const double timeout_seconds = 1.0) const

Public Static Functions

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<>(...)

Protected Functions

void createOpenGLContext(): Throws an exception on initialization error

void doRender()

void internalSetMinMaxRange()

void internal_setRenderingFPS(double FPS)

Set the rendering FPS (users don’t call this, the method is for internal MRPT objects only)

See also

getRenderingFPS

void internal_emitGrabImageEvent(const std::string &fil): called by CMyGLCanvas_DisplayWindow3D::OnPostRenderSwapBuffers

Protected Attributes

mrpt::viz::Scene::Ptr m_3Dscene: Internal OpenGL object (see general discussion in about usage of this object)

mutable std::recursive_timed_mutex m_csAccess3DScene: Critical section for accessing m_3Dscene

mrpt::void_ptr_noncopy m_DisplayDeviceContext

mrpt::void_ptr_noncopy m_GLRenderingContext

std::string m_grab_imgs_prefix

unsigned int m_grab_imgs_idx = {0}

bool m_is_capturing_imgs = {false}

mrpt::img::CImage::Ptr m_last_captured_img

mutable std::mutex m_last_captured_img_cs

mrpt::system::TTimeStamp m_lastFullScreen

double m_last_FPS = 10.0

See also

getRenderingFPS

std::mutex m_last_FPS_mtx

Friends

friend class C3DWindowDialog

friend class CMyGLCanvas_DisplayWindow3D