0032590: Visualization, V3d_View - improve API for setting Image Based Lighting

Added method V3d_View::SetImageBasedLighting() for managing IBL.
OpenGl_View implementation has been revised to handle IBL updates in a more straightforward way,

src/Graphic3d/Graphic3d_CView.cxx

@@ -26,6 +26,7 @@ IMPLEMENT_STANDARD_RTTIEXT(Graphic3d_CView,Graphic3d_DataStructureManager)
 //=======================================================================
 Graphic3d_CView::Graphic3d_CView (const Handle(Graphic3d_StructureManager)& theMgr)
 : myBgColor                (Quantity_NOC_BLACK),
+  myBackgroundType         (Graphic3d_TOB_NONE),
   myStructureManager       (theMgr),
   myCamera                 (new Graphic3d_Camera()),
   myHiddenObjects          (new Graphic3d_NMapOfTransient()),

src/Graphic3d/Graphic3d_CView.hxx

@@ -35,6 +35,7 @@
 #include <Graphic3d_TextureEnv.hxx>
 #include <Graphic3d_TypeOfAnswer.hxx>
 #include <Graphic3d_TypeOfBackfacingModel.hxx>
+#include <Graphic3d_TypeOfBackground.hxx>
 #include <Graphic3d_TypeOfShadingModel.hxx>
 #include <Graphic3d_TypeOfVisualization.hxx>
 #include <Graphic3d_Vec3.hxx>
@@ -359,6 +360,8 @@ public:
   //! Returns reference to current rendering parameters and effect settings.
   Graphic3d_RenderingParams& ChangeRenderingParams() { return myRenderParams; }
 
+public:
+
   //! Returns background  fill color.
   virtual Aspect_Background Background() const { return Aspect_Background (myBgColor.GetRGB()); }
 
@@ -372,7 +375,13 @@ public:
   virtual void SetGradientBackground (const Aspect_GradientBackground& theBackground) = 0;
 
   //! Returns background image texture map.
-  virtual Handle(Graphic3d_TextureMap) BackgroundImage() = 0;
+  const Handle(Graphic3d_TextureMap)& BackgroundImage() { return myBackgroundImage; }
+
+  //! Returns cubemap being set last time on background.
+  const Handle(Graphic3d_CubeMap)& BackgroundCubeMap() const { return myCubeMapBackground; }
+
+  //! Returns cubemap being set last time on background.
+  const Handle(Graphic3d_CubeMap)& IBLCubeMap() const { return myCubeMapIBL; }
 
   //! Sets image texture or environment cubemap as background.
   //! @param theTextureMap [in] source to set a background;
@@ -388,28 +397,26 @@ public:
   //! Sets background image fill style.
   virtual void SetBackgroundImageStyle (const Aspect_FillMethod theFillStyle) = 0;
 
-  //! Returns cubemap being set last time on background.
+  //! Returns background type.
-  virtual Handle(Graphic3d_CubeMap) BackgroundCubeMap() const = 0;
+  Graphic3d_TypeOfBackground BackgroundType() const { return myBackgroundType; }
 
-  //! Generates PBR specular probe and irradiance map
+  //! Sets background type.
-  //! in order to provide environment indirect illumination in PBR shading model (Image Based Lighting).
+  void SetBackgroundType (Graphic3d_TypeOfBackground theType) { myBackgroundType = theType; }
-  //! The source of environment data is background cubemap.
-  //! If PBR is unavailable it does nothing.
-  //! If PBR is available but there is no cubemap being set to background it clears all IBL maps (see 'ClearPBREnvironment').
-  virtual void GeneratePBREnvironment() = 0;
 
-  //! Fills PBR specular probe and irradiance map with white color.
+  //! Enables or disables IBL (Image Based Lighting) from background cubemap.
-  //! So that environment indirect illumination will be constant
+  //! Has no effect if PBR is not used.
-  //! and will be fully controlled by ambient light sources.
+  //! @param[in] theToEnableIBL enable or disable IBL from background cubemap
-  //! If PBR is unavailable it does nothing.
+  //! @param[in] theToUpdate redraw the view
-  virtual void ClearPBREnvironment() = 0;
+  virtual void SetImageBasedLighting (Standard_Boolean theToEnableIBL) = 0;
 
   //! Returns environment texture set for the view.
-  virtual Handle(Graphic3d_TextureEnv) TextureEnv() const = 0; 
+  const Handle(Graphic3d_TextureEnv)& TextureEnv() const { return myTextureEnvData; }
 
   //! Sets environment texture for the view.
   virtual void SetTextureEnv (const Handle(Graphic3d_TextureEnv)& theTextureEnv) = 0;
 
+public:
+
   //! Returns list of lights of the view.
   virtual const Handle(Graphic3d_LightSet)& Lights() const = 0;
 
@@ -568,7 +575,14 @@ protected:
 
   Standard_Integer myId;
   Graphic3d_RenderingParams myRenderParams;
