4 ➡️ 5 (#399)

Signed-off-by: Louise Poubel <[email protected]>

.github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
         uses: ignition-tooling/action-ignition-ci@bionic
         with:
           codecov-enabled: true
+          doxygen-enabled: true
   focal-ci:
     runs-on: ubuntu-latest
     name: Ubuntu Focal CI

CMakeLists.txt

@@ -21,7 +21,7 @@ ign_configure_project(VERSION_SUFFIX)
 # Set project-specific options
 #============================================================================
 
-# ignition-rendering currently has no options that are unique to it
+option(USE_UNOFFICAL_OGRE_VERSIONS "Accept unsupported Ogre versions in the build" OFF)
 
 #============================================================================
 # Search for project-specific dependencies
@@ -63,10 +63,26 @@ endif()
 # Find OGRE
 list(APPEND ign_ogre_components "RTShaderSystem" "Terrain" "Overlay")
 
-ign_find_package(IgnOGRE VERSION 1.8.0
-  COMPONENTS ${ign_ogre_components}
-  REQUIRED_BY ogre
-  PRIVATE_FOR ogre)
+# Ogre versions greater than 1.9 are not officialy supported.
+# Display a warning for the users on this setup unless they provide
+# USE_UNOFFICAL_OGRE_VERSIONS flag
+if (NOT USE_UNOFFICAL_OGRE_VERSIONS)
+  ign_find_package(IgnOGRE VERSION 1.10
+    COMPONENTS ${ign_ogre_components})
+
+  if (OGRE_FOUND)
+    IGN_BUILD_WARNING("Ogre 1.x versions greater than 1.9 are not officially supported."
+                      "The software might compile and even work but support from upstream"
+                      "could be reduced to accepting patches for newer versions")
+  else()
+    # If ogre 1.10 or greater was not found, then proceed to look for 1.9.x
+    # versions which are offically supported
+    ign_find_package(IgnOGRE VERSION 1.9.0
+      COMPONENTS ${ign_ogre_components}
+      REQUIRED_BY ogre
+      PRIVATE_FOR ogre)
+  endif()
+endif()
 
 if (OGRE_FOUND)
   # find boost - mainly needed on macOS and also by the terrain component
@@ -154,6 +170,7 @@ configure_file(${CMAKE_SOURCE_DIR}/tutorials.md.in ${CMAKE_BINARY_DIR}/tutorials
 ign_create_docs(
   API_MAINPAGE_MD "${CMAKE_BINARY_DIR}/api.md"
   TUTORIALS_MAINPAGE_MD "${CMAKE_BINARY_DIR}/tutorials.md"
+  IMAGE_PATH_DIRS "${CMAKE_SOURCE_DIR}/tutorials/img"
   TAGFILES
     "${IGNITION-COMMON_DOXYGEN_TAGFILE} = ${IGNITION-COMMON_API_URL}"
     "${IGNITION-MATH_DOXYGEN_TAGFILE} = ${IGNITION-MATH_API_URL}"

Changelog.md

@@ -366,6 +366,10 @@
 
 ### Ignition Rendering 3.X.X (2021-XX-XX)
 
+1. CMake warning on Ogre versions that are not officially supported.
+   To disable the new warning, it is enough to enable the cmake option USE_UNOFFICAL_OGRE_VERSIONS
+    * [Pull request 376](https://github.com/ignitionrobotics/ign-rendering/pull/376)
+
 ### Ignition Rendering 3.5.0 (2021-05-25)
 
 1. Include MoveTo Helper class to ign-rendering

include/ignition/rendering/Camera.hh

@@ -81,8 +81,8 @@ namespace ignition
       public: virtual math::Angle HFOV() const = 0;
 
       /// \brief Set the camera's horizontal field-of-view
-      /// \param[in] _angle Desired horizontal field-of-view
-      public: virtual void SetHFOV(const math::Angle &_angle) = 0;
+      /// \param[in] _hfov Desired horizontal field-of-view
+      public: virtual void SetHFOV(const math::Angle &_hfov) = 0;
 
       /// \brief Get the camera's aspect ratio
       /// \return The camera's aspect ratio

include/ignition/rendering/GaussianNoisePass.hh

@@ -58,7 +58,7 @@ namespace ignition
       public: virtual void SetMean(double _mean) = 0;
 
       /// \brief Set stddev.
-      /// \param[in] _stddev Standard deviation of Gaussian noise.
+      /// \param[in] _stdDev Standard deviation of Gaussian noise.
       public: virtual void SetStdDev(double _stdDev) = 0;
 
       /// \brief Set the mean of the bias value. Bias is computed based on

include/ignition/rendering/Geometry.hh

@@ -55,13 +55,13 @@ namespace ignition
       /// \param[in] _name Name of registered Material
       /// \param[in] _unique True if the specified material should be cloned
       public: virtual void SetMaterial(const std::string &_name,
-                  bool unique = true) = 0;
+                  bool _unique = true) = 0;
 
       /// \brief Set the materials of this Geometry
       /// \param[in] _material New Material to be assigned
       /// \param[in] _unique True if the given material should be cloned
       public: virtual void SetMaterial(MaterialPtr _material,
-                  bool unique = true) = 0;
+                  bool _unique = true) = 0;
 
       /// \brief Get the material of this geometry
       /// \return Material used by this geometry

include/ignition/rendering/GpuRays.hh

@@ -54,7 +54,7 @@ namespace ignition
       /// \brief Configure behaviour for data values outside of camera range
       /// \param[in] _clamp True to clamp data to camera clip distances,
       // false to leave data values as +/-inf when out of camera range
-      public: virtual void SetClamp(const bool _value) = 0;
+      public: virtual void SetClamp(const bool _clamp) = 0;
 
       /// \brief Get behaviour for data values outside of camera range
       /// \return True if data values are clampped to camera clip distances,

include/ignition/rendering/HeightmapDescriptor.hh

@@ -123,15 +123,15 @@ inline namespace IGNITION_RENDERING_VERSION_NAMESPACE {
     public: double MinHeight() const;
 
     /// \brief Set the minimum height of the blend in meters.
-    /// \param[in] _uri The minimum height of the blend in meters.
+    /// \param[in] _minHeight The minimum height of the blend in meters.
     public: void SetMinHeight(double _minHeight);
 
     /// \brief Get the heightmap blend's fade distance.
     /// \return The fade distance of the heightmap blend in meters.
     public: double FadeDistance() const;
 
     /// \brief Set the distance over which the blend occurs.
-    /// \param[in] _uri The distance in meters.
+    /// \param[in] _fadeDistance The distance in meters.
     public: void SetFadeDistance(double _fadeDistance);
 
     /// \brief Private data pointer.
@@ -149,7 +149,7 @@ inline namespace IGNITION_RENDERING_VERSION_NAMESPACE {
     public: HeightmapDescriptor();
 
     /// \brief Copy constructor
-    /// \param[in] _heightmap HeightmapDescriptor to copy.
+    /// \param[in] _desc HeightmapDescriptor to copy.
     public: HeightmapDescriptor(const HeightmapDescriptor &_desc);
 
     /// \brief Move constructor

include/ignition/rendering/Light.hh

@@ -96,7 +96,7 @@ namespace ignition
       public: virtual double AttenuationRange() const = 0;
 
       /// \brief Set the attenuation range
-      /// \param[in] _value New attenuation range
+      /// \param[in] _range New attenuation range
       public: virtual void SetAttenuationRange(double _range) = 0;
 
       /// \brief Determine if this light cast shadows
@@ -179,7 +179,7 @@ namespace ignition
       public: virtual void SetInnerAngle(double _radians) = 0;
 
       /// \brief Set the inner angle of the spotlight
-      /// \param[in] _radians New inner angle of the spotlight
+      /// \param[in] _angle New inner angle of the spotlight
       public: virtual void SetInnerAngle(const math::Angle &_angle) = 0;
 
       /// \brief Get the outer angle of the spotlight
@@ -191,7 +191,7 @@ namespace ignition
       public: virtual void SetOuterAngle(double _radians) = 0;
 
       /// \brief Set the outer angle of the spotlight
-      /// \param[in] _radians New outer angle of the spotlight
+      /// \param[in] _angle New outer angle of the spotlight
       public: virtual void SetOuterAngle(const math::Angle &_angle) = 0;
 
       /// \brief Get the falloff of the spotlight

include/ignition/rendering/LightVisual.hh

@@ -60,20 +60,20 @@ namespace ignition
       /// \return The light visual type
       public: virtual LightVisualType Type() = 0;
 
-      /// \brief set inner angle for spot lights
-      /// \param[in] _type inner angle
+      /// \brief Set inner angle for spot lights
+      /// \param[in] _innerAngle Inner angle
       public: virtual void SetInnerAngle(double _innerAngle) = 0;
 
       /// \brief Get inner angle
       /// \return The light inner angle
       public: virtual double InnerAngle() = 0;
 
-      /// \brief set inner angle for spot lights
-      /// \param[in] _type inner angle
+      /// \brief Set outer angle for spot lights
+      /// \param[in] _outerAngle Outer angle
       public: virtual void SetOuterAngle(double _outerAngle) = 0;
 
-      /// \brief Get inner angle
-      /// \return The light inner angle
+      /// \brief Get outer angle
+      /// \return The light outer angle
       public: virtual double OuterAngle() = 0;
     };
     }

include/ignition/rendering/Marker.hh

@@ -100,7 +100,7 @@ namespace ignition
       public: virtual int32_t Layer() const = 0;
 
       /// \brief Set the render type of this Marker
-      /// \param[in] The desired render type
+      /// \param[in] _markerType The desired render type
       public: virtual void SetType(
                   const ignition::rendering::MarkerType _markerType) = 0;
 

include/ignition/rendering/Material.hh

@@ -220,8 +220,8 @@ namespace ignition
       public: virtual std::string Texture() const = 0;
 
       /// \brief Set the material texture
-      /// \param[in] _name URI of the new texture file
-      public: virtual void SetTexture(const std::string &_name) = 0;
+      /// \param[in] _texture URI of the new texture file
+      public: virtual void SetTexture(const std::string &_texture) = 0;
 
       /// \brief Removes any texture mapped to this material
       public: virtual void ClearTexture() = 0;
@@ -235,8 +235,8 @@ namespace ignition
       public: virtual std::string NormalMap() const = 0;
 
       /// \brief Set the material normal map
-      /// \param[in] _name URI of the new normal map file
-      public: virtual void SetNormalMap(const std::string &_name) = 0;
+      /// \param[in] _normalMap URI of the new normal map file
+      public: virtual void SetNormalMap(const std::string &_normalMap) = 0;
 
       /// \brief Removes any normal map mapped to this material
       public: virtual void ClearNormalMap() = 0;
@@ -250,8 +250,9 @@ namespace ignition
       public: virtual std::string RoughnessMap() const = 0;
 
       /// \brief Set the material roughness map
-      /// \param[in] _name URI of the new roughness map file
-      public: virtual void SetRoughnessMap(const std::string &_name) = 0;
+      /// \param[in] _roughnessMap URI of the new roughness map file
+      public: virtual void SetRoughnessMap(
+        const std::string &_roughnessMap) = 0;
 
       /// \brief Removes any roughness map mapped to this material
       public: virtual void ClearRoughnessMap() = 0;
@@ -265,8 +266,9 @@ namespace ignition
       public: virtual std::string MetalnessMap() const = 0;
 
       /// \brief Set the material metalness map
-      /// \param[in] _name URI of the new metalness map file
-      public: virtual void SetMetalnessMap(const std::string &_name) = 0;
+      /// \param[in] _metalnessMap URI of the new metalness map file
+      public: virtual void SetMetalnessMap(
+        const std::string &_metalnessMap) = 0;
 
       /// \brief Removes any metalness map mapped to this material
       public: virtual void ClearMetalnessMap() = 0;
@@ -280,8 +282,9 @@ namespace ignition
       public: virtual std::string EnvironmentMap() const = 0;
 
       /// \brief Set the material environment map
-      /// \param[in] _name URI of the new environment map file
-      public: virtual void SetEnvironmentMap(const std::string &_name) = 0;
+      /// \param[in] _metalnessMap URI of the new environment map file
+      public: virtual void SetEnvironmentMap(
+        const std::string &_metalnessMap) = 0;
 
       /// \brief Removes any environment map mapped to this material
       public: virtual void ClearEnvironmentMap() = 0;
@@ -295,8 +298,9 @@ namespace ignition
       public: virtual std::string EmissiveMap() const = 0;
 
       /// \brief Set the material emissive map
-      /// \param[in] _name URI of the new emissive map file
-      public: virtual void SetEmissiveMap(const std::string &_name) = 0;
+      /// \param[in] _emissiveMap URI of the new emissive map file
+      public: virtual void SetEmissiveMap(
+        const std::string &_emissiveMap) = 0;
 
       /// \brief Removes any emissive map mapped to this material
       public: virtual void ClearEmissiveMap() = 0;
@@ -314,9 +318,9 @@ namespace ignition
       public: virtual unsigned int LightMapTexCoordSet() const = 0;
 
       /// \brief Set the material light map
-      /// \param[in] _name URI of the new light map file
+      /// \param[in] _lightMap URI of the new light map file
       /// \param[in] _uvSet Texture coordinate set to use
-      public: virtual void SetLightMap(const std::string &_name,
+      public: virtual void SetLightMap(const std::string &_lightMap,
           unsigned int _uvSet = 0u) = 0;
 
       /// \brief Removes any light map mapped to this material

include/ignition/rendering/Mesh.hh

@@ -139,13 +139,13 @@ namespace ignition
       /// \param[in] _name Name of registered Material
       /// \param[in] _unique True if the specified material should be cloned
       public: virtual void SetMaterial(const std::string &_name,
-                  bool unique = true) = 0;
+                  bool _unique = true) = 0;
 
       /// \brief Set the materials of this SubMesh
       /// \param[in] _material New Material to be assigned
       /// \param[in] _unique True if the given material should be cloned
       public: virtual void SetMaterial(MaterialPtr _material,
-                  bool unique = true) = 0;
+                  bool _unique = true) = 0;
     };
     }
   }

