0032086: Visualization - support deferred data loading

1) Extend Poly_Triangulation by mesh purpose, possibility to be cleared and late-load deferred data interfaces.
2) Update BRep_TFace to store list of triangulations istead of single one. And also active one. Update getter and setter of single triangulation and add new methods to interaction with whole triangulations list.
3) Update BRep_Tool to get single triangulation of face according to the input mesh purpose or whole triangulations list.
4) Update BRep_Builder to make face by not only single triangulation but whole triangulations list with specified active one.
5) Add new methods to BRepTools to interact with shape triangulations (Load/Unload/Activate/LoadAll/UnloadAllTriangulation(s))
6) Add new 'tlateload'command for shape to load/unload/activate triangulations.
7) Update 'trinfo' command by '-lods' options to print detailaed information about LODs of this shape
8) Support empty triangulations by selection. Use bounding box selection in this case.
9) Add new 'outdisplist' option to XDispaly command to print list of displayed objects to output variable but not to theDI
10) Add new '-noecho' option to vdisplay command to skip printing of displayed objects to theDI
11) Create new RWMesh_TriangulationSource as mesh data wrapper for delayed triangulation loading.
12) Create new RWMesh_TriangulationReader as base interface for reading primitive array from the buffer.
13) Cache nodes/triangles number defined in glTF file
14) Use RWMesh_TriangulationSource class as base of RWGltf_GltfLatePrimitiveArray one and RWMesh_TriangulationReader class as base of RWGltf_TriangulationReader one
15) Add possibilty to support of LODs by glTF reader. It is possible to skip data loading and load them later
16) Add new '-skiplateloading' (to skip triangulation loading), '-keeplate' (to keep information about deferred storage to load/unload triangulation later),
'-toprintdebuginfo' (to print additional debug information) options to ReadGltf command
17) Add new test of glTF late loading

src/Poly/FILES

@@ -21,6 +21,7 @@ Poly_HArray1OfTriangle.hxx
 Poly_ListOfTriangulation.hxx
 Poly_MakeLoops.cxx
 Poly_MakeLoops.hxx
+Poly_MeshPurpose.hxx
 Poly_Polygon2D.cxx
 Poly_Polygon2D.hxx
 Poly_Polygon3D.cxx

src/Poly/Poly_MeshPurpose.hxx

@@ -0,0 +1,33 @@
+// Copyright (c) 2021 OPEN CASCADE SAS
+//
+// This file is part of Open CASCADE Technology software library.
+//
+// This library is free software; you can redistribute it and/or modify it under
+// the terms of the GNU Lesser General Public License version 2.1 as published
+// by the Free Software Foundation, with special exception defined in the file
+// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
+// distribution for complete text of the license and disclaimer of any warranty.
+//
+// Alternatively, this file may be used under the terms of Open CASCADE
+// commercial license or contractual agreement.
+
+#ifndef _Poly_MeshPurpose_HeaderFile
+#define _Poly_MeshPurpose_HeaderFile
+
+//! Purpose of triangulation using.
+typedef unsigned int Poly_MeshPurpose;
+enum
+{
+  // main flags
+  Poly_MeshPurpose_NONE               = 0,      //!< no special use (default)
+  Poly_MeshPurpose_Calculation        = 0x0001, //!< mesh for algorithms
+  Poly_MeshPurpose_Presentation       = 0x0002, //!< mesh for presentation (LODs usage)
+  // special purpose bits (should not be set externally)
+  Poly_MeshPurpose_Active             = 0x0004, //!< mesh marked as currently active in a list
+  Poly_MeshPurpose_Loaded             = 0x0008, //!< mesh has currently loaded data
+  Poly_MeshPurpose_AnyFallback        = 0x0010, //!< a special flag for BRep_Tools::Triangulation() to return any other defined mesh,
+                                                //   if none matching other criteria was found user-defined flags should have higher values
+  Poly_MeshPurpose_USER               = 0x0020  //!< application-defined flags
+};
+
+#endif // _Poly_MeshPurpose_HeaderFile

src/Poly/Poly_Triangulation.cxx

@@ -17,6 +17,7 @@
 #include <Poly_Triangulation.hxx>
 
 #include <gp_Pnt.hxx>
+#include <OSD_FileSystem.hxx>
 #include <Poly_Triangle.hxx>
 #include <Standard_Dump.hxx>
 #include <Standard_Type.hxx>
@@ -29,7 +30,8 @@ IMPLEMENT_STANDARD_RTTIEXT (Poly_Triangulation, Standard_Transient)
 //=======================================================================
 Poly_Triangulation::Poly_Triangulation()
 : myCachedMinMax (NULL),
-  myDeflection   (0)
+  myDeflection   (0),
+  myPurpose      (Poly_MeshPurpose_NONE)
 {
   //
 }