-  Quantity_ColorRGBA        myBgColor;
+
+  Quantity_ColorRGBA           myBgColor;
+  Handle(Graphic3d_TextureMap) myBackgroundImage;
+  Handle(Graphic3d_CubeMap)    myCubeMapBackground;  //!< Cubemap displayed at background
+  Handle(Graphic3d_CubeMap)    myCubeMapIBL;         //!< Cubemap used for environment lighting
+  Handle(Graphic3d_TextureEnv) myTextureEnvData;
+  Graphic3d_TypeOfBackground   myBackgroundType;     //!< Current type of background
+
   Handle(Graphic3d_StructureManager) myStructureManager;
   Handle(Graphic3d_Camera)  myCamera;
   Graphic3d_SequenceOfStructure myStructsToCompute;

src/OpenGl/OpenGl_View.cxx

@@ -129,9 +129,8 @@ OpenGl_View::OpenGl_View (const Handle(Graphic3d_StructureManager)& theMgr,
   myIsImmediateDrawn     (Standard_False),
   myTextureParams   (new OpenGl_Aspects()),
   myCubeMapParams   (new OpenGl_Aspects()),
-  myBackgroundType  (Graphic3d_TOB_NONE),
   myPBREnvState     (OpenGl_PBREnvState_NONEXISTENT),
-  myPBREnvRequest   (OpenGl_PBREnvRequest_NONE),
+  myPBREnvRequest   (Standard_False),
   // ray-tracing fields initialization
   myRaytraceInitStatus     (OpenGl_RT_NONE),
   myIsRaytraceDataValid    (Standard_False),
@@ -553,49 +552,62 @@ void OpenGl_View::SetGradientBackground (const Aspect_GradientBackground& theBac
 void OpenGl_View::SetBackgroundImage (const Handle(Graphic3d_TextureMap)& theTextureMap,
                                       Standard_Boolean theToUpdatePBREnv)
 {
+  Handle(Graphic3d_TextureMap) aNewMap = theTextureMap;
   if (theTextureMap.IsNull()
   || !theTextureMap->IsDone())
+  {
+    if (!theTextureMap.IsNull())
+    {
+      Message::SendFail ("Error: unable to set image background");
+    }
+    aNewMap.Nullify();
+  }
+
+  Handle(Graphic3d_CubeMap) aCubeMap = Handle(Graphic3d_CubeMap)::DownCast (aNewMap);
+  if (theToUpdatePBREnv)
+  {
+    // update PBR environment
+    const TCollection_AsciiString anIdOld = !myCubeMapIBL.IsNull()
+                                           ? myCubeMapIBL->GetId()
+                                           : TCollection_AsciiString();
+    const TCollection_AsciiString anIdNew = !aCubeMap.IsNull()
+                                           ? aCubeMap->GetId()
+                                           : TCollection_AsciiString();
+    if (anIdNew != anIdOld)
+    {
+      myPBREnvRequest = true;
+    }
+    myCubeMapIBL = aCubeMap;
+  }
+
+  if (aNewMap.IsNull())
   {
     if (myBackgroundType == Graphic3d_TOB_TEXTURE
      || myBackgroundType == Graphic3d_TOB_CUBEMAP)
     {
       myBackgroundType = Graphic3d_TOB_NONE;
-      if (theToUpdatePBREnv)
-      {
-        myPBREnvRequest = OpenGl_PBREnvRequest_CLEAR;
-      }
     }
     return;
   }
 
   Handle(Graphic3d_AspectFillArea3d) anAspect = new Graphic3d_AspectFillArea3d();
-  Handle(Graphic3d_TextureSet) aTextureSet = new Graphic3d_TextureSet (theTextureMap);
+  Handle(Graphic3d_TextureSet) aTextureSet = new Graphic3d_TextureSet (aNewMap);
   anAspect->SetInteriorStyle (Aspect_IS_SOLID);
   anAspect->SetFaceCulling (Graphic3d_TypeOfBackfacingModel_DoubleSided);
   anAspect->SetShadingModel (Graphic3d_TypeOfShadingModel_Unlit);
   anAspect->SetTextureSet (aTextureSet);
   anAspect->SetTextureMapOn (true);
 
-  if (Handle(Graphic3d_Texture2D) aTextureMap = Handle(Graphic3d_Texture2D)::DownCast (theTextureMap))
+  if (Handle(Graphic3d_Texture2D) aTextureMap = Handle(Graphic3d_Texture2D)::DownCast (aNewMap))
   {
-    if (theToUpdatePBREnv && myBackgroundType == Graphic3d_TOB_CUBEMAP)
-    {
-      myPBREnvRequest = OpenGl_PBREnvRequest_CLEAR;
-    }
-
     myTextureParams->SetAspect (anAspect);
     myBackgroundType  = Graphic3d_TOB_TEXTURE;
     myBackgroundImage = aTextureMap;
     return;
   }
 
-  if (Handle(Graphic3d_CubeMap) aCubeMap = Handle(Graphic3d_CubeMap)::DownCast (theTextureMap))
+  if (!aCubeMap.IsNull())
   {
-    if (theToUpdatePBREnv)
-    {
-      myPBREnvRequest = OpenGl_PBREnvRequest_BAKE;
-    }
-
     aCubeMap->SetMipmapsGeneration (Standard_True);
     if (const Handle(OpenGl_Context)& aCtx = myWorkspace->GetGlContext())
     {
@@ -610,13 +622,43 @@ void OpenGl_View::SetBackgroundImage (const Handle(Graphic3d_TextureMap)& theTex
     myWorkspace->ApplyAspects();
 
     myBackgroundType = Graphic3d_TOB_CUBEMAP;
-    myBackgroundCubeMap = aCubeMap;
+    myCubeMapBackground = aCubeMap;
     return;
   }
 
   throw Standard_ProgramError ("OpenGl_View::SetBackgroundImage() - invalid texture map set for background");
 }
 
+// =======================================================================
+// function : SetImageBasedLighting
+// purpose  :
+// =======================================================================
+void OpenGl_View::SetImageBasedLighting (Standard_Boolean theToEnableIBL)
+{
+  if (!theToEnableIBL
+    || myBackgroundType != Graphic3d_TOB_CUBEMAP)
+  {
+    if (!myCubeMapIBL.IsNull())
+    {
+      myPBREnvRequest = true;
+      myCubeMapIBL.Nullify();
+    }
+    return;
+  }
+
+  const TCollection_AsciiString anIdOld = !myCubeMapIBL.IsNull()
+                                         ? myCubeMapIBL->GetId()
+                                         : TCollection_AsciiString();
+  const TCollection_AsciiString anIdNew = !myCubeMapBackground.IsNull()
+                                         ? myCubeMapBackground->GetId()
+                                         : TCollection_AsciiString();
+  if (anIdNew != anIdOld)
+  {
+    myPBREnvRequest = true;
+  }
+  myCubeMapIBL = myCubeMapBackground;
+}
+
 // =======================================================================
 // function : BackgroundImageStyle
 // purpose  :
@@ -635,15 +677,6 @@ void OpenGl_View::SetBackgroundImageStyle (const Aspect_FillMethod theFillStyle)
   myBackgrounds[Graphic3d_TOB_TEXTURE]->SetTextureFillMethod (theFillStyle);
 }
 
-// =======================================================================
-// function : BackgroundCubeMap
-// purpose  :
-// =======================================================================
-Handle(Graphic3d_CubeMap) OpenGl_View::BackgroundCubeMap() const
-{
-  return myBackgroundCubeMap;
-}
-
 // =======================================================================
 // function : SpecIBLMapLevels
 // purpose  :
@@ -955,8 +988,8 @@ void OpenGl_View::drawBackground (const Handle(OpenGl_Workspace)& theWorkspace,
 
   if (myBackgroundType == Graphic3d_TOB_CUBEMAP)
   {
-    myCubeMapParams->Aspect()->ShaderProgram()->PushVariableInt ("uZCoeff", myBackgroundCubeMap->ZIsInverted() ? -1 : 1);
+    myCubeMapParams->Aspect()->ShaderProgram()->PushVariableInt ("uZCoeff", myCubeMapBackground->ZIsInverted() ? -1 : 1);
-    myCubeMapParams->Aspect()->ShaderProgram()->PushVariableInt ("uYCoeff", myBackgroundCubeMap->IsTopDown() ? 1 : -1);
+    myCubeMapParams->Aspect()->ShaderProgram()->PushVariableInt ("uYCoeff", myCubeMapBackground->IsTopDown() ? 1 : -1);
     const OpenGl_Aspects* anOldAspectFace = theWorkspace->SetAspects (myCubeMapParams);
 
     myBackgrounds[Graphic3d_TOB_CUBEMAP]->Render (theWorkspace, theProjection);
@@ -1203,7 +1236,7 @@ bool OpenGl_View::prepareFrameBuffers (Graphic3d_Camera::Projection& theProj)
       myPBREnvironment->Release (aCtx.get());
       myPBREnvironment.Nullify();
       myPBREnvState = OpenGl_PBREnvState_NONEXISTENT;
-      myPBREnvRequest = OpenGl_PBREnvRequest_BAKE;
+      myPBREnvRequest = true;
       ++myLightsRevision;
     }
 
@@ -1297,7 +1330,7 @@ bool OpenGl_View::prepareFrameBuffers (Graphic3d_Camera::Projection& theProj)
         myWorkspace->ApplyAspects();
       }
     }
-    processPBREnvRequest (aCtx);
+    updatePBREnvironment (aCtx);
   }
 
   // create color and coverage accumulation buffers required for OIT algorithm
@@ -3042,19 +3075,51 @@ Standard_Boolean OpenGl_View::checkPBRAvailability() const
 }
 
 // =======================================================================
