Representation of invalid HdSceneIndexPrim

ppt-adsk · October 20, 2023, 3:18pm

It is often very convenient to have a concept of an invalid object, to represent error conditions or invalid queries. An invalid HdSceneIndexPrim

github.com

PixarAnimationStudios/OpenUSD/blob/10b62439e9242a55101cf8b200f2c7e02420e1b0/pxr/imaging/hd/sceneIndex.h#L51


      
          #include "pxr/imaging/hd/dataSourceLocator.h"
          #include "pxr/imaging/hd/sceneIndexObserver.h"
          
          PXR_NAMESPACE_OPEN_SCOPE
          
          
          ///
          /// Small struct representing a 'prim' in the Hydra scene index. A prim is
          /// represented by a container data source which contains a tree of properties.
          ///
          struct HdSceneIndexPrim
          {
              TfToken primType;
              HdContainerDataSourceHandle dataSource;
          };
          
          ///
          /// \class HdSceneIndexBase
          ///
          /// Abstract interface to scene data. This class can be queried for scene
          /// data directly, and it can also register observers to be notified about

seems to be one that has a null data source, as demonstrated here:

github.com

PixarAnimationStudios/OpenUSD/blob/10b62439e9242a55101cf8b200f2c7e02420e1b0/pxr/imaging/hd/mergingSceneIndex.cpp#L217


      
          }
          
          HdSceneIndexPrim
          HdMergingSceneIndex::GetPrim(const SdfPath &primPath) const
          {
              TRACE_FUNCTION();
          
              HdSceneIndexPrim result;
          
              if (_inputs.size() == 0) {
                  return result;
              }
          
              if (_inputs.size() == 1) {
                  return _inputs[0].sceneIndex->GetPrim(primPath);
              }
          
              TfSmallVector<HdContainerDataSourceHandle, 8> contributingDataSources;
              for (const _InputEntry &entry : _inputs) {
                  if (primPath.HasPrefix(entry.sceneRoot)) {
                      HdSceneIndexPrim prim = entry.sceneIndex->GetPrim(primPath);

It appears that it is legal for the prim type to be empty for a valid prim, which is then a typeless prim. Only the dataSource data member determines an invalid prim, when it is null. Is this interpretation correct?

My uncertainty is based on the fact that a retained scene index uses an SdfPathTable to store prims:

github.com

PixarAnimationStudios/OpenUSD/blob/10b62439e9242a55101cf8b200f2c7e02420e1b0/pxr/imaging/hd/retainedSceneIndex.h#L107


      
              HdRetainedSceneIndex();
          
          private:
          
              struct _PrimEntry
              {
                  HdSceneIndexPrim prim;
              };
          
              using _PrimEntryTable = SdfPathTable<_PrimEntry>;
              _PrimEntryTable _entries;
          
          };
          
          PXR_NAMESPACE_CLOSE_SCOPE
          
          #endif // PXR_IMAGING_HD_RETAINED_SCENE_INDEX_H

And SdfPathTable inserts missing ancestors on inserting a prim:

github.com

PixarAnimationStudios/OpenUSD/blob/10b62439e9242a55101cf8b200f2c7e02420e1b0/pxr/usd/sdf/pathTable.h#L53


      
          void Sdf_VisitPathTableInParallel(void **, size_t, TfFunctionRef<void(void*&)>);
          
          /// \class SdfPathTable
          ///
          /// A mapping from SdfPath to \a MappedType, somewhat similar to map<SdfPath,
          /// MappedType> and TfHashMap<SdfPath, MappedType>, but with key
          /// differences.  Notably:
          ///
          /// Works exclusively with absolute paths.
          ///
          /// Inserting a path \a p also implicitly inserts all of \a p's ancestors.
          ///
          /// Erasing a path \a p also implicitly erases all of \a p's descendants.
          ///
          /// The table has an order: it's a preordering of the paths in the table, but
          /// with arbitrary sibling order.  Given a path \a p in the table, all other
          /// paths in the table with \a p as a prefix appear contiguously, immediately
          /// following \a p.  For example, suppose a table contains the paths:
          ///
          ///   {'/a/b/c', '/a', '/a/d', '/', '/a/b'}
          ///

However, inserted ancestors are inserted with the default mapped type:

github.com

PixarAnimationStudios/OpenUSD/blob/10b62439e9242a55101cf8b200f2c7e02420e1b0/pxr/usd/sdf/pathTable.h#L722


      
          static SdfPath _GetParentPath(SdfPath const &path) {
              return path.GetParentPath();
          }
          
          void _UpdateTreeForNewEntry(_IterBoolPair const &iresult) {
              // New element -- make sure the parent is inserted.
              _Entry * const newEntry = iresult.first._entry;
              SdfPath const &parentPath = _GetParentPath(newEntry->value.first);
              if (!parentPath.IsEmpty()) {
                  iterator parIter =
                      insert(value_type(parentPath, mapped_type())).first;
                  // Add the new entry to the parent's children.
                  parIter._entry->AddChild(newEntry);
              }
          }
          
          // Helper to insert \a value in the hash table.  Is responsible for growing
          // storage space when necessary.  Does not consider the tree structure.
          template <class MakeEntryFn>
          _IterBoolPair _InsertInTableImpl(key_type const &key,
                                           MakeEntryFn &&makeEntry) {

which for HdSceneIndexPrim is a prim with a null data source.

Therefore, a retained scene index can return prims that have a null data source. Hopefully someone can explain what appears to me to be a discrepancy. Thanks for any help!

Pierre

tomc · November 18, 2023, 12:36am

You’re correct that we do have typeless prims with data. I think sometimes we have typeless prims without data (but which have a path, and might later get data), and currently those are represented by a null datasource; I don’t think that’s semantically a problem, although it requires a null check before you refer to the datasource. Does that all make sense?

I guess if we wanted an invalid value with a null datasource, we could have the default constructor refer to a static empty container datasource.