1 // Created on: 1992-01-17
3 // Copyright (c) 1992-1999 Matra Datavision
4 // Copyright (c) 1999-2014 OPEN CASCADE SAS
6 // This file is part of Open CASCADE Technology software library.
8 // This library is free software; you can redistribute it and/or modify it under
9 // the terms of the GNU Lesser General Public License version 2.1 as published
10 // by the Free Software Foundation, with special exception defined in the file
11 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
12 // distribution for complete text of the license and disclaimer of any warranty.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _V3d_Viewer_HeaderFile
18 #define _V3d_Viewer_HeaderFile
20 #include <Aspect_Background.hxx>
21 #include <Aspect_GenId.hxx>
22 #include <Aspect_GradientBackground.hxx>
23 #include <Aspect_GradientFillMethod.hxx>
24 #include <Aspect_GridDrawMode.hxx>
25 #include <Aspect_GridType.hxx>
28 #include <Graphic3d_StructureManager.hxx>
29 #include <Graphic3d_Vertex.hxx>
30 #include <Graphic3d_ZLayerSettings.hxx>
32 #include <Standard.hxx>
33 #include <Standard_Boolean.hxx>
34 #include <Standard_CString.hxx>
35 #include <Standard_ExtString.hxx>
36 #include <Standard_Integer.hxx>
37 #include <Standard_Real.hxx>
38 #include <Standard_Type.hxx>
40 #include <TColStd_MapOfInteger.hxx>
41 #include <TColStd_ListIteratorOfListOfTransient.hxx>
42 #include <TColStd_SequenceOfInteger.hxx>
43 #include <TCollection_AsciiString.hxx>
44 #include <TCollection_ExtendedString.hxx>
46 #include <V3d_ListOfLight.hxx>
47 #include <V3d_ListOfView.hxx>
48 #include <V3d_TypeOfOrientation.hxx>
49 #include <V3d_TypeOfShadingModel.hxx>
50 #include <V3d_TypeOfView.hxx>
51 #include <V3d_TypeOfVisualization.hxx>
53 #include <Quantity_Color.hxx>
54 #include <Quantity_Length.hxx>
55 #include <Quantity_Parameter.hxx>
56 #include <Quantity_PlaneAngle.hxx>
57 #include <Quantity_TypeOfColor.hxx>
60 class Graphic3d_AspectMarker3d;
61 class Graphic3d_GraphicDriver;
62 class Graphic3d_Group;
63 class Graphic3d_Structure;
65 class V3d_CircularGrid;
67 class V3d_RectangularGrid;
71 //! Defines services on Viewer type objects.
72 //! The methods of this class allow editing and
73 //! interrogation of the parameters linked to the viewer
74 //! its friend classes (View,light,plane).
75 class V3d_Viewer : public Standard_Transient
77 friend class V3d_View;
78 friend class V3d_Light;
79 DEFINE_STANDARD_RTTIEXT(V3d_Viewer, Standard_Transient)
82 //! Create a Viewer with the given graphic driver and with default parameters:
83 //! - View orientation: V3d_XposYnegZpos
84 //! - View background: Quantity_NOC_GRAY30
85 //! - Shading model: V3d_GOURAUD
86 Standard_EXPORT V3d_Viewer (const Handle(Graphic3d_GraphicDriver)& theDriver);
88 //! Returns True if One View more can be defined in this Viewer.
89 Standard_EXPORT Standard_Boolean IfMoreViews() const;
91 //! Creates a view in the viewer according to its default parameters.
92 Standard_EXPORT Handle(V3d_View) CreateView();
94 //! Activates all of the views of a viewer attached to a window.
95 Standard_EXPORT void SetViewOn();
97 //! Activates a particular view in the Viewer.
98 //! Must be call if the Window attached to the view has been Deiconified.
99 Standard_EXPORT void SetViewOn (const Handle(V3d_View)& theView);
101 //! Deactivates all the views of a Viewer
102 //! attached to a window.
103 Standard_EXPORT void SetViewOff();
105 //! Deactivates a particular view in the Viewer.
106 //! Must be call if the Window attached to the view
107 //! has been Iconified .
108 Standard_EXPORT void SetViewOff (const Handle(V3d_View)& theView);
110 //! Deprecated, Redraw() should be used instead.
111 void Update() { Redraw(); }
113 //! Redraws all the views of the Viewer even if no
114 //! modification has taken place. Must be called if
115 //! all the views of the Viewer are exposed, as for
116 //! example in a global DeIconification.
117 Standard_EXPORT void Redraw() const;
119 //! Updates layer of immediate presentations.
120 Standard_EXPORT void RedrawImmediate() const;
122 //! Invalidates viewer content but does not redraw it.
123 Standard_EXPORT void Invalidate() const;
125 //! Suppresses the Viewer.
126 Standard_EXPORT void Remove();
128 //! Return Graphic Driver instance.
129 const Handle(Graphic3d_GraphicDriver)& Driver() const { return myDriver; }
131 //! Returns the structure manager associated to this viewer.
132 Handle(Graphic3d_StructureManager) StructureManager() const { return myStructureManager; }
134 //! Return default Rendering Parameters.
135 //! By default these parameters are set in a new V3d_View.
136 const Graphic3d_RenderingParams& DefaultRenderingParams() const { return myDefaultRenderingParams; }
138 //! Set default Rendering Parameters.
139 void SetDefaultRenderingParams (const Graphic3d_RenderingParams& theParams) { myDefaultRenderingParams = theParams; }
141 //! Defines the default background colour of views
142 //! attached to the viewer by supplying the name of the
143 //! colour under the form Quantity_NOC_xxxx .
144 void SetDefaultBackgroundColor (const Quantity_NameOfColor theName) { myBackground.SetColor (Quantity_Color (theName)); }
146 //! Defines the default background colour of views
147 //! attached to the viewer by supplying the color object
148 void SetDefaultBackgroundColor (const Quantity_Color& theColor) { myBackground.SetColor (theColor); }
150 //! Returns the gradient background of the view.
151 const Aspect_GradientBackground& GetGradientBackground() const { return myGradientBackground; }
153 //! Defines the default gradient background colours of view
154 //! attached to the viewer by supplying the name of the
155 //! colours under the form Quantity_NOC_xxxx .
156 void SetDefaultBgGradientColors (const Quantity_NameOfColor theName1,
157 const Quantity_NameOfColor theName2,
158 const Aspect_GradientFillMethod theFillStyle = Aspect_GFM_HOR)
160 myGradientBackground.SetColors (Quantity_Color (theName1), Quantity_Color (theName2), theFillStyle);
163 //! Defines the default gradient background colours of views
164 //! attached to the viewer by supplying the colour objects
165 void SetDefaultBgGradientColors (const Quantity_Color& theColor1,
166 const Quantity_Color& theColor2,
167 const Aspect_GradientFillMethod theFillStyle = Aspect_GFM_HOR)
169 myGradientBackground.SetColors (theColor1, theColor2, theFillStyle);
172 //! Returns the default size of the view.
173 Standard_Real DefaultViewSize() const { return myViewSize; }
175 //! Gives a default size for the creation of views of the viewer.
176 Standard_EXPORT void SetDefaultViewSize (const Standard_Real theSize);
178 //! Returns the default Projection.
179 V3d_TypeOfOrientation DefaultViewProj() const { return myViewProj; }
181 //! Sets the default projection for creating views in the viewer.
182 void SetDefaultViewProj (const V3d_TypeOfOrientation theOrientation) { myViewProj = theOrientation; }
184 //! Returns the default type of Visualization.
185 V3d_TypeOfVisualization DefaultVisualization() const { return myVisualization; }
187 //! Gives the default visualization mode.
188 void SetDefaultVisualization (const V3d_TypeOfVisualization theType) { myVisualization = theType; }
190 //! Returns the default type of Shading
191 V3d_TypeOfShadingModel DefaultShadingModel() const { return myShadingModel; }
193 //! Gives the default type of SHADING.
194 void SetDefaultShadingModel (const V3d_TypeOfShadingModel theType) { myShadingModel = theType; }
196 void SetDefaultTypeOfView (const V3d_TypeOfView theType) { myDefaultTypeOfView = theType; }
198 //! Returns the default background colour object.
199 Quantity_Color DefaultBackgroundColor() const { return myBackground.Color(); }
201 //! Returns the gradient background colour objects of the view.
202 void DefaultBgGradientColors (Quantity_Color& theColor1, Quantity_Color& theColor2) const { myGradientBackground.Colors (theColor1, theColor2); }
204 //! Return all Z layer ids in sequence ordered by overlay level from lowest layer to highest ( foreground ).
205 //! The first layer ID in sequence is the default layer that can't be removed.
206 Standard_EXPORT void GetAllZLayers (TColStd_SequenceOfInteger& theLayerSeq) const;
208 //! Add a new top-level Z layer to all managed views and get its ID as <theLayerId> value.
209 //! The Z layers are controlled entirely by viewer, it is not possible to add a layer to a particular view.
210 //! The method returns Standard_False if the layer can not be created.
211 //! The layer mechanism allows to display structures in higher layers in overlay of structures in lower layers.
212 Standard_EXPORT Standard_Boolean AddZLayer (Standard_Integer& theLayerId);
214 //! Remove Z layer with ID <theLayerId>.
215 //! Method returns Standard_False if the layer can not be removed or doesn't exists.
216 //! By default, there are always default bottom-level layer that can't be removed.
217 Standard_EXPORT Standard_Boolean RemoveZLayer (const Standard_Integer theLayerId);
219 //! Returns the settings of a single Z layer.
220 Standard_EXPORT Graphic3d_ZLayerSettings ZLayerSettings (const Standard_Integer theLayerId);
222 //! Sets the settings for a single Z layer.
223 Standard_EXPORT void SetZLayerSettings (const Standard_Integer theLayerId, const Graphic3d_ZLayerSettings& theSettings);
227 //! Return an iterator for active views.
228 V3d_ListOfViewIterator ActiveViewIterator() const { return V3d_ListOfViewIterator (myActiveViews); }
230 //! Initializes an internal iterator on the active views.
231 void InitActiveViews() { myActiveViewsIterator.Initialize (myActiveViews); }
233 //! Returns true if there are more active view(s) to return.
234 Standard_Boolean MoreActiveViews() const { return myActiveViewsIterator.More(); }
236 //! Go to the next active view (if there is not, ActiveView will raise an exception)
237 void NextActiveViews() { if (!myActiveViews.IsEmpty()) myActiveViewsIterator.Next(); }
239 const Handle(V3d_View)& ActiveView() const { return myActiveViewsIterator.Value(); }
241 //! returns true if there is only one active view.
242 Standard_Boolean LastActiveView() const { return myActiveViews.Extent() == 1; }
246 //! Return an iterator for defined views.
247 V3d_ListOfViewIterator DefinedViewIterator() const { return V3d_ListOfViewIterator (myDefinedViews); }
249 //! Initializes an internal iterator on the Defined views.
250 void InitDefinedViews() { myDefinedViewsIterator.Initialize (myDefinedViews); }
252 //! returns true if there are more Defined view(s) to return.
253 Standard_Boolean MoreDefinedViews() const { return myDefinedViewsIterator.More(); }
255 //! Go to the next Defined view (if there is not, DefinedView will raise an exception)
256 void NextDefinedViews() { if (!myDefinedViews.IsEmpty()) myDefinedViewsIterator.Next(); }
258 const Handle(V3d_View)& DefinedView() const { return myDefinedViewsIterator.Value(); }
260 public: //! @name lights management
262 //! Defines default lights:
263 //! positional-light 0.3 0. 0.
264 //! directional-light V3d_XnegYposZpos
265 //! directional-light V3d_XnegYneg
267 Standard_EXPORT void SetDefaultLights();
269 //! Activates MyLight in the viewer.
270 Standard_EXPORT void SetLightOn (const Handle(V3d_Light)& theLight);
272 //! Activates all the lights defined in this viewer.
273 Standard_EXPORT void SetLightOn();
275 //! Deactivates MyLight in this viewer.
276 Standard_EXPORT void SetLightOff (const Handle(V3d_Light)& theLight);
278 //! Deactivate all the Lights defined in this viewer.
279 Standard_EXPORT void SetLightOff();
281 //! Delete Light in Sequence Of Lights.
282 Standard_EXPORT void DelLight (const Handle(V3d_Light)& theLight);
284 //! Updates the lights of all the views of a viewer.
285 Standard_EXPORT void UpdateLights();
287 Standard_EXPORT Standard_Boolean IsGlobalLight (const Handle(V3d_Light)& TheLight) const;
289 //! Return an iterator for defined lights.
290 V3d_ListOfLightIterator ActiveLightIterator() const { return V3d_ListOfLightIterator (myActiveLights); }
292 //! Initializes an internal iteratator on the active Lights.
293 void InitActiveLights() { myActiveLightsIterator.Initialize (myActiveLights); }
295 //! returns true if there are more active Light(s) to return.
296 Standard_Boolean MoreActiveLights() const { return myActiveLightsIterator.More(); }
298 //! Go to the next active Light (if there is not, ActiveLight() will raise an exception)
299 void NextActiveLights() { myActiveLightsIterator.Next(); }
301 const Handle(V3d_Light)& ActiveLight() const { return myActiveLightsIterator.Value(); }
305 //! Return an iterator for defined lights.
306 V3d_ListOfLightIterator DefinedLightIterator() const { return V3d_ListOfLightIterator (myDefinedLights); }
308 //! Initializes an internal iterattor on the Defined Lights.
309 void InitDefinedLights() { myDefinedLightsIterator.Initialize (myDefinedLights); }
311 //! Returns true if there are more Defined Light(s) to return.
312 Standard_Boolean MoreDefinedLights() const { return myDefinedLightsIterator.More(); }
314 //! Go to the next Defined Light (if there is not, DefinedLight() will raise an exception)
315 void NextDefinedLights() { if (!myDefinedLights.IsEmpty()) myDefinedLightsIterator.Next(); }
317 const Handle(V3d_Light)& DefinedLight() const { return myDefinedLightsIterator.Value(); }
319 public: //! @name objects management
321 //! Erase all Objects in All the views.
322 Standard_EXPORT void Erase() const;
324 //! UnHighlight all Objects in All the views.
325 Standard_EXPORT void UnHighlight() const;
329 //! returns true if the computed mode can be used.
330 Standard_Boolean ComputedMode() const { return myComputedMode; }
332 //! Set if the computed mode can be used.
333 void SetComputedMode (const Standard_Boolean theMode) { myComputedMode = theMode; }
335 //! returns true if by default the computed mode must be used.
336 Standard_Boolean DefaultComputedMode() const { return myDefaultComputedMode; }
338 //! Set if by default the computed mode must be used.
339 void SetDefaultComputedMode (const Standard_Boolean theMode) { myDefaultComputedMode = theMode; }
341 public: //! @name privileged plane management
343 Standard_EXPORT gp_Ax3 PrivilegedPlane() const;
345 Standard_EXPORT void SetPrivilegedPlane (const gp_Ax3& thePlane);
347 Standard_EXPORT void DisplayPrivilegedPlane (const Standard_Boolean theOnOff, const Quantity_Length theSize = 1);
349 public: //! @name grid management
351 //! Activates the grid in all views of <me>.
352 Standard_EXPORT void ActivateGrid (const Aspect_GridType aGridType, const Aspect_GridDrawMode aGridDrawMode);
354 //! Deactivates the grid in all views of <me>.
355 Standard_EXPORT void DeactivateGrid();
357 //! Show/Don't show grid echo to the hit point.
358 //! If TRUE,the grid echo will be shown at ConvertToGrid() time.
359 Standard_EXPORT void SetGridEcho (const Standard_Boolean showGrid = Standard_True);
361 //! Show grid echo <aMarker> to the hit point.
362 //! Warning: When the grid echo marker is not set,
363 //! a default marker is build with the attributes:
364 //! marker type : Aspect_TOM_STAR
365 //! marker color : Quantity_NOC_GRAY90
366 //! marker size : 3.0
367 Standard_EXPORT void SetGridEcho (const Handle(Graphic3d_AspectMarker3d)& aMarker);
369 //! Returns TRUE when grid echo must be displayed
371 Standard_EXPORT Standard_Boolean GridEcho() const;
373 //! Returns Standard_True if a grid is activated in <me>.
374 Standard_EXPORT Standard_Boolean IsActive() const;
376 //! Returns the defined grid in <me>.
377 Standard_EXPORT Handle(Aspect_Grid) Grid() const;
379 //! Returns the current grid type defined in <me>.
380 Standard_EXPORT Aspect_GridType GridType() const;
382 //! Returns the current grid draw mode defined in <me>.
383 Standard_EXPORT Aspect_GridDrawMode GridDrawMode() const;
385 //! Returns the definition of the rectangular grid.
386 Standard_EXPORT void RectangularGridValues (Quantity_Length& XOrigin, Quantity_Length& YOrigin, Quantity_Length& XStep, Quantity_Length& YStep, Quantity_PlaneAngle& RotationAngle) const;
388 //! Sets the definition of the rectangular grid.
389 //! <XOrigin>, <YOrigin> defines the origin of the grid.
390 //! <XStep> defines the interval between 2 vertical lines.
391 //! <YStep> defines the interval between 2 horizontal lines.
392 //! <RotationAngle> defines the rotation angle of the grid.
393 Standard_EXPORT void SetRectangularGridValues (const Quantity_Length XOrigin, const Quantity_Length YOrigin, const Quantity_Length XStep, const Quantity_Length YStep, const Quantity_PlaneAngle RotationAngle);
395 //! Returns the definition of the circular grid.
396 Standard_EXPORT void CircularGridValues (Quantity_Length& XOrigin, Quantity_Length& YOrigin, Quantity_Length& RadiusStep, Standard_Integer& DivisionNumber, Quantity_PlaneAngle& RotationAngle) const;
398 //! Sets the definition of the circular grid.
399 //! <XOrigin>, <YOrigin> defines the origin of the grid.
400 //! <RadiusStep> defines the interval between 2 circles.
401 //! <DivisionNumber> defines the section number of one half circle.
402 //! <RotationAngle> defines the rotation angle of the grid.
403 Standard_EXPORT void SetCircularGridValues (const Quantity_Length XOrigin, const Quantity_Length YOrigin, const Quantity_Length RadiusStep, const Standard_Integer DivisionNumber, const Quantity_PlaneAngle RotationAngle);
405 //! Returns the location and the size of the grid.
406 Standard_EXPORT void CircularGridGraphicValues (Quantity_Length& Radius, Quantity_Length& OffSet) const;
408 //! Sets the location and the size of the grid.
409 //! <XSize> defines the width of the grid.
410 //! <YSize> defines the height of the grid.
411 //! <OffSet> defines the displacement along the plane normal.
412 Standard_EXPORT void SetCircularGridGraphicValues (const Quantity_Length Radius, const Quantity_Length OffSet);
414 //! Returns the location and the size of the grid.
415 Standard_EXPORT void RectangularGridGraphicValues (Quantity_Length& XSize, Quantity_Length& YSize, Quantity_Length& OffSet) const;
417 //! Sets the location and the size of the grid.
418 //! <XSize> defines the width of the grid.
419 //! <YSize> defines the height of the grid.
420 //! <OffSet> defines the displacement along the plane normal.
421 Standard_EXPORT void SetRectangularGridGraphicValues (const Quantity_Length XSize, const Quantity_Length YSize, const Quantity_Length OffSet);
423 //! Display grid echo at requested point in the view.
424 Standard_EXPORT void ShowGridEcho (const Handle(V3d_View)& theView, const Graphic3d_Vertex& thePoint);
426 //! Temporarly hide grid echo.
427 Standard_EXPORT void HideGridEcho (const Handle(V3d_View)& theView);
429 public: //! @name deprecated methods
431 Standard_DEPRECATED("This constructor is deprecated")
432 Standard_EXPORT V3d_Viewer (const Handle(Graphic3d_GraphicDriver)& theDriver,
433 const Standard_ExtString theName,
434 const Standard_CString theDomain = "",
435 const Quantity_Length theViewSize = 1000.0,
436 const V3d_TypeOfOrientation theViewProj = V3d_XposYnegZpos,
437 const Quantity_NameOfColor theViewBackground = Quantity_NOC_GRAY30,
438 const V3d_TypeOfVisualization theVisualization = V3d_ZBUFFER,
439 const V3d_TypeOfShadingModel theShadingModel = V3d_GOURAUD,
440 const Standard_Boolean theComputedMode = Standard_True,
441 const Standard_Boolean theDefaultComputedMode = Standard_True);
443 //! Defines the default base colour of views attached
444 //! to the Viewer by supplying the type of colour
445 //! definition and the three component values.
446 Standard_DEPRECATED("This method is deprecated - SetDefaultBackgroundColor() taking Quantity_Color should be used instead")
447 void SetDefaultBackgroundColor (const Quantity_TypeOfColor theType,
448 const Quantity_Parameter theV1,
449 const Quantity_Parameter theV2,
450 const Quantity_Parameter theV3)
452 Standard_Real aV1 = theV1;
453 Standard_Real aV2 = theV2;
454 Standard_Real aV3 = theV3;
455 if (aV1 < 0.0) aV1 = 0.0; else if (aV1 > 1.0) aV1 = 1.0;
456 if (aV2 < 0.0) aV2 = 0.0; else if (aV2 > 1.0) aV2 = 1.0;
457 if (aV3 < 0.0) aV3 = 0.0; else if (aV3 > 1.0) aV3 = 1.0;
458 SetDefaultBackgroundColor (Quantity_Color (aV1, aV2, aV3, theType));
461 Standard_DEPRECATED("This method is deprecated - DefaultBackgroundColor() without arguments should be used instead")
462 void DefaultBackgroundColor (const Quantity_TypeOfColor theType, Quantity_Parameter& theV1, Quantity_Parameter& theV2, Quantity_Parameter& theV3) const
464 Quantity_Color aColor = DefaultBackgroundColor();
465 aColor.Values (theV1, theV2, theV3, theType) ;
470 //! Returns the default background colour.
471 const Aspect_Background& GetBackgroundColor() const { return myBackground; }
473 //! Adds View in Sequence Of Views.
474 Standard_EXPORT void AddView (const Handle(V3d_View)& theView);
476 //! Delete View in Sequence Of Views.
477 Standard_EXPORT void DelView (const Handle(V3d_View)& theView);
479 //! Adds Light in Sequence Of Lights.
480 Standard_EXPORT void AddLight (const Handle(V3d_Light)& theLight);
484 Handle(Graphic3d_GraphicDriver) myDriver;
485 Handle(Graphic3d_StructureManager) myStructureManager;
486 TColStd_MapOfInteger myLayerIds;
487 Aspect_GenId myZLayerGenId;
489 V3d_ListOfView myDefinedViews;
490 V3d_ListOfView myActiveViews;
491 V3d_ListOfLight myDefinedLights;
492 V3d_ListOfLight myActiveLights;
494 Aspect_Background myBackground;
495 Aspect_GradientBackground myGradientBackground;
496 Standard_Real myViewSize;
497 V3d_TypeOfOrientation myViewProj;
498 V3d_TypeOfVisualization myVisualization;
499 V3d_TypeOfShadingModel myShadingModel;
500 V3d_TypeOfView myDefaultTypeOfView;
501 Graphic3d_RenderingParams myDefaultRenderingParams;
503 V3d_ListOfView::Iterator myActiveViewsIterator;
504 V3d_ListOfView::Iterator myDefinedViewsIterator;
505 V3d_ListOfLight::Iterator myActiveLightsIterator;
506 V3d_ListOfLight::Iterator myDefinedLightsIterator;
508 Standard_Boolean myComputedMode;
509 Standard_Boolean myDefaultComputedMode;
511 gp_Ax3 myPrivilegedPlane;
512 Handle(Graphic3d_Structure) myPlaneStructure;
513 Standard_Boolean myDisplayPlane;
514 Quantity_Length myDisplayPlaneLength;
516 Handle(V3d_RectangularGrid) myRGrid;
517 Handle(V3d_CircularGrid) myCGrid;
518 Aspect_GridType myGridType;
519 Standard_Boolean myGridEcho;
520 Handle(Graphic3d_Structure) myGridEchoStructure;
521 Handle(Graphic3d_Group) myGridEchoGroup;
522 Handle(Graphic3d_AspectMarker3d) myGridEchoAspect;
523 Graphic3d_Vertex myGridEchoLastVert;
527 DEFINE_STANDARD_HANDLE(V3d_Viewer, Standard_Transient)
529 #endif // _V3d_Viewer_HeaderFile