All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdImagingInstanceAdapter Class Reference

Delegate support for instanced prims. More...

+ Inheritance diagram for UsdImagingInstanceAdapter:

Public Types

using BaseAdapter = UsdImagingPrimAdapter
 

Public Member Functions

virtual SdfPath Populate (UsdPrim const &prim, UsdImagingIndexProxy *index, UsdImagingInstancerContext const *instancerContext=nullptr) override
 Called to populate the RenderIndex for this UsdPrim. More...
 
virtual bool ShouldCullChildren () const override
 
virtual bool IsInstancerAdapter () const override
 
Parallel Setup and Resolve
virtual void TrackVariability (UsdPrim const &prim, SdfPath const &cachePath, HdDirtyBits *timeVaryingBits, UsdImagingInstancerContext const *instancerContext=NULL) const override
 For the given prim, variability is detected and stored in timeVaryingBits. More...
 
virtual void UpdateForTime (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time, HdDirtyBits requestedBits, UsdImagingInstancerContext const *instancerContext=NULL) const override
 Populates the cache for the given prim, time and requestedBits. More...
 
Change Processing
virtual HdDirtyBits ProcessPropertyChange (UsdPrim const &prim, SdfPath const &cachePath, TfToken const &propertyName) override
 Returns a bit mask of attributes to be updated, or HdChangeTracker::AllDirty if the entire prim must be resynchronized. More...
 
virtual void ProcessPrimResync (SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 When a PrimResync event occurs, the prim may have been deleted entirely, adapter plug-ins should override this method to free any per-prim state that was accumulated in the adapter. More...
 
virtual void ProcessPrimRemoval (SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 Removes all associated Rprims and dependencies from the render index without scheduling them for repopulation. More...
 
virtual void MarkDirty (UsdPrim const &prim, SdfPath const &cachePath, HdDirtyBits dirty, UsdImagingIndexProxy *index) override
 
virtual void MarkRefineLevelDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
virtual void MarkReprDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
virtual void MarkCullStyleDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
virtual void MarkRenderTagDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
virtual void MarkTransformDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
virtual void MarkVisibilityDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index) override
 
Instancing
std::vector< VtArray< TfToken > > GetInstanceCategories (UsdPrim const &prim) override
 Return an array of the categories used by each instance. More...
 
GfMatrix4d GetInstancerTransform (UsdPrim const &instancerPrim, SdfPath const &instancerPath, UsdTimeCode time) const override
 Get the instancer transform for the given prim. More...
 
size_t SampleInstancerTransform (UsdPrim const &instancerPrim, SdfPath const &instancerPath, UsdTimeCode time, size_t maxSampleCount, float *sampleTimes, GfMatrix4d *sampleValues) override
 Sample the instancer transform for the given prim. More...
 
size_t SampleTransform (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time, size_t maxNumSamples, float *sampleTimes, GfMatrix4d *sampleValues) override
 Samples the transform for the given prim. More...
 
size_t SamplePrimvar (UsdPrim const &usdPrim, SdfPath const &cachePath, TfToken const &key, UsdTimeCode time, size_t maxNumSamples, float *sampleTimes, VtValue *sampleValues) override
 Sample the primvar for the given prim. More...
 
TfToken GetPurpose (UsdPrim const &usdPrim, SdfPath const &cachePath, TfToken const &instanceInheritablePurpose) const override
 Returns the purpose token for prim. More...
 
PxOsdSubdivTags GetSubdivTags (UsdPrim const &usdPrim, SdfPath const &cachePath, UsdTimeCode time) const override
 Get the subdiv tags for this prim. More...
 
VtValue GetTopology (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time) const override
 Gets the topology object of a specific Usd prim. More...
 
HdCullStyle GetCullStyle (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time) const override
 Gets the cullstyle of a specific path in the scene graph. More...
 
GfRange3d GetExtent (UsdPrim const &usdPrim, SdfPath const &cachePath, UsdTimeCode time) const override
 Reads the extent from the given prim. More...
 
bool GetVisible (UsdPrim const &usdPrim, SdfPath const &cachePath, UsdTimeCode time) const override
 Returns true if the given prim is visible, taking into account inherited visibility values. More...
 
bool GetDoubleSided (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time) const override
 Reads double-sided from the given prim. If not authored, returns false. More...
 
GfMatrix4d GetTransform (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time, bool ignoreRootTransform=false) const override
 Fetches the transform for the given prim at the given time from a pre-computed cache of prim transforms. More...
 
SdfPath GetMaterialId (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time) const override
 
HdExtComputationInputDescriptorVector GetExtComputationInputs (UsdPrim const &prim, SdfPath const &cachePath, const UsdImagingInstancerContext *instancerContext) const override
 
HdExtComputationOutputDescriptorVector GetExtComputationOutputs (UsdPrim const &prim, SdfPath const &cachePath, const UsdImagingInstancerContext *instancerContext) const override
 
HdExtComputationPrimvarDescriptorVector GetExtComputationPrimvars (UsdPrim const &prim, SdfPath const &cachePath, HdInterpolation interpolation, const UsdImagingInstancerContext *instancerContext) const override
 
VtValue GetExtComputationInput (UsdPrim const &prim, SdfPath const &cachePath, TfToken const &name, UsdTimeCode time, const UsdImagingInstancerContext *instancerContext) const override
 
std::string GetExtComputationKernel (UsdPrim const &prim, SdfPath const &cachePath, const UsdImagingInstancerContext *instancerContext) const override
 
VtValue Get (UsdPrim const &prim, SdfPath const &cachePath, TfToken const &key, UsdTimeCode time) const override
 Gets the value of the parameter named key for the given prim (which has the given cache path) and given time. More...
 
Nested instancing support
virtual GfMatrix4d GetRelativeInstancerTransform (SdfPath const &parentInstancerPath, SdfPath const &instancerPath, UsdTimeCode time) const override
 Returns the transform of protoInstancerPath relative to instancerPath. More...
 
Picking & selection
virtual SdfPath GetScenePrimPath (SdfPath const &cachePath, int instanceIndex, HdInstancerContext *instancerContext) const override
 
virtual bool PopulateSelection (HdSelection::HighlightMode const &highlightMode, SdfPath const &cachePath, UsdPrim const &usdPrim, int const hydraInstanceIndex, VtIntArray const &parentInstanceIndices, HdSelectionSharedPtr const &result) const override
 
- Public Member Functions inherited from UsdImagingPrimAdapter
virtual USDIMAGING_API HdDirtyBits ProcessPrimChange (UsdPrim const &prim, SdfPath const &cachePath, TfTokenVector const &changedFields)
 Returns a bit mask of attributes to be updated, or HdChangeTracker::AllDirty if the entire prim must be resynchronized. More...
 
virtual USDIMAGING_API void MarkMaterialDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index)
 
