libf3d: Improve API for [[nodiscard]] and missing this* return

library/private/interactor_impl.h

@@ -56,21 +56,21 @@ class interactor_impl : public interactor
   std::pair<std::string, std::string> getBindingDocumentation(
     const interaction_bind_t& bind) const override;
 
-  void toggleAnimation() override;
-  void startAnimation() override;
-  void stopAnimation() override;
+  interactor& toggleAnimation() override;
+  interactor& startAnimation() override;
+  interactor& stopAnimation() override;
   bool isPlayingAnimation() override;
 
-  void enableCameraMovement() override;
-  void disableCameraMovement() override;
+  interactor& enableCameraMovement() override;
+  interactor& disableCameraMovement() override;
 
   bool playInteraction(
     const std::string& file, double deltaTime, std::function<void()> userCallBack) override;
   bool recordInteraction(const std::string& file) override;
 
-  void start(double deltaTime, std::function<void()> userCallBack) override;
-  void stop() override;
-  void requestRender() override;
+  interactor& start(double deltaTime, std::function<void()> userCallBack) override;
+  interactor& stop() override;
+  interactor& requestRender() override;
   ///@}
 
   /**

library/public/camera.h

@@ -35,19 +35,19 @@ class F3D_EXPORT camera
    * Angles are in degrees.
    */
   virtual camera& setPosition(const point3_t& pos) = 0;
-  virtual point3_t getPosition() = 0;
+  [[nodiscard]] virtual point3_t getPosition() = 0;
   virtual void getPosition(point3_t& pos) = 0;
   virtual camera& setFocalPoint(const point3_t& foc) = 0;
-  virtual point3_t getFocalPoint() = 0;
+  [[nodiscard]] virtual point3_t getFocalPoint() = 0;
   virtual void getFocalPoint(point3_t& foc) = 0;
   virtual camera& setViewUp(const vector3_t& up) = 0;
-  virtual vector3_t getViewUp() = 0;
+  [[nodiscard]] virtual vector3_t getViewUp() = 0;
   virtual void getViewUp(vector3_t& up) = 0;
   virtual camera& setViewAngle(const angle_deg_t& angle) = 0;
-  virtual angle_deg_t getViewAngle() = 0;
+  [[nodiscard]] virtual angle_deg_t getViewAngle() = 0;
   virtual void getViewAngle(angle_deg_t& angle) = 0;
   virtual camera& setState(const camera_state_t& state) = 0;
-  virtual camera_state_t getState() = 0;
+  [[nodiscard]] virtual camera_state_t getState() = 0;
   virtual void getState(camera_state_t& state) = 0;
   ///@}
 

library/public/context.h

@@ -29,42 +29,42 @@ class F3D_EXPORT context
    * Create a GLX context function.
    * Only supported on Linux.
    */
-  static function glx();
+  [[nodiscard]] static function glx();
 
   /**
    * Create a WGL context function.
    * Only supported on Windows.
    */
-  static function wgl();
+  [[nodiscard]] static function wgl();
 
   /**
    * Create a COCOA context function.
    * This is usually required when using a headless context and a GPU device.
    * Only supported on macOS.
    */
-  static function cocoa();
+  [[nodiscard]] static function cocoa();
 
   /**
    * Create a EGL context function.
    * This is usually required when using a headless context and a GPU device.
    * Only supported on Linux and Windows.
    */
-  static function egl();
+  [[nodiscard]] static function egl();
 
   /**
    * Create a OSMesa context function.
    * This is usually required when using a headless context and no GPU device.
    * Only supported on Linux and Windows.
    */
-  static function osmesa();
+  [[nodiscard]] static function osmesa();
 
   /**
    * Create a context function from a library name and a function name.
    * The library name must be specified without its prefix and extension.
    * For example, `getSymbol("EGL", "eglGetProcAddress")` looks for the symbol
    * `eglGetProcAddress` in the library `libEGL.so` on Linux.
    */
-  static function getSymbol(const std::string& lib, const std::string& func);
+  [[nodiscard]] static function getSymbol(const std::string& lib, const std::string& func);
 
   /**
    * An exception that can be thrown when the requested library cannot be loaded.

library/public/engine.h

@@ -45,12 +45,12 @@ class F3D_EXPORT engine
    * Windows: Try Win32, then EGL, then OSMesa
    * macOS: Always use Cocoa
    */
-  static engine create(bool offscreen = false);
+  [[nodiscard]] static engine create(bool offscreen = false);
 
   /**
    * Create an engine with no window.
    */
-  static engine createNone();
+  [[nodiscard]] static engine createNone();
 
   /**
    * Create an engine with a GLX window.
@@ -59,7 +59,7 @@ class F3D_EXPORT engine
    * Optionally, the window can be hidden by setting offscreen to true.
    * Throws engine::loading_exception in case of window creation failure.
    */
-  static engine createGLX(bool offscreen = false);
+  [[nodiscard]] static engine createGLX(bool offscreen = false);
 
   /**
    * Create an engine with a WGL window.
@@ -68,7 +68,7 @@ class F3D_EXPORT engine
    * Optionally, the window can be hidden by setting offscreen to true.
    * Throws engine::loading_exception in case of window creation failure.
    */
-  static engine createWGL(bool offscreen = false);
+  [[nodiscard]] static engine createWGL(bool offscreen = false);
 
   /**
    * Create an engine with an offscreen EGL window.
@@ -77,14 +77,14 @@ class F3D_EXPORT engine
    * `VTK_DEFAULT_EGL_DEVICE_INDEX` allows its selection.
    * Throws engine::loading_exception in case of failure.
    */
-  static engine createEGL();
+  [[nodiscard]] static engine createEGL();
 
   /**
    * Create an engine with an offscreen OSMesa window.
    * VTK >= 9.4 required.
    * Throws engine::loading_exception in case of window creation failure.
    */
-  static engine createOSMesa();
+  [[nodiscard]] static engine createOSMesa();
 
   /**
    * Create an engine with an external window.
@@ -95,47 +95,47 @@ class F3D_EXPORT engine
    *  f3d::engine eng = f3d::engine::createExternal(glfwGetProcAddress);
    * \endcode
    */
-  static engine createExternal(const context::function& getProcAddress);
+  [[nodiscard]] static engine createExternal(const context::function& getProcAddress);
 
   /**
    * Create an engine with an external GLX context.
    * Equivalent to createExternal(f3d::context::glx());
    * VTK >= 9.4 required.
    * Throws context::loading_exception if GLX library is not found or if not running on Linux.
    */
-  static engine createExternalGLX();
+  [[nodiscard]] static engine createExternalGLX();
 
   /**
    * Create an engine with an external WGL context.
    * Equivalent to createExternal(f3d::context::wgl());
    * VTK >= 9.4 required.
    * Throws context::loading_exception if WGL library is not found or if not running on Windows.
    */
-  static engine createExternalWGL();
+  [[nodiscard]] static engine createExternalWGL();
 
   /**
    * Create an engine with an external COCOA context.
    * Equivalent to createExternal(f3d::context::cocoa());
    * VTK >= 9.4 required.
    * Throws context::loading_exception if WGL library is not found or if not running on Windows.
    */
-  static engine createExternalCOCOA();
+  [[nodiscard]] static engine createExternalCOCOA();
 
   /**
    * Create an engine with an external EGL context.
    * Equivalent to createExternal(f3d::context::egl());
    * VTK >= 9.4 required.
    * Throws context::loading_exception if EGL library is not found.
    */
-  static engine createExternalEGL();
+  [[nodiscard]] static engine createExternalEGL();
 
   /**
    * Create an engine with an external OSMesa context.
    * Equivalent to createExternal(f3d::context::osmesa());
    * VTK >= 9.4 required.
    * Throws context::loading_exception if OSMesa library is not found.
    */
-  static engine createExternalOSMesa();
+  [[nodiscard]] static engine createExternalOSMesa();
 
   /**
    * Engine destructor, delete all object instances as well.
@@ -160,7 +160,7 @@ class F3D_EXPORT engine
    * - Linux: ~/.cache/f3d
    * - macOS: ~/Library/Caches/f3d
    */
-  void setCachePath(const std::string& cachePath);
+  engine& setCachePath(const std::string& cachePath);
 
   /**
    * Engine provide a default options that you can use using engine::getOptions().
@@ -179,24 +179,24 @@ class F3D_EXPORT engine
   /**
    * Get the default options provided by the engine.
    */
-  options& getOptions();
+  [[nodiscard]] options& getOptions();
 
   /**
    * Get the window provided by the engine, if any.
    * If not, will throw a engine::no_window_exception.
    */
-  window& getWindow();
+  [[nodiscard]] window& getWindow();
 
   /**
    * Get the loaded provided by the engine.
    */
-  scene& getScene();
+  [[nodiscard]] scene& getScene();
 
   /**
    * Get the interactor provided by the engine, if any.
    * If not, will throw a engine::no_interactor_exception.
    */
-  interactor& getInteractor();
+  [[nodiscard]] interactor& getInteractor();
 
   /**
    * Load a plugin.
@@ -225,7 +225,7 @@ class F3D_EXPORT engine
    * Listed plugins can be loaded using engine::loadPlugin function.
    * Note that the listed plugins may fail to load if the library is not found or incompatible.
    */
-  static std::vector<std::string> getPluginsList(const std::string& pluginPath);
+  [[nodiscard]] static std::vector<std::string> getPluginsList(const std::string& pluginPath);
 
   /**
    * A structure providing information about the libf3d.
@@ -247,7 +247,7 @@ class F3D_EXPORT engine
   /**
    * Get a struct containing info about the libf3d.
    */
-  static libInformation getLibInfo();
+  [[nodiscard]] static libInformation getLibInfo();
 
   /**
    * A structure providing information about a reader.
@@ -267,7 +267,7 @@ class F3D_EXPORT engine
   /**
    * Get a vector of struct containing info about the supported readers.
    */
