Added render order to material

CMakeLists.txt

@@ -35,7 +35,7 @@ set(IGN_MATH_VER ${ignition-math6_VERSION_MAJOR})
 # Find ignition-common
 ign_find_package(ignition-common3 REQUIRED
   COMPONENTS graphics events
-  VERSION 3.9)
+  VERSION 3.10)
 set(IGN_COMMON_VER ${ignition-common3_VERSION_MAJOR})
 
 #--------------------------------------

examples/simple_demo/Main.cc

@@ -79,14 +79,16 @@ void buildScene(ScenePtr _scene)
   center->SetMaterial(green);
   root->AddChild(center);
 
-
+//! [red material]
   // create red material
   MaterialPtr red = _scene->CreateMaterial();
   red->SetAmbient(0.5, 0.0, 0.0);
   red->SetDiffuse(1.0, 0.0, 0.0);
   red->SetSpecular(0.5, 0.5, 0.5);
   red->SetShininess(50);
   red->SetReflectivity(0);
+  red->SetRenderOrder(3);
+//! [red material]
 
   // create sphere visual
   VisualPtr sphere = _scene->CreateVisual();
@@ -116,12 +118,15 @@ void buildScene(ScenePtr _scene)
   box->SetMaterial(blue);
   root->AddChild(box);
 
+//! [white material]
   // create white material
   MaterialPtr white = _scene->CreateMaterial();
   white->SetAmbient(0.5, 0.5, 0.5);
   white->SetDiffuse(0.8, 0.8, 0.8);
   white->SetReceiveShadows(true);
   white->SetReflectivity(0);
+  white->SetRenderOrder(0);
+//! [white material]
 
   // create plane visual
   VisualPtr plane = _scene->CreateVisual();
@@ -131,6 +136,15 @@ void buildScene(ScenePtr _scene)
   plane->SetMaterial(white);
   root->AddChild(plane);
 
+  // create plane visual
+  VisualPtr plane2 = _scene->CreateVisual();
+  plane2->AddGeometry(_scene->CreatePlane());
+  plane2->SetLocalScale(5, 8, 1);
+  plane2->SetLocalPosition(4, 0.5, -0.5);
+  plane2->Scale(0.1, 0.1, 1);
+  plane2->SetMaterial(red);
+  root->AddChild(plane2);
+
   // create axis visual
   VisualPtr axis = _scene->CreateAxisVisual();
   axis->SetLocalPosition(4.0, 0.5, -0.4);

include/ignition/rendering/Material.hh

@@ -322,6 +322,17 @@ namespace ignition
       /// \brief Removes any light map mapped to this material
       public: virtual void ClearLightMap() = 0;
 
+      /// \brief Set the render order. When polygons are coplanar, you can get
+      /// problems with 'depth fighting' where the pixels from the two polys
+      /// compete for the same screen pixel. This param help to avoid this
+      /// problem.
+      /// \param[in] _renderOrder Render order to set to
+      public: virtual void SetRenderOrder(const float _renderOrder) = 0;
+
+      /// \brief Get the render order value of this material.
+      /// \return Material render order
+      public: virtual float RenderOrder() const = 0;
+
       /// \brief Set the roughness value. Only affects material of type MT_PBS
       /// \param[in] _roughness Roughness to set to
       public: virtual void SetRoughness(const float _roughness) = 0;

include/ignition/rendering/MeshDescriptor.hh

@@ -65,12 +65,16 @@ namespace ignition
       public: const common::Mesh *mesh = nullptr;
       IGN_COMMON_WARN_RESUME__DLL_INTERFACE_MISSING
 
+      IGN_COMMON_WARN_IGNORE__DLL_INTERFACE_MISSING
       /// \brief Name of the registered Mesh
       public: std::string meshName;
+      IGN_COMMON_WARN_RESUME__DLL_INTERFACE_MISSING
 
+      IGN_COMMON_WARN_IGNORE__DLL_INTERFACE_MISSING
       /// \brief Name of the sub-mesh to be loaded. An empty string signifies
       /// all sub-meshes should be loaded.
       public: std::string subMeshName;
+      IGN_COMMON_WARN_RESUME__DLL_INTERFACE_MISSING
 
       /// \brief Denotes if the loaded sub-mesh vertices should be centered
       public: bool centerSubMesh = false;