virtual USDIMAGING_API void MarkLightParamsDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index)
 
virtual USDIMAGING_API void MarkWindowPolicyDirty (UsdPrim const &prim, SdfPath const &cachePath, UsdImagingIndexProxy *index)
 
virtual USDIMAGING_API void InvokeComputation (SdfPath const &cachePath, HdExtComputationContext *context)
 
USDIMAGING_API GfMatrix4d GetRootTransform () const
 The root transform provided by the delegate. More...
 
USDIMAGING_API void SetDelegate (UsdImagingDelegate *delegate)
 A thread-local XformCache provided by the delegate. More...
 
USDIMAGING_API bool IsChildPath (SdfPath const &path) const
 
USDIMAGING_API TfToken GetInheritablePurpose (UsdPrim const &prim) const
 Returns the purpose token for prim, but only if it is inheritable by child prims (i.e. More...
 
USDIMAGING_API SdfPath GetMaterialUsdPath (UsdPrim const &prim) const
 Gets the material path for the given prim, walking up namespace if necessary. More...
 
USDIMAGING_API TfToken GetModelDrawMode (UsdPrim const &prim)
 Gets the model:drawMode attribute for the given prim, walking up the namespace if necessary. More...
 
USDIMAGING_API VtArray
< VtIntArray > 
GetPerPrototypeIndices (UsdPrim const &prim, UsdTimeCode time) const
 Computes the per-prototype instance indices for a UsdGeomPointInstancer. More...
 
virtual USDIMAGING_API VtValue GetMaterialResource (UsdPrim const &prim, SdfPath const &cachePath, UsdTimeCode time) const
 
virtual USDIMAGING_API const
TfTokenVector
GetExtComputationSceneInputNames (SdfPath const &cachePath) const
 
virtual bool IsSupported (UsdImagingIndexProxy const *index) const
 Returns true if the adapter can be populated into the target index. More...
 
 UsdImagingPrimAdapter ()
 
virtual USDIMAGING_API ~UsdImagingPrimAdapter ()
 
virtual USDIMAGING_API bool ShouldIgnoreNativeInstanceSubtrees () const
 
virtual USDIMAGING_API bool CanPopulateUsdInstance () const
 

Volume field information

virtual
HdVolumeFieldDescriptorVector 
GetVolumeFieldDescriptors (UsdPrim const &usdPrim, SdfPath const &id, UsdTimeCode time) const override
 
virtual void _RemovePrim (SdfPath const &cachePath, UsdImagingIndexProxy *index) overridefinal
 

Detailed Description

Delegate support for instanced prims.

In addition to prim schemas that support instancing, like the point instancer, USD has a built in instancing feature that will allow prims composed from the same assets, with compatible attributes, to be de-duplicated inside of USD.

When these prims are found during scene load, the prim location is marked as an instance (meaning prim.IsInstance() == true), and its descendants are added to a new hidden scene root. There can be multiple prototype scene roots, and each one can be pointed to by many instance prims, and these prototype sub-scenes can themselves contain instances.

We handle this by sending all instance prims to the instance adapter. In order to preserve USD's native instancing work during rendering, for each prototype scene root, we insert one hydra gprim per prototype USD gprim, and we insert a hydra instancer that computes all of the places these gprims (and any child instancers) are referenced in the scene, adjusting the instancing count accordingly.

The instance adapter is responsible for computing and passing down a small amount of inheritable data that we allow to vary per-instance: for example, transform and visibility state, and inherited constant primvars. Otherwise, prototypes have no knowledge of the instance prims that refer to them.

Just like the scene root, the root of the prototype tree isn't allowed to have attributes or a prim type; those are set on the instance prim instead. This means if a gprim is directly instanced, USD won't actually de-duplicate it. The instance adapter could theoretically bucket such gprims together, but the difficulty of doing so is the same as the difficulty of deduplicating arbitrary prims in the scene. Instead, the instance adapter refuses to image directly-instanced gprims, and the recommended authoring guidelines is to only enable USD instancing on enclosing scopes or xforms.

There's a small set of extremely-special-case prims that are allowed to be directly instanced, including cards and support prims that designate e.g. skinning buffers. These prim adapters opt-in via CanPopulateUsdInstance, and generally require very careful coding and support in the instance adapter; but they are useful for restricted schemas where we know how to vary the data per-instance or know how to efficiently aggregate instances.

Finally, there's a small (hopefully shrinking) set of inherited attributes that we need to respect, but don't know how to vary per-instance; for example, material bindings. If two instances point to the same USD proto root, but have different material bindings, we currently populate two hydra instancers with two sets of hydra prototypes. This cuts into the efficiency of instancing, so we try to minimize it.

Definition at line 91 of file instanceAdapter.h.

Member Function Documentation

VtValue Get ( UsdPrim const &  prim,
SdfPath const &  cachePath,
TfToken const &  key,
UsdTimeCode  time 
) const
overridevirtual

Gets the value of the parameter named key for the given prim (which has the given cache path) and given time.

Reimplemented from UsdImagingPrimAdapter.

HdCullStyle GetCullStyle ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Gets the cullstyle of a specific path in the scene graph.

Reimplemented from UsdImagingPrimAdapter.

bool GetDoubleSided ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Reads double-sided from the given prim. If not authored, returns false.

Reimplemented from UsdImagingPrimAdapter.

GfRange3d GetExtent ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Reads the extent from the given prim.

If the extent is not authored, an empty GfRange3d is returned, the extent will not be computed.

Reimplemented from UsdImagingPrimAdapter.

std::vector<VtArray<TfToken> > GetInstanceCategories ( UsdPrim const &  prim)
overridevirtual

Return an array of the categories used by each instance.

Reimplemented from UsdImagingPrimAdapter.

GfMatrix4d GetInstancerTransform ( UsdPrim const &  instancerPrim,
SdfPath const &  instancerPath,
UsdTimeCode  time 
) const
overridevirtual

Get the instancer transform for the given prim.

See Also
HdSceneDelegate::GetInstancerTransform()

Reimplemented from UsdImagingPrimAdapter.

TfToken GetPurpose ( UsdPrim const &  prim,
SdfPath const &  cachePath,
TfToken const &  instanceInheritablePurpose 
) const
overridevirtual

Returns the purpose token for prim.

If a non-empty instanceInheritablePurpose is specified and the prim doesn't have an explicitly authored or inherited purpose, it may inherit the instancer's purpose if the instance has an explicit purpose.

Reimplemented from UsdImagingPrimAdapter.

virtual GfMatrix4d GetRelativeInstancerTransform ( SdfPath const &  instancerPath,
SdfPath const &  protoInstancerPath,
UsdTimeCode  time 
) const
overridevirtual

Returns the transform of protoInstancerPath relative to instancerPath.

instancerPath must be managed by this adapter.

Reimplemented from UsdImagingPrimAdapter.

PxOsdSubdivTags GetSubdivTags ( UsdPrim const &  usdPrim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Get the subdiv tags for this prim.

Reimplemented from UsdImagingPrimAdapter.

VtValue GetTopology ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Gets the topology object of a specific Usd prim.

If the adapter is a mesh it will return an HdMeshTopology, if it is of type basis curves, it will return an HdBasisCurvesTopology. If the adapter does not have a topology, it returns an empty VtValue.

Reimplemented from UsdImagingPrimAdapter.

GfMatrix4d GetTransform ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time,
bool  ignoreRootTransform = false 
) const
overridevirtual

Fetches the transform for the given prim at the given time from a pre-computed cache of prim transforms.

Requesting transforms at incoherent times is currently inefficient.

Reimplemented from UsdImagingPrimAdapter.

bool GetVisible ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time 
) const
overridevirtual