@@ -45,7 +47,8 @@ Poly_Triangulation::Poly_Triangulation (const Standard_Integer theNbNodes,
 : myCachedMinMax (NULL),
   myDeflection(0),
   myNodes     (theNbNodes),
-  myTriangles (1, theNbTriangles)
+  myTriangles (1, theNbTriangles),
+  myPurpose   (Poly_MeshPurpose_NONE)
 {
   if (theHasUVNodes)
   {
@@ -66,7 +69,8 @@ Poly_Triangulation::Poly_Triangulation (const TColgp_Array1OfPnt&    theNodes,
 : myCachedMinMax (NULL),
   myDeflection   (0),
   myNodes        (theNodes.Length()),
-  myTriangles    (1, theTriangles.Length())
+  myTriangles    (1, theTriangles.Length()),
+  myPurpose      (Poly_MeshPurpose_NONE)
 {
   const Poly_ArrayOfNodes aNodeWrapper (theNodes.First(), theNodes.Length());
   myNodes = aNodeWrapper;
@@ -85,7 +89,8 @@ Poly_Triangulation::Poly_Triangulation (const TColgp_Array1OfPnt&    theNodes,
   myDeflection   (0),
   myNodes        (theNodes.Length()),
   myTriangles    (1, theTriangles.Length()),
-  myUVNodes      (theNodes.Length())
+  myUVNodes      (theNodes.Length()),
+  myPurpose      (Poly_MeshPurpose_NONE)
 {
   const Poly_ArrayOfNodes aNodeWrapper (theNodes.First(), theNodes.Length());
   myNodes = aNodeWrapper;
@@ -124,11 +129,33 @@ Poly_Triangulation::Poly_Triangulation (const Handle(Poly_Triangulation)& theTri
   myNodes     (theTriangulation->myNodes),
   myTriangles (theTriangulation->myTriangles),
   myUVNodes   (theTriangulation->myUVNodes),
-  myNormals   (theTriangulation->myNormals)
+  myNormals   (theTriangulation->myNormals),
+  myPurpose   (theTriangulation->myPurpose)
 {
   SetCachedMinMax (theTriangulation->CachedMinMax());
 }
 
+//=======================================================================
+//function : Clear
+//purpose  : 
+//=======================================================================
+void Poly_Triangulation::Clear()
+{
+  if (!myNodes.IsEmpty())
+  {
+    Poly_ArrayOfNodes anEmptyNodes;
+    anEmptyNodes.SetDoublePrecision (myNodes.IsDoublePrecision());
+    myNodes.Move (anEmptyNodes);
+  }
+  if (!myTriangles.IsEmpty())
+  {
+    Poly_Array1OfTriangle anEmptyTriangles;
+    myTriangles.Move(anEmptyTriangles);
+  }
+  RemoveUVNodes();
+  RemoveNormals();
+}
+
 //=======================================================================
 //function : RemoveUVNodes
 //purpose  :
@@ -354,6 +381,8 @@ void Poly_Triangulation::DumpJson (Standard_OStream& theOStream, Standard_Intege
   if (!myNormals.IsEmpty())
     OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myNormals.Size())
   OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myTriangles.Size())
+  OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myPurpose)
+
 }
 
 // =======================================================================
@@ -483,3 +512,55 @@ void Poly_Triangulation::ComputeNormals()
     aNorm3f = aMod == 0.0f ? gp_Vec3f (0.0f, 0.0f, 1.0f) : (aNorm3f / aMod);
   }
 }
+
+//=======================================================================
+//function : LoadDeferredData
+//purpose  :
+//=======================================================================
+Standard_Boolean Poly_Triangulation::LoadDeferredData (const Handle(OSD_FileSystem)& theFileSystem)
+{
+  if (!HasDeferredData())
+  {
+    return false;
+  }
+  if (!loadDeferredData (theFileSystem, this))
+  {
+    return false;
+  }
+  SetMeshPurpose (myPurpose | Poly_MeshPurpose_Loaded);
+  return true;
+}
+
+//=======================================================================
+//function : DetachedLoadDeferredData
+//purpose  :
+//=======================================================================
+Handle(Poly_Triangulation) Poly_Triangulation::DetachedLoadDeferredData (const Handle(OSD_FileSystem)& theFileSystem) const
+{
+  if (!HasDeferredData())
+  {
+    return Handle(Poly_Triangulation)();
+  }
+  Handle(Poly_Triangulation) aResult = createNewEntity();
+  if (!loadDeferredData(theFileSystem, aResult))
+  {
+    return Handle(Poly_Triangulation)();
+  }
+  aResult->SetMeshPurpose(aResult->MeshPurpose() | Poly_MeshPurpose_Loaded);
+  return aResult;
+}
+
+//=======================================================================
+//function : UnloadDeferredData
+//purpose  :
+//=======================================================================
+Standard_Boolean Poly_Triangulation::UnloadDeferredData()
+{
+  if (HasDeferredData())
+  {
+    Clear();
+    SetMeshPurpose (myPurpose & ~Poly_MeshPurpose_Loaded);
+    return true;
+  }
+  return false;
+}

src/Poly/Poly_Triangulation.hxx

@@ -22,10 +22,12 @@
 #include <Poly_HArray1OfTriangle.hxx>
 #include <Poly_ArrayOfNodes.hxx>
 #include <Poly_ArrayOfUVNodes.hxx>
+#include <Poly_MeshPurpose.hxx>
 #include <TColgp_HArray1OfPnt.hxx>
 #include <TColgp_HArray1OfPnt2d.hxx>
 #include <TShort_HArray1OfShortReal.hxx>
 
+class OSD_FileSystem;
 class Poly_Triangulation;
 DEFINE_STANDARD_HANDLE(Poly_Triangulation, Standard_Transient)
 
@@ -105,6 +107,9 @@ public:
   //! See more on deflection in Polygon2D
   void Deflection (const Standard_Real theDeflection) { myDeflection = theDeflection; }
 
+  //! Clears internal arrays of nodes and all attributes.
+  Standard_EXPORT virtual void Clear();
+
   //! Returns TRUE if triangulation has some geometry.
   virtual Standard_Boolean HasGeometry() const { return !myNodes.IsEmpty() && !myTriangles.IsEmpty(); }
 
@@ -180,6 +185,12 @@ public:
                                    float(theNormal.Z())));
   }
 
