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
9 -- under the terms of the GNU Lesser General Public 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 -- Modified FMN - 02/02/98 -> Specifique UNIX
18 -- CAL - 16/07/98 -> S3892. Ajout grilles 3d.
19 -- GG - 15/12/99 -> GER61351 Add SetDefaultBackgroundColor()
20 -- and DefaultBackgroundColor() methods
21 -- GG - 20/01/00 -> IMP200100 Add GridDrawMode() method
22 -- GG - 24/01/00 -> IMP240100 Add SetGridEcho() methods
23 -- Add GridEcho() method.
24 -- Add ShowGridEcho() private method
25 -- SAV - 26/11/02 -> Add new field to store grid echo aspect
27 class Viewer from V3d inherits TShared from MMgt
31 ---Purpose: Defines services on Viewer type objects.
32 -- The methods of this class allow editing and
33 -- interrogation of the parameters linked to the viewer
34 -- its friend classes (View,light,plane).
36 ---Keywords: Viewer,Default Attributes
42 GraphicDriver from Graphic3d,
43 TypeOfUpdate from V3d,
44 TypeOfVisualization from V3d,
45 TypeOfShadingModel from V3d,
46 TypeOfSurfaceDetail from V3d,
47 TypeOfOrientation from V3d,
50 ListOfTransient from V3d,
51 ListIteratorOfListOfTransient from TColStd,
52 SequenceOfInteger from TColStd,
54 Vector from Graphic3d,
55 ViewManager from Visual3d,
56 NameOfColor from Quantity,
57 TypeOfColor from Quantity,
60 PlaneAngle from Quantity,
61 Background from Aspect,
62 GradientBackground from Aspect,
63 Parameter from Quantity,
64 AsciiString,ExtendedString from TCollection,
65 Ax3 from gp,Structure from Graphic3d,
66 Vertex from Graphic3d,
68 AspectMarker3d from Graphic3d,
69 RectangularGrid from V3d,
70 CircularGrid from V3d,
73 GridDrawMode from Aspect,
74 GradientFillMethod from Aspect
82 Create (theDriver : GraphicDriver from Graphic3d;
83 theName : ExtString from Standard;
84 theDomain : CString from Standard = "";
85 theViewSize : Length from Quantity = 1000.0 ;
86 theViewProj : TypeOfOrientation from V3d= V3d_XposYnegZpos ;
87 theViewBackground : NameOfColor from Quantity = Quantity_NOC_GRAY30;
88 theVisualization : TypeOfVisualization from V3d = V3d_ZBUFFER;
89 theShadingModel : TypeOfShadingModel from V3d = V3d_GOURAUD ;
90 theUpdateMode : TypeOfUpdate from V3d = V3d_WAIT;
91 theComputedMode : Boolean from Standard = Standard_True;
92 theDefaultComputedMode: Boolean from Standard = Standard_True;
93 theSurfaceDetail : TypeOfSurfaceDetail from V3d = V3d_TEX_NONE)
94 returns mutable Viewer from V3d
95 ---Purpose: Create a Viewer with the given graphic driver and the given parameters or
96 -- with their default values.
97 -- Currently creating of more than 100 viewer instances
98 -- is not supported and leads to an exception.
99 -- This limitation might be addressed in some future OCCT releases.
100 raises BadValue from V3d ;
101 ---Purpose: If the size of the view is <= 0
102 -- Warning: Client must creates a graphic driver
104 CreateView (me: mutable) returns mutable View from V3d;
106 ---Purpose: creates a view in the viewer according to its
107 -- default parameters.
109 -------------------------------------------------------
110 ---Category: Methods to modify the status of the viewer
111 -------------------------------------------------------
113 SetViewOn (me:mutable );
115 ---Purpose: Activates all of the views of a viewer attached
118 SetViewOn (me:mutable; View : View from V3d )
120 ---Purpose: Activates a particular view in the Viewer .
121 -- Must be call if the Window attached to the view
122 -- has been Deiconified .
123 raises BadValue from V3d;
124 -- If the view is not mapped on the window.
126 SetViewOff (me:mutable);
128 ---Purpose: Deactivates all the views of a Viewer
129 -- attached to a window.
131 SetViewOff (me:mutable; View : View from V3d)
133 ---Purpose: Deactivates a particular view in the Viewer.
134 -- Must be call if the Window attached to the view
135 -- has been Iconified .
136 raises BadValue from V3d;
137 -- If the view is not mapped on the window.
139 Update (me:mutable ) is static;
141 ---Purpose: Deprecated, Redraw() should be used instead.
143 UpdateLights (me: mutable);
145 ---Purpose: Updates the lights of all the views of a viewer.
149 ---Purpose: Redraws all the views of the Viewer even if no
150 -- modification has taken place. Must be called if
151 -- all the views of the Viewer are exposed, as for
152 -- example in a global DeIconification.
156 ---Purpose: Suppresses the Viewer.
160 ---Purpose: Erase all Objects in All the views.
164 ---Purpose: UnHighlight all Objects in All the views.
166 SetDefaultBackgroundColor (me:mutable; Type : TypeOfColor; V1, V2, V3 : Parameter );
168 ---Purpose: Defines the default base colour of views attached
169 -- to the Viewer by supplying the type of colour
170 -- definition and the three component values..
172 SetDefaultBackgroundColor (me:mutable; Name : NameOfColor );
174 ---Purpose: Defines the default background colour of views
175 -- attached to the viewer by supplying the name of the
176 -- colour under the form Quantity_NOC_xxxx .
178 SetDefaultBackgroundColor (me:mutable; Color : Color from Quantity);
180 ---Purpose: Defines the default background colour of views
181 -- attached to the viewer by supplying the color object
183 SetDefaultBgGradientColors ( me:mutable;
186 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
188 ---Purpose: Defines the default gradient background colours of view
189 -- attached to the viewer by supplying the name of the
190 -- colours under the form Quantity_NOC_xxxx .
192 SetDefaultBgGradientColors ( me : mutable ;
193 Color1 : Color from Quantity;
194 Color2 : Color from Quantity;
195 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
197 ---Purpose: Defines the default gradient background colours of views
198 -- attached to the viewer by supplying the colour objects
200 SetDefaultViewSize (me:mutable; Size : Length )
202 ---Purpose: Gives a default size for the creation of views of
204 raises BadValue from V3d;
205 -- If the size of the view is <= 0
207 SetDefaultViewProj (me:mutable; Orientation : TypeOfOrientation );
209 ---Purpose: Gives the default projection for creating views
212 SetDefaultVisualization(me:mutable; Type : TypeOfVisualization from V3d);
214 ---Purpose: Gives the default visualisation mode..
217 SetZBufferManagment(me: mutable; Automatic: Boolean from Standard);
219 ---Purpose: defines the strategy concerning the ZBuffer activity.
220 -- If Automatic is true, ZBuffer will be activated or
221 -- deactivated depending on the fact that faces exist or
222 -- not in the Viewer. This will optimize the response time
223 -- in the case where only wireframe objects are displayed.
224 -- If Automatic is False, ZBuffer will be activated or
225 -- deactivated depending on the choice of SetVisualization
227 -- Note that by default, the ZBufferManagment is not automatic.
229 ZBufferManagment(me) returns Boolean from Standard;
231 ---Purpose: returns the ZBuffer stategy choice.
233 SetDefaultShadingModel(me:mutable; Type : TypeOfShadingModel from V3d);
235 ---Purpose: Gives the default type of SHADING.
237 SetDefaultSurfaceDetail(me:mutable; Type : TypeOfSurfaceDetail from V3d);
239 ---Purpose: Gives the default type of texture mapping.
241 SetDefaultAngle (me:mutable; Angle : PlaneAngle from Quantity);
244 SetUpdateMode ( me: mutable ; Mode : TypeOfUpdate from V3d );
246 ---Purpose: Defines the mode of regenerating the views making
247 -- up the viewer. This can be immediate <ASAP> or
248 -- deferred <WAIT>. In this latter case, the views are
249 -- updated when the method Update(me) is called.
251 SetDefaultTypeOfView(me:mutable; Type : TypeOfView from V3d);
255 SetPrivilegedPlane(me: mutable; aPlane: Ax3 from gp);
258 PrivilegedPlane(me) returns Ax3 from gp;
261 DisplayPrivilegedPlane(me: mutable; OnOff: Boolean from Standard; aSize: Length from Quantity = 1);
264 SetLightOn(me:mutable; MyLight : Light from V3d )
266 ---Purpose: Activates MyLight in the viewer.
267 raises BadValue from V3d;
268 -- If No More Light can be activated in MyViewer .
270 SetLightOn(me:mutable)
272 ---Purpose: Activates all the lights defined in this viewer.
273 raises BadValue from V3d;
274 -- If No More Light can be activated in MyViewer .
276 SetLightOff(me:mutable; MyLight : Light from V3d );
278 ---Purpose: Desactivate MyLight in this viewer.
280 SetLightOff(me:mutable);
282 ---Purpose: Deactivate all the Lights defined in this viewer.
284 DelLight(me:mutable; MyLight : Light from V3d);
286 ---Purpose: Delete Light in Sequence Of Lights.
288 SetCurrentSelectedLight (me : mutable; TheLight : Light from V3d);
290 ---Purpose: Defines the selected light.
292 ClearCurrentSelectedLight (me : mutable);
294 ---Purpose: Defines the selected light at NULL.
296 -----------------------------------------
297 ---Category: Inquire methods
298 -----------------------------------------
300 DefaultBackgroundColor ( me ; Type : TypeOfColor ; V1,V2,V3 : out Parameter);
302 ---Purpose: Returns the default background colour depending of the type.
303 DefaultBackgroundColor ( me ) returns Color from Quantity;
305 ---Purpose: Returns the default background colour object.
307 DefaultBgGradientColors( me;
308 Color1 : out Color from Quantity;
309 Color2 : out Color from Quantity) ;
311 ---Purpose: Returns the gradient background colour objects of the view.
313 DefaultViewSize ( me) returns Length;
315 ---Purpose: Returns the default size of the view.
317 DefaultViewProj ( me) returns TypeOfOrientation;
319 ---Purpose: Returns the default Projection.
321 DefaultVisualization ( me ) returns TypeOfVisualization from V3d;
323 ---Purpose: Returns the default type of Visualization.
325 DefaultShadingModel ( me ) returns TypeOfShadingModel from V3d;
327 ---Purpose: Returns the default type of Shading
329 DefaultSurfaceDetail ( me ) returns TypeOfSurfaceDetail from V3d;
331 ---Purpose: Returns the default type of texture mapping
333 DefaultAngle ( me ) returns PlaneAngle from Quantity;
336 UpdateMode ( me ) returns TypeOfUpdate from V3d;
338 ---Purpose: Returns the regeneration mode of views in the viewer.
340 IfMoreViews( me ) returns Boolean;
342 ---Purpose: Returns True if One View more can be
343 -- activated in this Viewer.
346 ------------------------------
347 ---Category: iteration methods
348 ------------------------------
350 InitActiveViews(me: mutable);
352 ---Purpose: initializes an iteration on the active views.
354 MoreActiveViews (me) returns Boolean from Standard;
356 ---Purpose: returns true if there are more active view(s) to return.
358 NextActiveViews (me: mutable);
360 ---Purpose : Go to the next active view
361 -- (if there is not, ActiveView will raise an exception)
363 ActiveView(me) returns mutable View from V3d;
366 LastActiveView(me) returns Boolean from Standard;
368 ---Purpose: returns true if there is only
371 InitDefinedViews(me: mutable);
373 ---Purpose: initializes an iteration on the Defined views.
376 MoreDefinedViews (me) returns Boolean from Standard;
378 ---Purpose: returns true if there are more Defined view(s) to return.
381 NextDefinedViews (me: mutable);
383 ---Purpose : Go to the next Defined view
384 -- (if there is not, DefinedView will raise an exception)
386 DefinedView(me) returns View from V3d;
389 InitActiveLights(me: mutable);
391 ---Purpose: initializes an iteration on the active Lights.
393 MoreActiveLights (me) returns Boolean from Standard;
395 ---Purpose: returns true if there are more active Light(s) to return.
398 NextActiveLights (me: mutable);
400 ---Purpose : Go to the next active Light
401 -- (if there is not, ActiveLight will raise an exception)
404 ActiveLight(me) returns mutable Light from V3d;
407 InitDefinedLights(me: mutable);
409 ---Purpose: initializes an iteration on the Defined Lights.
411 MoreDefinedLights (me) returns Boolean from Standard;
413 ---Purpose: returns true if there are more Defined Light(s) to return.
415 NextDefinedLights (me: mutable);
417 ---Purpose : Go to the next Defined Light
418 -- (if there is not, DefinedLight will raise an exception)
420 DefinedLight(me) returns Light from V3d;
423 Viewer (me) returns mutable ViewManager ;
425 ---Purpose: Returns the viewer associated to Visual3d .
427 CurrentSelectedLight (me) returns Light from V3d;
429 ---Purpose: Returns the Selected Light.
431 IsGlobalLight (me; TheLight : Light from V3d) returns Boolean;
434 ComputedMode(me) returns Boolean from Standard;
436 ---Purpose: returns true if the computed mode can be used.
438 DefaultComputedMode(me) returns Boolean from Standard;
440 ---Purpose: returns true if by default the computed mode must be used.
442 -----------------------------------------
443 ---Category: grid management
444 -----------------------------------------
446 ActivateGrid (me : mutable;
447 aGridType : GridType from Aspect;
448 aGridDrawMode : GridDrawMode from Aspect)
450 ---Purpose: Activates the grid in all views of <me>.
452 ---Category: grid management
454 DeactivateGrid (me : mutable)
456 ---Purpose: Deactivates the grid in all views of <me>.
458 ---Category: grid management
460 SetGridEcho (me : mutable;
461 showGrid: Boolean from Standard = Standard_True) is static;
462 ---Purpose: Show/Don't show grid echo to the hit point.
463 -- If TRUE,the grid echo will be shown at ConvertToGrid() time.
465 ---Category: grid management
467 SetGridEcho (me : mutable;
468 aMarker: AspectMarker3d from Graphic3d) is static;
469 ---Purpose: Show grid echo <aMarker> to the hit point.
470 -- Warning: When the grid echo marker is not set,
471 -- a default marker is build with the attributes:
472 -- marker type : Aspect_TOM_STAR
473 -- marker color : Quantity_NOC_GRAY90
476 ---Category: grid management
478 GridEcho (me) returns Boolean from Standard is static;
479 ---Purpose: Returns TRUE when grid echo must be displayed
482 ---Category: grid management
485 returns Boolean from Standard
487 ---Purpose: Returns Standard_True if a grid is activated in <me>.
489 ---Category: grid management
492 returns mutable Grid from Aspect
494 ---Purpose : Returns the defined grid in <me>.
496 ---Category: grid management
499 returns GridType from Aspect
501 ---Purpose: Returns the current grid type defined in <me>.
503 ---Category: grid management
506 returns GridDrawMode from Aspect
508 ---Purpose: Returns the current grid draw mode defined in <me>.
510 ---Category: grid management
512 RectangularGridValues (me;
513 XOrigin, YOrigin : out Length from Quantity;
514 XStep, YStep : out Length from Quantity;
515 RotationAngle : out PlaneAngle from Quantity)
517 ---Purpose: Returns the definition of the rectangular grid.
519 ---Category: grid management
521 SetRectangularGridValues (me : mutable;
522 XOrigin, YOrigin : Length from Quantity;
523 XStep, YStep : Length from Quantity;
524 RotationAngle : PlaneAngle from Quantity)
526 ---Purpose: Sets the definition of the rectangular grid.
527 --- <XOrigin>, <YOrigin> defines the origin of the grid.
528 --- <XStep> defines the interval between 2 vertical lines.
529 --- <YStep> defines the interval between 2 horizontal lines.
530 --- <RotationAngle> defines the rotation angle of the grid.
532 ---Category: grid management
534 CircularGridValues (me;
535 XOrigin, YOrigin : out Length from Quantity;
536 RadiusStep : out Length from Quantity;
537 DivisionNumber : out Integer from Standard;
538 RotationAngle : out PlaneAngle from Quantity)
540 ---Purpose: Returns the definition of the circular grid.
542 ---Category: grid management
544 SetCircularGridValues (me : mutable;
545 XOrigin, YOrigin : Length from Quantity;
546 RadiusStep : Length from Quantity;
547 DivisionNumber : Integer from Standard;
548 RotationAngle : PlaneAngle from Quantity)
550 ---Purpose: Sets the definition of the circular grid.
551 --- <XOrigin>, <YOrigin> defines the origin of the grid.
552 --- <RadiusStep> defines the interval between 2 circles.
553 --- <DivisionNumber> defines the section number of one half circle.
554 --- <RotationAngle> defines the rotation angle of the grid.
556 ---Category: grid management
558 CircularGridGraphicValues (me;
559 Radius : out Length from Quantity;
560 OffSet : out Length from Quantity)
562 ---Purpose: Returns the location and the size of the grid.
564 ---Category: grid management
566 SetCircularGridGraphicValues (me : mutable;
567 Radius : Length from Quantity;
568 OffSet : Length from Quantity)
570 ---Purpose: Sets the location and the size of the grid.
571 --- <XSize> defines the width of the grid.
572 --- <YSize> defines the height of the grid.
573 --- <OffSet> defines the displacement along the plane normal.
575 ---Category: grid management
577 RectangularGridGraphicValues (me;
578 XSize, YSize : out Length from Quantity;
579 OffSet : out Length from Quantity)
581 ---Purpose: Returns the location and the size of the grid.
583 ---Category: grid management
585 SetRectangularGridGraphicValues (me : mutable;
586 XSize, YSize : Length from Quantity;
587 OffSet : Length from Quantity)
589 ---Purpose: Sets the location and the size of the grid.
590 --- <XSize> defines the width of the grid.
591 --- <YSize> defines the height of the grid.
592 --- <OffSet> defines the displacement along the plane normal.
594 ---Category: grid management
596 -----------------------------------------
597 ---Category: Private or Protected methods
598 -----------------------------------------
600 GetBackgroundColor ( me )
601 returns Background from Aspect is private;
602 ---Purpose: Returns the default background colour.
604 GetGradientBackground ( me ) returns GradientBackground from Aspect;
606 ---Purpose: Returns the gradient background of the view.
608 AddView( me: mutable; MyView : View from V3d) is private;
609 ---Purpose: Adds View in Sequence Of Views.
611 DelView( me: mutable; MyView : View from V3d) is private;
612 ---Purpose: Delete View in Sequence Of Views.
614 AddLight( me: mutable; MyLight : Light from V3d) is private;
615 ---Purpose: Adds Light in Sequence Of Lights.
617 SetDefaultLights(me: mutable);
618 ---Purpose: defines default lights -
619 -- positional-light 0.3 0. 0.
620 -- directional-light V3d_XnegYposZpos
621 -- directional-light V3d_XnegYneg
624 IsActive(me; aView: View from V3d)
625 returns Boolean from Standard is private;
627 ShowGridEcho(me : mutable;
628 aView: View from V3d;
629 aPoint: Vertex from Graphic3d) is private;
631 -- Display grid echo at requested point in the view.
633 AddZLayer ( me : mutable;
634 theLayerId : in out Integer from Standard )
635 returns Boolean from Standard is static;
636 ---Purpose: Add a new top-level Z layer to all managed views and get
637 -- its ID as <theLayerId> value. The Z layers are controlled entirely
638 -- by viewer, it is not possible to add a layer to a
639 -- particular view. The method returns Standard_False if the layer can
640 -- not be created. The layer mechanism allows to display structures
641 -- in higher layers in overlay of structures in lower layers.
643 RemoveZLayer ( me : mutable;
644 theLayerId : Integer from Standard )
645 returns Boolean from Standard is static;
646 ---Purpose: Remove Z layer with ID <theLayerId>. Method returns
647 -- Standard_False if the layer can not be removed or doesn't exists.
648 -- By default, there are always default bottom-level layer that can't
652 theLayerSeq : out SequenceOfInteger from TColStd )
654 ---Purpose: Return all Z layer ids in sequence ordered by overlay level
655 -- from lowest layer to highest ( foreground ). The first layer ID
656 -- in sequence is the default layer that can't be removed.
658 Driver(me) returns mutable GraphicDriver from Graphic3d
660 ---C++: return const &
662 NextName(me) returns ExtString from Standard
665 Domain(me) returns CString from Standard
668 IncrCount(me:mutable) is static protected;
672 myNextCount: Integer from Standard;
673 myDriver: GraphicDriver from Graphic3d;
674 myName: ExtendedString from TCollection;
675 myDomain: AsciiString from TCollection;
677 MyViewer: ViewManager from Visual3d ;
678 MyDefinedViews: ListOfTransient from V3d;
679 MyActiveViews: ListOfTransient from V3d;
680 MyDefinedLights: ListOfTransient from V3d;
681 MyActiveLights: ListOfTransient from V3d;
682 MyBackground: Background from Aspect ;
683 MyGradientBackground: GradientBackground from Aspect ;
685 MyViewProj: TypeOfOrientation from V3d ;
686 MyVisualization: TypeOfVisualization from V3d ;
687 MyShadingModel: TypeOfShadingModel from V3d ;
688 MySurfaceDetail: TypeOfSurfaceDetail from V3d ;
689 MyDefaultAngle: PlaneAngle from Quantity;
690 MyDefaultTypeOfView: TypeOfView from V3d;
691 MyCurrentSelectedLight: Light from V3d;
692 myActiveViewsIterator: ListIteratorOfListOfTransient from TColStd;
693 myDefinedViewsIterator: ListIteratorOfListOfTransient from TColStd;
694 myActiveLightsIterator: ListIteratorOfListOfTransient from TColStd;
695 myDefinedLightsIterator: ListIteratorOfListOfTransient from TColStd;
696 myComputedMode: Boolean from Standard;
697 myDefaultComputedMode: Boolean from Standard;
698 myPrivilegedPlane: Ax3 from gp;
699 myPlaneStructure: Structure from Graphic3d;
700 myDisplayPlane: Boolean from Standard;
701 myDisplayPlaneLength: Length from Quantity;
703 myRGrid: RectangularGrid from V3d;
704 myCGrid: CircularGrid from V3d;
705 myGridType: GridType from Aspect;
707 myGridEcho: Boolean from Standard;
708 myGridEchoStructure: Structure from Graphic3d;
709 myGridEchoGroup: Group from Graphic3d;
710 myGridEchoAspect : AspectMarker3d from Graphic3d;
714 class Light from V3d,
715 SetPlane from package V3d (aViewer: Viewer from V3d; x1,y1,z1,x2,y2,z2: Length from Quantity)