Returns true if the given prim is visible, taking into account inherited visibility values.

Inherited values are strongest, Usd has no notion of "super vis/invis".

Reimplemented from UsdImagingPrimAdapter.

virtual SdfPath Populate ( UsdPrim const &  prim,
UsdImagingIndexProxy index,
UsdImagingInstancerContext const *  instancerContext = nullptr 
)
overridevirtual

Called to populate the RenderIndex for this UsdPrim.

The adapter is expected to create one or more prims in the render index using the given proxy.

Implements UsdImagingPrimAdapter.

virtual void ProcessPrimRemoval ( SdfPath const &  cachePath,
UsdImagingIndexProxy index 
)
overridevirtual

Removes all associated Rprims and dependencies from the render index without scheduling them for repopulation.

Reimplemented from UsdImagingPrimAdapter.

virtual void ProcessPrimResync ( SdfPath const &  cachePath,
UsdImagingIndexProxy index 
)
overridevirtual

When a PrimResync event occurs, the prim may have been deleted entirely, adapter plug-ins should override this method to free any per-prim state that was accumulated in the adapter.

Reimplemented from UsdImagingPrimAdapter.

virtual HdDirtyBits ProcessPropertyChange ( UsdPrim const &  prim,
SdfPath const &  cachePath,
TfToken const &  propertyName 
)
overridevirtual