-// function : bakePBREnvironment
+// function : updatePBREnvironment
 // purpose  :
 // =======================================================================
-void OpenGl_View::bakePBREnvironment (const Handle(OpenGl_Context)& theCtx)
+void OpenGl_View::updatePBREnvironment (const Handle(OpenGl_Context)& theCtx)
 {
-  const Handle(OpenGl_TextureSet)& aTextureSet = myCubeMapParams->TextureSet (theCtx);
+  if (myPBREnvState != OpenGl_PBREnvState_CREATED
-  if (!aTextureSet.IsNull()
+  || !myPBREnvRequest)
-   && !aTextureSet->IsEmpty())
+  {
+    myPBREnvRequest = false;
+    return;
+  }
+
+  myPBREnvRequest = false;
+
+  Handle(OpenGl_TextureSet) aGlTextureSet;
+  OpenGl_Aspects* aTmpGlAspects = NULL;
+  if (!myCubeMapIBL.IsNull()
+    && myCubeMapIBL == myCubeMapBackground)
+  {
+    aGlTextureSet = myCubeMapParams->TextureSet (theCtx);
+  }
+  else if (!myCubeMapIBL.IsNull())
+  {
+    myCubeMapIBL->SetMipmapsGeneration (Standard_True);
+
+    Handle(Graphic3d_AspectFillArea3d) anAspect = new Graphic3d_AspectFillArea3d();
+    {
+      Handle(Graphic3d_TextureSet) aTextureSet = new Graphic3d_TextureSet (myCubeMapIBL);
+      anAspect->SetInteriorStyle (Aspect_IS_SOLID);
+      anAspect->SetTextureSet (aTextureSet);
+      anAspect->SetTextureMapOn (true);
+    }
+
+    aTmpGlAspects = new OpenGl_Aspects();
+    aTmpGlAspects->SetAspect (anAspect);
+    aGlTextureSet = aTmpGlAspects->TextureSet (theCtx);
+  }
+
+  if (!aGlTextureSet.IsNull()
+   && !aGlTextureSet->IsEmpty())
   {
     myPBREnvironment->Bake (theCtx,
-                            aTextureSet->First(),
+                            aGlTextureSet->First(),
-                            myBackgroundCubeMap->ZIsInverted(),
+                            myCubeMapIBL->ZIsInverted(),
-                            myBackgroundCubeMap->IsTopDown(),
+                            myCubeMapIBL->IsTopDown(),
                             myRenderParams.PbrEnvBakingDiffNbSamples,
                             myRenderParams.PbrEnvBakingSpecNbSamples,
                             myRenderParams.PbrEnvBakingProbability);
@@ -3063,31 +3128,6 @@ void OpenGl_View::bakePBREnvironment (const Handle(OpenGl_Context)& theCtx)
   {
     myPBREnvironment->Clear (theCtx);
   }
-}
+  aGlTextureSet.Nullify();
-
+  OpenGl_Element::Destroy (theCtx.get(), aTmpGlAspects);
-// =======================================================================
-// function : clearPBREnvironment
-// purpose  :
-// =======================================================================
-void OpenGl_View::clearPBREnvironment (const Handle(OpenGl_Context)& theCtx)
-{
-  myPBREnvironment->Clear (theCtx);
-}
-
-// =======================================================================
-// function : clearPBREnvironment
-// purpose  :
-// =======================================================================
-void OpenGl_View::processPBREnvRequest (const Handle(OpenGl_Context)& theCtx)
-{
-  if (myPBREnvState == OpenGl_PBREnvState_CREATED)
-  {
-    switch (myPBREnvRequest)
-    {
-      case OpenGl_PBREnvRequest_NONE:  return;
-      case OpenGl_PBREnvRequest_BAKE:  bakePBREnvironment  (theCtx); break;
-      case OpenGl_PBREnvRequest_CLEAR: clearPBREnvironment (theCtx); break;
-    }
-  }
-  myPBREnvRequest = OpenGl_PBREnvRequest_NONE;
 }

src/OpenGl/OpenGl_View.hxx

@@ -16,15 +16,11 @@
 #ifndef _OpenGl_View_Header
 #define _OpenGl_View_Header
 
-#include <Aspect_FillMethod.hxx>
-#include <Aspect_GradientFillMethod.hxx>
 #include <Graphic3d_CView.hxx>
 #include <Graphic3d_CullingTool.hxx>
 #include <Graphic3d_GraduatedTrihedron.hxx>
 #include <Graphic3d_SequenceOfHClipPlane.hxx>
 #include <Graphic3d_ToneMappingMethod.hxx>
-#include <Graphic3d_TypeOfBackground.hxx>
-#include <Graphic3d_TypeOfShadingModel.hxx>
 #include <Graphic3d_WorldViewProjState.hxx>
 #include <Graphic3d_ZLayerSettings.hxx>
 #include <math_BullardGenerator.hxx>
@@ -41,7 +37,6 @@
 #include <map>
 #include <set>
 
-class Graphic3d_StructureManager;
 class OpenGl_BackgroundArray;
 class OpenGl_DepthPeeling;
 class OpenGl_GraphicDriver;
@@ -206,9 +201,6 @@ public:
   //! Sets gradient background fill colors.
   Standard_EXPORT virtual void SetGradientBackground (const Aspect_GradientBackground& theBackground) Standard_OVERRIDE;
 
-  //! Returns background image texture map.
-  virtual Handle(Graphic3d_TextureMap) BackgroundImage() Standard_OVERRIDE { return myBackgroundImage; }
-
   //! Sets image texture or environment cubemap as background.
   //! @param theTextureMap [in] source to set a background;
   //!                           should be either Graphic3d_Texture2D or Graphic3d_CubeMap
@@ -217,38 +209,25 @@ public:
   Standard_EXPORT virtual void SetBackgroundImage (const Handle(Graphic3d_TextureMap)& theTextureMap,
                                                    Standard_Boolean theToUpdatePBREnv = Standard_True) Standard_OVERRIDE;
 
+  //! Sets environment texture for the view.
+  Standard_EXPORT virtual void SetTextureEnv (const Handle(Graphic3d_TextureEnv)& theTextureEnv) Standard_OVERRIDE;
+
   //! Returns background image fill style.
   Standard_EXPORT virtual Aspect_FillMethod BackgroundImageStyle() const Standard_OVERRIDE;
 
   //! Sets background image fill style.
   Standard_EXPORT virtual void SetBackgroundImageStyle (const Aspect_FillMethod theFillStyle) Standard_OVERRIDE;
 
-  //! Returns cubemap being set last time on background.
+  //! Enables or disables IBL (Image Based Lighting) from background cubemap.
-  Standard_EXPORT Handle(Graphic3d_CubeMap) BackgroundCubeMap() const Standard_OVERRIDE;
+  //! Has no effect if PBR is not used.
-
+  //! @param[in] theToEnableIBL enable or disable IBL from background cubemap
-  //! Generates PBR specular probe and irradiance map
+  //! @param[in] theToUpdate redraw the view
-  //! in order to provide environment indirect illumination in PBR shading model (Image Based Lighting).
+  Standard_EXPORT virtual void SetImageBasedLighting (Standard_Boolean theToEnableIBL) Standard_OVERRIDE;
-  //! The source of environment data is background cubemap.
-  //! If PBR is unavailable it does nothing.
-  //! If PBR is available but there is no cubemap being set to background it clears all IBL maps (see 'ClearPBREnvironment').
-  virtual void GeneratePBREnvironment() Standard_OVERRIDE { myPBREnvRequest = OpenGl_PBREnvRequest_BAKE; }
-
-  //! Fills PBR specular probe and irradiance map with white color.
-  //! So that environment indirect illumination will be constant
-  //! and will be fully controlled by ambient light sources.
-  //! If PBR is unavailable it does nothing.
-  virtual void ClearPBREnvironment() Standard_OVERRIDE { myPBREnvRequest = OpenGl_PBREnvRequest_CLEAR; }
 
   //! Returns number of mipmap levels used in specular IBL map.
   //! 0 if PBR environment is not created.
   Standard_EXPORT unsigned int SpecIBLMapLevels() const;
 
-  //! Returns environment texture set for the view.
-  virtual Handle(Graphic3d_TextureEnv) TextureEnv() const Standard_OVERRIDE { return myTextureEnvData; }
-
-  //! Sets environment texture for the view.
-  Standard_EXPORT virtual void SetTextureEnv (const Handle(Graphic3d_TextureEnv)& theTextureEnv) Standard_OVERRIDE;
-
   //! Returns local camera origin currently set for rendering, might be modified during rendering.
   const gp_XYZ& LocalOrigin() const { return myLocalOrigin; }
 
@@ -470,8 +449,6 @@ protected:
   gp_XYZ                          myLocalOrigin;
   Handle(OpenGl_FrameBuffer)      myFBO;
   Standard_Boolean                myToShowGradTrihedron;
-  Handle(Graphic3d_TextureMap)    myBackgroundImage;
-  Handle(Graphic3d_TextureEnv)    myTextureEnvData;
   Graphic3d_GraduatedTrihedron    myGTrihedronData;
 
   Handle(Graphic3d_LightSet)      myNoShadingLight;
@@ -495,8 +472,6 @@ protected:
   OpenGl_GraduatedTrihedron myGraduatedTrihedron;
   OpenGl_FrameStatsPrs      myFrameStatsPrs;
 
-  Handle(OpenGl_TextureSet) myTextureEnv;
-
   //! Framebuffers for OpenGL output.
   Handle(OpenGl_FrameBuffer) myOpenGlFBO;
   Handle(OpenGl_FrameBuffer) myOpenGlFBO2;
@@ -532,9 +507,8 @@ protected: //! @name Background parameters
 
   OpenGl_Aspects*            myTextureParams;                     //!< Stores texture and its parameters for textured background
   OpenGl_Aspects*            myCubeMapParams;                     //!< Stores cubemap and its parameters for cubemap background
-  Handle(Graphic3d_CubeMap)  myBackgroundCubeMap;                 //!< Cubemap has been set as background
-  Graphic3d_TypeOfBackground myBackgroundType;                    //!< Current type of background
   OpenGl_BackgroundArray*    myBackgrounds[Graphic3d_TypeOfBackground_NB]; //!< Array of primitive arrays of different background types
+  Handle(OpenGl_TextureSet)  myTextureEnv;
 
 protected: //! @name methods related to PBR
 
@@ -543,14 +517,7 @@ protected: //! @name methods related to PBR
 
   //! Generates IBL maps used in PBR pipeline.
   //! If background cubemap is not set clears all IBL maps.
-  Standard_EXPORT void bakePBREnvironment (const Handle(OpenGl_Context)& theCtx);
+  Standard_EXPORT void updatePBREnvironment (const Handle(OpenGl_Context)& theCtx);
-
-  //! Fills all IBL maps with white color.
-  //! So that environment lighting is considered to be constant and is completely controls by ambient light sources.
-  Standard_EXPORT void clearPBREnvironment (const Handle(OpenGl_Context)& theCtx);
-
-  //! Process requests to generate or to clear PBR environment.
-  Standard_EXPORT void processPBREnvRequest (const Handle(OpenGl_Context)& theCtx);
 
 protected: //! @name fields and types related to PBR
 
@@ -562,17 +529,9 @@ protected: //! @name fields and types related to PBR
     OpenGl_PBREnvState_CREATED
   };
 
