include/opencascade/BRepGraphInc_Populate.hxx

0001 // Copyright (c) 2026 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _BRepGraphInc_Populate_HeaderFile
0015 #define _BRepGraphInc_Populate_HeaderFile
0016
0017 #include <BRepGraph_NodeId.hxx>
0018 #include <NCollection_LinearVector.hxx>
0019 #include <Standard_DefineAlloc.hxx>
0020 #include <Standard_Handle.hxx>
0021
0022 class TopoDS_Shape;
0023 class BRepGraph;
0024
0025 //! @brief Backend topology/geometry population for BRepGraph.
0026 //!
0027 //! This class is part of the BRepGraphInc backend and is intended for
0028 //! backend maintenance, tests, and low-level infrastructure only.
0029 //! External code should enter through BRepGraph::ShapesView::Add(), which owns the
0030 //! public lifecycle, cache invalidation, and layer coordination.
0031 //!
0032 //! The builder stores forward child relations only. Reverse relations are rebuilt
0033 //! by BRepGraphInc_Storage after population.
0034 class BRepGraphInc_Populate
0035 {
0036 public:
0037   DEFINE_STANDARD_ALLOC
0038
0039   //! Result of a build operation.
0040   enum class BuildStatus
0041   {
0042     Success,             //!< All faces built successfully.
0043     SuccessWithWarnings, //!< Build completed with diagnostics, e.g. unbounded natural faces.
0044     Failed               //!< Build failed (e.g., null shape, internal error).
0045   };
0046
0047   //! Options controlling population.
0048   struct Options
0049   {
0050   };
0051
0052   //! Build backend incidence storage from a TopoDS_Shape.
0053   //! @param[out] theGraph    graph whose storage to populate (cleared first)
0054   //! @param[in]  theShape    root shape
0055   //! @param[in]  theParallel if true, face-level extraction runs in parallel
0056   //! @param[in]  theOptions  optional post-pass controls
0057   //! @return build status indicating success, warnings, or failure
0058   [[nodiscard]] static Standard_EXPORT BuildStatus Perform(BRepGraph&          theGraph,
0059                                                            const TopoDS_Shape& theShape,
0060                                                            bool                theParallel,
0061                                                            const Options& theOptions = Options());
0062
0063   //! Extend existing backend storage with additional shapes (no clear).
0064   //! Flattens hierarchy containers away; Solid/Shell/Compound/CompSolid inputs
0065   //! contribute appended face roots instead of container entities.
0066   //! Recomputes the built-in metadata layers from the populated storage.
0067   //! @param[in,out] theGraph         graph whose storage to extend
0068   //! @param[in]     theShape         shape to append
0069   //! @param[in]     theParallel      if true, face-level extraction runs in parallel
0070   //! @param[out]    theAppendedRoots collected root NodeIds for non-container shapes
0071   //! @param[in]     theOptions       optional post-pass controls
0072   //! @return build status indicating success, warnings, or failure
0073   [[nodiscard]] static Standard_EXPORT BuildStatus
0074     AppendFlattened(BRepGraph&                                  theGraph,
0075                     const TopoDS_Shape&                         theShape,
0076                     bool                                        theParallel,
0077                     NCollection_LinearVector<BRepGraph_NodeId>& theAppendedRoots,
0078                     const Options&                              theOptions = Options());
0079
0080   //! Extend existing backend storage with additional shapes (no clear).
0081   //! Preserves the full shape hierarchy: Solid/Shell/Compound/CompSolid nodes
0082   //! are created alongside Face/Edge/Vertex nodes. Shapes already present in
0083   //! the storage with the same definition identity (TShape + Location, orientation ignored)
0084   //! are deduplicated and not re-added.
0085   //! @param[in,out] theGraph    graph whose storage to extend
0086   //! @param[in]     theShape    shape to append
0087   //! @param[in]     theParallel if true, face-level extraction runs in parallel
0088   //! @param[in]     theOptions  optional post-pass controls
0089   //! @return build status indicating success, warnings, or failure
0090   [[nodiscard]] static Standard_EXPORT BuildStatus Append(BRepGraph&          theGraph,
0091                                                           const TopoDS_Shape& theShape,
0092                                                           bool                theParallel,
0093                                                           const Options& theOptions = Options());
0094
0095   BRepGraphInc_Populate() = delete;
0096 };
0097
0098 #endif // _BRepGraphInc_Populate_HeaderFile