Returns a bit mask of attributes to be updated, or HdChangeTracker::AllDirty if the entire prim must be resynchronized.

Implements UsdImagingPrimAdapter.

size_t SampleInstancerTransform ( UsdPrim const &  instancerPrim,
SdfPath const &  instancerPath,
UsdTimeCode  time,
size_t  maxNumSamples,
float *  sampleTimes,
GfMatrix4d sampleValues 
)
overridevirtual

Sample the instancer transform for the given prim.

See Also
HdSceneDelegate::SampleInstancerTransform()

Reimplemented from UsdImagingPrimAdapter.

size_t SamplePrimvar ( UsdPrim const &  usdPrim,
SdfPath const &  cachePath,
TfToken const &  key,
UsdTimeCode  time,
size_t  maxNumSamples,
float *  sampleTimes,
VtValue sampleValues 
)
overridevirtual

Sample the primvar for the given prim.

See Also
HdSceneDelegate::SamplePrimvar()

Reimplemented from UsdImagingPrimAdapter.

size_t SampleTransform ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time,
size_t  maxNumSamples,
float *  sampleTimes,
GfMatrix4d sampleValues 
)
overridevirtual

Samples the transform for the given prim.

Reimplemented from UsdImagingPrimAdapter.

virtual void TrackVariability ( UsdPrim const &  prim,
SdfPath const &  cachePath,
HdDirtyBits *  timeVaryingBits,
UsdImagingInstancerContext const *  instancerContext = NULL 
) const
overridevirtual

For the given prim, variability is detected and stored in timeVaryingBits.

Initial values are cached into the value cache.

This method is expected to be called from multiple threads.

Implements UsdImagingPrimAdapter.

virtual void UpdateForTime ( UsdPrim const &  prim,
SdfPath const &  cachePath,
UsdTimeCode  time,
HdDirtyBits  requestedBits,
UsdImagingInstancerContext const *  instancerContext = NULL 
) const
overridevirtual

Populates the cache for the given prim, time and requestedBits.

This method is expected to be called from multiple threads.

Implements UsdImagingPrimAdapter.


The documentation for this class was generated from the following file: