[engine] Material doc and small refactor

src/Engine/Data/BlinnPhongMaterial.hpp

@@ -22,13 +22,13 @@ class ShaderProgram;
 
 //! [TextureSemantics]
 namespace TextureSemantics {
-///@ BlinnPhongMaterial's textures
+/// \brief BlinnPhongMaterial's textures.
 enum class BlinnPhongMaterial { TEX_DIFFUSE, TEX_SPECULAR, TEX_NORMAL, TEX_SHININESS, TEX_ALPHA };
 } // namespace TextureSemantics
 //! [TextureSemantics]
 
-/**
- * Implementation of the Blinn-Phong Material BSDF.
+/** \brief Implementation of the Blinn-Phong Material BSDF.
+ *
  * \todo due to "Material.glsl" interface modification, must test this version with all plugins,
  * apps, ... that uses Radium Renderer
  */
@@ -43,14 +43,12 @@ class RA_ENGINE_API BlinnPhongMaterial final
   public:
     using TextureSemantic = TextureSemantics::BlinnPhongMaterial;
 
-    /**
-     * Construct a named Blinn-Phongmaterial
+    /** \brief Construct a named BlinnPhongMaterial.
+     *
      * \param instanceName The name of this instance of the material
      */
     explicit BlinnPhongMaterial( const std::string& instanceName );
 
-    using MaterialTextureSet<TextureSemantic>::addTexture;
-
     void updateGL() override;
     void updateFromParameters() override;
     bool isTransparent() const override;
@@ -68,15 +66,11 @@ class RA_ENGINE_API BlinnPhongMaterial final
      */
     static void unregisterMaterial();
 
-    /**
-     * Get a json containing metadata about the parameters of the material.
-     * \return the metadata in json format
-     */
-    inline nlohmann::json getParametersMetadata() const override;
+    inline nlohmann::json getParametersMetadata() const override { return s_parametersMetadata; }
 
     inline void setColoredByVertexAttrib( bool state ) override;
 
-    inline bool isColoredByVertexAttrib() const override;
+    inline bool isColoredByVertexAttrib() const override { return m_perVertexColor; }
 
     inline void setDiffuseColor( Core::Utils::Color c );
     inline void setSpecularColor( Core::Utils::Color c );
@@ -99,8 +93,7 @@ class RA_ENGINE_API BlinnPhongMaterial final
     bool m_renderAsSplat { false };
     static nlohmann::json s_parametersMetadata;
 
-    /**
-     * Update the rendering parameters for the Material
+    /** \brief Update the rendering parameters for the Material
      */
     void updateRenderingParameters();
 };
@@ -117,21 +110,13 @@ class RA_ENGINE_API BlinnPhongMaterialConverter final
     Material* operator()( const Ra::Core::Asset::MaterialData* toconvert );
 };
 
-inline nlohmann::json BlinnPhongMaterial::getParametersMetadata() const {
-    return s_parametersMetadata;
-}
-
 inline void BlinnPhongMaterial::setColoredByVertexAttrib( bool state ) {
     if ( state != m_perVertexColor ) {
         m_perVertexColor = state;
         needUpdate();
     }
 }
 