include/ignition/rendering/base/BaseMaterial.hh

@@ -248,6 +248,12 @@ namespace ignition
       // Documentation inherited
       public: virtual void ClearLightMap() override;
 
+      // Documentation inherited
+      public: virtual void SetRenderOrder(const float _renderOrder) override;
+
+      // Documentation inherited
+      public: virtual float RenderOrder() const override;
+
       // Documentation inherited
       public: virtual void SetRoughness(const float _roughness) override;
 
@@ -338,6 +344,9 @@ namespace ignition
       /// \brief Enable two sided rendering
       protected: bool twoSidedEnabled = false;
 
+      /// \brief Material render order
+      protected: double renderOrder = 0.0;
+
       /// \brief Shininess factor
       protected: double shininess = 0.0;
 
@@ -529,6 +538,13 @@ namespace ignition
       this->receiveShadows = _receive;
     }
 
+    //////////////////////////////////////////////////
+    template <class T>
+    void BaseMaterial<T>::SetRenderOrder(const float _renderorder)
+    {
+      this->renderOrder = _renderorder;
+    }
+
     //////////////////////////////////////////////////
     template <class T>
     math::Color BaseMaterial<T>::Ambient() const
@@ -571,6 +587,13 @@ namespace ignition
       return this->transparency;
     }
 
+    //////////////////////////////////////////////////
+    template <class T>
+    float BaseMaterial<T>::RenderOrder() const
+    {
+      return this->renderOrder;
+    }
+
     //////////////////////////////////////////////////
     template <class T>
     double BaseMaterial<T>::Reflectivity() const
@@ -923,6 +946,7 @@ namespace ignition
       this->SetDiffuse(_material->Diffuse());
       this->SetSpecular(_material->Specular());
       this->SetEmissive(_material->Emissive());
+      this->SetRenderOrder(_material->RenderOrder());
       this->SetShininess(_material->Shininess());
       this->SetTransparency(_material->Transparency());
       this->SetAlphaFromTexture(_material->TextureAlphaEnabled(),
@@ -962,6 +986,7 @@ namespace ignition
       this->SetTransparency(_material.Transparency());
       this->SetAlphaFromTexture(_material.TextureAlphaEnabled(),
           _material.AlphaThreshold(), _material.TwoSidedEnabled());
+      this->SetRenderOrder(_material.RenderOrder());
       // TODO(anyone): update common::Material
       this->SetReflectivity(0);
       this->SetTexture(_material.TextureImage());
@@ -1015,6 +1040,7 @@ namespace ignition
       this->SetDiffuse(1.0, 1.0, 1.0);
       this->SetSpecular(0.2, 0.2, 0.2);
       this->SetEmissive(0, 0, 0);
+      this->SetRenderOrder(0);
       this->SetShininess(1.5);
       this->SetTransparency(0);
       this->SetReflectivity(0);
@@ -1026,6 +1052,7 @@ namespace ignition
       this->ClearRoughnessMap();
       this->ClearMetalnessMap();
       this->ClearEmissiveMap();
+      this->ClearLightMap();
       this->SetRoughness(kDefaultPbr.Roughness());
       this->SetMetalness(kDefaultPbr.Metalness());
       this->SetShaderType(ST_PIXEL);

ogre/include/ignition/rendering/ogre/OgreMaterial.hh

@@ -103,6 +103,15 @@ namespace ignition
       public: virtual void SetReceiveShadows(const bool _receiveShadows)
                   override;
 
+      // Documentation inherited
+      public: virtual float RenderOrder() const override;
+
+      // Documentation inherited
+      // Review the official documentation to get more details about this
+      // parameter, in particular Ogre::Pass::setDepthBias()
+      // https://www.ogre3d.org/docs/api/1.8/class_ogre_1_1_pass.html
+      public: virtual void SetRenderOrder(const float _renderOrder) override;
+
       public: virtual bool ReflectionEnabled() const override;
 
       public: virtual void SetReflectionEnabled(const bool _enabled) override;

ogre/src/OgreMaterial.cc

@@ -156,6 +156,19 @@ void OgreMaterial::SetEmissive(const math::Color &_color)
 #endif
 }
 
