1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkCaptionActor2D.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   vtkCaptionActor2D
17  * @brief   draw text label associated with a point
18  *
19  * vtkCaptionActor2D is a hybrid 2D/3D actor that is used to associate text
20  * with a point (the AttachmentPoint) in the scene. The caption can be
21  * drawn with a rectangular border and a leader connecting
22  * the caption to the attachment point. Optionally, the leader can be
23  * glyphed at its endpoint to create arrow heads or other indicators.
24  *
25  * To use the caption actor, you normally specify the Position and Position2
26  * coordinates (these are inherited from the vtkActor2D superclass). (Note
27  * that Position2 can be set using vtkActor2D's SetWidth() and SetHeight()
28  * methods.)  Position and Position2 define the size of the caption, and a
29  * third point, the AttachmentPoint, defines a point that the caption is
30  * associated with.  You must also define the caption text,
31  * whether you want a border around the caption, and whether you want a
32  * leader from the caption to the attachment point. The font attributes of
33  * the text can be set through the vtkTextProperty associated to this actor.
34  * You also indicate whether you want
35  * the leader to be 2D or 3D. (2D leaders are always drawn over the
36  * underlying geometry. 3D leaders may be occluded by the geometry.) The
37  * leader may also be terminated by an optional glyph (e.g., arrow).
38  *
39  * The trickiest part about using this class is setting Position, Position2,
40  * and AttachmentPoint correctly. These instance variables are
41  * vtkCoordinates, and can be set up in various ways. In default usage, the
42  * AttachmentPoint is defined in the world coordinate system, Position is the
43  * lower-left corner of the caption and relative to AttachmentPoint (defined
44  * in display coordaintes, i.e., pixels), and Position2 is relative to
45  * Position and is the upper-right corner (also in display
46  * coordinates). However, the user has full control over the coordinates, and
47  * can do things like place the caption in a fixed position in the renderer,
48  * with the leader moving with the AttachmentPoint.
49  *
50  * @sa
51  * vtkLegendBoxActor vtkTextMapper vtkTextActor vtkTextProperty
52  * vtkCoordinate
53 */
54 
55 #ifndef vtkCaptionActor2D_h
56 #define vtkCaptionActor2D_h
57 
58 #include "vtkRenderingAnnotationModule.h" // For export macro
59 #include "vtkActor2D.h"
60 
61 class vtkActor;
62 class vtkAlgorithmOutput;
63 class vtkAppendPolyData;
64 class vtkCaptionActor2DConnection;
65 class vtkGlyph2D;
66 class vtkGlyph3D;
67 class vtkPolyData;
68 class vtkPolyDataMapper2D;
69 class vtkPolyDataMapper;
70 class vtkTextActor;
71 class vtkTextMapper;
72 class vtkTextProperty;
73 
74 class VTKRENDERINGANNOTATION_EXPORT vtkCaptionActor2D : public vtkActor2D
75 {
76 public:
77   vtkTypeMacro(vtkCaptionActor2D,vtkActor2D);
78   void PrintSelf(ostream& os, vtkIndent indent) override;
79 
80   static vtkCaptionActor2D *New();
81 
82   //@{
83   /**
84    * Define the text to be placed in the caption. The text can be multiple
85    * lines (separated by "\n").
86    */
87   virtual void SetCaption(const char* caption);
88   virtual char* GetCaption();
89   //@}
90 
91   //@{
92   /**
93    * Set/Get the attachment point for the caption. By default, the attachment
94    * point is defined in world coordinates, but this can be changed using
95    * vtkCoordinate methods.
96    */
97   vtkWorldCoordinateMacro(AttachmentPoint);
98   //@}
99 
100   //@{
101   /**
102    * Enable/disable the placement of a border around the text.
103    */
104   vtkSetMacro(Border,vtkTypeBool);
105   vtkGetMacro(Border,vtkTypeBool);
106   vtkBooleanMacro(Border,vtkTypeBool);
107   //@}
108 
109   //@{
110   /**
111    * Enable/disable drawing a "line" from the caption to the
112    * attachment point.
113    */
114   vtkSetMacro(Leader,vtkTypeBool);
115   vtkGetMacro(Leader,vtkTypeBool);
116   vtkBooleanMacro(Leader,vtkTypeBool);
117   //@}
118 
119   //@{
120   /**
121    * Indicate whether the leader is 2D (no hidden line) or 3D (z-buffered).
122    */
123   vtkSetMacro(ThreeDimensionalLeader,vtkTypeBool);
124   vtkGetMacro(ThreeDimensionalLeader,vtkTypeBool);
125   vtkBooleanMacro(ThreeDimensionalLeader,vtkTypeBool);
126   //@}
127 
128   //@{
129   /**
130    * Specify a glyph to be used as the leader "head". This could be something
131    * like an arrow or sphere. If not specified, no glyph is drawn. Note that
132    * the glyph is assumed to be aligned along the x-axis and is rotated about
133    * the origin. SetLeaderGlyphData() directly uses the polydata without
134    * setting a pipeline connection. SetLeaderGlyphConnection() sets up a
135    * pipeline connection and causes an update to the input during render.
136    */
137   virtual void SetLeaderGlyphData(vtkPolyData*);
138   virtual void SetLeaderGlyphConnection(vtkAlgorithmOutput*);
139   virtual vtkPolyData* GetLeaderGlyph();
140   //@}
141 
142   //@{
143   /**
144    * Specify the relative size of the leader head. This is expressed as a
145    * fraction of the size (diagonal length) of the renderer. The leader
146    * head is automatically scaled so that window resize, zooming or other
147    * camera motion results in proportional changes in size to the leader
148    * glyph.
149    */
150   vtkSetClampMacro(LeaderGlyphSize,double,0.0,0.1);
151   vtkGetMacro(LeaderGlyphSize,double);
152   //@}
153 
154   //@{
155   /**
156    * Specify the maximum size of the leader head (if any) in pixels. This
157    * is used in conjunction with LeaderGlyphSize to cap the maximum size of
158    * the LeaderGlyph.
159    */
160   vtkSetClampMacro(MaximumLeaderGlyphSize,int,1,1000);
161   vtkGetMacro(MaximumLeaderGlyphSize,int);
162   //@}
163 
164   //@{
165   /**
166    * Set/Get the padding between the caption and the border. The value
167    * is specified in pixels.
168    */
169   vtkSetClampMacro(Padding, int, 0, 50);
170   vtkGetMacro(Padding, int);
171   //@}
172 
173   //@{
174   /**
175    * Get the text actor used by the caption. This is useful if you want to control
176    * justification and other characteristics of the text actor.
177    */
178   vtkGetObjectMacro(TextActor,vtkTextActor);
179   //@}
180 
181   //@{
182   /**
183    * Set/Get the text property.
184    */
185   virtual void SetCaptionTextProperty(vtkTextProperty *p);
186   vtkGetObjectMacro(CaptionTextProperty,vtkTextProperty);
187   //@}
188 
189   /**
190    * Shallow copy of this scaled text actor. Overloads the virtual
191    * vtkProp method.
192    */
193   void ShallowCopy(vtkProp *prop) override;
194 
195   //@{
196   /**
197    * Enable/disable whether to attach the arrow only to the edge,
198    * NOT the vertices of the caption border.
199    */
200   vtkSetMacro(AttachEdgeOnly,vtkTypeBool);
201   vtkGetMacro(AttachEdgeOnly,vtkTypeBool);
202   vtkBooleanMacro(AttachEdgeOnly,vtkTypeBool);
203   //@}
204 
205   /**
206    * WARNING: INTERNAL METHOD - NOT INTENDED FOR GENERAL USE
207    * DO NOT USE THIS METHOD OUTSIDE OF THE RENDERING PROCESS.
208    * Release any graphics resources that are being consumed by this actor.
209    * The parameter window could be used to determine which graphic
210    * resources to release.
211    */
212   void ReleaseGraphicsResources(vtkWindow *) override;
213 
214   //@{
215   /**
216    * WARNING: INTERNAL METHOD - NOT INTENDED FOR GENERAL USE
217    * DO NOT USE THIS METHOD OUTSIDE OF THE RENDERING PROCESS.
218    * Draw the legend box to the screen.
219    */
220   int RenderOpaqueGeometry(vtkViewport* viewport) override;
RenderTranslucentPolygonalGeometry(vtkViewport *)221   int RenderTranslucentPolygonalGeometry(vtkViewport* ) override {return 0;}
222   int RenderOverlay(vtkViewport* viewport) override;
223   //@}
224 
225   /**
226    * Does this prop have some translucent polygonal geometry?
227    */
228   vtkTypeBool HasTranslucentPolygonalGeometry() override;
229 
230 protected:
231   vtkCaptionActor2D();
232   ~vtkCaptionActor2D() override;
233 
234   vtkCoordinate *AttachmentPointCoordinate;
235 
236   vtkTypeBool   Border;
237   vtkTypeBool   Leader;
238   vtkTypeBool   ThreeDimensionalLeader;
239   double LeaderGlyphSize;
240   int   MaximumLeaderGlyphSize;
241 
242   int   Padding;
243   vtkTypeBool   AttachEdgeOnly;
244 
245 
246 private:
247   vtkTextActor        *TextActor;
248   vtkTextProperty     *CaptionTextProperty;
249 
250   vtkPolyData         *BorderPolyData;
251   vtkPolyDataMapper2D *BorderMapper;
252   vtkActor2D          *BorderActor;
253 
254   vtkPolyData         *HeadPolyData;    // single attachment point for glyphing
255   vtkGlyph3D          *HeadGlyph;       // for 3D leader
256   vtkPolyData         *LeaderPolyData;  // line represents the leader
257   vtkAppendPolyData   *AppendLeader;    // append head and leader
258 
259   // for 2D leader
260   vtkCoordinate       *MapperCoordinate2D;
261   vtkPolyDataMapper2D *LeaderMapper2D;
262   vtkActor2D          *LeaderActor2D;
263 
264   // for 3D leader
265   vtkPolyDataMapper   *LeaderMapper3D;
266   vtkActor            *LeaderActor3D;
267 
268   vtkCaptionActor2DConnection* LeaderGlyphConnectionHolder;
269 
270 private:
271   vtkCaptionActor2D(const vtkCaptionActor2D&) = delete;
272   void operator=(const vtkCaptionActor2D&) = delete;
273 };
274 
275 
276 #endif
277 
278 
279 
280