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 raises BadValue from Viewer ;
109 ---Purpose: If the size of the view is <= 0
110 -- if ComputedMode is false, only the degenerate mode will be used.
112 -- Warning: Client must creates a graphic-device of type
113 -- Graphic3d_GraphicDevice under UNIX
114 -- or Graphic3d_WNTGraphicDevice under WindowsNT
116 CreateView (me: mutable) returns mutable View from V3d;
118 ---Purpose: creates a view in the viewer according to its
119 -- default parameters.
121 DefaultOrthographicView(me: mutable) returns mutable OrthographicView from V3d;
123 DefaultPerspectiveView(me: mutable) returns mutable PerspectiveView from V3d;
125 -------------------------------------------------------
126 ---Category: Methods to modify the status of the viewer
127 -------------------------------------------------------
129 SetViewOn (me:mutable );
131 ---Purpose: Activates all of the views of a viewer attached
134 SetViewOn (me:mutable; View : View from V3d )
136 ---Purpose: Activates a particular view in the Viewer .
137 -- Must be call if the Window attached to the view
138 -- has been Deiconified .
139 raises BadValue from Viewer;
140 -- If the view is not mapped on the window.
142 SetViewOff (me:mutable);
144 ---Purpose: Deactivates all the views of a Viewer
145 -- attached to a window.
147 SetViewOff (me:mutable; View : View from V3d)
149 ---Purpose: Deactivates a particular view in the Viewer.
150 -- Must be call if the Window attached to the view
151 -- has been Iconified .
152 raises BadValue from Viewer;
153 -- If the view is not mapped on the window.
155 Update (me:mutable ) is redefined static;
157 ---Purpose: Deprecated, Redraw() should be used instead.
159 UpdateLights (me: mutable);
161 ---Purpose: Updates the lights of all the views of a viewer.
165 ---Purpose: Redraws all the views of the Viewer even if no
166 -- modification has taken place. Must be called if
167 -- all the views of the Viewer are exposed, as for
168 -- example in a global DeIconification.
172 ---Purpose: Suppresses the Viewer.
176 ---Purpose: Erase all Objects in All the views.
180 ---Purpose: UnHighlight all Objects in All the views.
182 SetDefaultBackgroundColor (me:mutable; Type : TypeOfColor; V1, V2, V3 : Parameter );
184 ---Purpose: Defines the default base colour of views attached
185 -- to the Viewer by supplying the type of colour
186 -- definition and the three component values..
188 SetDefaultBackgroundColor (me:mutable; Name : NameOfColor );
190 ---Purpose: Defines the default background colour of views
191 -- attached to the viewer by supplying the name of the
192 -- colour under the form Quantity_NOC_xxxx .
194 SetDefaultBackgroundColor (me:mutable; Color : Color from Quantity);
196 ---Purpose: Defines the default background colour of views
197 -- attached to the viewer by supplying the color object
199 SetDefaultBgGradientColors ( me:mutable;
202 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
204 ---Purpose: Defines the default gradient background colours of view
205 -- attached to the viewer by supplying the name of the
206 -- colours under the form Quantity_NOC_xxxx .
208 SetDefaultBgGradientColors ( me : mutable ;
209 Color1 : Color from Quantity;
210 Color2 : Color from Quantity;
211 FillStyle : GradientFillMethod from Aspect = Aspect_GFM_HOR );
213 ---Purpose: Defines the default gradient background colours of views
214 -- attached to the viewer by supplying the colour objects
216 SetDefaultViewSize (me:mutable; Size : Length )
218 ---Purpose: Gives a default size for the creation of views of
220 raises BadValue from Viewer;
221 -- If the size of the view is <= 0
223 SetDefaultViewProj (me:mutable; Orientation : TypeOfOrientation );
225 ---Purpose: Gives the default projection for creating views
228 SetDefaultVisualization(me:mutable; Type : TypeOfVisualization from V3d);
230 ---Purpose: Gives the default visualisation mode..
233 SetZBufferManagment(me: mutable; Automatic: Boolean from Standard);
235 ---Purpose: defines the strategy concerning the ZBuffer activity.
236 -- If Automatic is true, ZBuffer will be activated or
237 -- deactivated depending on the fact that faces exist or
238 -- not in the Viewer. This will optimize the response time
239 -- in the case where only wireframe objects are displayed.
240 -- If Automatic is False, ZBuffer will be activated or
241 -- deactivated depending on the choice of SetVisualization
243 -- Note that by default, the ZBufferManagment is not automatic.
245 ZBufferManagment(me) returns Boolean from Standard;
247 ---Purpose: returns the ZBuffer stategy choice.
249 SetDefaultShadingModel(me:mutable; Type : TypeOfShadingModel from V3d);
251 ---Purpose: Gives the default type of SHADING.
253 SetDefaultSurfaceDetail(me:mutable; Type : TypeOfSurfaceDetail from V3d);
255 ---Purpose: Gives the default type of texture mapping.
257 SetDefaultAngle (me:mutable; Angle : PlaneAngle from Quantity);
260 SetUpdateMode ( me: mutable ; Mode : TypeOfUpdate from V3d );
262 ---Purpose: Defines the mode of regenerating the views making
263 -- up the viewer. This can be immediate <ASAP> or
264 -- deferred <WAIT>. In this latter case, the views are
265 -- updated when the method Update(me) is called.
267 SetDefaultTypeOfView(me:mutable; Type : TypeOfView from V3d);
271 SetPrivilegedPlane(me: mutable; aPlane: Ax3 from gp);
274 PrivilegedPlane(me) returns Ax3 from gp;
277 DisplayPrivilegedPlane(me: mutable; OnOff: Boolean from Standard; aSize: Length from Quantity = 1);
280 SetLightOn(me:mutable; MyLight : Light from V3d )
282 ---Purpose: Activates MyLight in the viewer.
283 raises BadValue from Viewer;
284 -- If No More Light can be activated in MyViewer .
286 SetLightOn(me:mutable)
288 ---Purpose: Activates all the lights defined in this viewer.
289 raises BadValue from Viewer;
290 -- If No More Light can be activated in MyViewer .
292 SetLightOff(me:mutable; MyLight : Light from V3d );
294 ---Purpose: Desactivate MyLight in this viewer.
296 SetLightOff(me:mutable);
298 ---Purpose: Deactivate all the Lights defined in this viewer.
300 DelLight(me:mutable; MyLight : Light from V3d);
302 ---Purpose: Delete Light in Sequence Of Lights.
304 SetCurrentSelectedLight (me : mutable; TheLight : Light from V3d);
306 ---Purpose: Defines the selected light.
308 ClearCurrentSelectedLight (me : mutable);
310 ---Purpose: Defines the selected light at NULL.
312 -----------------------------------------
313 ---Category: Inquire methods
314 -----------------------------------------
316 DefaultBackgroundColor ( me ; Type : TypeOfColor ; V1,V2,V3 : out Parameter);
318 ---Purpose: Returns the default background colour depending of the type.
319 DefaultBackgroundColor ( me ) returns Color from Quantity;
321 ---Purpose: Returns the default background colour object.
323 DefaultBgGradientColors( me;
324 Color1 : out Color from Quantity;
325 Color2 : out Color from Quantity) ;
327 ---Purpose: Returns the gradient background colour objects of the view.
329 DefaultViewSize ( me) returns Length;
331 ---Purpose: Returns the default size of the view.
333 DefaultViewProj ( me) returns TypeOfOrientation;
335 ---Purpose: Returns the default Projection.
337 DefaultVisualization ( me ) returns TypeOfVisualization from V3d;
339 ---Purpose: Returns the default type of Visualization.
341 DefaultShadingModel ( me ) returns TypeOfShadingModel from V3d;
343 ---Purpose: Returns the default type of Shading
345 DefaultSurfaceDetail ( me ) returns TypeOfSurfaceDetail from V3d;
347 ---Purpose: Returns the default type of texture mapping
349 DefaultAngle ( me ) returns PlaneAngle from Quantity;
352 UpdateMode ( me ) returns TypeOfUpdate from V3d;
354 ---Purpose: Returns the regeneration mode of views in the viewer.
356 IfMoreViews( me ) returns Boolean;
358 ---Purpose: Returns True if One View more can be
359 -- activated in this Viewer.
362 ------------------------------
363 ---Category: iteration methods
364 ------------------------------
366 InitActiveViews(me: mutable);
368 ---Purpose: initializes an iteration on the active views.
370 MoreActiveViews (me) returns Boolean from Standard;
372 ---Purpose: returns true if there are more active view(s) to return.
374 NextActiveViews (me: mutable);
376 ---Purpose : Go to the next active view
377 -- (if there is not, ActiveView will raise an exception)
379 ActiveView(me) returns mutable View from V3d;
382 LastActiveView(me) returns Boolean from Standard;
384 ---Purpose: returns true if there is only
387 InitDefinedViews(me: mutable);
389 ---Purpose: initializes an iteration on the Defined views.
392 MoreDefinedViews (me) returns Boolean from Standard;
394 ---Purpose: returns true if there are more Defined view(s) to return.
397 NextDefinedViews (me: mutable);
399 ---Purpose : Go to the next Defined view
400 -- (if there is not, DefinedView will raise an exception)
402 DefinedView(me) returns View from V3d;
405 InitActiveLights(me: mutable);
407 ---Purpose: initializes an iteration on the active Lights.
409 MoreActiveLights (me) returns Boolean from Standard;
411 ---Purpose: returns true if there are more active Light(s) to return.
414 NextActiveLights (me: mutable);
416 ---Purpose : Go to the next active Light
417 -- (if there is not, ActiveLight will raise an exception)
420 ActiveLight(me) returns mutable Light from V3d;
423 InitDefinedLights(me: mutable);
425 ---Purpose: initializes an iteration on the Defined Lights.
427 MoreDefinedLights (me) returns Boolean from Standard;
429 ---Purpose: returns true if there are more Defined Light(s) to return.
431 NextDefinedLights (me: mutable);
433 ---Purpose : Go to the next Defined Light
434 -- (if there is not, DefinedLight will raise an exception)
436 DefinedLight(me) returns Light from V3d;
439 AddPlane( me: mutable; MyPlane : Plane from V3d);
440 ---Purpose: Adds Plane in Sequence Of Planes.
442 DelPlane( me: mutable; MyPlane : Plane from V3d);
443 ---Purpose: Delete Plane in Sequence Of Planes.
445 InitDefinedPlanes(me: mutable);
447 ---Purpose: initializes an iteration on the Defined Planes.
449 MoreDefinedPlanes (me) returns Boolean from Standard;
451 ---Purpose: returns true if there are more Defined Plane(s) to return.
453 NextDefinedPlanes (me: mutable);
455 ---Purpose : Go to the next Defined Plane
456 -- (if there is not, DefinedPlane will raise an exception)
458 DefinedPlane(me) returns Plane from V3d;
461 Viewer (me) returns mutable ViewManager ;
463 ---Purpose: Returns the viewer associated to Visual3d .
465 CurrentSelectedLight (me) returns Light from V3d;
467 ---Purpose: Returns the Selected Light.
469 IsGlobalLight (me; TheLight : Light from V3d) returns Boolean;
472 ComputedMode(me) returns Boolean from Standard;
474 ---Purpose: returns true if the computed mode can be used.
476 DefaultComputedMode(me) returns Boolean from Standard;
478 ---Purpose: returns true if by default the computed mode must be used.
480 -----------------------------------------
481 ---Category: grid management
482 -----------------------------------------
484 ActivateGrid (me : mutable;
485 aGridType : GridType from Aspect;
486 aGridDrawMode : GridDrawMode from Aspect)
488 ---Purpose: Activates the grid in all views of <me>.
490 ---Category: grid management
492 DeactivateGrid (me : mutable)
494 ---Purpose: Deactivates the grid in all views of <me>.
496 ---Category: grid management
498 SetGridEcho (me : mutable;
499 showGrid: Boolean from Standard = Standard_True) is static;
500 ---Purpose: Show/Don't show grid echo to the hit point.
501 -- If TRUE,the grid echo will be shown at ConvertToGrid() time.
503 ---Category: grid management
505 SetGridEcho (me : mutable;
506 aMarker: AspectMarker3d from Graphic3d) is static;
507 ---Purpose: Show grid echo <aMarker> to the hit point.
508 -- Warning: When the grid echo marker is not set,
509 -- a default marker is build with the attributes:
510 -- marker type : Aspect_TOM_STAR
511 -- marker color : Quantity_NOC_GRAY90
514 ---Category: grid management
516 GridEcho (me) returns Boolean from Standard is static;
517 ---Purpose: Returns TRUE when grid echo must be displayed
520 ---Category: grid management
523 returns Boolean from Standard
525 ---Purpose: Returns Standard_True if a grid is activated in <me>.
527 ---Category: grid management
530 returns mutable Grid from Aspect
532 ---Purpose : Returns the defined grid in <me>.
534 ---Category: grid management
537 returns GridType from Aspect
539 ---Purpose: Returns the current grid type defined in <me>.
541 ---Category: grid management
544 returns GridDrawMode from Aspect
546 ---Purpose: Returns the current grid draw mode defined in <me>.
548 ---Category: grid management
550 RectangularGridValues (me;
551 XOrigin, YOrigin : out Length from Quantity;
552 XStep, YStep : out Length from Quantity;
553 RotationAngle : out PlaneAngle from Quantity)
555 ---Purpose: Returns the definition of the rectangular grid.
557 ---Category: grid management
559 SetRectangularGridValues (me : mutable;
560 XOrigin, YOrigin : Length from Quantity;
561 XStep, YStep : Length from Quantity;
562 RotationAngle : PlaneAngle from Quantity)
564 ---Purpose: Sets the definition of the rectangular grid.
565 --- <XOrigin>, <YOrigin> defines the origin of the grid.
566 --- <XStep> defines the interval between 2 vertical lines.
567 --- <YStep> defines the interval between 2 horizontal lines.
568 --- <RotationAngle> defines the rotation angle of the grid.
570 ---Category: grid management
572 CircularGridValues (me;
573 XOrigin, YOrigin : out Length from Quantity;
574 RadiusStep : out Length from Quantity;
575 DivisionNumber : out Integer from Standard;
576 RotationAngle : out PlaneAngle from Quantity)
578 ---Purpose: Returns the definition of the circular grid.
580 ---Category: grid management
582 SetCircularGridValues (me : mutable;
583 XOrigin, YOrigin : Length from Quantity;
584 RadiusStep : Length from Quantity;
585 DivisionNumber : Integer from Standard;
586 RotationAngle : PlaneAngle from Quantity)
588 ---Purpose: Sets the definition of the circular grid.
589 --- <XOrigin>, <YOrigin> defines the origin of the grid.
590 --- <RadiusStep> defines the interval between 2 circles.
591 --- <DivisionNumber> defines the section number of one half circle.
592 --- <RotationAngle> defines the rotation angle of the grid.
594 ---Category: grid management
596 CircularGridGraphicValues (me;
597 Radius : out Length from Quantity;
598 OffSet : out Length from Quantity)
600 ---Purpose: Returns the location and the size of the grid.
602 ---Category: grid management
604 SetCircularGridGraphicValues (me : mutable;
605 Radius : Length from Quantity;
606 OffSet : Length from Quantity)
608 ---Purpose: Sets the location and the size of the grid.
609 --- <XSize> defines the width of the grid.
610 --- <YSize> defines the height of the grid.
611 --- <OffSet> defines the displacement along the plane normal.
613 ---Category: grid management
615 RectangularGridGraphicValues (me;
616 XSize, YSize : out Length from Quantity;
617 OffSet : out Length from Quantity)
619 ---Purpose: Returns the location and the size of the grid.
621 ---Category: grid management
623 SetRectangularGridGraphicValues (me : mutable;
624 XSize, YSize : Length from Quantity;
625 OffSet : Length from Quantity)
627 ---Purpose: Sets the location and the size of the grid.
628 --- <XSize> defines the width of the grid.
629 --- <YSize> defines the height of the grid.
630 --- <OffSet> defines the displacement along the plane normal.
632 ---Category: grid management
634 -----------------------------------------
635 ---Category: Private or Protected methods
636 -----------------------------------------
638 GetBackgroundColor ( me )
639 returns Background from Aspect is private;
640 ---Purpose: Returns the default background colour.
642 GetGradientBackground ( me ) returns GradientBackground from Aspect;
644 ---Purpose: Returns the gradient background of the view.
646 AddView( me: mutable; MyView : View from V3d) is private;
647 ---Purpose: Adds View in Sequence Of Views.
649 DelView( me: mutable; MyView : View from V3d) is private;
650 ---Purpose: Delete View in Sequence Of Views.
652 AddLight( me: mutable; MyLight : Light from V3d) is private;
653 ---Purpose: Adds Light in Sequence Of Lights.
655 SetDefaultLights(me: mutable);
656 ---Purpose: defines default lights -
657 -- positional-light 0.3 0. 0.
658 -- directional-light V3d_XnegYposZpos
659 -- directional-light V3d_XnegYneg
664 IsActive(me; aView: View from V3d)
665 returns Boolean from Standard is private;
667 ShowGridEcho(me : mutable;
668 aView: View from V3d;
669 aPoint: Vertex from Graphic3d) is private;
671 -- Display grid echo at requested point in the view.
673 AddZLayer ( me : mutable;
674 theLayerId : in out Integer from Standard )
675 returns Boolean from Standard is static;
676 ---Purpose: Add a new top-level Z layer to all managed views and get
677 -- its ID as <theLayerId> value. The Z layers are controlled entirely
678 -- by viewer, it is not possible to add a layer to a
679 -- particular view. The method returns Standard_False if the layer can
680 -- not be created. The layer mechanism allows to display structures
681 -- in higher layers in overlay of structures in lower layers.
683 RemoveZLayer ( me : mutable;
684 theLayerId : Integer from Standard )
685 returns Boolean from Standard is static;
686 ---Purpose: Remove Z layer with ID <theLayerId>. Method returns
687 -- Standard_False if the layer can not be removed or doesn't exists.
688 -- By default, there are always default bottom-level layer that can't
692 theLayerSeq : out SequenceOfInteger from TColStd )
694 ---Purpose: Return all Z layer ids in sequence ordered by overlay level
695 -- from lowest layer to highest ( foreground ). The first layer ID
696 -- in sequence is the default layer that can't be removed.
700 MyViewer: ViewManager from Visual3d ;
701 MyDefinedViews: ListOfTransient from V3d;
702 MyActiveViews: ListOfTransient from V3d;
703 MyDefinedLights: ListOfTransient from V3d;
704 MyActiveLights: ListOfTransient from V3d;
705 MyDefinedPlanes: ListOfTransient from V3d;
706 MyBackground: Background from Aspect ;
707 MyGradientBackground: GradientBackground from Aspect ;
709 MyViewProj: TypeOfOrientation from V3d ;
710 MyVisualization: TypeOfVisualization from V3d ;
711 MyShadingModel: TypeOfShadingModel from V3d ;
712 MySurfaceDetail: TypeOfSurfaceDetail from V3d ;
713 MyDefaultAngle: PlaneAngle from Quantity;
714 MyDefaultTypeOfView: TypeOfView from V3d;
715 MyDefaultOrthographicView: OrthographicView from V3d;
716 MyDefaultPerspectiveView: PerspectiveView from V3d;
717 MyCurrentSelectedLight: Light from V3d;
718 myActiveViewsIterator: ListIteratorOfListOfTransient from TColStd;
719 myDefinedViewsIterator: ListIteratorOfListOfTransient from TColStd;
720 myActiveLightsIterator: ListIteratorOfListOfTransient from TColStd;
721 myDefinedLightsIterator: ListIteratorOfListOfTransient from TColStd;
722 myDefinedPlanesIterator: ListIteratorOfListOfTransient from TColStd;
723 myComputedMode: Boolean from Standard;
724 myDefaultComputedMode: Boolean from Standard;
725 myPrivilegedPlane: Ax3 from gp;
726 myPlaneStructure: Structure from Graphic3d;
727 myDisplayPlane: Boolean from Standard;
728 myDisplayPlaneLength: Length from Quantity;
730 myRGrid: RectangularGrid from V3d;
731 myCGrid: CircularGrid from V3d;
732 myGridType: GridType from Aspect;
734 myGridEcho: Boolean from Standard;
735 myGridEchoStructure: Structure from Graphic3d;
736 myGridEchoGroup: Group from Graphic3d;
737 myGridEchoAspect : AspectMarker3d from Graphic3d;
741 class Light from V3d,
742 class Plane from V3d,
743 SetPlane from package V3d (aViewer: Viewer from V3d; x1,y1,z1,x2,y2,z2: Length from Quantity)