+//////////////////////////////////////////////////
+float OgreMaterial::RenderOrder() const
+{
+  return this->renderOrder;
+}
+
+//////////////////////////////////////////////////
+void OgreMaterial::SetRenderOrder(const float _renderOrder)
+{
+  this->renderOrder = _renderOrder;
+  this->ogrePass->setDepthBias(this->renderOrder);
+}
+
 //////////////////////////////////////////////////
 double OgreMaterial::Shininess() const
 {

ogre2/include/ignition/rendering/ogre2/Ogre2Material.hh

@@ -71,6 +71,14 @@ namespace ignition
       public: virtual void SetAlphaFromTexture(bool _enabled,
           double _alpha = 0.5, bool _twoSided = true) override;
 
+      // Documentation inherited
+      public: virtual float RenderOrder() const override;
+
+      // Documentation inherited
+      // Review the official documentation to get more details about this
+      // parameter, in particular mDepthBiasConstant
+      public: virtual void SetRenderOrder(const float _renderOrder) override;
+
       // Documentation inherited
       public: virtual bool ReceiveShadows() const override;
 

ogre2/src/Ogre2Material.cc

@@ -154,8 +154,8 @@ void Ogre2Material::SetAlphaFromTexture(bool _enabled,
   Ogre::HlmsBlendblock block;
   if (_enabled)
   {
-    block.setBlendType(Ogre::SBT_TRANSPARENT_ALPHA);
     this->ogreDatablock->setAlphaTest(Ogre::CMPF_GREATER_EQUAL);
+    block.setBlendType(Ogre::SBT_TRANSPARENT_ALPHA);
     this->ogreDatablock->setBlendblock(block);
   }
   else
@@ -167,6 +167,22 @@ void Ogre2Material::SetAlphaFromTexture(bool _enabled,
   this->ogreDatablock->setTwoSidedLighting(_twoSided);
 }
 
+//////////////////////////////////////////////////
+float Ogre2Material::RenderOrder() const
+{
+  return this->renderOrder;
+}
+
+//////////////////////////////////////////////////
+void Ogre2Material::SetRenderOrder(const float _renderOrder)
+{
+  this->renderOrder = _renderOrder;
+  Ogre::HlmsMacroblock macroblock(
+      *this->ogreDatablock->getMacroblock());
+  macroblock.mDepthBiasConstant = _renderOrder;
+  this->ogreDatablock->setMacroblock(macroblock);
+}
+
 //////////////////////////////////////////////////
 bool Ogre2Material::ReceiveShadows() const
 {

tutorials.md.in

@@ -22,6 +22,7 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
 8. \subpage simple_demo  "Simple demo"
 9. \subpage text_geom  "Text geom"
 10. \subpage particles  "Particles"
+11. \subpage render_order  "Render Order"
 
 ## License
 

tutorials/21_render_order.md

@@ -0,0 +1,52 @@
+\page render_order Render order
+
+This example shows how to set the render order for coplanar polygons.
+
+The material API allows changing the render order. When polygons are coplanar, you can get problems
+with `depth fighting` (also known as z fighting) where the pixels from the two polys compete for the same screen pixel.
+As you can see in the following image:
+
+@image html img/render_order_bad.png
+
+The method `SetRenderOrder` in the Material class allows you to avoid this issue. The higher value will
+be rendered on top of other coplanar polygons. This method will set the depth bias value of objects that the material is assigned to.
+
+In the `simple_demo` example you can find two materials with different render orders. The red material
+(`SetRenderOrder(3)`) has a higher value than the white material (`SetRenderOrder(3)`).
+
+\snippet examples/simple_demo/Main.cc red material
+
+\snippet examples/simple_demo/Main.cc white material
+
+As you can see in the following image the depth fighting issue is resolved.
+
+@image html img/render_order_good.png
+
+You can set this in your SDF file including in the material tag a new tag called `render_order` with
+a float value:
+
+```xml
+<material>
+  <render_order>5</render_order>
+  <ambient>0 0 1 1</ambient>
+  <diffuse>0 0 1 1</diffuse>
+  <specular>0 0 1 1</specular>
+</material>
+```
+
+Clone the source code, create a build directory and use `cmake` and `make` to compile the code:
+
+```{.sh}
+git clone https://github.com/ignitionrobotics/ign-rendering
+cd ign-rendering/examples/simple_demo
+mkdir build
+cd build
+cmake ..
+make
+```
+
+Execute the example:
+
+```{.sh}
+./simple_demo
+```