-  //! Type of action which can be done with PBR environment.
-  enum PBREnvironmentRequest
-  {
-    OpenGl_PBREnvRequest_NONE,
-    OpenGl_PBREnvRequest_BAKE,
-    OpenGl_PBREnvRequest_CLEAR
-  };
-
   Handle(OpenGl_PBREnvironment) myPBREnvironment; //!< manager of IBL maps used in PBR pipeline
   PBREnvironmentState           myPBREnvState;    //!< state of PBR environment
-  PBREnvironmentRequest         myPBREnvRequest;  //!< type of action is requested to be done with PBR environment
+  Standard_Boolean              myPBREnvRequest;  //!< update PBR environment
 
 protected: //! @name data types related to ray-tracing
 
@@ -761,7 +720,7 @@ protected: //! @name data types related to ray-tracing
     //! Enables/disables depth-of-field effect (path tracing, perspective camera).
     Standard_Boolean DepthOfField;
 
-    //! Enables/disables cubemap backgraund.
+    //! Enables/disables cubemap background.
     Standard_Boolean CubemapForBack;
 
     //! Tone mapping method for path tracing.

src/OpenGl/OpenGl_View_Raytrace.cxx

@@ -1422,7 +1422,7 @@ Standard_Boolean OpenGl_View::initRaytraceResources (const Standard_Integer theS
     }
     myTileSampler.SetSize (myRenderParams, myRaytraceParameters.AdaptiveScreenSampling ? Graphic3d_Vec2i (theSizeX, theSizeY) : Graphic3d_Vec2i (0, 0));
 
