HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
instancer.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_HD_INSTANCER_H
25 #define PXR_IMAGING_HD_INSTANCER_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hd/api.h"
29 #include "pxr/imaging/hd/version.h"
30 #include "pxr/imaging/hd/types.h"
31 
32 #include "pxr/usd/sdf/path.h"
33 
34 #include <mutex>
35 
37 
38 class HdSceneDelegate;
39 class HdRenderIndex;
40 class HdRprim;
41 class HdRenderParam;
42 
43 /// \class HdInstancer
44 ///
45 /// This class exists to facilitate point cloud style instancing. Instancers,
46 /// conceptually, are instructions to draw N objects; for each object, store
47 /// which Rprim you're drawing and what instance-specific primvars you're
48 /// binding.
49 ///
50 /// "/InstancerA": prototypes = ["/sphere", "/cube", "/sphere"];
51 /// translate = [ <0,0,0>, <1,0,0>, <0,1,0>]
52 ///
53 /// Hydra stores this in reverse: Rprims store which instancer is drawing them,
54 /// and the instancer stores which indices in that array of N objects are the
55 /// given Rprim.
56 ///
57 /// "/sphere": instancerId = "/InstancerA"
58 /// "/cube": instancerId = "/InstancerA"
59 /// Instancer A: indices("/sphere") = [0, 2]
60 /// indices("/cube") = [1]
61 /// translate = [<0,0,0>, <1,0,0>, <0,1,0>]
62 ///
63 /// Instancing is implemented by the prototype drawing itself multiple times,
64 /// and looking up per-instance data each time based on "indices": so
65 /// "/sphere" would draw itself once with translate=<0,0,0> and once with
66 /// translate=<0,1,0>.
67 ///
68 /// To make things more exciting, instancers can be nested.
69 ///
70 /// "/cube": instancerId = "/InstancerA"
71 /// "/InstancerA": instancerId = "/InstancerB"
72 /// indices("/cube") = [0, 1]
73 /// translate = [<0,0,0>, <1,0,0>]
74 /// "/InstancerB": indices("/InstancerA") = [0, 1]
75 /// translate = [<0,0,0>, <0,1,0>]
76 ///
77 /// In this case, "/cube" draws itself four times, for each of the
78 /// index tuples <0,0>, <0,1>, <1,0>, <1,1> where the first index is
79 /// the index in instancerA, and the second index is in instancerB.
80 ///
81 /// If the same primvar (e.g. "translate") shows up at multiple levels of
82 /// nesting, it's resolved as follows:
83 ///
84 /// Transforms
85 /// ----------
86 ///
87 /// Instance primvars "translate", "rotate", "scale", and "instanceTransform"
88 /// are used to compute the final transform of an instance. "translate"
89 /// and "scale" are interpreted as vec3: position, and axis-aligned scale
90 /// respectively. "rotate" is interpreted as a vec4 quaternion, and
91 /// "instanceTransform" is a 4x4 matrix. In the transform computation,
92 /// everything is converted to a 4x4 matrix.
93 ///
94 /// There are additional transforms: "instancerTransform" comes from
95 /// HdSceneDelegate::GetInstancerTransform(instancer, proto), and represents
96 /// the constant transform between the instancer and the prototype. It
97 /// varies with each level of nesting, but not across instances.
98 ///
99 /// "transform" is the proto Rprim's local transform.
100 ///
101 /// The final instance transform for instance "index" is computed as:
102 ///
103 /// nested_transform(level) = instancerTransform(level) *
104 /// translate(level, index) *
105 /// rotate(level, index) *
106 /// scale(level, index) *
107 /// instanceTransform(level, index);
108 /// output_transform = product(i : nested-levels - 1 -> 0) {
109 /// nested_transform(i)
110 /// } * transform;
111 ///
112 /// Any transforms not provided by the scene delegate are set to identity.
113 ///
114 /// Class responsibilities
115 /// ======================
116 ///
117 /// HdInstancer's primary role is to track the "indices" arrays for each
118 /// proto used by an instancer, and any provided primvar arrays. The
119 /// implementation is in the renderer-specific instancers, like HdStInstancer.
120 ///
121 /// All data access (aside from local caches) is routed to the HdSceneDelegate.
122 ///
123 
124 class HdInstancer {
125 public:
126  /// Constructor.
127  HD_API
128  HdInstancer(HdSceneDelegate* delegate, SdfPath const& id);
129 
130  HD_API
131  virtual ~HdInstancer();
132 
133  /// Returns the identifier.
134  SdfPath const& GetId() const { return _id; }
135 
136  /// Returns the parent instancer identifier.
137  SdfPath const& GetParentId() const { return _parentId; }
138 
139  HdSceneDelegate* GetDelegate() const { return _delegate; }
140 
141  HD_API
143  HdRprim const& rprim);
144 
145  HD_API
146  static TfTokenVector const & GetBuiltinPrimvarNames();
147 
148  HD_API
149  virtual void Sync(HdSceneDelegate *sceneDelegate,
150  HdRenderParam *renderParam,
151  HdDirtyBits *dirtyBits);
152 
153  HD_API
154  virtual void Finalize(HdRenderParam *renderParam);
155 
156  HD_API
157  virtual HdDirtyBits GetInitialDirtyBitsMask() const;
158 
159  HD_API
160  static void _SyncInstancerAndParents(
161  HdRenderIndex &renderIndex,
162  SdfPath const& instancerId);
163 
164 protected:
165  HD_API
166  void _UpdateInstancer(HdSceneDelegate *delegate,
167  HdDirtyBits *dirtyBits);
168 
169 private:
170  HdSceneDelegate* _delegate;
171  SdfPath _id;
172  SdfPath _parentId;
173 
174  // XXX: This mutex exists for _SyncInstancerAndParents, which will go
175  // away when the render index calls sync on instancers.
176  std::mutex _instanceLock;
177 };
178 
179 
181 
182 #endif // PXR_IMAGING_HD_INSTANCER_H
virtual HD_API void Sync(HdSceneDelegate *sceneDelegate, HdRenderParam *renderParam, HdDirtyBits *dirtyBits)
uint32_t HdDirtyBits
Definition: types.h:127
virtual HD_API ~HdInstancer()
#define HD_API
Definition: api.h:40
HdSceneDelegate * GetDelegate() const
Definition: instancer.h:139
virtual HD_API void Finalize(HdRenderParam *renderParam)
Definition: rprim.h:68
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
Definition: path.h:288
SdfPath const & GetId() const
Returns the identifier.
Definition: instancer.h:134
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
GLuint index
Definition: glcorearb.h:785
virtual HD_API HdDirtyBits GetInitialDirtyBitsMask() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HD_API void _UpdateInstancer(HdSceneDelegate *delegate, HdDirtyBits *dirtyBits)
SdfPath const & GetParentId() const
Returns the parent instancer identifier.
Definition: instancer.h:137
HD_API HdInstancer(HdSceneDelegate *delegate, SdfPath const &id)
Constructor.
static HD_API TfTokenVector const & GetBuiltinPrimvarNames()
static HD_API void _SyncInstancerAndParents(HdRenderIndex &renderIndex, SdfPath const &instancerId)
static HD_API int GetInstancerNumLevels(HdRenderIndex &index, HdRprim const &rprim)