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 <Standard.hxx>
21 #include <Standard_Type.hxx>
23 #include <Standard_Integer.hxx>
24 #include <TCollection_ExtendedString.hxx>
25 #include <TCollection_AsciiString.hxx>
26 #include <V3d_ListOfTransient.hxx>
27 #include <Aspect_Background.hxx>
28 #include <Aspect_GradientBackground.hxx>
29 #include <Standard_Real.hxx>
30 #include <V3d_TypeOfOrientation.hxx>
31 #include <V3d_TypeOfVisualization.hxx>
32 #include <V3d_TypeOfShadingModel.hxx>
33 #include <V3d_TypeOfSurfaceDetail.hxx>
34 #include <Quantity_PlaneAngle.hxx>
35 #include <V3d_TypeOfView.hxx>
36 #include <TColStd_ListIteratorOfListOfTransient.hxx>
37 #include <Standard_Boolean.hxx>
39 #include <Quantity_Length.hxx>
40 #include <Aspect_GridType.hxx>
41 #include <Graphic3d_Vertex.hxx>
42 #include <MMgt_TShared.hxx>
43 #include <Standard_ExtString.hxx>
44 #include <Standard_CString.hxx>
45 #include <Quantity_NameOfColor.hxx>
46 #include <V3d_TypeOfUpdate.hxx>
47 #include <Quantity_TypeOfColor.hxx>
48 #include <Quantity_Parameter.hxx>
49 #include <Aspect_GradientFillMethod.hxx>
50 #include <Aspect_GridDrawMode.hxx>
51 #include <Graphic3d_ZLayerSettings.hxx>
52 #include <TColStd_SequenceOfInteger.hxx>
53 class Graphic3d_GraphicDriver;
54 class Visual3d_ViewManager;
56 class Graphic3d_Structure;
57 class V3d_RectangularGrid;
58 class V3d_CircularGrid;
59 class Graphic3d_Group;
60 class Graphic3d_AspectMarker3d;
66 class Aspect_Background;
67 class Aspect_GradientBackground;
71 DEFINE_STANDARD_HANDLE(V3d_Viewer, MMgt_TShared)
73 //! Defines services on Viewer type objects.
74 //! The methods of this class allow editing and
75 //! interrogation of the parameters linked to the viewer
76 //! its friend classes (View,light,plane).
77 class V3d_Viewer : public MMgt_TShared
83 //! Create a Viewer with the given graphic driver and the given parameters or
84 //! with their default values.
85 //! Currently creating of more than 100 viewer instances
86 //! is not supported and leads to an exception.
87 //! This limitation might be addressed in some future OCCT releases.
88 //! If the size of the view is <= 0
89 //! Warning: Client must creates a graphic driver
90 Standard_EXPORT V3d_Viewer(const Handle(Graphic3d_GraphicDriver)& theDriver, const Standard_ExtString theName, const Standard_CString theDomain = "", const Quantity_Length theViewSize = 1000.0, const V3d_TypeOfOrientation theViewProj = V3d_XposYnegZpos, const Quantity_NameOfColor theViewBackground = Quantity_NOC_GRAY30, const V3d_TypeOfVisualization theVisualization = V3d_ZBUFFER, const V3d_TypeOfShadingModel theShadingModel = V3d_GOURAUD, const V3d_TypeOfUpdate theUpdateMode = V3d_WAIT, const Standard_Boolean theComputedMode = Standard_True, const Standard_Boolean theDefaultComputedMode = Standard_True, const V3d_TypeOfSurfaceDetail theSurfaceDetail = V3d_TEX_NONE);
92 //! creates a view in the viewer according to its
93 //! default parameters.
94 Standard_EXPORT Handle(V3d_View) CreateView();
96 //! Activates all of the views of a viewer attached
98 Standard_EXPORT void SetViewOn();
100 //! Activates a particular view in the Viewer .
101 //! Must be call if the Window attached to the view
102 //! has been Deiconified .
103 Standard_EXPORT void SetViewOn (const Handle(V3d_View)& View);
105 //! Deactivates all the views of a Viewer
106 //! attached to a window.
107 Standard_EXPORT void SetViewOff();
109 //! Deactivates a particular view in the Viewer.
110 //! Must be call if the Window attached to the view
111 //! has been Iconified .
112 Standard_EXPORT void SetViewOff (const Handle(V3d_View)& View);
114 //! Deprecated, Redraw() should be used instead.
115 Standard_EXPORT void Update();
117 //! Updates the lights of all the views of a viewer.
118 Standard_EXPORT void UpdateLights();
120 //! Redraws all the views of the Viewer even if no
121 //! modification has taken place. Must be called if
122 //! all the views of the Viewer are exposed, as for
123 //! example in a global DeIconification.
124 Standard_EXPORT void Redraw() const;
126 //! Updates layer of immediate presentations.
127 Standard_EXPORT void RedrawImmediate() const;
129 //! Invalidates viewer content but does not redraw it.
130 Standard_EXPORT void Invalidate() const;
132 //! Suppresses the Viewer.
133 Standard_EXPORT void Remove();
135 //! Erase all Objects in All the views.
136 Standard_EXPORT void Erase() const;
138 //! UnHighlight all Objects in All the views.
139 Standard_EXPORT void UnHighlight() const;
141 //! Defines the default base colour of views attached
142 //! to the Viewer by supplying the type of colour
143 //! definition and the three component values..
144 Standard_EXPORT void SetDefaultBackgroundColor (const Quantity_TypeOfColor Type, const Quantity_Parameter V1, const Quantity_Parameter V2, const Quantity_Parameter V3);
146 //! Defines the default background colour of views
147 //! attached to the viewer by supplying the name of the
148 //! colour under the form Quantity_NOC_xxxx .
149 Standard_EXPORT void SetDefaultBackgroundColor (const Quantity_NameOfColor Name);
151 //! Defines the default background colour of views
152 //! attached to the viewer by supplying the color object
153 Standard_EXPORT void SetDefaultBackgroundColor (const Quantity_Color& Color);
155 //! Defines the default gradient background colours of view
156 //! attached to the viewer by supplying the name of the
157 //! colours under the form Quantity_NOC_xxxx .
158 Standard_EXPORT void SetDefaultBgGradientColors (const Quantity_NameOfColor Name1, const Quantity_NameOfColor Name2, const Aspect_GradientFillMethod FillStyle = Aspect_GFM_HOR);
160 //! Defines the default gradient background colours of views
161 //! attached to the viewer by supplying the colour objects
162 Standard_EXPORT void SetDefaultBgGradientColors (const Quantity_Color& Color1, const Quantity_Color& Color2, const Aspect_GradientFillMethod FillStyle = Aspect_GFM_HOR);
164 //! Gives a default size for the creation of views of
166 Standard_EXPORT void SetDefaultViewSize (const Quantity_Length Size);
168 //! Gives the default projection for creating views
170 Standard_EXPORT void SetDefaultViewProj (const V3d_TypeOfOrientation Orientation);
172 //! Gives the default visualisation mode..
173 Standard_EXPORT void SetDefaultVisualization (const V3d_TypeOfVisualization Type);
175 //! defines the strategy concerning the ZBuffer activity.
176 //! If Automatic is true, ZBuffer will be activated or
177 //! deactivated depending on the fact that faces exist or
178 //! not in the Viewer. This will optimize the response time
179 //! in the case where only wireframe objects are displayed.
180 //! If Automatic is False, ZBuffer will be activated or
181 //! deactivated depending on the choice of SetVisualization
183 //! Note that by default, the ZBufferManagment is not automatic.
184 Standard_EXPORT void SetZBufferManagment (const Standard_Boolean Automatic);
186 //! returns the ZBuffer stategy choice.
187 Standard_EXPORT Standard_Boolean ZBufferManagment() const;
189 //! Gives the default type of SHADING.
190 Standard_EXPORT void SetDefaultShadingModel (const V3d_TypeOfShadingModel Type);
192 //! Gives the default type of texture mapping.
193 Standard_EXPORT void SetDefaultSurfaceDetail (const V3d_TypeOfSurfaceDetail Type);
195 Standard_EXPORT void SetDefaultAngle (const Quantity_PlaneAngle Angle);
197 //! Defines the mode of regenerating the views making
198 //! up the viewer. This can be immediate <ASAP> or
199 //! deferred <WAIT>. In this latter case, the views are
200 //! updated when the method Update(me) is called.
201 Standard_EXPORT void SetUpdateMode (const V3d_TypeOfUpdate Mode);
203 Standard_EXPORT void SetDefaultTypeOfView (const V3d_TypeOfView Type);
205 Standard_EXPORT void SetPrivilegedPlane (const gp_Ax3& aPlane);
207 Standard_EXPORT gp_Ax3 PrivilegedPlane() const;
209 Standard_EXPORT void DisplayPrivilegedPlane (const Standard_Boolean OnOff, const Quantity_Length aSize = 1);
211 //! Activates MyLight in the viewer.
212 Standard_EXPORT void SetLightOn (const Handle(V3d_Light)& MyLight);
214 //! Activates all the lights defined in this viewer.
215 Standard_EXPORT void SetLightOn();
217 //! Desactivate MyLight in this viewer.
218 Standard_EXPORT void SetLightOff (const Handle(V3d_Light)& MyLight);
220 //! Deactivate all the Lights defined in this viewer.
221 Standard_EXPORT void SetLightOff();
223 //! Delete Light in Sequence Of Lights.
224 Standard_EXPORT void DelLight (const Handle(V3d_Light)& MyLight);
226 //! Defines the selected light.
227 Standard_EXPORT void SetCurrentSelectedLight (const Handle(V3d_Light)& TheLight);
229 //! Defines the selected light at NULL.
230 Standard_EXPORT void ClearCurrentSelectedLight();
232 //! Returns the default background colour depending of the type.
233 Standard_EXPORT void DefaultBackgroundColor (const Quantity_TypeOfColor Type, Quantity_Parameter& V1, Quantity_Parameter& V2, Quantity_Parameter& V3) const;
235 //! Returns the default background colour object.
236 Standard_EXPORT Quantity_Color DefaultBackgroundColor() const;
238 //! Returns the gradient background colour objects of the view.
239 Standard_EXPORT void DefaultBgGradientColors (Quantity_Color& Color1, Quantity_Color& Color2) const;
241 //! Returns the default size of the view.
242 Standard_EXPORT Quantity_Length DefaultViewSize() const;
244 //! Returns the default Projection.
245 Standard_EXPORT V3d_TypeOfOrientation DefaultViewProj() const;
247 //! Returns the default type of Visualization.
248 Standard_EXPORT V3d_TypeOfVisualization DefaultVisualization() const;
250 //! Returns the default type of Shading
251 Standard_EXPORT V3d_TypeOfShadingModel DefaultShadingModel() const;
253 //! Returns the default type of texture mapping
254 Standard_EXPORT V3d_TypeOfSurfaceDetail DefaultSurfaceDetail() const;
256 Standard_EXPORT Quantity_PlaneAngle DefaultAngle() const;
258 //! Returns the regeneration mode of views in the viewer.
259 Standard_EXPORT V3d_TypeOfUpdate UpdateMode() const;
261 //! Returns True if One View more can be
262 //! activated in this Viewer.
263 Standard_EXPORT Standard_Boolean IfMoreViews() const;
265 //! initializes an iteration on the active views.
266 Standard_EXPORT void InitActiveViews();
268 //! returns true if there are more active view(s) to return.
269 Standard_EXPORT Standard_Boolean MoreActiveViews() const;
271 //! Go to the next active view
272 //! (if there is not, ActiveView will raise an exception)
273 Standard_EXPORT void NextActiveViews();
275 Standard_EXPORT Handle(V3d_View) ActiveView() const;
277 //! returns true if there is only
279 Standard_EXPORT Standard_Boolean LastActiveView() const;
281 //! initializes an iteration on the Defined views.
282 Standard_EXPORT void InitDefinedViews();
284 //! returns true if there are more Defined view(s) to return.
285 Standard_EXPORT Standard_Boolean MoreDefinedViews() const;
287 //! Go to the next Defined view
288 //! (if there is not, DefinedView will raise an exception)
289 Standard_EXPORT void NextDefinedViews();
291 Standard_EXPORT Handle(V3d_View) DefinedView() const;
293 //! initializes an iteration on the active Lights.
294 Standard_EXPORT void InitActiveLights();
296 //! returns true if there are more active Light(s) to return.
297 Standard_EXPORT Standard_Boolean MoreActiveLights() const;
299 //! Go to the next active Light
300 //! (if there is not, ActiveLight will raise an exception)
301 Standard_EXPORT void NextActiveLights();
303 Standard_EXPORT Handle(V3d_Light) ActiveLight() const;
305 //! initializes an iteration on the Defined Lights.
306 Standard_EXPORT void InitDefinedLights();
308 //! returns true if there are more Defined Light(s) to return.
309 Standard_EXPORT Standard_Boolean MoreDefinedLights() const;
311 //! Go to the next Defined Light
312 //! (if there is not, DefinedLight will raise an exception)
313 Standard_EXPORT void NextDefinedLights();
315 Standard_EXPORT Handle(V3d_Light) DefinedLight() const;
317 //! Returns the viewer associated to Visual3d .
318 Standard_EXPORT Handle(Visual3d_ViewManager) Viewer() const;
320 //! Returns the Selected Light.
321 Standard_EXPORT Handle(V3d_Light) CurrentSelectedLight() const;
323 Standard_EXPORT Standard_Boolean IsGlobalLight (const Handle(V3d_Light)& TheLight) const;
325 //! returns true if the computed mode can be used.
326 Standard_EXPORT Standard_Boolean ComputedMode() const;
328 //! returns true if by default the computed mode must be used.
329 Standard_EXPORT Standard_Boolean DefaultComputedMode() const;
331 //! Activates the grid in all views of <me>.
332 Standard_EXPORT void ActivateGrid (const Aspect_GridType aGridType, const Aspect_GridDrawMode aGridDrawMode);
334 //! Deactivates the grid in all views of <me>.
335 Standard_EXPORT void DeactivateGrid();
337 //! Show/Don't show grid echo to the hit point.
338 //! If TRUE,the grid echo will be shown at ConvertToGrid() time.
339 Standard_EXPORT void SetGridEcho (const Standard_Boolean showGrid = Standard_True);
341 //! Show grid echo <aMarker> to the hit point.
342 //! Warning: When the grid echo marker is not set,
343 //! a default marker is build with the attributes:
344 //! marker type : Aspect_TOM_STAR
345 //! marker color : Quantity_NOC_GRAY90
346 //! marker size : 3.0
347 Standard_EXPORT void SetGridEcho (const Handle(Graphic3d_AspectMarker3d)& aMarker);
349 //! Returns TRUE when grid echo must be displayed
351 Standard_EXPORT Standard_Boolean GridEcho() const;
353 //! Returns Standard_True if a grid is activated in <me>.
354 Standard_EXPORT Standard_Boolean IsActive() const;
356 //! Returns the defined grid in <me>.
357 Standard_EXPORT Handle(Aspect_Grid) Grid() const;
359 //! Returns the current grid type defined in <me>.
360 Standard_EXPORT Aspect_GridType GridType() const;
362 //! Returns the current grid draw mode defined in <me>.
363 Standard_EXPORT Aspect_GridDrawMode GridDrawMode() const;
365 //! Returns the definition of the rectangular grid.
366 Standard_EXPORT void RectangularGridValues (Quantity_Length& XOrigin, Quantity_Length& YOrigin, Quantity_Length& XStep, Quantity_Length& YStep, Quantity_PlaneAngle& RotationAngle) const;
368 //! Sets the definition of the rectangular grid.
369 //! <XOrigin>, <YOrigin> defines the origin of the grid.
370 //! <XStep> defines the interval between 2 vertical lines.
371 //! <YStep> defines the interval between 2 horizontal lines.
372 //! <RotationAngle> defines the rotation angle of the grid.
373 Standard_EXPORT void SetRectangularGridValues (const Quantity_Length XOrigin, const Quantity_Length YOrigin, const Quantity_Length XStep, const Quantity_Length YStep, const Quantity_PlaneAngle RotationAngle);
375 //! Returns the definition of the circular grid.
376 Standard_EXPORT void CircularGridValues (Quantity_Length& XOrigin, Quantity_Length& YOrigin, Quantity_Length& RadiusStep, Standard_Integer& DivisionNumber, Quantity_PlaneAngle& RotationAngle) const;
378 //! Sets the definition of the circular grid.
379 //! <XOrigin>, <YOrigin> defines the origin of the grid.
380 //! <RadiusStep> defines the interval between 2 circles.
381 //! <DivisionNumber> defines the section number of one half circle.
382 //! <RotationAngle> defines the rotation angle of the grid.
383 Standard_EXPORT void SetCircularGridValues (const Quantity_Length XOrigin, const Quantity_Length YOrigin, const Quantity_Length RadiusStep, const Standard_Integer DivisionNumber, const Quantity_PlaneAngle RotationAngle);
385 //! Returns the location and the size of the grid.
386 Standard_EXPORT void CircularGridGraphicValues (Quantity_Length& Radius, Quantity_Length& OffSet) const;
388 //! Sets the location and the size of the grid.
389 //! <XSize> defines the width of the grid.
390 //! <YSize> defines the height of the grid.
391 //! <OffSet> defines the displacement along the plane normal.
392 Standard_EXPORT void SetCircularGridGraphicValues (const Quantity_Length Radius, const Quantity_Length OffSet);
394 //! Returns the location and the size of the grid.
395 Standard_EXPORT void RectangularGridGraphicValues (Quantity_Length& XSize, Quantity_Length& YSize, Quantity_Length& OffSet) const;
397 //! Sets the location and the size of the grid.
398 //! <XSize> defines the width of the grid.
399 //! <YSize> defines the height of the grid.
400 //! <OffSet> defines the displacement along the plane normal.
401 Standard_EXPORT void SetRectangularGridGraphicValues (const Quantity_Length XSize, const Quantity_Length YSize, const Quantity_Length OffSet);
403 //! Returns the gradient background of the view.
404 Standard_EXPORT Aspect_GradientBackground GetGradientBackground() const;
406 //! defines default lights -
407 //! positional-light 0.3 0. 0.
408 //! directional-light V3d_XnegYposZpos
409 //! directional-light V3d_XnegYneg
411 Standard_EXPORT void SetDefaultLights();
414 //! Display grid echo at requested point in the view.
415 Standard_EXPORT void ShowGridEcho (const Handle(V3d_View)& theView, const Graphic3d_Vertex& thePoint);
418 //! Temporarly hide grid echo.
419 Standard_EXPORT void HideGridEcho (const Handle(V3d_View)& theView);
421 //! Sets the settings for a single Z layer.
422 Standard_EXPORT void SetZLayerSettings (const Standard_Integer theLayerId, const Graphic3d_ZLayerSettings& theSettings);
424 //! Returns the settings of a single Z layer.
425 Standard_EXPORT Graphic3d_ZLayerSettings ZLayerSettings (const Standard_Integer theLayerId);
427 //! Add a new top-level Z layer to all managed views and get
428 //! its ID as <theLayerId> value. The Z layers are controlled entirely
429 //! by viewer, it is not possible to add a layer to a
430 //! particular view. The method returns Standard_False if the layer can
431 //! not be created. The layer mechanism allows to display structures
432 //! in higher layers in overlay of structures in lower layers.
433 Standard_EXPORT Standard_Boolean AddZLayer (Standard_Integer& theLayerId);
435 //! Remove Z layer with ID <theLayerId>. Method returns
436 //! Standard_False if the layer can not be removed or doesn't exists.
437 //! By default, there are always default bottom-level layer that can't
439 Standard_EXPORT Standard_Boolean RemoveZLayer (const Standard_Integer theLayerId);
441 //! Return all Z layer ids in sequence ordered by overlay level
442 //! from lowest layer to highest ( foreground ). The first layer ID
443 //! in sequence is the default layer that can't be removed.
444 Standard_EXPORT void GetAllZLayers (TColStd_SequenceOfInteger& theLayerSeq) const;
446 Standard_EXPORT const Handle(Graphic3d_GraphicDriver)& Driver() const;
448 Standard_EXPORT Standard_ExtString NextName() const;
450 Standard_EXPORT Standard_CString Domain() const;
453 friend class V3d_View;
454 friend class V3d_Light;
457 DEFINE_STANDARD_RTTI(V3d_Viewer,MMgt_TShared)
462 Standard_EXPORT void IncrCount();
469 //! Returns the default background colour.
470 Standard_EXPORT Aspect_Background GetBackgroundColor() const;
472 //! Adds View in Sequence Of Views.
473 Standard_EXPORT void AddView (const Handle(V3d_View)& MyView);
475 //! Delete View in Sequence Of Views.
476 Standard_EXPORT void DelView (const Handle(V3d_View)& MyView);
478 //! Adds Light in Sequence Of Lights.
479 Standard_EXPORT void AddLight (const Handle(V3d_Light)& MyLight);
481 Standard_EXPORT Standard_Boolean IsActive (const Handle(V3d_View)& aView) const;
483 Standard_Integer myNextCount;
484 Handle(Graphic3d_GraphicDriver) myDriver;
485 TCollection_ExtendedString myName;
486 TCollection_AsciiString myDomain;
487 Handle(Visual3d_ViewManager) MyViewer;
488 V3d_ListOfTransient MyDefinedViews;
489 V3d_ListOfTransient MyActiveViews;
490 V3d_ListOfTransient MyDefinedLights;
491 V3d_ListOfTransient MyActiveLights;
492 Aspect_Background MyBackground;
493 Aspect_GradientBackground MyGradientBackground;
494 Standard_Real MyViewSize;
495 V3d_TypeOfOrientation MyViewProj;
496 V3d_TypeOfVisualization MyVisualization;
497 V3d_TypeOfShadingModel MyShadingModel;
498 V3d_TypeOfSurfaceDetail MySurfaceDetail;
499 Quantity_PlaneAngle MyDefaultAngle;
500 V3d_TypeOfView MyDefaultTypeOfView;
501 Handle(V3d_Light) MyCurrentSelectedLight;
502 TColStd_ListIteratorOfListOfTransient myActiveViewsIterator;
503 TColStd_ListIteratorOfListOfTransient myDefinedViewsIterator;
504 TColStd_ListIteratorOfListOfTransient myActiveLightsIterator;
505 TColStd_ListIteratorOfListOfTransient myDefinedLightsIterator;
506 Standard_Boolean myComputedMode;
507 Standard_Boolean myDefaultComputedMode;
508 gp_Ax3 myPrivilegedPlane;
509 Handle(Graphic3d_Structure) myPlaneStructure;
510 Standard_Boolean myDisplayPlane;
511 Quantity_Length myDisplayPlaneLength;
512 Handle(V3d_RectangularGrid) myRGrid;
513 Handle(V3d_CircularGrid) myCGrid;
514 Aspect_GridType myGridType;
515 Standard_Boolean myGridEcho;
516 Handle(Graphic3d_Structure) myGridEchoStructure;
517 Handle(Graphic3d_Group) myGridEchoGroup;
518 Handle(Graphic3d_AspectMarker3d) myGridEchoAspect;
519 Graphic3d_Vertex myGridEchoLastVert;
530 #endif // _V3d_Viewer_HeaderFile