include/ignition/rendering/RayQuery.hh

@@ -45,6 +45,12 @@ namespace ignition
       /// \brief Intersected object id
       public: unsigned int objectId = 0;
 
+      /// \brief Returns false if result is not valid
+      public: operator bool() const
+              {
+                return distance > 0;
+              }
+
       /// \brief Returns false if result is not valid
       public: operator bool()
               {
@@ -69,7 +75,7 @@ namespace ignition
       public: virtual math::Vector3d Origin() const = 0;
 
       /// \brief Set ray direction
-      /// \param[in] _origin Ray origin
+      /// \param[in] _dir Ray origin
       public: virtual void SetDirection(const math::Vector3d &_dir) = 0;
 
       /// \brief Get ray direction
@@ -83,8 +89,7 @@ namespace ignition
                 const math::Vector2d &_coord) = 0;
 
       /// \brief Compute intersections
-      /// \param[out] A vector of intersection results
-      /// \return True if results are not empty
+      /// \return A vector of intersection results
       public: virtual RayQueryResult ClosestPoint() = 0;
     };
     }

include/ignition/rendering/RenderEngine.hh

@@ -164,7 +164,7 @@ namespace ignition
                   const std::string &_name) = 0;
 
       /// \brief Add path to media resource location
-      /// \param[in] _paths Absolute path to resource location
+      /// \param[in] _path Absolute path to resource location
       public: virtual void AddResourcePath(const std::string &_path) = 0;
 
       /// \brief Get the render pass system for this engine.