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