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/usd/sdf/path.h"
31 
33 
34 class HdSceneDelegate;
35 class HdRenderIndex;
36 class HdRprim;
37 
38 /// \class HdInstancer
39 ///
40 /// This class exists to facilitate point cloud style instancing. Instancers,
41 /// conceptually, are instructions to draw N objects; for each object, store
42 /// which Rprim you're drawing and what instance-specific primvars you're
43 /// binding.
44 ///
45 /// "/InstancerA": prototypes = ["/sphere", "/cube", "/sphere"];
46 /// translate = [ <0,0,0>, <1,0,0>, <0,1,0>]
47 ///
48 /// Hydra stores this in reverse: Rprims store which instancer is drawing them,
49 /// and the instancer stores which indices in that array of N objects are the
50 /// given Rprim.
51 ///
52 /// "/sphere": instancerId = "/InstancerA"
53 /// "/cube": instancerId = "/InstancerA"
54 /// Instancer A: indices("/sphere") = [0, 2]
55 /// indices("/cube") = [1]
56 /// translate = [<0,0,0>, <1,0,0>, <0,1,0>]
57 ///
58 /// Instancing is implemented by the prototype drawing itself multiple times,
59 /// and looking up per-instance data each time based on "indices": so
60 /// "/sphere" would draw itself once with translate=<0,0,0> and once with
61 /// translate=<0,1,0>.
62 ///
63 /// To make things more exciting, instancers can be nested.
64 ///
65 /// "/cube": instancerId = "/InstancerA"
66 /// "/InstancerA": instancerId = "/InstancerB"
67 /// indices("/cube") = [0, 1]
68 /// translate = [<0,0,0>, <1,0,0>]
69 /// "/InstancerB": indices("/InstancerA") = [0, 1]
70 /// translate = [<0,0,0>, <0,1,0>]
71 ///
72 /// In this case, "/cube" draws itself four times, for each of the
73 /// index tuples <0,0>, <0,1>, <1,0>, <1,1> where the first index is
74 /// the index in instancerA, and the second index is in instancerB.
75 ///
76 /// If the same primvar (e.g. "translate") shows up at multiple levels of
77 /// nesting, it's resolved as follows:
78 ///
79 /// Transforms
80 /// ----------
81 ///
82 /// Instance primvars "translate", "rotate", "scale", and "instanceTransform"
83 /// are used to compute the final transform of an instance. "translate"
84 /// and "scale" are interpreted as vec3: position, and axis-aligned scale
85 /// respectively. "rotate" is interpreted as a vec4 quaternion, and
86 /// "instanceTransform" is a 4x4 matrix. In the transform computation,
87 /// everything is converted to a 4x4 matrix.
88 ///
89 /// There are additional transforms: "instancerTransform" comes from
90 /// HdSceneDelegate::GetInstancerTransform(instancer, proto), and represents
91 /// the constant transform between the instancer and the prototype. It
92 /// varies with each level of nesting, but not across instances.
93 ///
94 /// "transform" is the proto Rprim's local transform.
95 ///
96 /// The final instance transform for instance "index" is computed as:
97 ///
98 /// nested_transform(level) = instancerTransform(level) *
99 /// translate(level, index) *
100 /// rotate(level, index) *
101 /// scale(level, index) *
102 /// instanceTransform(level, index);
103 /// output_transform = product(i : nested-levels - 1 -> 0) {
104 /// nested_transform(i)
105 /// } * transform;
106 ///
107 /// Any transforms not provided by the scene delegate are set to identity.
108 ///
109 /// Class responsibilities
110 /// ======================
111 ///
112 /// HdInstancer's primary role is to track the "indices" arrays for each
113 /// proto used by an instancer, and any provided primvar arrays. The
114 /// implementation is in the renderer-specific instancers, like HdStInstancer.
115 ///
116 /// All data access (aside from local caches) is delegated to the HdSceneDelegate.
117 ///
118 
119 class HdInstancer {
120 public:
121  /// Constructor.
122  HD_API
123  HdInstancer(HdSceneDelegate* delegate, SdfPath const& id,
124  SdfPath const &parentInstancerId);
125  virtual ~HdInstancer() {}
126 
127  /// Returns the identifier.
128  SdfPath const& GetId() const { return _id; }
129 
130  /// Returns the parent instancer identifier.
131  SdfPath const& GetParentId() const { return _parentId; }
132 
133  HdSceneDelegate* GetDelegate() const { return _delegate; }
134 
135  HD_API
137  HdRprim const& rprim);
138 
139  HD_API
140  TfTokenVector const & GetBuiltinPrimvarNames() const;
141 
142 private:
143  HdSceneDelegate* _delegate;
144  SdfPath _id;
145  SdfPath _parentId;
146 };
147 
148 
150 
151 #endif // PXR_IMAGING_HD_INSTANCER_H
GLuint index
Definition: glew.h:1814
#define HD_API
Definition: api.h:40
HdSceneDelegate * GetDelegate() const
Definition: instancer.h:133
HD_API TfTokenVector const & GetBuiltinPrimvarNames() const
Definition: rprim.h:68
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
Definition: path.h:288
HD_API HdInstancer(HdSceneDelegate *delegate, SdfPath const &id, SdfPath const &parentInstancerId)
Constructor.
virtual ~HdInstancer()
Definition: instancer.h:125
SdfPath const & GetId() const
Returns the identifier.
Definition: instancer.h:128
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
SdfPath const & GetParentId() const
Returns the parent instancer identifier.
Definition: instancer.h:131
static HD_API int GetInstancerNumLevels(HdRenderIndex &index, HdRprim const &rprim)