-    const bool isCubemapForBack = !myBackgroundCubeMap.IsNull();
+    const bool isCubemapForBack = !myCubeMapBackground.IsNull();
     if (myRaytraceParameters.CubemapForBack != isCubemapForBack)
     {
       myRaytraceParameters.CubemapForBack = isCubemapForBack;
@@ -2694,8 +2694,8 @@ Standard_Boolean OpenGl_View::setUniformState (const Standard_Integer        the
                           toDisableEnvironmentMap ? 0 : 1);
   if (myRaytraceParameters.CubemapForBack)
   {
-    theProgram->SetUniform (theGlContext, "uZCoeff", myBackgroundCubeMap->ZIsInverted() ? -1 :  1);
+    theProgram->SetUniform (theGlContext, "uZCoeff", myCubeMapBackground->ZIsInverted() ? -1 :  1);
-    theProgram->SetUniform (theGlContext, "uYCoeff", myBackgroundCubeMap->IsTopDown()   ?  1 : -1);
+    theProgram->SetUniform (theGlContext, "uYCoeff", myCubeMapBackground->IsTopDown()   ?  1 : -1);
     theProgram->SetUniform (theGlContext, myUniformLocations[theProgramId][OpenGl_RT_uEnvMapForBack],
                             myBackgroundType == Graphic3d_TOB_CUBEMAP ? 1 : 0);
   }

src/V3d/V3d_View.cxx

@@ -530,25 +530,22 @@ void V3d_View::SetBackgroundCubeMap (const Handle(Graphic3d_CubeMap)& theCubeMap
 }
 
 //=============================================================================
-//function : GeneratePBREnvironment
+//function : IsImageBasedLighting
 //purpose  :
 //=============================================================================
-void V3d_View::GeneratePBREnvironment (Standard_Boolean theToUpdate)
+Standard_Boolean V3d_View::IsImageBasedLighting() const
 {
-  myView->GeneratePBREnvironment();
+  return !myView->IBLCubeMap().IsNull();
-  if (myImmediateUpdate || theToUpdate)
-  {
-    Redraw();
-  }
 }
 
 //=============================================================================
-//function : ClearPBREnvironment
+//function : SetImageBasedLighting
 //purpose  :
 //=============================================================================
-void V3d_View::ClearPBREnvironment (Standard_Boolean theToUpdate)
+void V3d_View::SetImageBasedLighting (Standard_Boolean theToEnableIBL,
+                                      Standard_Boolean theToUpdate)
 {
-  myView->ClearPBREnvironment();
+  myView->SetImageBasedLighting (theToEnableIBL);
   if (myImmediateUpdate || theToUpdate)
   {
     Redraw();

src/V3d/V3d_View.hxx

@@ -175,6 +175,8 @@ public:
   //! displayed objects.
   Standard_EXPORT void ZFitAll (const Standard_Real theScaleFactor = 1.0) const;
 
+public:
+
   //! Defines the background color of the view by the color definition type and the three corresponding values.
   Standard_EXPORT void SetBackgroundColor (const Quantity_TypeOfColor theType,
                                            const Standard_Real theV1,
@@ -217,17 +219,24 @@ public:
                                              Standard_Boolean                 theToUpdatePBREnv = Standard_True,
                                              Standard_Boolean                 theToUpdate = Standard_False);
 
-  //! Generates PBR specular probe and irradiance map
+  //! Returns TRUE if IBL (Image Based Lighting) from background cubemap is enabled.
-  //! in order to provide environment indirect illumination in PBR shading model (Image Based Lighting).
+  Standard_EXPORT Standard_Boolean IsImageBasedLighting() const;
-  //! The source of environment data is background cubemap.
-  //! If PBR is unavailable it does nothing.
-  //! If PBR is available but there is no cubemap being set to background it clears all IBL maps (see 'ClearPBREnvironment').
-  Standard_EXPORT void GeneratePBREnvironment (Standard_Boolean theToUpdate = Standard_False);
 
-  //! Fills PBR specular probe and irradiance map with white color.
+  //! Enables or disables IBL (Image Based Lighting) from background cubemap.
-  //! So that environment indirect illumination will be constant and will be fully controlled by ambient light sources.
+  //! Has no effect if PBR is not used.
-  //! If PBR is unavailable it does nothing.
+  //! @param[in] theToEnableIBL enable or disable IBL from background cubemap
-  Standard_EXPORT void ClearPBREnvironment (Standard_Boolean theToUpdate = Standard_False);
+  //! @param[in] theToUpdate redraw the view
+  Standard_EXPORT void SetImageBasedLighting (Standard_Boolean theToEnableIBL,
+                                              Standard_Boolean theToUpdate = Standard_False);
+
+  //! Activates IBL from background cubemap.
+  void GeneratePBREnvironment (Standard_Boolean theToUpdate = Standard_False) { SetImageBasedLighting (Standard_True, theToUpdate); }
+
+  //! Disables IBL from background cubemap; fills PBR specular probe and irradiance map with white color.
+  void ClearPBREnvironment (Standard_Boolean theToUpdate = Standard_False) { SetImageBasedLighting (Standard_True, theToUpdate); }
+
+  //! Sets the environment texture to use. No environment texture by default.
+  Standard_EXPORT void SetTextureEnv (const Handle(Graphic3d_TextureEnv)& theTexture);
 
   //! Definition of an axis from its origin and
   //! its orientation .
@@ -236,8 +245,7 @@ public:
   Standard_EXPORT void SetAxis (const Standard_Real X, const Standard_Real Y, const Standard_Real Z,
                                 const Standard_Real Vx, const Standard_Real Vy, const Standard_Real Vz);
 
-  //! Sets the environment texture to use. No environment texture by default.
+public:
-  Standard_EXPORT void SetTextureEnv (const Handle(Graphic3d_TextureEnv)& theTexture);
 
   //! Defines the visualization type in the view.
   Standard_EXPORT void SetVisualization (const V3d_TypeOfVisualization theType);

src/ViewerTest/ViewerTest_ViewerCommands.cxx

@@ -2694,9 +2694,11 @@ static int VBackground (Draw_Interpretor& theDI,
 
   NCollection_Sequence<TCollection_AsciiString> aCubeMapSeq;
   Graphic3d_CubeMapOrder aCubeOrder = Graphic3d_CubeMapOrder::Default();
-  bool isCubeZInverted = false, isCubeGenPBREnv = true;
+  bool isCubeZInverted = false;
   bool isSRgb = true;
 
+  int toUseIBL = 1;
+
   Handle(V3d_View) aView = ViewerTest::CurrentView();
   ViewerTest_AutoUpdater anUpdateTool (ViewerTest::GetAISContext(), aView);
   for (Standard_Integer anArgIter = 1; anArgIter < theNbArgs; ++anArgIter)
@@ -2780,9 +2782,36 @@ static int VBackground (Draw_Interpretor& theDI,
       isCubeZInverted = Draw::ParseOnOffNoIterator (theNbArgs, theArgVec, anArgIter);
     }
     else if (anArg == "-pbrenv"
-          || anArg == "-nopbrenv")
+          || anArg == "-nopbrenv"
+          || anArg == "-ibl"
+          || anArg == "-noibl")
     {
-      isCubeGenPBREnv = Draw::ParseOnOffNoIterator (theNbArgs, theArgVec, anArgIter);
+      toUseIBL = !anArg.StartsWith ("-no") ? 1 : 0;
+      if (anArgIter + 1 < theNbArgs)
+      {
+        TCollection_AsciiString anIblArg (theArgVec[anArgIter + 1]);
+        anIblArg.LowerCase();
+        if (anIblArg == "keep"
+         || anIblArg == "-1")
+        {
+          toUseIBL = -1;
+          ++anArgIter;
+        }
+        else if (anIblArg == "ibl"
+              || anIblArg == "1"
+              || anIblArg == "on")
+        {
+          toUseIBL = !anArg.StartsWith ("-no") ? 1 : 0;
+          ++anArgIter;
+        }
+        else if (anIblArg == "noibl"
+              || anIblArg == "0"
+              || anIblArg == "off")
+        {
+          toUseIBL = !anArg.StartsWith ("-no") ? 0 : 1;
+          ++anArgIter;
+        }
+      }
     }
     else if (anArg == "-srgb"
           || anArg == "-nosrgb")
@@ -2905,6 +2934,10 @@ static int VBackground (Draw_Interpretor& theDI,
     {
       aView->SetBgGradientStyle (hasGradientMode ? aGradientMode : Aspect_GradientFillMethod_None);
       aView->SetBackgroundColor (aColors[0].GetRGB());
+      if (toUseIBL != -1)
+      {
+        aView->SetBackgroundCubeMap (Handle(Graphic3d_CubeMap)(), true);
+      }
     }
   }
   else if (aNbColors == 2)
@@ -2934,6 +2967,10 @@ static int VBackground (Draw_Interpretor& theDI,
         }
       }
       aView->SetBgGradientColors (aColors[0].GetRGB(), aColors[1].GetRGB(), aGradientMode);
+      if (toUseIBL != -1)
+      {
+        aView->SetBackgroundCubeMap (Handle(Graphic3d_CubeMap)(), true);
+      }
     }
   }
   else if (hasGradientMode)
