1 -- Created on: 1992-01-17
3 -- Copyright (c) 1992-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
21 -- Modified FMN - 02/02/98 -> Specifique UNIX
22 -- CAL - 16/07/98 -> S3892. Ajout grilles 3d.
23 -- GG - 15/12/99 -> GER61351 Add SetDefaultBackgroundColor()
24 -- and DefaultBackgroundColor() methods
25 -- GG - 20/01/00 -> IMP200100 Add GridDrawMode() method
26 -- GG - 24/01/00 -> IMP240100 Add SetGridEcho() methods
27 -- Add GridEcho() method.
28 -- Add ShowGridEcho() private method
29 -- SAV - 26/11/02 -> Add new field to store grid echo aspect
35 ---Purpose: Defines services on Viewer type objects.
36 -- The methods of this class allow editing and
37 -- interrogation of the parameters linked to the viewer
38 -- its friend classes (View,light,plane).
40 ---Keywords: Viewer,Default Attributes
50 GraphicDevice from Aspect,
51 TypeOfUpdate from V3d,
52 TypeOfVisualization from V3d,
53 TypeOfShadingModel from V3d,
54 TypeOfSurfaceDetail from V3d,
55 TypeOfOrientation from V3d,
59 ListOfTransient from V3d,
60 ListIteratorOfListOfTransient from TColStd,
61 SequenceOfInteger from TColStd,
63 Vector from Graphic3d,
64 ViewManager from Visual3d,
65 NameOfColor from Quantity,
66 TypeOfColor from Quantity,
69 PlaneAngle from Quantity,
70 Background from Aspect,
71 GradientBackground from Aspect,
72 Parameter from Quantity,
73 OrthographicView from V3d,
74 PerspectiveView from V3d,
75 AsciiString,ExtendedString from TCollection,
76 Ax3 from gp,Structure from Graphic3d,
77 Vertex from Graphic3d,
79 AspectMarker3d from Graphic3d,
80 RectangularGrid from V3d,
81 CircularGrid from V3d,
84 GridDrawMode from Aspect,
85 GradientFillMethod from Aspect
93 Create ( Device : GraphicDevice from Aspect;
94 aName : ExtString from Standard;
95 aDomain : CString from Standard = "";
96 ViewSize : Length from Quantity = 1000.0 ;
97 ViewProj : TypeOfOrientation from V3d= V3d_XposYnegZpos ;
98 ViewBackground : NameOfColor from Quantity = Quantity_NOC_GRAY30;
99 Visualization : TypeOfVisualization from V3d = V3d_ZBUFFER;
100 ShadingModel : TypeOfShadingModel from V3d = V3d_GOURAUD ;
101 UpdateMode : TypeOfUpdate from V3d = V3d_WAIT;
102 ComputedMode : Boolean from Standard = Standard_True;
103 DefaultComputedMode: Boolean from Standard = Standard_True;
104 SurfaceDetail : TypeOfSurfaceDetail from V3d = V3d_TEX_NONE)
105 returns mutable Viewer from V3d
106 ---Purpose: Create a Viewer on the given device with the given parameters or
107 -- with their default values.
108 -- Currently creating of more than 100 viewer instances
109 -- is not supported and leads to an exception.
110 -- This limitation might be addressed in some future OCCT releases.
111 raises BadValue from Viewer ;
112 ---Purpose: If the size of the view is <= 0
113 -- if ComputedMode is false, only the degenerate mode will be used.
115 -- Warning: Client must creates a graphic-device of type
116 -- Graphic3d_GraphicDevice under UNIX
117 -- or Graphic3d_WNTGraphicDevice under WindowsNT
119 CreateView (me: mutable) returns mutable View from V3d;
121 ---Purpose: creates a view in the viewer according to its
122 -- default parameters.
124 DefaultOrthographicView(me: mutable) returns mutable OrthographicView from V3d;
126 DefaultPerspectiveView(me: mutable) returns mutable PerspectiveView from V3d;
128 -------------------------------------------------------
129 ---Category: Methods to modify the status of the viewer
130 -------------------------------------------------------
132 SetViewOn (me:mutable );
134 ---Purpose: Activates all of the views of a viewer attached
137 SetViewOn (me:mutable; View : View from V3d )
139 ---Purpose: Activates a particular view in the Viewer .
140 -- Must be call if the Window attached to the view
141 -- has been Deiconified .
142 raises BadValue from Viewer;
143 -- If the view is not mapped on the window.
145 SetViewOff (me:mutable);
147 ---Purpose: Deactivates all the views of a Viewer
148 -- attached to a window.
150 SetViewOff (me:mutable; View : View from V3d)
152 ---Purpose: Deactivates a particular view in the Viewer.
153 -- Must be call if the Window attached to the view
154 -- has been Iconified .
155 raises BadValue from Viewer;
156 -- If the view is not mapped on the window.
158 Update (me:mutable ) is redefined static;
160 ---Purpose: Deprecated, Redraw() should be used instead.
162 UpdateLights (me: mutable);
164 ---Purpose: Updates the lights of all the views of a viewer.
168 ---Purpose: Redraws all the views of the Viewer even if no
169 -- modification has taken place. Must be called if
170 -- all the views of the Viewer are exposed, as for
171 -- example in a global DeIconification.
175 ---Purpose: Suppresses the Viewer.
179 ---Purpose: Erase all Objects in All the views.
183 ---Purpose: UnHighlight all Objects in All the views.
185 SetDefaultBackgroundColor (me:mutable; Type : TypeOfColor; V1, V2, V3 : Parameter );
187 ---Purpose: Defines the default base colour of views attached
188 -- to the Viewer by supplying the type of colour
189 -- definition and the three component values..
191 SetDefaultBackgroundColor (me:mutable; Name : NameOfColor );
193 ---Purpose: Defines the default background colour of views
194 -- attached to the viewer by supplying the name of the
195 -- colour under the form Quantity_NOC_xxxx .
197 SetDefaultBackgroundColor (me:mutable; Color : Color from Quantity);
199 ---Purpose: Defines the default background colour of views
200 -- attached to the viewer by supplying the color object
202 SetDefaultBgGradientColors ( me:mutable;
205 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
207 ---Purpose: Defines the default gradient background colours of view
208 -- attached to the viewer by supplying the name of the
209 -- colours under the form Quantity_NOC_xxxx .
211 SetDefaultBgGradientColors ( me : mutable ;
212 Color1 : Color from Quantity;
213 Color2 : Color from Quantity;
214 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
216 ---Purpose: Defines the default gradient background colours of views
217 -- attached to the viewer by supplying the colour objects
219 SetDefaultViewSize (me:mutable; Size : Length )
221 ---Purpose: Gives a default size for the creation of views of
223 raises BadValue from Viewer;
224 -- If the size of the view is <= 0
226 SetDefaultViewProj (me:mutable; Orientation : TypeOfOrientation );
228 ---Purpose: Gives the default projection for creating views
231 SetDefaultVisualization(me:mutable; Type : TypeOfVisualization from V3d);
233 ---Purpose: Gives the default visualisation mode..
236 SetZBufferManagment(me: mutable; Automatic: Boolean from Standard);
238 ---Purpose: defines the strategy concerning the ZBuffer activity.
239 -- If Automatic is true, ZBuffer will be activated or
240 -- deactivated depending on the fact that faces exist or
241 -- not in the Viewer. This will optimize the response time
242 -- in the case where only wireframe objects are displayed.
243 -- If Automatic is False, ZBuffer will be activated or
244 -- deactivated depending on the choice of SetVisualization
246 -- Note that by default, the ZBufferManagment is not automatic.
248 ZBufferManagment(me) returns Boolean from Standard;
250 ---Purpose: returns the ZBuffer stategy choice.
252 SetDefaultShadingModel(me:mutable; Type : TypeOfShadingModel from V3d);
254 ---Purpose: Gives the default type of SHADING.
256 SetDefaultSurfaceDetail(me:mutable; Type : TypeOfSurfaceDetail from V3d);
258 ---Purpose: Gives the default type of texture mapping.
260 SetDefaultAngle (me:mutable; Angle : PlaneAngle from Quantity);
263 SetUpdateMode ( me: mutable ; Mode : TypeOfUpdate from V3d );
265 ---Purpose: Defines the mode of regenerating the views making
266 -- up the viewer. This can be immediate <ASAP> or
267 -- deferred <WAIT>. In this latter case, the views are
268 -- updated when the method Update(me) is called.
270 SetDefaultTypeOfView(me:mutable; Type : TypeOfView from V3d);
274 SetPrivilegedPlane(me: mutable; aPlane: Ax3 from gp);
277 PrivilegedPlane(me) returns Ax3 from gp;
280 DisplayPrivilegedPlane(me: mutable; OnOff: Boolean from Standard; aSize: Length from Quantity = 1);
283 SetLightOn(me:mutable; MyLight : Light from V3d )
285 ---Purpose: Activates MyLight in the viewer.
286 raises BadValue from Viewer;
287 -- If No More Light can be activated in MyViewer .
289 SetLightOn(me:mutable)
291 ---Purpose: Activates all the lights defined in this viewer.
292 raises BadValue from Viewer;
293 -- If No More Light can be activated in MyViewer .
295 SetLightOff(me:mutable; MyLight : Light from V3d );
297 ---Purpose: Desactivate MyLight in this viewer.
299 SetLightOff(me:mutable);
301 ---Purpose: Deactivate all the Lights defined in this viewer.
303 DelLight(me:mutable; MyLight : Light from V3d);
305 ---Purpose: Delete Light in Sequence Of Lights.
307 SetCurrentSelectedLight (me : mutable; TheLight : Light from V3d);
309 ---Purpose: Defines the selected light.
311 ClearCurrentSelectedLight (me : mutable);
313 ---Purpose: Defines the selected light at NULL.
315 -----------------------------------------
316 ---Category: Inquire methods
317 -----------------------------------------
319 DefaultBackgroundColor ( me ; Type : TypeOfColor ; V1,V2,V3 : out Parameter);
321 ---Purpose: Returns the default background colour depending of the type.
322 DefaultBackgroundColor ( me ) returns Color from Quantity;
324 ---Purpose: Returns the default background colour object.
326 DefaultBgGradientColors( me;
327 Color1 : out Color from Quantity;
328 Color2 : out Color from Quantity) ;
330 ---Purpose: Returns the gradient background colour objects of the view.
332 DefaultViewSize ( me) returns Length;
334 ---Purpose: Returns the default size of the view.
336 DefaultViewProj ( me) returns TypeOfOrientation;
338 ---Purpose: Returns the default Projection.
340 DefaultVisualization ( me ) returns TypeOfVisualization from V3d;
342 ---Purpose: Returns the default type of Visualization.
344 DefaultShadingModel ( me ) returns TypeOfShadingModel from V3d;
346 ---Purpose: Returns the default type of Shading
348 DefaultSurfaceDetail ( me ) returns TypeOfSurfaceDetail from V3d;
350 ---Purpose: Returns the default type of texture mapping
352 DefaultAngle ( me ) returns PlaneAngle from Quantity;
355 UpdateMode ( me ) returns TypeOfUpdate from V3d;
357 ---Purpose: Returns the regeneration mode of views in the viewer.
359 IfMoreViews( me ) returns Boolean;
361 ---Purpose: Returns True if One View more can be
362 -- activated in this Viewer.
365 ------------------------------
366 ---Category: iteration methods
367 ------------------------------
369 InitActiveViews(me: mutable);
371 ---Purpose: initializes an iteration on the active views.
373 MoreActiveViews (me) returns Boolean from Standard;
375 ---Purpose: returns true if there are more active view(s) to return.
377 NextActiveViews (me: mutable);
379 ---Purpose : Go to the next active view
380 -- (if there is not, ActiveView will raise an exception)
382 ActiveView(me) returns mutable View from V3d;
385 LastActiveView(me) returns Boolean from Standard;
387 ---Purpose: returns true if there is only
390 InitDefinedViews(me: mutable);
392 ---Purpose: initializes an iteration on the Defined views.
395 MoreDefinedViews (me) returns Boolean from Standard;
397 ---Purpose: returns true if there are more Defined view(s) to return.
400 NextDefinedViews (me: mutable);
402 ---Purpose : Go to the next Defined view
403 -- (if there is not, DefinedView will raise an exception)
405 DefinedView(me) returns View from V3d;
408 InitActiveLights(me: mutable);
410 ---Purpose: initializes an iteration on the active Lights.
412 MoreActiveLights (me) returns Boolean from Standard;
414 ---Purpose: returns true if there are more active Light(s) to return.
417 NextActiveLights (me: mutable);
419 ---Purpose : Go to the next active Light
420 -- (if there is not, ActiveLight will raise an exception)
423 ActiveLight(me) returns mutable Light from V3d;
426 InitDefinedLights(me: mutable);
428 ---Purpose: initializes an iteration on the Defined Lights.
430 MoreDefinedLights (me) returns Boolean from Standard;
432 ---Purpose: returns true if there are more Defined Light(s) to return.
434 NextDefinedLights (me: mutable);
436 ---Purpose : Go to the next Defined Light
437 -- (if there is not, DefinedLight will raise an exception)
439 DefinedLight(me) returns Light from V3d;
442 AddPlane( me: mutable; MyPlane : Plane from V3d);
443 ---Purpose: Adds Plane in Sequence Of Planes.
445 DelPlane( me: mutable; MyPlane : Plane from V3d);
446 ---Purpose: Delete Plane in Sequence Of Planes.
448 InitDefinedPlanes(me: mutable);
450 ---Purpose: initializes an iteration on the Defined Planes.
452 MoreDefinedPlanes (me) returns Boolean from Standard;
454 ---Purpose: returns true if there are more Defined Plane(s) to return.
456 NextDefinedPlanes (me: mutable);
458 ---Purpose : Go to the next Defined Plane
459 -- (if there is not, DefinedPlane will raise an exception)
461 DefinedPlane(me) returns Plane from V3d;
464 Viewer (me) returns mutable ViewManager ;
466 ---Purpose: Returns the viewer associated to Visual3d .
468 CurrentSelectedLight (me) returns Light from V3d;
470 ---Purpose: Returns the Selected Light.
472 IsGlobalLight (me; TheLight : Light from V3d) returns Boolean;
475 ComputedMode(me) returns Boolean from Standard;
477 ---Purpose: returns true if the computed mode can be used.
479 DefaultComputedMode(me) returns Boolean from Standard;
481 ---Purpose: returns true if by default the computed mode must be used.
483 -----------------------------------------
484 ---Category: grid management
485 -----------------------------------------
487 ActivateGrid (me : mutable;
488 aGridType : GridType from Aspect;
489 aGridDrawMode : GridDrawMode from Aspect)
491 ---Purpose: Activates the grid in all views of <me>.
493 ---Category: grid management
495 DeactivateGrid (me : mutable)
497 ---Purpose: Deactivates the grid in all views of <me>.
499 ---Category: grid management
501 SetGridEcho (me : mutable;
502 showGrid: Boolean from Standard = Standard_True) is static;
503 ---Purpose: Show/Don't show grid echo to the hit point.
504 -- If TRUE,the grid echo will be shown at ConvertToGrid() time.
506 ---Category: grid management
508 SetGridEcho (me : mutable;
509 aMarker: AspectMarker3d from Graphic3d) is static;
510 ---Purpose: Show grid echo <aMarker> to the hit point.
511 -- Warning: When the grid echo marker is not set,
512 -- a default marker is build with the attributes:
513 -- marker type : Aspect_TOM_STAR
514 -- marker color : Quantity_NOC_GRAY90
517 ---Category: grid management
519 GridEcho (me) returns Boolean from Standard is static;
520 ---Purpose: Returns TRUE when grid echo must be displayed
523 ---Category: grid management
526 returns Boolean from Standard
528 ---Purpose: Returns Standard_True if a grid is activated in <me>.
530 ---Category: grid management
533 returns mutable Grid from Aspect
535 ---Purpose : Returns the defined grid in <me>.
537 ---Category: grid management
540 returns GridType from Aspect
542 ---Purpose: Returns the current grid type defined in <me>.
544 ---Category: grid management
547 returns GridDrawMode from Aspect
549 ---Purpose: Returns the current grid draw mode defined in <me>.
551 ---Category: grid management
553 RectangularGridValues (me;
554 XOrigin, YOrigin : out Length from Quantity;
555 XStep, YStep : out Length from Quantity;
556 RotationAngle : out PlaneAngle from Quantity)
558 ---Purpose: Returns the definition of the rectangular grid.
560 ---Category: grid management
562 SetRectangularGridValues (me : mutable;
563 XOrigin, YOrigin : Length from Quantity;
564 XStep, YStep : Length from Quantity;
565 RotationAngle : PlaneAngle from Quantity)
567 ---Purpose: Sets the definition of the rectangular grid.
568 --- <XOrigin>, <YOrigin> defines the origin of the grid.
569 --- <XStep> defines the interval between 2 vertical lines.
570 --- <YStep> defines the interval between 2 horizontal lines.
571 --- <RotationAngle> defines the rotation angle of the grid.
573 ---Category: grid management
575 CircularGridValues (me;
576 XOrigin, YOrigin : out Length from Quantity;
577 RadiusStep : out Length from Quantity;
578 DivisionNumber : out Integer from Standard;
579 RotationAngle : out PlaneAngle from Quantity)
581 ---Purpose: Returns the definition of the circular grid.
583 ---Category: grid management
585 SetCircularGridValues (me : mutable;
586 XOrigin, YOrigin : Length from Quantity;
587 RadiusStep : Length from Quantity;
588 DivisionNumber : Integer from Standard;
589 RotationAngle : PlaneAngle from Quantity)
591 ---Purpose: Sets the definition of the circular grid.
592 --- <XOrigin>, <YOrigin> defines the origin of the grid.
593 --- <RadiusStep> defines the interval between 2 circles.
594 --- <DivisionNumber> defines the section number of one half circle.
595 --- <RotationAngle> defines the rotation angle of the grid.
597 ---Category: grid management
599 CircularGridGraphicValues (me;
600 Radius : out Length from Quantity;
601 OffSet : out Length from Quantity)
603 ---Purpose: Returns the location and the size of the grid.
605 ---Category: grid management
607 SetCircularGridGraphicValues (me : mutable;
608 Radius : Length from Quantity;
609 OffSet : Length from Quantity)
611 ---Purpose: Sets the location and the size of the grid.
612 --- <XSize> defines the width of the grid.
613 --- <YSize> defines the height of the grid.
614 --- <OffSet> defines the displacement along the plane normal.
616 ---Category: grid management
618 RectangularGridGraphicValues (me;
619 XSize, YSize : out Length from Quantity;
620 OffSet : out Length from Quantity)
622 ---Purpose: Returns the location and the size of the grid.
624 ---Category: grid management
626 SetRectangularGridGraphicValues (me : mutable;
627 XSize, YSize : Length from Quantity;
628 OffSet : Length from Quantity)
630 ---Purpose: Sets the location and the size of the grid.
631 --- <XSize> defines the width of the grid.
632 --- <YSize> defines the height of the grid.
633 --- <OffSet> defines the displacement along the plane normal.
635 ---Category: grid management
637 -----------------------------------------
638 ---Category: Private or Protected methods
639 -----------------------------------------
641 GetBackgroundColor ( me )
642 returns Background from Aspect is private;
643 ---Purpose: Returns the default background colour.
645 GetGradientBackground ( me ) returns GradientBackground from Aspect;
647 ---Purpose: Returns the gradient background of the view.
649 AddView( me: mutable; MyView : View from V3d) is private;
650 ---Purpose: Adds View in Sequence Of Views.
652 DelView( me: mutable; MyView : View from V3d) is private;
653 ---Purpose: Delete View in Sequence Of Views.
655 AddLight( me: mutable; MyLight : Light from V3d) is private;
656 ---Purpose: Adds Light in Sequence Of Lights.
658 SetDefaultLights(me: mutable);
659 ---Purpose: defines default lights -
660 -- positional-light 0.3 0. 0.
661 -- directional-light V3d_XnegYposZpos
662 -- directional-light V3d_XnegYneg
667 IsActive(me; aView: View from V3d)
668 returns Boolean from Standard is private;
670 ShowGridEcho(me : mutable;
671 aView: View from V3d;
672 aPoint: Vertex from Graphic3d) is private;
674 -- Display grid echo at requested point in the view.
676 AddZLayer ( me : mutable;
677 theLayerId : in out Integer from Standard )
678 returns Boolean from Standard is static;
679 ---Purpose: Add a new top-level Z layer to all managed views and get
680 -- its ID as <theLayerId> value. The Z layers are controlled entirely
681 -- by viewer, it is not possible to add a layer to a
682 -- particular view. The method returns Standard_False if the layer can
683 -- not be created. The layer mechanism allows to display structures
684 -- in higher layers in overlay of structures in lower layers.
686 RemoveZLayer ( me : mutable;
687 theLayerId : Integer from Standard )
688 returns Boolean from Standard is static;
689 ---Purpose: Remove Z layer with ID <theLayerId>. Method returns
690 -- Standard_False if the layer can not be removed or doesn't exists.
691 -- By default, there are always default bottom-level layer that can't
695 theLayerSeq : out SequenceOfInteger from TColStd )
697 ---Purpose: Return all Z layer ids in sequence ordered by overlay level
698 -- from lowest layer to highest ( foreground ). The first layer ID
699 -- in sequence is the default layer that can't be removed.
703 MyViewer: ViewManager from Visual3d ;
704 MyDefinedViews: ListOfTransient from V3d;
705 MyActiveViews: ListOfTransient from V3d;
706 MyDefinedLights: ListOfTransient from V3d;
707 MyActiveLights: ListOfTransient from V3d;
708 MyDefinedPlanes: ListOfTransient from V3d;
709 MyBackground: Background from Aspect ;
710 MyGradientBackground: GradientBackground from Aspect ;
712 MyViewProj: TypeOfOrientation from V3d ;
713 MyVisualization: TypeOfVisualization from V3d ;
714 MyShadingModel: TypeOfShadingModel from V3d ;
715 MySurfaceDetail: TypeOfSurfaceDetail from V3d ;
716 MyDefaultAngle: PlaneAngle from Quantity;
717 MyDefaultTypeOfView: TypeOfView from V3d;
718 MyDefaultOrthographicView: OrthographicView from V3d;
719 MyDefaultPerspectiveView: PerspectiveView from V3d;
720 MyCurrentSelectedLight: Light from V3d;
721 myActiveViewsIterator: ListIteratorOfListOfTransient from TColStd;
722 myDefinedViewsIterator: ListIteratorOfListOfTransient from TColStd;
723 myActiveLightsIterator: ListIteratorOfListOfTransient from TColStd;
724 myDefinedLightsIterator: ListIteratorOfListOfTransient from TColStd;
725 myDefinedPlanesIterator: ListIteratorOfListOfTransient from TColStd;
726 myComputedMode: Boolean from Standard;
727 myDefaultComputedMode: Boolean from Standard;
728 myPrivilegedPlane: Ax3 from gp;
729 myPlaneStructure: Structure from Graphic3d;
730 myDisplayPlane: Boolean from Standard;
731 myDisplayPlaneLength: Length from Quantity;
733 myRGrid: RectangularGrid from V3d;
734 myCGrid: CircularGrid from V3d;
735 myGridType: GridType from Aspect;
737 myGridEcho: Boolean from Standard;
738 myGridEchoStructure: Structure from Graphic3d;
739 myGridEchoGroup: Group from Graphic3d;
740 myGridEchoAspect : AspectMarker3d from Graphic3d;
744 class Light from V3d,
745 class Plane from V3d,
746 SetPlane from package V3d (aViewer: Viewer from V3d; x1,y1,z1,x2,y2,z2: Length from Quantity)