HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
selectionTracker.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_HDX_SELECTION_TRACKER_H
25 #define PXR_IMAGING_HDX_SELECTION_TRACKER_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hdx/api.h"
31 #include "pxr/base/vt/array.h"
32 #include <vector>
33 #include <memory>
34 
36 
37 
38 class HdRenderIndex;
39 
41  std::shared_ptr<class HdxSelectionTracker>;
42 
43 /// ----------------------------------------------------------------------------
44 /// Selection highlighting in Hydra:
45 ///
46 /// Hydra Storm (*) supports selection highlighting of:
47 /// (a) a set of rprims, wherein each rprim is entirely highlighted
48 /// (b) a set of instances of an rprim, wherein each instance is highlighted
49 /// (c) a set of subprimitives of an rprim, wherein each subprim is highlighted.
50 /// Subprimitives support is limited to elements (faces of meshes, or
51 /// individual curves of basis curves), edges of meshes/curves,
52 /// and points of meshes.
53 ///
54 /// * While the goal is have an architecture that is extensible by rendering
55 /// backends, the current implementation is heavily influenced by the Storm
56 /// backend.
57 ///
58 /// Background:
59 /// The current selection implementation is, in a sense, global in nature.
60 /// If there are no selected objects, we do not bind any selection-related
61 /// resources, nor does the shader execute any selection-related operations.
62 ///
63 /// If there are one or more selected objects, we *don't* choose to have them
64 /// in a separate 'selection' collection.
65 /// Instead, we stick by AZDO principles and avoid command buffer changes as
66 /// a result of selection updates (which would involve removal of draw items
67 /// corresponding to the selected objects from each render pass' command buffer
68 /// and building the selection pass' command buffer).
69 /// We build an integer buffer encoding of the selected items, for use in the
70 /// fragment shader, that allows us to perform a small number of lookups to
71 /// quickly tell us if a fragment needs to be highlighted.
72 ///
73 /// For scene indices, the HdxSelectionTracker uses the HdSelectionsSchema
74 /// (instaniated with GetFromParent of a prim data source) for a prim to
75 /// determine the prim's selection status. However, to support scene delegates,
76 /// we do support settings the selection directly with SetSelection.
77 /// If both are used, the union of the selections is taken.
78 ///
79 /// Conceptually, the implementation is split into:
80 /// (a) HdSelection (for clients using scene delegates) : Client facing API
81 /// that builds a collection of selected items. This is agnostic of the
82 /// rendering backend.
83 /// HdSelectionsSchema (for clients using scene indices) : Scene indices
84 /// can populate this schema for each selected prim.
85 /// (b) HdxSelectionTracker: Base class that observes (a) and encodes it as
86 /// needed by (c). This may be specialized to be backend specific.
87 /// (c) HdxSelectionTask : A scene task that, currently, only syncs resources
88 /// related to selection highlighting. Currently, this is tied to Storm.
89 /// (d) HdxRenderSetupTask : A scene task that sets up the render pass shader
90 /// to use the selection highlighting mixin in the render pass(es) of
91 /// HdxRenderTask. This is relevant only to Storm.
92 ///
93 /// ----------------------------------------------------------------------------
94 
95 
96 /// \class HdxSelectionTracker
97 ///
98 /// HdxSelectionTracker takes HdSelection and generates a GPU buffer to be used
99 /// \class HdxSelectionTracker
100 ///
101 /// HdxSelectionTracker is a base class for observing selection state and
102 /// providing selection highlighting details to interested clients.
103 ///
104 /// Applications may use HdxSelectionTracker as-is, or extend it as needed.
105 ///
106 /// HdxSelectionTask takes HdxSelectionTracker as a task parameter, and uploads
107 /// the selection buffer encoding to the GPU.
108 ///
110 {
111 public:
112  HDX_API
114  virtual ~HdxSelectionTracker();
115 
116  /// Optional override to update the selection (either compute HdSelection and
117  /// call SetSelection or update a scene index with selection information using
118  /// the HdSelectionsSchema) during HdxSelectionTask::Prepare.
119  HDX_API
120  virtual void UpdateSelection(HdRenderIndex *index);
121 
122  /// Encodes the selection state (HdxSelection) as an integer array. This is
123  /// uploaded to the GPU and decoded in the fragment shader to provide
124  /// selection highlighting behavior. See HdxSelectionTask.
125  /// Returns true if offsets has anything selected.
126  /// \p enableSelection is a global on/off switch for selection; if it's
127  /// false, nothing will be encoded.
128  HDX_API
129  virtual bool GetSelectionOffsetBuffer(const HdRenderIndex *index,
130  bool enableSelection,
131  VtIntArray *offsets) const;
132 
133  HDX_API
134  virtual VtVec4fArray GetSelectedPointColors(const HdRenderIndex *index);
135 
136  /// Returns a monotonically increasing version number, which increments
137  /// whenever the result of GetBuffers has changed. Note that this number may
138  /// overflow and become negative, thus clients should use a not-equal
139  /// comparison.
140  HDX_API
141  int GetVersion() const;
142 
143  /// Set the collection of selected objects. The ultimate selection (used for
144  /// selection highlighting) will be the union of the collection set here and
145  /// the one computed by querying the scene indices (using the
146  /// HdxSelectionSceneIndexObserver).
147  HDX_API
149 
150  /// Returns selection set with SetSelection.
151  ///
152  /// XXX: Rename to GetSelection
153  HDX_API
154  HdSelectionSharedPtr const &GetSelectionMap() const;
155 
156 protected:
157  /// Increments the internal selection state version, used for invalidation
158  /// via GetVersion().
159  HDX_API
160  void _IncrementVersion();
161 
162 private:
163  bool _GetSelectionOffsets(HdSelectionSharedPtr const &selection,
165  const HdRenderIndex *index,
166  size_t modeOffset,
167  std::vector<int>* offsets) const;
168 
169  // A helper class to obtain the union of the selection computed
170  // by querying the scene indices (with the HdxSelectionSceneIndexObserver)
171  // and the selection set with SetSelection.
172  class _MergedSelection;
173  std::unique_ptr<_MergedSelection> _mergedSelection;
174 };
175 
176 
178 
179 #endif //PXR_IMAGING_HDX_SELECTION_TRACKER_H
GT_API const UT_StringHolder selection
HDX_API HdSelectionSharedPtr const & GetSelectionMap() const
virtual ~HdxSelectionTracker()
#define HDX_API
Definition: api.h:40
std::shared_ptr< class HdxSelectionTracker > HdxSelectionTrackerSharedPtr
GLuint GLsizei const GLuint const GLintptr * offsets
Definition: glcorearb.h:2621
virtual HDX_API bool GetSelectionOffsetBuffer(const HdRenderIndex *index, bool enableSelection, VtIntArray *offsets) const
virtual HDX_API VtVec4fArray GetSelectedPointColors(const HdRenderIndex *index)
HighlightMode
Selection modes allow differentiation in selection highlight behavior.
Definition: selection.h:56
GLenum mode
Definition: glcorearb.h:99
virtual HDX_API void UpdateSelection(HdRenderIndex *index)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
GLuint index
Definition: glcorearb.h:786
HDX_API int GetVersion() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HDX_API HdxSelectionTracker()
HDX_API void _IncrementVersion()
std::shared_ptr< class HdSelection > HdSelectionSharedPtr
Definition: selection.h:40
HDX_API void SetSelection(HdSelectionSharedPtr const &selection)