@@ -2991,7 +3028,12 @@ static int VBackground (Draw_Interpretor& theDI,
     aCubeMap->GetParams()->SetRepeat (false);
     aCubeMap->GetParams()->SetTextureUnit (Graphic3d_TextureUnit_EnvMap);
 
-    aView->SetBackgroundCubeMap (aCubeMap, isCubeGenPBREnv);
+    aView->SetBackgroundCubeMap (aCubeMap, toUseIBL != -1);
+  }
+  if (toUseIBL != -1
+  && !aView.IsNull())
+  {
+    aView->SetImageBasedLighting (toUseIBL == 1);
   }
 
   return 0;
@@ -13661,7 +13703,8 @@ void ViewerTest::ViewerCommands(Draw_Interpretor& theCommands)
     "\n\t\t:            [-gradient Color1 Color2 [-default]"
     "\n\t\t:            [-gradientMode {NONE|HORIZONTAL|VERTICAL|DIAG1|DIAG2|CORNER1|CORNER2|CORNER3|ELLIPTICAL}]=VERT]"
     "\n\t\t:            [-imageFile ImageFile [-imageMode {CENTERED|TILED|STRETCH|NONE}]=CENTERED [-srgb {0|1}]=1]"
-    "\n\t\t:            [-cubemap CubemapFile1 [CubeMapFiles2-5] [-order TilesIndexes1-6] [-invertedz]=0 [-pbrEnv {0|1}]=1]"
+    "\n\t\t:            [-cubemap CubemapFile1 [CubeMapFiles2-5] [-order TilesIndexes1-6] [-invertedz]=0]"
+    "\n\t\t:            [-pbrEnv {ibl|noibl|keep}]"
     "\n\t\t: Changes background or some background settings."
     "\n\t\t:  -color        sets background color"
     "\n\t\t:  -gradient     sets background gradient starting and ending colors"
@@ -13671,7 +13714,7 @@ void ViewerTest::ViewerCommands(Draw_Interpretor& theCommands)
     "\n\t\t:  -imageMode    sets image fill type"
     "\n\t\t:  -cubemap      sets environment cubemap as background"
     "\n\t\t:  -invertedz    sets inversion of Z axis for background cubemap rendering; FALSE when unspecified"
-    "\n\t\t:  -pbrEnv       sets PBR environment baking flag while updating cubemap; TRUE when unspecified"
+    "\n\t\t:  -pbrEnv       sets on/off Image Based Lighting (IBL) from background cubemap for PBR"
     "\n\t\t:  -srgb         prefer sRGB texture format when applicable; TRUE when unspecified"
     "\n\t\t:  -order        defines order of tiles in one image cubemap"
     "\n\t\t:    TileIndexi defubes an index in range [0, 5] for i tile of one image packed cubemap"

tests/opengl/data/textures/cubemap_ibl

@@ -0,0 +1,25 @@
+puts "============"
+puts "0032590: Visualization, V3d_View - improve API for setting Image Based Lighting"
+puts "============"
+puts ""
+
+set aCubeMapLabs [locate_data_file cubemap_labels.png]
+
+pload MODELING VISUALIZATION
+
+# PBR doesn't work with Compatible Profile on macOS
+if { $::tcl_platform(os) == "Darwin" } { vcaps -core }
+
+vclear
+vclose ALL
+source $env(CSF_OCCTSamplesPath)/tcl/vis_pbr_spheres.tcl
+vcamera -fovy 100
+
+vbackground -cubemap $aCubeMapLabs -pbrEnv noIBL
+vdump $imagedir/${casename}_1.png
+
+vbackground -pbrEnv IBL
+vdump $imagedir/${casename}_2.png
+
+vbackground BLACK -pbrEnv KEEP
+vdump $imagedir/${casename}_3.png