0024752: Visualization - inherit OpenGl_Group from Graphic3d_Group
[occt.git] / src / Graphic3d / Graphic3d_Group.cdl
1 -- Created on: 1991-09-06
2 -- Created by: NW,JPB,CAL
3 -- Copyright (c) 1991-1999 Matra Datavision
4 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
5 --
6 -- This file is part of Open CASCADE Technology software library.
7 --
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.
13 --
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
16
17 deferred class Group from Graphic3d inherits TShared
18     
19         ---Version:
20
21         ---Purpose: This class allows the definition of groups
22         --     of primitives inside of graphic objects (presentations).
23         --     A group contains the primitives and attributes
24         --     for which the range is limited to this group.
25         --     The primitives of a group can be globally suppressed.
26         --
27         --      There are two main group usage models:
28         --
29         --        1) Non-modifiable, or unbounded, group ('black box'). 
30         --           Developers can repeat a sequence of 
31         --           SetPrimitivesAspect() with AddPrimitiveArray() methods arbitrary number of times
32         --           to define arbitrary number of primitive "blocks" each having individual apect values.
33         --           Any modification of such a group is forbidden, as aspects and primitives are mixed 
34         --           in memory without any high-level logical structure, and any modification is very likely to result
35         --           in corruption of the group internal data.
36         --           It is necessary to recreate such a group as a whole when some attribute should be changed.
37         --           (for example, in terms of AIS it is necessary to re-Compute() the whole presentation each time).
38         --        2) Bounded group. Developers should specify the necessary group aspects with help of
39         --           SetGroupPrimitivesAspect() and then add primitives to the group.
40         --           Such a group have simplified organization in memory (a single block of attributes
41         --           followed by a block of primitives) and therefore it can be modified, if it is necessary to
42         --           change parameters of some aspect that has already been set, using methods:
43         --           IsGroupPrimitivesAspectSet() to detect which aspect was set for primitives;
44         --           GroupPrimitivesAspect() to read current aspect values
45         --           and SetGroupPrimitivesAspect() to set new values.
46         -- 
47         --        Developers are strongly recommended to take all the above into account when filling Graphic3d_Group
48         --        with aspects and primitives and choose the group usage model beforehand out of application needs.
49
50         ---Warning:
51         ---References:
52     
53     uses
54     
55         Array1OfInteger             from TColStd,
56         Array1OfReal                from TColStd,
57         HArray1OfByte               from TColStd,
58     
59         ExtendedString              from TCollection,
60     
61         PlaneAngle                  from Quantity,
62     
63         Array1OfEdge                from Aspect,
64         Edge                        from Aspect,
65     
66         GroupAspect                 from Graphic3d,
67         AspectLine3d                from Graphic3d,
68         AspectMarker3d              from Graphic3d,
69         AspectText3d                from Graphic3d,
70         AspectFillArea3d            from Graphic3d,
71         CAspectLine                 from Graphic3d,
72         CAspectFillArea             from Graphic3d,
73         CAspectMarker               from Graphic3d,
74         CAspectText                 from Graphic3d,
75         CStructurePtr               from Graphic3d,
76         HorizontalTextAlignment     from Graphic3d,
77         CBitFields4                 from Graphic3d,
78         GraphicDriver               from Graphic3d,
79         Structure                   from Graphic3d,
80         StructurePtr                from Graphic3d,
81         TextPath                    from Graphic3d,
82         Vector                      from Graphic3d,
83         Array1OfVertex              from Graphic3d,
84         Array2OfVertex              from Graphic3d,
85         Vertex                      from Graphic3d,
86         VerticalTextAlignment       from Graphic3d, 
87         ArrayOfPrimitives           from Graphic3d,
88         ListOfPArray                from Graphic3d,
89         TransModeFlags              from Graphic3d,
90         CBounds                     from Graphic3d,
91         Ax2                         from gp
92     
93     raises
94
95         GroupDefinitionError        from Graphic3d,
96
97     OutOfRange          from Standard
98     
99     is
100         Initialize (theStructure : Structure from Graphic3d)
101             returns mutable Group from Graphic3d;
102         ---Level: Public
103         ---Purpose: Creates a group in the structure <AStructure>.
104     
105         ---------------------------------------------------
106         -- Category: Methods to modify the class definition
107         ---------------------------------------------------
108     
109         Clear ( me  : mutable;
110                 theUpdateStructureMgr : Boolean from Standard = Standard_True )
111         is virtual;
112         ---Level: Public
113         ---Purpose: Supress all primitives and attributes of <me>.
114         --          To clear group without update in Graphic3d_StructureManager
115         --          pass Standard_False as <theUpdateStructureMgr>. This
116         --          used on context and viewer destruction, when the pointer
117         --          to structure manager in Graphic3d_Structure could be 
118         --          already released (pointers are used here to avoid handle 
119         --          cross-reference);
120         ---Category: Methods to modify the class definition
121
122         UpdateAspectLine ( me          : mutable;
123                            theIsGlobal : Boolean from Standard )
124         is deferred;
125
126         UpdateAspectFace ( me          : mutable;
127                            theIsGlobal : Boolean from Standard )
128         is deferred;
129
130         UpdateAspectMarker ( me          : mutable;
131                              theIsGlobal : Boolean from Standard )
132         is deferred;
133
134         UpdateAspectText ( me          : mutable;
135                            theIsGlobal : Boolean from Standard )
136         is deferred;
137
138         Destroy ( me    : mutable )
139             is static;
140         ---Level: Public
141         ---Purpose: Supress the group <me> in the structure.
142         ---Category: Methods to modify the class definition
143         ---C++: alias ~
144     
145         Remove ( me : mutable )
146             is static;
147         ---Level: Public
148         ---Purpose: Supress the group <me> in the structure.
149         --  Warning: No more graphic operations in <me> after this call.
150         ---Category: Methods to modify the class definition
151
152         --SetTransformPersistence( me     : mutable;
153         --                         AFlag  : TransModeFlags from Graphic3d )
154         ---Level: Public
155     ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
156         --is static;
157
158     --TransformPersistence( me )
159     --      returns TransModeFlags from Graphic3d
160         ---Level: Public
161     ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
162         --is static;
163     
164         SetGroupPrimitivesAspect ( me   : mutable )
165             is static;
166         ---Level: Public
167         ---Purpose: Removes the context for all the line primitives
168         --      of the group.
169         ---Category: Methods to modify the class definition
170     
171         SetGroupPrimitivesAspect ( me   : mutable;
172                                    CTX  : AspectLine3d from Graphic3d )
173             is static;
174         ---Level: Public
175         ---Purpose: Modifies the context for all the line primitives
176         --      of the group.
177         ---Category: Methods to modify the class definition
178     
179         SetGroupPrimitivesAspect ( me   : mutable;
180                                    CTX  : AspectFillArea3d from Graphic3d )
181             is static;
182         ---Level: Public
183         ---Purpose: Modifies the context for all the face primitives
184         --      of the group.
185         ---Category: Methods to modify the class definition
186     
187         SetGroupPrimitivesAspect ( me   : mutable;
188                                    CTX  : AspectText3d from Graphic3d )
189             is static;
190         ---Level: Public
191         ---Purpose: Modifies the context for all the text primitives
192         --      of the group.
193         ---Category: Methods to modify the class definition
194     
195         SetGroupPrimitivesAspect ( me   : mutable;
196                                    CTX  : AspectMarker3d from Graphic3d )
197             is static;
198         ---Level: Public
199         ---Purpose: Modifies the context for all the marker primitives
200         --      of the group.
201         ---Category: Methods to modify the class definition
202     
203         SetPrimitivesAspect ( me    : mutable;
204                               CTX   : AspectLine3d from Graphic3d )
205             is static;
206         ---Level: Public
207         ---Purpose: Modifies the current context of the group to give
208         --      another aspect for all the line primitives created
209         --      after this call in the group.
210         ---Category: Methods to modify the class definition
211     
212         SetPrimitivesAspect ( me    : mutable;
213                               CTX   : AspectFillArea3d from Graphic3d )
214             is static;
215         ---Level: Public
216         ---Purpose: Modifies the current context of the group to give
217         --      another aspect for all the face primitives created
218         --      after this call in the group.
219         ---Category: Methods to modify the class definition
220     
221         SetPrimitivesAspect ( me    : mutable;
222                               CTX   : AspectText3d from Graphic3d )
223             is static;
224         ---Level: Public
225         ---Purpose: Modifies the current context of the group to give
226         --      another aspect for all the text primitives created
227         --      after this call in the group.
228         ---Category: Methods to modify the class definition
229     
230         SetPrimitivesAspect ( me    : mutable;
231                               CTX   : AspectMarker3d from Graphic3d )
232             is static;
233         ---Level: Public
234         ---Purpose: Modifies the current context of the group to give
235         --      another aspect for all the marker primitives created
236         --      after this call in the group.
237         ---Category: Methods to modify the class definition
238     
239         SetMinMaxValues ( me                : mutable;
240                           XMin, YMin, ZMin  : Real from Standard;
241                           XMax, YMax, ZMax  : Real from Standard )
242             is static;
243         ---Level: Public
244         ---Purpose: Sets the coordinates of the boundary box of the
245         --      group <me>.
246         ---Category: Methods to modify the class definition
247
248         -----------------------------------
249         -- Category: Methods to create Text
250         -----------------------------------
251     
252         --------------------------------------------
253         -- Summary of Texts                       --
254         --                                        --
255         -- Text  has  geometric  and nongeometric --
256         -- attributes.                            --
257         --                                        --
258         -- The geometric text attributes are :    --
259         --                                        --
260         --  Character Height.                 --
261         --  Character Up Vector.              --
262         --  Text Path.                        --
263         --  Text Alignment Horizontal.        --
264         --  Text Alignment Vertical.          --
265         --                                        --
266         -- The nongeometric text attributes are : --
267         --                                        --
268         --  Text Font.                        --
269         --  Character Spacing.                --
270         --  Character Expansion Factor.       --
271         --  Text Color.                       --
272         --------------------------------------------
273     
274         Text (  me  : mutable;
275             AText   : CString from Standard;
276             APoint  : Vertex from Graphic3d;
277             AHeight : Real from Standard;
278             AAngle  : PlaneAngle from Quantity;
279             ATp : TextPath from Graphic3d;
280             AHta    : HorizontalTextAlignment from Graphic3d;
281             AVta    : VerticalTextAlignment from Graphic3d;
282             EvalMinMax  : Boolean from Standard = Standard_True )
283         is virtual;
284         ---Level: Public
285         ---Purpose: Creates the string <AText> at position <APoint>.
286         --      The 3D point of attachment is projected. The text is
287         --      written in the plane of projection.
288         --      The attributes are given with respect to the plane of
289         --      projection.
290         --      AHeight : Height of text.
291         --            (Relative to the Normalized Projection
292         --              Coordinates (NPC) Space).
293         --      AAngle  : Orientation of the text
294         --            (with respect to the horizontal).
295         ---Category: Methods to create Text
296
297         Text ( me   : mutable;
298                AText    : CString from Standard;
299                APoint   : Vertex from Graphic3d;
300                AHeight  : Real from Standard;
301                EvalMinMax   : Boolean from Standard = Standard_True )
302             is static;
303         ---Level: Public
304         ---Purpose: Creates the string <AText> at position <APoint>.
305         --      The 3D point of attachment is projected. The text is
306         --      written in the plane of projection.
307         --      The attributes are given with respect to the plane of
308         --      projection.
309         --      AHeight : Height of text.
310         --            (Relative to the Normalized Projection
311         --              Coordinates (NPC) Space).
312         --      The other attributes have the following default values:
313         --      AAngle  : PI / 2.
314         --      ATp     : TP_RIGHT
315         --      AHta    : HTA_LEFT
316         --      AVta    : VTA_BOTTOM
317         ---Category: Methods to create Text
318     
319         Text (  me          : mutable;
320                 AText       : ExtendedString from TCollection;
321                 APoint      : Vertex from Graphic3d;
322                 AHeight     : Real from Standard;
323                 AAngle      : PlaneAngle from Quantity;
324                 ATp         : TextPath from Graphic3d;
325                 AHta        : HorizontalTextAlignment from Graphic3d;
326                 AVta        : VerticalTextAlignment from Graphic3d;
327                 EvalMinMax  : Boolean from Standard = Standard_True )
328             is static;
329         ---Level: Internal
330         ---Purpose: Creates the string <AText> at position <APoint>.
331         --      The 3D point of attachment is projected. The text is
332         --      written in the plane of projection.
333         --      The attributes are given with respect to the plane of
334         --      projection.
335         --      AHeight : Height of text.
336         --            (Relative to the Normalized Projection
337         --              Coordinates (NPC) Space).
338         --      AAngle  : Orientation of the text
339         --            (with respect to the horizontal).
340         ---Category: Methods to create Text
341     
342         Text ( me           : mutable;
343                AText        : ExtendedString from TCollection;
344                APoint       : Vertex from Graphic3d;
345                AHeight      : Real from Standard;
346                EvalMinMax   : Boolean from Standard = Standard_True )
347             is static;
348         ---Level: Internal
349         ---Purpose: Creates the string <AText> at position <APoint>.
350         --      The 3D point of attachment is projected. The text is
351         --      written in the plane of projection.
352         --      The attributes are given with respect to the plane of
353         --      projection.
354         --      AHeight : Height of text.
355         --            (Relative to the Normalized Projection
356         --              Coordinates (NPC) Space).
357         --      The other attributes have the following default values:
358         --      AAngle  : PI / 2.
359         --      ATp     : TP_RIGHT
360         --      AHta    : HTA_LEFT
361         --      AVta    : VTA_BOTTOM
362         ---Category: Methods to create Text
363     
364         ---------------------------------------
365         ---Category: Methods to create Triangle
366         ---------------------------------------
367
368     AddPrimitiveArray( me      : mutable;
369                        thePrim : ArrayOfPrimitives from Graphic3d;
370                        theToEvalMinMax : Boolean from Standard = Standard_True ) is virtual;
371     ---Level: Public
372     ---Purpose: Adds an array of primitives for display
373
374     Marker ( me              : mutable;
375              thePoint        : Vertex from Graphic3d;
376              theToEvalMinMax : Boolean from Standard = Standard_True )
377     is static;
378     ---Level: Public
379     ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
380
381     UserDraw ( me               : mutable;
382                theObject        : Address from Standard;
383                theToEvalMinMax  : Boolean from Standard = Standard_True;
384                theContainsFacet : Boolean from Standard = Standard_False )
385     is virtual;
386     ---Level: Public
387     ---Purpose: Creates a UserDraw primitive using obsolete API.
388
389     SetStencilTestOptions (me          : mutable;
390                            theIsEnabled: Boolean from Standard)
391     is deferred;
392     ---Purpose: sets the stencil test to theIsEnabled state;
393
394     SetFlippingOptions (me           : mutable;
395                         theIsEnabled : Boolean from Standard;
396                         theRefPlane  : Ax2 from gp)
397     is deferred;
398     ---Purpose: sets the flipping to theIsEnabled state.
399
400         ----------------------------
401         -- Category: Inquire methods
402         ----------------------------
403
404         IsGroupPrimitivesAspectSet ( me;
405                     theAspect : GroupAspect from Graphic3d )
406             returns Boolean from Standard
407             is static;
408         ---Level: Public
409         ---Purpose: Returns TRUE if aspect is set for the group.
410         ---Category: Inquire methods
411
412         GroupPrimitivesAspect ( me;
413                                 CTXL    : AspectLine3d from Graphic3d;
414                                 CTXT    : AspectText3d from Graphic3d;
415                                 CTXM    : AspectMarker3d from Graphic3d;
416                                 CTXF    : AspectFillArea3d from Graphic3d )
417                 is static;
418         ---Level: Public
419         ---Purpose: Returns the context of all the primitives of the group.
420         ---Category: Inquire methods
421     
422         PrimitivesAspect ( me;
423                            CTXL : AspectLine3d from Graphic3d;
424                            CTXT : AspectText3d from Graphic3d;
425                            CTXM : AspectMarker3d from Graphic3d;
426                            CTXF : AspectFillArea3d from Graphic3d )
427                 is static;
428         ---Level: Public
429         ---Purpose: Returns the last inserted context in the group <me>
430         --          foreach kind of primitives.
431         ---Category: Inquire methods
432
433         ContainsFacet ( me )
434             returns Boolean from Standard
435             is static;
436         ---Level: Internal
437         ---Purpose: Returns Standard_True if the group <me> contains
438         --      Polygons, Triangles or Quadrangles.
439         ---Category: Inquire methods
440     
441         IsDeleted ( me )
442             returns Boolean from Standard
443             is static;
444         ---Level: Public
445         ---Purpose: Returns Standard_True if the group <me> is deleted.
446         --      <me> is deleted after the call Remove (me) or the
447         --      associated structure is deleted.
448         ---Category: Inquire methods
449     
450         IsEmpty ( me )
451             returns Boolean from Standard
452             is static;
453         ---Level: Public
454         ---Purpose: Returns Standard_True if the group <me> is empty.
455         ---Warning: A group is empty if the MinMaxValues method returns :
456         --      XMin = YMin = ZMin = RealFirst ().
457         --      XMax = YMax = ZMax = RealLast ().
458         ---Category: Inquire methods
459     
460         MinMaxValues ( me;
461                        XMin, YMin, ZMin : out Real from Standard;
462                        XMax, YMax, ZMax : out Real from Standard )
463             is static;
464         ---Level: Public
465         ---Purpose: Returns the coordinates of the boundary box of the
466         --      group <me>.
467         ---Warning: If the group <me> is empty then :
468         --      XMin = YMin = ZMin = RealFirst ().
469         --      XMax = YMax = ZMax = RealLast ().
470         ---Category: Inquire methods
471     
472         Structure ( me )
473             returns mutable Structure from Graphic3d
474             is static;
475         ---Level: Public
476         ---Purpose: Returns the structure containing the group <me>.
477         ---Category: Inquire methods
478     
479         ----------------------------
480         -- Category: Private methods
481         ----------------------------
482         
483         MinMaxCoord ( me;
484                       XMin, YMin, ZMin : out Real from Standard;
485                       XMax, YMax, ZMax : out Real from Standard )
486             is static private;
487         ---Level: Internal
488         ---Purpose: Returns the extreme coordinates found in the group.
489         ---Warning: If the group <me> is empty then :
490         --      XMin = YMin = ZMin = RealFirst ().
491         --      XMax = YMax = ZMax = RealLast ().
492         ---Category: Private methods
493     
494         Update ( me )
495             is static private;
496         ---Level: Internal
497         ---Purpose: Calls the Update method of the StructureManager which
498         --      contains the associated Structure of the Group <me>.
499         ---Category: Private methods
500     
501     fields
502     
503     --
504     -- Class    :   Graphic3d_Group
505     --
506     -- Purpose  :   Declaration of variables specific to groups
507     --          of primitives.
508     --
509     -- Reminder :   A group is defined in a structure
510     --          It acts as the smallest editable entity.
511
512   -- the state of the different contexts for primitives
513   myCBitFields   : CBitFields4 from Graphic3d is protected;
514
515   -- the structure contains the group
516   myStructure    : StructurePtr from Graphic3d is protected;
517
518   -- the min-max
519   myBounds       : CBounds from Graphic3d is protected;
520
521   ContextLine     : CAspectLine     from Graphic3d is protected;
522   ContextFillArea : CAspectFillArea from Graphic3d is protected;
523   ContextMarker   : CAspectMarker   from Graphic3d is protected;
524   ContextText     : CAspectText     from Graphic3d is protected;
525
526   -- temporary field - to be removed
527   myListOfPArray : ListOfPArray from Graphic3d is protected;
528
529 friends
530
531   class Structure from Graphic3d
532
533 end Group;