HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
instancedBySchema.h
Go to the documentation of this file.
1 //
2 // Copyright 2023 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 ////////////////////////////////////////////////////////////////////////
8 
9 /* ************************************************************************** */
10 /* ** ** */
11 /* ** This file is generated by a script. ** */
12 /* ** ** */
13 /* ** Do not edit it directly (unless it is within a CUSTOM CODE section)! ** */
14 /* ** Edit hdSchemaDefs.py instead to make changes. ** */
15 /* ** ** */
16 /* ************************************************************************** */
17 
18 #ifndef PXR_IMAGING_HD_INSTANCED_BY_SCHEMA_H
19 #define PXR_IMAGING_HD_INSTANCED_BY_SCHEMA_H
20 
21 /// \file
22 
23 #include "pxr/imaging/hd/api.h"
24 
25 #include "pxr/imaging/hd/schema.h"
26 
27 // --(BEGIN CUSTOM CODE: Includes)--
28 // --(END CUSTOM CODE: Includes)--
29 
31 
32 // --(BEGIN CUSTOM CODE: Declares)--
33 // --(END CUSTOM CODE: Declares)--
34 
35 #define HD_INSTANCED_BY_SCHEMA_TOKENS \
36  (instancedBy) \
37  (paths) \
38  (prototypeRoots) \
39 
40 TF_DECLARE_PUBLIC_TOKENS(HdInstancedBySchemaTokens, HD_API,
42 
43 //-----------------------------------------------------------------------------
44 
45 // A schema marking a prim as instanced by another prim.
46 //
47 // Many renderers need to know not what prototypes an instancer has, but
48 // rather what instancers a prototype has; this is encoded in "instancedBy". A
49 // prim is "instancedBy" /Instancer if /Instancer has a prototype path that's
50 // a parent of the prim. A complicating exception is if /A instances /A/B,
51 // which instances /A/B/C, we don't consider /A to be instancing /A/B/C
52 // directly; this is to support nested explicit instancing of things like
53 // leaves/trees/forests.
54 //
55 // This value is computed based on the instancer topology of instancer prims
56 // in the scene.
57 //
58 // Note: if multiple instancers reference a prototype, it's possible for
59 // instancedBy to contain multiple entries. Some renderers may be able to read
60 // this directly, but some may need to duplicate prims with an op so that each
61 // prim has a single instancer, depending on how the renderer exposes
62 // instancing.
63 //
64 
66 {
67 public:
68  /// \name Schema retrieval
69  /// @{
70 
71  HdInstancedBySchema(HdContainerDataSourceHandle container)
72  : HdSchema(container) {}
73 
74  /// Retrieves a container data source with the schema's default name token
75  /// "instancedBy" from the parent container and constructs a
76  /// HdInstancedBySchema instance.
77  /// Because the requested container data source may not exist, the result
78  /// should be checked with IsDefined() or a bool comparison before use.
79  HD_API
81  const HdContainerDataSourceHandle &fromParentContainer);
82 
83  /// @}
84 
85 // --(BEGIN CUSTOM CODE: Schema Methods)--
86 // --(END CUSTOM CODE: Schema Methods)--
87 
88  /// \name Member accessor
89  /// @{
90 
91  HD_API
93 
94  HD_API
96 
97  /// @}
98 
99  /// \name Schema location
100  /// @{
101 
102  /// Returns a token where the container representing this schema is found in
103  /// a container by default.
104  HD_API
105  static const TfToken &GetSchemaToken();
106 
107  /// Returns an HdDataSourceLocator (relative to the prim-level data source)
108  /// where the container representing this schema is found by default.
109  HD_API
110  static const HdDataSourceLocator &GetDefaultLocator();
111 
112  /// @}
113 
114  /// \name Data source locators for members
115  ///
116  /// The following methods return an HdDataSourceLocator (relative to the
117  /// prim-level data source) where the data source for a member can be found.
118  ///
119  /// This is often useful for checking intersection against the
120  /// HdDataSourceLocatorSet sent with HdDataSourceObserver::PrimsDirtied.
121  /// @{
122 
123  /// Prim-level relative data source locator to locate paths.
124  HD_API
125  static const HdDataSourceLocator &GetPathsLocator();
126  /// @}
127 
128  /// \name Schema construction
129  /// @{
130 
131  /// \deprecated Use Builder instead.
132  ///
133  /// Builds a container data source which includes the provided child data
134  /// sources. Parameters with nullptr values are excluded. This is a
135  /// low-level interface. For cases in which it's desired to define
136  /// the container with a sparse set of child fields, the Builder class
137  /// is often more convenient and readable.
138  HD_API
139  static HdContainerDataSourceHandle
141  const HdPathArrayDataSourceHandle &paths,
142  const HdPathArrayDataSourceHandle &prototypeRoots
143  );
144 
145  /// \class HdInstancedBySchema::Builder
146  ///
147  /// Utility class for setting sparse sets of child data source fields to be
148  /// filled as arguments into BuildRetained. Because all setter methods
149  /// return a reference to the instance, this can be used in the "builder
150  /// pattern" form.
151  class Builder
152  {
153  public:
154  HD_API
155  Builder &SetPaths(
156  const HdPathArrayDataSourceHandle &paths);
157  HD_API
159  const HdPathArrayDataSourceHandle &prototypeRoots);
160 
161  /// Returns a container data source containing the members set thus far.
162  HD_API
163  HdContainerDataSourceHandle Build();
164 
165  private:
167  HdPathArrayDataSourceHandle _prototypeRoots;
168 
169  };
170 
171  /// @}
172 };
173 
175 
176 #endif
static HD_API const HdDataSourceLocator & GetPathsLocator()
Prim-level relative data source locator to locate paths.
HD_API HdPathArrayDataSourceHandle GetPaths() const
static HD_API const TfToken & GetSchemaToken()
HdPathArrayDataSource::Handle HdPathArrayDataSourceHandle
#define HD_API
Definition: api.h:23
Definition: token.h:70
static HD_API const HdDataSourceLocator & GetDefaultLocator()
HD_API HdPathArrayDataSourceHandle GetPrototypeRoots() const
#define HD_INSTANCED_BY_SCHEMA_TOKENS
TF_DECLARE_PUBLIC_TOKENS(HdInstancedBySchemaTokens, HD_API, HD_INSTANCED_BY_SCHEMA_TOKENS)
HD_API Builder & SetPaths(const HdPathArrayDataSourceHandle &paths)
static HD_API HdInstancedBySchema GetFromParent(const HdContainerDataSourceHandle &fromParentContainer)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
HdInstancedBySchema(HdContainerDataSourceHandle container)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
static HD_API HdContainerDataSourceHandle BuildRetained(const HdPathArrayDataSourceHandle &paths, const HdPathArrayDataSourceHandle &prototypeRoots)
HD_API Builder & SetPrototypeRoots(const HdPathArrayDataSourceHandle &prototypeRoots)
HD_API HdContainerDataSourceHandle Build()
Returns a container data source containing the members set thus far.