+  //! Returns mesh purpose bits.
+  Poly_MeshPurpose MeshPurpose() const { return myPurpose; }
+
+  //! Sets mesh purpose bits.
+  void SetMeshPurpose (const Poly_MeshPurpose thePurpose) { myPurpose = thePurpose; }
+
   //! Returns cached min - max range of triangulation data,
   //! which is VOID by default (e.g, no cached information).
   Standard_EXPORT const Bnd_Box& CachedMinMax() const;
@@ -246,7 +257,7 @@ public:
   //! If an array for normals is not allocated yet, do it now.
   Standard_EXPORT void AddNormals();
 
-  //! Deallocates the Normals array.
+  //! Deallocates the normals array.
   Standard_EXPORT void RemoveNormals();
 
   //! Compute smooth normals by averaging triangle normals.
@@ -304,6 +315,50 @@ public:
   Standard_DEPRECATED("Deprecated method, SetTriangle() should be used instead")
   Poly_Triangle& ChangeTriangle (const Standard_Integer theIndex) { return myTriangles.ChangeValue (theIndex); }
 
+public: //! @name late-load deferred data interface
+
+  //! Returns number of deferred nodes that can be loaded using LoadDeferredData().
+  //! Note: this is estimated values, which might be different from actually loaded values.
+  //! Always check triangulation size of actually loaded data in code to avoid out-of-range issues.
+  virtual Standard_Integer NbDeferredNodes() const { return 0; }
+
+  //! Returns number of deferred triangles that can be loaded using LoadDeferredData().
+  //! Note: this is estimated values, which might be different from actually loaded values
+  //! Always check triangulation size of actually loaded data in code to avoid out-of-range issues.
+  virtual Standard_Integer NbDeferredTriangles() const { return 0; }
+
+  //! Returns TRUE if there is some triangulation data that can be loaded using LoadDeferredData().
+  virtual Standard_Boolean HasDeferredData() const { return NbDeferredTriangles() > 0; }
+
+  //! Loads triangulation data into itself
+  //! from some deferred storage using specified shared input file system.
+  Standard_EXPORT virtual Standard_Boolean LoadDeferredData (const Handle(OSD_FileSystem)& theFileSystem = Handle(OSD_FileSystem)());
+
+  //! Loads triangulation data into new Poly_Triangulation object
+  //! from some deferred storage using specified shared input file system.
+  Standard_EXPORT virtual Handle(Poly_Triangulation) DetachedLoadDeferredData
+    (const Handle(OSD_FileSystem)& theFileSystem = Handle(OSD_FileSystem)()) const;
+
+  //! Releases triangulation data if it has connected deferred storage.
+  Standard_EXPORT virtual Standard_Boolean UnloadDeferredData();
+
+protected:
+
+  //! Creates new triangulation object (can be inheritor of Poly_Triangulation).
+  virtual Handle(Poly_Triangulation) createNewEntity() const
+  {
+    return new Poly_Triangulation();
+  }
+
+  //! Load triangulation data from deferred storage using specified shared input file system.
+  virtual Standard_Boolean loadDeferredData (const Handle(OSD_FileSystem)& theFileSystem,
+                                             const Handle(Poly_Triangulation)& theDestTriangulation) const
+  {
+    (void )theFileSystem;
+    (void )theDestTriangulation;
+    return false;
+  }
+
 protected:
 
   //! Clears cached min - max range saved previously.
@@ -321,6 +376,7 @@ protected:
   Poly_Array1OfTriangle        myTriangles;
   Poly_ArrayOfUVNodes          myUVNodes;
   NCollection_Array1<gp_Vec3f> myNormals;
+  Poly_MeshPurpose             myPurpose;
 
 };