-inline bool BlinnPhongMaterial::isColoredByVertexAttrib() const {
-    return m_perVertexColor;
-}
-
 inline void BlinnPhongMaterial::setSpecularExponent( Scalar n ) {
     m_ns = n;
     needUpdate();

src/Engine/Data/LambertianMaterial.cpp

@@ -18,8 +18,6 @@ nlohmann::json LambertianMaterial::s_parametersMetadata = {};
 LambertianMaterial::LambertianMaterial( const std::string& instanceName ) :
     SimpleMaterial( instanceName, materialName, Material::MaterialAspect::MAT_OPAQUE ) {}
 
-LambertianMaterial::~LambertianMaterial() {}
-
 void LambertianMaterial::registerMaterial() {
     // Get the Radium Resource location on the filesystem
     auto resourcesRootDir { RadiumEngine::getInstance()->getResourcesDir() };

src/Engine/Data/LambertianMaterial.hpp

@@ -7,13 +7,13 @@ namespace Engine {
 namespace Data {
 
 namespace TextureSemantics {
-///@ LambertianMaterial's textures are the same than SimpleMaterial ones. Just alias the semantic
-/// enumeration.
+/** \brief  LambertianMaterial's textures are the same than SimpleMaterial ones, just alias.
+ */
 using LambertianMaterial = SimpleMaterial;
 } // namespace TextureSemantics
 
-/**
- * Implementation of the Lambertian Material BSDF.
+/** \brief Implementation of the Lambertian Material BSDF.
+ *
  * This material implements a lambertian diffuse BSDF.
  * This material could not be loaded from a file and must be defined and associated to
  * renderobjects programatically.
@@ -26,39 +26,29 @@ using LambertianMaterial = SimpleMaterial;
 class RA_ENGINE_API LambertianMaterial final : public SimpleMaterial
 {
   public:
-    /**
-     * Construct a named Lambertian material
+    /** \brief Construct a named Lambertian material.
+     *
      * \param instanceName The name of the material
      */
     explicit LambertianMaterial( const std::string& instanceName );
 
-    /**
-     * Destructor.
-     * \note The material does not have ownership on its texture nor its shaders.
-     * This destructor do not delete the associated textures and the corresponding shaders.
-     */
-    ~LambertianMaterial() override;
+    ~LambertianMaterial() override = default;
 
-    /**
-     * Register the material in the material library.
+    /** \brief Register the material in the material library.
+     *
      * After registration, the material could be instantiated by any Radium system, renderer,
      * plugin, ...
      */
     static void registerMaterial();
 
-    /**
-     * Remove the material from the material library.
+    /** \brief Remove the material from the material library.
+     *
      * After removal, the material is no more available, ...
      */
     static void unregisterMaterial();
 
     void updateFromParameters() override;
 
-    /**
-     * Get a json containing metadata about the parameters of the material.
-     *
-     * \return the metadata in json format
-     */
     nlohmann::json getParametersMetadata() const override;
 
   private:

src/Engine/Data/Material.cpp

@@ -11,14 +11,6 @@ Material::Material( const std::string& instanceName,
     m_aspect { aspect },
     m_materialName { materialName } {}
 
-bool Material::isTransparent() const {
-    return m_aspect == MaterialAspect::MAT_TRANSPARENT;
-}
-
-std::list<std::string> Material::getPropertyList() const {
-    return ShaderParameterProvider::getPropertyList();
-}
-
 } // namespace Data
 } // namespace Engine
 } // namespace Ra

src/Engine/Data/Material.hpp

@@ -15,17 +15,16 @@ namespace Ra {
 namespace Engine {
 namespace Data {
 
-/**
- * Base class for materials/
+/** \brief Base class for materials.
+ *
  * Do not assume a given Material representation but only make the difference between opaque and
  * transparent materials.
- *
  */
 class RA_ENGINE_API Material : public Data::ShaderParameterProvider
 {
   public:
-    /**
-     * Identifies the type of the material.
+    /** \brief Identifies the type of the material.
+     *
      *  MAT_OPAQUE and MAT_TRANSPARENT implements the GLSL "surfacic" BSDF interface
      *  MAT_DENSITY implements the GLSL "volumetric" interface
      */
@@ -35,15 +34,17 @@ class RA_ENGINE_API Material : public Data::ShaderParameterProvider
         MAT_DENSITY      /// <- The material implements the VOLUME interface
     };
 
+    /**
+     * \note The material does not have ownership on its texture nor its shaders.
+     * This destructor do not delete the associated textures and the corresponding shaders.
+     */
     virtual ~Material() = default;
 
-    /**
-     * \return the name of the material instance
+    /** \return the name of the material instance
      */
     inline const std::string& getInstanceName() const { return m_instanceName; }
 
-    /**
-     * \return the name of the material, can be used a UUID
+    /** \return the name of the material, can be used a UUID
      * \note the material name is expected to be used to define the ShaderConfiguration name
      */
     inline const std::string& getMaterialName() const { return m_materialName; }
@@ -53,20 +54,19 @@ class RA_ENGINE_API Material : public Data::ShaderParameterProvider
      */
     inline void setMaterialAspect( const MaterialAspect& aspect ) { m_aspect = aspect; }
 
-    /** Get the aspect (MAT_OPAQUE or MAT_TRANSPARENT) of the material.
+    /** \brief Get the aspect (MAT_OPAQUE or MAT_TRANSPARENT) of the material.
      *
      * \return the current aspect of the Material
      */
     inline const MaterialAspect& getMaterialAspect() const { return m_aspect; }
 
-    /** Test if material is transperent.
-     * \return true if the material is transparent
+    /** \return true if the material is transparent.
      */
-    virtual bool isTransparent() const;
+    virtual bool isTransparent() const { return m_aspect == MaterialAspect::MAT_TRANSPARENT; }
 
-    /**
-     * Get the list of properties the material migh use in a shader.
-     * each property will be added to the shader used for rendering this material under the form
+    /** * \brief Get the list of properties the material migh use in a shader.
+     *
+     * Each property will be added to the shader used for rendering this material under the form
      * "#define theProperty". Shaders that support the given property could then fully render the
      * material. Others migh render the meterial eroneously.
      *
@@ -75,30 +75,31 @@ class RA_ENGINE_API Material : public Data::ShaderParameterProvider
      * \todo : Validate this proposal
      * \todo : make the property list modifiable as well
      */
-    std::list<std::string> getPropertyList() const override;
+    std::list<std::string> getPropertyList() const override {
+        return ShaderParameterProvider::getPropertyList();
+    }
 
-    /**
-     * \brief Makes the Material take its base color from the VERTEX_COLOR attribute of the rendered
-     * geometry \param state activate (true) or deactivate (false) VERTEX_COLOR attribute usage
+    /** \brief Makes the Material take its base color from the VERTEX_COLOR attribute of the
+     * rendered geometry.
+     *
+     * \param state activate (true) or deactivate (false) VERTEX_COLOR attribute usage
      *
      * Any material that support per-vertex color parameterization should implement this method
      * accordingly
      */
-    virtual void setColoredByVertexAttrib( bool /* state */ ) {};
+    virtual void setColoredByVertexAttrib( [[maybe_unused]] bool state ) {};
 
-    /**
-     * \brief Indicates if the material takes the VERTEX_COLOR attribute into account.
+    /** \brief Indicates if the material takes the VERTEX_COLOR attribute into account.
      */
     virtual bool isColoredByVertexAttrib() const { return false; }
 
-    /** Mark the Material as needing update before the next OpenGL call
-     *
+    /** \brief Mark the Material as needing update before the next OpenGL call.
      */
-    inline void needUpdate() { m_isDirty = true; }
+    inline void needUpdate() { setDirty(); }
 
   protected:
-    /**
-     * Creates a named material with the given aspect
+    /** \brief Creates a named material with the given aspect.
+     *
      * \param instanceName
      * \param materialName
      * \param aspect
@@ -107,7 +108,8 @@ class RA_ENGINE_API Material : public Data::ShaderParameterProvider
                        const std::string& materialName,
                        MaterialAspect aspect = MaterialAspect::MAT_OPAQUE );
 
-    /** Change the Material Name
+    /** \brief Change the material name.
+     *
      * \note This method should be used carefully as the name is a key for render technique factory
      */
     inline void setMaterialName( std::string newName ) { m_materialName = std::move( newName ); }

src/Engine/Data/MaterialTextureSet.hpp

@@ -7,7 +7,7 @@ namespace Ra {
 namespace Engine {
 namespace Data {
 
-/** @brief Base class to manage a set of textures indexed by semantic (enum).
+/** \brief Base class to manage a set of textures indexed by semantic (enum).
  */
 template <typename TextureSemantic>
 class MaterialTextureSet
@@ -20,11 +20,17 @@ class MaterialTextureSet
         m_textures[semantic] = texture;
     }
 
+    /** \brief Add texture to TextureManager fisrt, then to the texture set.
+     */
     void addTexture( const TextureSemantic& semantic, const TextureParameters& texture ) {
         auto texManager = RadiumEngine::getInstance()->getTextureManager();
         addTexture( semantic, texManager->addTexture( texture ) );
     }
 
+    /** \brief Texture getter from semantic.
+     *
+     * \return raw (non owning) ptr to the texture, `nullptr` if the texture is not found.
+     */
     Texture* getTexture( const TextureSemantic& semantic ) const {
         Texture* tex    = nullptr;
         auto texManager = RadiumEngine::getInstance()->getTextureManager();

src/Engine/Data/PlainMaterial.cpp

@@ -19,8 +19,6 @@ nlohmann::json PlainMaterial::s_parametersMetadata = {};
 PlainMaterial::PlainMaterial( const std::string& instanceName ) :
     SimpleMaterial( instanceName, materialName, Material::MaterialAspect::MAT_OPAQUE ) {}
 
-PlainMaterial::~PlainMaterial() = default;
-
 void PlainMaterial::registerMaterial() {
     // Get the Radium Resource location on the filesystem
     auto resourcesRootDir { RadiumEngine::getInstance()->getResourcesDir() };

src/Engine/Data/PlainMaterial.hpp

@@ -30,7 +30,7 @@ class RA_ENGINE_API PlainMaterial final : public SimpleMaterial
      * \note The material does not have ownership on its texture nor its shaders.
      * This destructor do not delete the associated textures and the corresponding shaders.
      */
-    ~PlainMaterial() override;
+    ~PlainMaterial() override = default;
 
     /**
      * Register the material in the material library.
@@ -47,11 +47,6 @@ class RA_ENGINE_API PlainMaterial final : public SimpleMaterial
 
     void updateFromParameters() override;
 
-    /**
-     * Get a json containing metadata about the parameters of the material.
-     *
-     * \return the metadata in json format
-     */
     nlohmann::json getParametersMetadata() const override;
 
   private:

src/Engine/Data/RawShaderMaterial.hpp

@@ -85,9 +85,6 @@ class RA_ENGINE_API RawShaderMaterial : public Material
         const std::vector<std::pair<Data::ShaderType, std::string>>& shaders,
         std::shared_ptr<Data::ShaderParameterProvider> paramProvider );
 
-    /**
-     * Destructor.
-     */
     ~RawShaderMaterial() override;
 
     /**
@@ -145,8 +142,7 @@ class RA_ENGINE_API RawShaderMaterial : public Material
 
   private:
     /**
-     * Compute the unique key that identify this material in shaders and technique factories
-     * \return
+     * \return the unique key that identify this material in shaders and technique factories
      */
     std::string computeKey();
 

src/Engine/Data/RenderParameters.hpp

@@ -347,8 +347,7 @@ class RA_ENGINE_API ParameterSetEditingInterface
   public:
     virtual ~ParameterSetEditingInterface() = default;
 
-    /**
-     * \brief Get a json containing metadata about the parameters.
+    /** \brief Get a json containing metadata about the parameters.
      *
      * \return the metadata in json format
      */