-  static std::vector<readerInformation> getReadersInfo();
+  [[nodiscard]] static std::vector<readerInformation> getReadersInfo();
 
   /**
    * An exception that can be thrown by the engine

library/public/image.h

@@ -76,8 +76,8 @@ class F3D_EXPORT image
   /**
    * Comparison operators, uses image::compare with a threshold of 1e-14.
    */
-  bool operator==(const image& reference) const;
-  bool operator!=(const image& reference) const;
+  [[nodiscard]] bool operator==(const image& reference) const;
+  [[nodiscard]] bool operator!=(const image& reference) const;
   ///@}
 
   /**
@@ -86,21 +86,21 @@ class F3D_EXPORT image
    * \warning Because of the normalization, this function can be slow, prefer getContent when
    * reading several pixels and normalization is not needed.
    */
-  std::vector<double> getNormalizedPixel(const std::pair<int, int>& xy) const;
+  [[nodiscard]] std::vector<double> getNormalizedPixel(const std::pair<int, int>& xy) const;
 
   /**
    * Get the list of supported image format extensions when opening a file.
    */
-  static std::vector<std::string> getSupportedFormats();
+  [[nodiscard]] static std::vector<std::string> getSupportedFormats();
 
   ///@{ @name Resolution
   /**
    * Set/Get image resolution.
    *
    * \deprecated { setResolution is deprecated, use the appropriate constructor }
    */
-  unsigned int getWidth() const;
-  unsigned int getHeight() const;
+  [[nodiscard]] unsigned int getWidth() const;
+  [[nodiscard]] unsigned int getHeight() const;
   ///@}
 
   ///@{ @name Channel Count
@@ -109,19 +109,19 @@ class F3D_EXPORT image
    *
    * \deprecated { setChannelCount is deprecated, use the appropriate constructor }
    */
-  unsigned int getChannelCount() const;
+  [[nodiscard]] unsigned int getChannelCount() const;
   ///@}
 
   /**
    * Get image channel type.
    * throw an `image::read_exception` if the type is unknown.
    */
-  ChannelType getChannelType() const;
+  [[nodiscard]] ChannelType getChannelType() const;
 
   /**
    * Get image channel type size in bytes.
    */
-  unsigned int getChannelTypeSize() const;
+  [[nodiscard]] unsigned int getChannelTypeSize() const;
 
   ///@{ @name Buffer Data
   /**
@@ -131,7 +131,7 @@ class F3D_EXPORT image
    * \deprecated { setData and getData are deprecated, use setContent and getContent instead }
    */
   image& setContent(void* buffer);
-  void* getContent() const;
+  [[nodiscard]] void* getContent() const;
   ///@}
 
   /**
@@ -163,10 +163,10 @@ class F3D_EXPORT image
    * Throw an `image::write_exception` if the format is incompatible with with image channel type or
    * channel count
    */
-  void save(const std::string& path, SaveFormat format = SaveFormat::PNG) const;
+  const image& save(const std::string& path, SaveFormat format = SaveFormat::PNG) const;
 
   /**
-   * Save an image to a memory buffer in the specified format.
+   * Save an image to a memory buffer in the specified format and returns it.
    * Default format is PNG if not specified.
    * PNG: Supports channel type BYTE and SHORT with channel count of 1 to 4
    * JPG: Supports channel type BYTE with channel count of 1 or 3
@@ -175,7 +175,7 @@ class F3D_EXPORT image
    * Throw an `image::write_exception` if the type is TIF or
    * if the format is incompatible with with image channel type or channel count.
    */
-  std::vector<unsigned char> saveBuffer(SaveFormat format = SaveFormat::PNG) const;
+  [[nodiscard]] std::vector<unsigned char> saveBuffer(SaveFormat format = SaveFormat::PNG) const;
 
   /**
    * Convert to colored text using ANSI escape sequences for printing in a terminal.
@@ -188,14 +188,14 @@ class F3D_EXPORT image
    * - 24-bit escape codes (`ESC[38;2;{r};{g};{b}m`, `ESC[48;2;{r};{g};{b}m`)
    * Throw a `image::write_exception` if the type is not byte RGB or RGBA.
    */
-  const f3d::image& toTerminalText(std::ostream& stream) const;
+  const image& toTerminalText(std::ostream& stream) const;
 
   /**
    * Convert to colored text using ANSI escape sequences for printing in a terminal.
    * See `toTerminalText(std::ostream& stream)`.
    * Throw a `image::write_exception` if the type is not byte RGB or RGBA.
    */
-  std::string toTerminalText() const;
+  [[nodiscard]] std::string toTerminalText() const;
 
   /**
    * Set the value for a metadata key. Setting an empty value (`""`) removes the key.
@@ -206,12 +206,12 @@ class F3D_EXPORT image
    * Get the value for a metadata key.
    * Throw a `image::read_exception` if key does not exist.
    */
-  std::string getMetadata(const std::string& key) const;
+  [[nodiscard]] std::string getMetadata(const std::string& key) const;
 
   /**
    * List all the metadata keys which have a value set.
    */
-  std::vector<std::string> allMetadata() const;
+  [[nodiscard]] std::vector<std::string> allMetadata() const;
 
   /**
    * An exception that can be thrown by the image when there.