VTK  9.2.20220630
vtkHardwareSelector.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Program: Visualization Toolkit
4  Module: vtkHardwareSelector.h
5 
6  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7  All rights reserved.
8  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
9 
10  This software is distributed WITHOUT ANY WARRANTY; without even
11  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12  PURPOSE. See the above copyright notice for more information.
13 
14 =========================================================================*/
15 /*
16  * @class vtkHardwareSelector
17  * @brief manager for OpenGL-based selection.
18  *
19  * vtkHardwareSelector is a helper that orchestrates color buffer based
20  * selection. This relies on OpenGL.
21  * vtkHardwareSelector can be used to select visible cells or points within a
22  * given rectangle of the RenderWindow.
23  * To use it, call in order:
24  * \li SetRenderer() - to select the renderer in which we
25  * want to select the cells/points.
26  * \li SetArea() - to set the rectangular region in the render window to select
27  * in.
28  * \li SetFieldAssociation() - to select the attribute to select i.e.
29  * cells/points etc.
30  * \li Finally, call Select().
31  * Select will cause the attached vtkRenderer to render in a special color mode,
32  * where each cell/point is given it own color so that later inspection of the
33  * Rendered Pixels can determine what cells are visible. Select() returns a new
34  * vtkSelection instance with the cells/points selected.
35  *
36  * Limitations:
37  * Antialiasing will break this class. If your graphics card settings force
38  * their use this class will return invalid results.
39  *
40  * Only Opaque geometry in Actors is selected from. Assemblies and LODMappers
41  * are not currently supported.
42  *
43  * During selection, visible datasets that can not be selected from are
44  * temporarily hidden so as not to produce invalid indices from their colors.
45  *
46  *
47  * The basic approach this class uses is to invoke render multiple times
48  * (passes) and have the mappers render pass specific information into
49  * the color buffer. For example during the ACTOR_PASS a mapper is
50  * supposed to render it's actor's id into the color buffer as a RGB
51  * value where R is the lower 8 bits, G is the next 8, etc. Giving us 24
52  * bits of unsigned int range.
53  *
54  * The same concept applies to the COMPOSITE_INDEX_PASS and the point and
55  * cell ID passes. As points and cells can easily exceed the 24 bit range
56  * of the color buffer we break them into two 24 bit passes for a total
57  * of 48 bits of range.
58  *
59  * During each pass the mappers render their data into the color buffer,
60  * the hardware selector grabs that buffer and then invokes
61  * ProcessSelectorPixelBuffer on all of the hit props. Giving them, and
62  * their mappers, a chance to modify the pixel buffer.
63  *
64  * Most mappers use this ProcessSelectorPixelBuffers pass to take when
65  * they rendered into the color buffer and convert it into what the
66  * hardware selector is expecting. This is because in some cases it is
67  * far easier and faster to render something else, such as
68  * gl_PrimitiveID or gl_VertexID and then in the processing convert those
69  * values to the appropriate VTK values.
70  *
71  * NOTE: The goal is for mappers to support hardware selection without
72  * having to rebuild any of their VBO/IBOs to maintain fast picking
73  * performance.
74  *
75  * NOTE: This class has a complex interaction with parallel compositing
76  * techniques such as IceT that are used on supercomputers. In those
77  * cases the local nodes render each pass, process it, send it to icet
78  * which composites it, and then must copy the result back to the hardware
79  * selector. Be aware of these interactions if you work on this class.
80  *
81  * NOTE: many mappers support remapping arrays from their local value to
82  * some other provided value. For example ParaView when creating a
83  * polydata from an unstructured grid will create point and cell data
84  * arrays on the polydata that may the polydata point and cell IDs back
85  * to the original unstructured grid's point and cell IDs. The hardware
86  * selection process honors those arrays and will provide the original
87  * unstructured grid point and cell ID when a selection is made.
88  * Likewise there are process and composite arrays that most mappers
89  * support that allow for parallel data generation, delivery, and local
90  * rendering while preserving the original process and composite values
91  * from when the data was distributed. Be aware the process array is a
92  * point data while the composite array is a cell data.
93  *
94  * TODO: This whole selection process could be nicely encapsulated as a
95  * RenderPass that internally renders multiple times with different
96  * settings. That would be my suggestion for the future.
97  *
98  * TODO: The pick method build into renderer could use the ACTOR pass of
99  * this class to do it's work eliminating some confusion and duplicate
100  * code paths.
101  *
102  * TODO: I am not sure where the composite array indirection is used.
103  *
104  *
105  * @sa
106  * vtkOpenGLHardwareSelector
107 
108  @par Online Examples:
109 
110  @htmlonly
111 
112  <div class="examplegrid">
113 
114  <a href="https://kitware.github.io/vtk-examples/site/Cxx/Filtering/ExtractVisibleCells">
115  <div class="examplegrid_container">
116  <img src="https://raw.githubusercontent.com/Kitware/vtk-examples/gh-pages/src/Testing/Baseline//Cxx/Filtering/TestExtractVisibleCells.png">
117  <div class="examplegrid_overlay">
118  <div class="examplegrid_text">ExtractVisibleCells</div>
119  </div>
120  </div>
121  </a>
122 
123 
124  <a href="https://kitware.github.io/vtk-examples/site/Cxx/Graphs/SelectedVerticesAndEdges">
125  <div class="examplegrid_container">
126  <img src="https://raw.githubusercontent.com/Kitware/vtk-examples/gh-pages/src/Testing/Baseline//Cxx/Graphs/TestSelectedVerticesAndEdges.png">
127  <div class="examplegrid_overlay">
128  <div class="examplegrid_text">SelectedVerticesAndEdges</div>
129  </div>
130  </div>
131  </a>
132 
133  </div>
134 
135  @endhtmlonly
136 
137  @par Tests:
138  @ref c2_vtk_t_vtkHardwareSelector "vtkHardwareSelector (Tests)"
139  */
140 
141 #ifndef vtkHardwareSelector_h
142 #define vtkHardwareSelector_h
143 
144 #include "vtkObject.h"
145 #include "vtkRenderingCoreModule.h" // For export macro
146 
147 #include <string> // for std::string
148 
149 class vtkRenderer;
150 class vtkRenderWindow;
151 class vtkSelection;
152 class vtkProp;
153 class vtkTextureObject;
154 
155 class VTKRENDERINGCORE_EXPORT vtkHardwareSelector : public vtkObject
156 {
157 public:
159 
163  {
164  bool Valid;
166  int PropID;
168  unsigned int CompositeID;
171  : Valid(false)
172  , ProcessID(-1)
173  , PropID(-1)
174  , Prop(nullptr)
175  , CompositeID(0)
176  , AttributeID(-1)
177  {
178  }
179  };
181 
182 public:
185  void PrintSelf(ostream& os, vtkIndent indent) override;
186 
188 
191  virtual void SetRenderer(vtkRenderer*);
192  vtkGetObjectMacro(Renderer, vtkRenderer);
194 
196 
199  vtkSetVector4Macro(Area, unsigned int);
200  vtkGetVector4Macro(Area, unsigned int);
202 
204 
214  vtkSetMacro(FieldAssociation, int);
215  vtkGetMacro(FieldAssociation, int);
217 
219 
224  vtkSetMacro(UseProcessIdFromData, bool);
225  vtkGetMacro(UseProcessIdFromData, bool);
227 
233 
235 
248  virtual bool CaptureBuffers();
249  PixelInformation GetPixelInformation(const unsigned int display_position[2])
250  {
251  return this->GetPixelInformation(display_position, 0);
252  }
253  PixelInformation GetPixelInformation(const unsigned int display_position[2], int maxDist)
254  {
255  unsigned int temp[2];
256  return this->GetPixelInformation(display_position, maxDist, temp);
257  }
259  const unsigned int display_position[2], int maxDist, unsigned int selected_position[2]);
260  void ClearBuffers() { this->ReleasePixBuffers(); }
261  // raw is before processing
262  unsigned char* GetRawPixelBuffer(int passNo) { return this->RawPixBuffer[passNo]; }
263  unsigned char* GetPixelBuffer(int passNo) { return this->PixBuffer[passNo]; }
265 
270  virtual void RenderCompositeIndex(unsigned int index);
271 
273 
279  virtual void UpdateMaximumCellId(vtkIdType attribid);
280  virtual void UpdateMaximumPointId(vtkIdType attribid);
282 
287  virtual void RenderProcessId(unsigned int processid);
288 
293  int Render(vtkRenderer* renderer, vtkProp** propArray, int propArrayCount);
294 
296 
300  vtkGetMacro(ActorPassOnly, bool);
301  vtkSetMacro(ActorPassOnly, bool);
303 
305 
311  vtkGetMacro(CaptureZValues, bool);
312  vtkSetMacro(CaptureZValues, bool);
314 
316 
319  virtual void BeginRenderProp();
320  virtual void EndRenderProp();
322 
324 
328  vtkSetMacro(ProcessID, int);
329  vtkGetMacro(ProcessID, int);
331 
333 
336  vtkGetVector3Macro(PropColorValue, float);
337  vtkSetVector3Macro(PropColorValue, float);
340 
342 
345  vtkGetMacro(CurrentPass, int);
347 
356  virtual vtkSelection* GenerateSelection() { return GenerateSelection(this->Area); }
357  virtual vtkSelection* GenerateSelection(unsigned int r[4])
358  {
359  return GenerateSelection(r[0], r[1], r[2], r[3]);
360  }
362  unsigned int x1, unsigned int y1, unsigned int x2, unsigned int y2);
363 
370  virtual vtkSelection* GeneratePolygonSelection(int* polygonPoints, vtkIdType count);
371 
377 
378  // it is very critical that these passes happen in the right order
379  // this is because of two complexities
380  //
381  // Compositing engines such as iceT send each pass as it
382  // renders. This means
383  //
384  // Mappers use point Ids or cell Id to update the process
385  // and composite ids. So the point and cell id passes
386  // have to happen before the last process and compoite
387  // passes respectively
388  //
389  //
391  {
392  // always must be first so that the prop IDs are set
394  // must always be second for composite mapper
396 
398  POINT_ID_HIGH24, // if needed
399  PROCESS_PASS, // must be after point id pass
400 
402  CELL_ID_HIGH24, // if needed
403 
404  MAX_KNOWN_PASS = CELL_ID_HIGH24,
405  MIN_KNOWN_PASS = ACTOR_PASS
406  };
407 
412 
413  static void Convert(vtkIdType id, float tcoord[3])
414  {
415  tcoord[0] = static_cast<float>((id & 0xff) / 255.0);
416  tcoord[1] = static_cast<float>(((id & 0xff00) >> 8) / 255.0);
417  tcoord[2] = static_cast<float>(((id & 0xff0000) >> 16) / 255.0);
418  }
419 
420  // grab the pixel buffer and save it
421  // typically called internally
422  virtual void SavePixelBuffer(int passNo);
423 
424  // does the selection process have high cell data
425  // requiring a high24 pass
427 
428  // does the selection process have high point data
429  // requiring a high24 pass
431 
432 protected:
435 
436  // Used to notify subclasses when a capture pass is occurring.
437  virtual void PreCapturePass(int pass) { (void)pass; }
438  virtual void PostCapturePass(int pass) { (void)pass; }
439 
440  // Called internally before and after each prop is rendered
441  // for device specific configuration/preparation etc.
442  virtual void BeginRenderProp(vtkRenderWindow*) = 0;
443  virtual void EndRenderProp(vtkRenderWindow*) = 0;
444 
445  double GetZValue(int propid);
446 
447  int Convert(unsigned long offset, unsigned char* pb)
448  {
449  if (!pb)
450  {
451  return 0;
452  }
453  offset = offset * 3;
454  unsigned char rgb[3];
455  rgb[0] = pb[offset];
456  rgb[1] = pb[offset + 1];
457  rgb[2] = pb[offset + 2];
458  int val = 0;
459  val |= rgb[2];
460  val = val << 8;
461  val |= rgb[1];
462  val = val << 8;
463  val |= rgb[0];
464  return val;
465  }
466 
468 
471  int Convert(unsigned int pos[2], unsigned char* pb) { return this->Convert(pos[0], pos[1], pb); }
472  int Convert(int xx, int yy, unsigned char* pb)
473  {
474  if (!pb)
475  {
476  return 0;
477  }
478  int offset = (yy * static_cast<int>(this->Area[2] - this->Area[0] + 1) + xx) * 3;
479  unsigned char rgb[3];
480  rgb[0] = pb[offset];
481  rgb[1] = pb[offset + 1];
482  rgb[2] = pb[offset + 2];
483  int val = 0;
484  val |= rgb[2];
485  val = val << 8;
486  val |= rgb[1];
487  val = val << 8;
488  val |= rgb[0];
489  return val;
490  }
492 
493  vtkIdType GetID(int low24, int mid24, int high16)
494  {
495  vtkIdType val = 0;
496  val |= high16;
497  val = val << 24;
498  val |= mid24;
499  val = val << 24;
500  val |= low24;
501  return val;
502  }
503 
507  virtual bool PassRequired(int pass);
508 
514  bool IsPropHit(int propid);
515 
519  virtual int GetPropID(int idx, vtkProp* vtkNotUsed(prop)) { return idx; }
520 
521  virtual void BeginSelection();
522  virtual void EndSelection();
523 
524  virtual void ProcessPixelBuffers();
525  void BuildPropHitList(unsigned char* rgbData);
526 
528 
533  unsigned int Area[4];
539 
540  // At most 10 passes.
541  unsigned char* PixBuffer[10];
542  unsigned char* RawPixBuffer[10];
547  int PropID;
548  float PropColorValue[3];
549 
551 
553 
554 private:
555  vtkHardwareSelector(const vtkHardwareSelector&) = delete;
556  void operator=(const vtkHardwareSelector&) = delete;
557 
558  class vtkInternals;
559  vtkInternals* Internals;
560 };
561 
562 #endif
static vtkHardwareSelector * New()
int Convert(unsigned long offset, unsigned char *pb)
vtkIdType MaximumCellId
Clears all pixel buffers.
virtual void BeginRenderProp()
Called by the mapper before and after rendering each prop.
virtual void UpdateMaximumPointId(vtkIdType attribid)
Called by any vtkMapper or vtkProp subclass to indicate the maximum cell or point attribute ID it use...
virtual void SavePixelBuffer(int passNo)
virtual void EndRenderProp(vtkRenderWindow *)=0
vtkRenderer * Renderer
Clears all pixel buffers.
virtual void EndRenderProp()
Called by the mapper before and after rendering each prop.
unsigned char * GetRawPixelBuffer(int passNo)
It is possible to use the vtkHardwareSelector for a custom picking.
virtual void SetRenderer(vtkRenderer *)
Get/Set the renderer to perform the selection on.
virtual vtkSelection * GenerateSelection(unsigned int r[4])
PixelInformation GetPixelInformation(const unsigned int display_position[2], int maxDist)
It is possible to use the vtkHardwareSelector for a custom picking.
vtkIdType GetID(int low24, int mid24, int high16)
virtual vtkSelection * GenerateSelection(unsigned int x1, unsigned int y1, unsigned int x2, unsigned int y2)
virtual void ProcessPixelBuffers()
vtkProp * GetPropFromID(int id)
returns the prop associated with a ID.
vtkIdType MaximumPointId
Clears all pixel buffers.
int FieldAssociation
Clears all pixel buffers.
~vtkHardwareSelector() override
void ReleasePixBuffers()
Clears all pixel buffers.
virtual void BeginSelection()
virtual void UpdateMaximumCellId(vtkIdType attribid)
Called by any vtkMapper or vtkProp subclass to indicate the maximum cell or point attribute ID it use...
virtual void PreCapturePass(int pass)
virtual bool PassRequired(int pass)
Returns is the pass indicated is needed.
int Convert(int xx, int yy, unsigned char *pb)
pos must be relative to the lower-left corner of this->Area.
virtual void PostCapturePass(int pass)
bool UseProcessIdFromData
Clears all pixel buffers.
bool IsPropHit(int propid)
After the ACTOR_PASS this return true or false depending upon whether the prop was hit in the ACTOR_P...
void SetPropColorValue(vtkIdType val)
Get/Set the color to be used by the prop when drawing.
std::string PassTypeToString(PassTypes type)
Convert a PassTypes enum value to a human readable string.
virtual int GetPropID(int idx, vtkProp *vtkNotUsed(prop))
Return a unique ID for the prop.
int Render(vtkRenderer *renderer, vtkProp **propArray, int propArrayCount)
Called by vtkRenderer to render the selection pass.
void BuildPropHitList(unsigned char *rgbData)
static void Convert(vtkIdType id, float tcoord[3])
int Convert(unsigned int pos[2], unsigned char *pb)
pos must be relative to the lower-left corner of this->Area.
PixelInformation GetPixelInformation(const unsigned int display_position[2])
It is possible to use the vtkHardwareSelector for a custom picking.
virtual void RenderCompositeIndex(unsigned int index)
Called by any vtkMapper or vtkProp subclass to render a composite-index.
virtual void EndSelection()
virtual vtkSelection * GeneratePolygonSelection(int *polygonPoints, vtkIdType count)
Generates the vtkSelection from pixel buffers.
virtual void BeginRenderProp(vtkRenderWindow *)=0
double GetZValue(int propid)
void ClearBuffers()
It is possible to use the vtkHardwareSelector for a custom picking.
vtkSelection * Select()
Perform the selection.
PixelInformation GetPixelInformation(const unsigned int display_position[2], int maxDist, unsigned int selected_position[2])
It is possible to use the vtkHardwareSelector for a custom picking.
void PrintSelf(ostream &os, vtkIndent indent) override
Methods invoked by print to print information about the object including superclasses.
virtual bool CaptureBuffers()
It is possible to use the vtkHardwareSelector for a custom picking.
virtual vtkSelection * GenerateSelection()
Generates the vtkSelection from pixel buffers.
unsigned char * GetPixelBuffer(int passNo)
It is possible to use the vtkHardwareSelector for a custom picking.
virtual void RenderProcessId(unsigned int processid)
Called by any vtkMapper or subclass to render process id.
a simple class to control print indentation
Definition: vtkIndent.h:119
abstract base class for most VTK objects
Definition: vtkObject.h:82
abstract superclass for all actors, volumes and annotations
Definition: vtkProp.h:76
create a window for renderers to draw into
abstract specification for renderers
Definition: vtkRenderer.h:182
data object that represents a "selection" in VTK.
Definition: vtkSelection.h:169
abstracts an OpenGL texture object.
@ type
Definition: vtkX3D.h:522
@ index
Definition: vtkX3D.h:252
@ offset
Definition: vtkX3D.h:444
@ string
Definition: vtkX3D.h:496
Struct used to return information about a pixel location.
int vtkIdType
Definition: vtkType.h:325
#define VTK_NEWINSTANCE