0024977: There are compilation errors in products csharp sample
[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         TypeOfPrimitiveArray        from Graphic3d,
89         IndexBuffer_Handle          from Graphic3d,
90         Buffer_Handle               from Graphic3d,
91         BoundBuffer_Handle          from Graphic3d,
92         TransModeFlags              from Graphic3d,
93         BndBox4f                    from Graphic3d,
94         Ax2                         from gp
95     
96     raises
97
98         GroupDefinitionError        from Graphic3d,
99
100     OutOfRange          from Standard
101     
102     is
103         Initialize (theStructure : Structure from Graphic3d)
104             returns Group from Graphic3d;
105         ---Level: Public
106         ---Purpose: Creates a group in the structure <AStructure>.
107     
108         ---------------------------------------------------
109         -- Category: Methods to modify the class definition
110         ---------------------------------------------------
111     
112         Clear ( me  : mutable;
113                 theUpdateStructureMgr : Boolean from Standard = Standard_True )
114         is virtual;
115         ---Level: Public
116         ---Purpose: Supress all primitives and attributes of <me>.
117         --          To clear group without update in Graphic3d_StructureManager
118         --          pass Standard_False as <theUpdateStructureMgr>. This
119         --          used on context and viewer destruction, when the pointer
120         --          to structure manager in Graphic3d_Structure could be 
121         --          already released (pointers are used here to avoid handle 
122         --          cross-reference);
123         ---Category: Methods to modify the class definition
124
125         UpdateAspectLine ( me          : mutable;
126                            theIsGlobal : Boolean from Standard )
127         is deferred;
128
129         UpdateAspectFace ( me          : mutable;
130                            theIsGlobal : Boolean from Standard )
131         is deferred;
132
133         UpdateAspectMarker ( me          : mutable;
134                              theIsGlobal : Boolean from Standard )
135         is deferred;
136
137         UpdateAspectText ( me          : mutable;
138                            theIsGlobal : Boolean from Standard )
139         is deferred;
140
141         Destroy ( me    : mutable )
142             is static;
143         ---Level: Public
144         ---Purpose: Supress the group <me> in the structure.
145         ---Category: Methods to modify the class definition
146         ---C++: alias ~
147     
148         Remove ( me : mutable )
149             is static;
150         ---Level: Public
151         ---Purpose: Supress the group <me> in the structure.
152         --  Warning: No more graphic operations in <me> after this call.
153         ---Category: Methods to modify the class definition
154
155         --SetTransformPersistence( me     : mutable;
156         --                         AFlag  : TransModeFlags from Graphic3d )
157         ---Level: Public
158     ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
159         --is static;
160
161     --TransformPersistence( me )
162     --      returns TransModeFlags from Graphic3d
163         ---Level: Public
164     ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
165         --is static;
166     
167         SetGroupPrimitivesAspect ( me   : mutable;
168                                    CTX  : AspectLine3d from Graphic3d )
169             is static;
170         ---Level: Public
171         ---Purpose: Modifies the context for all the line primitives
172         --      of the group.
173         ---Category: Methods to modify the class definition
174     
175         SetGroupPrimitivesAspect ( me   : mutable;
176                                    CTX  : AspectFillArea3d from Graphic3d )
177             is static;
178         ---Level: Public
179         ---Purpose: Modifies the context for all the face primitives
180         --      of the group.
181         ---Category: Methods to modify the class definition
182     
183         SetGroupPrimitivesAspect ( me   : mutable;
184                                    CTX  : AspectText3d from Graphic3d )
185             is static;
186         ---Level: Public
187         ---Purpose: Modifies the context for all the text primitives
188         --      of the group.
189         ---Category: Methods to modify the class definition
190     
191         SetGroupPrimitivesAspect ( me   : mutable;
192                                    CTX  : AspectMarker3d from Graphic3d )
193             is static;
194         ---Level: Public
195         ---Purpose: Modifies the context for all the marker primitives
196         --      of the group.
197         ---Category: Methods to modify the class definition
198     
199         SetPrimitivesAspect ( me    : mutable;
200                               CTX   : AspectLine3d from Graphic3d )
201             is static;
202         ---Level: Public
203         ---Purpose: Modifies the current context of the group to give
204         --      another aspect for all the line primitives created
205         --      after this call in the group.
206         ---Category: Methods to modify the class definition
207     
208         SetPrimitivesAspect ( me    : mutable;
209                               CTX   : AspectFillArea3d from Graphic3d )
210             is static;
211         ---Level: Public
212         ---Purpose: Modifies the current context of the group to give
213         --      another aspect for all the face primitives created
214         --      after this call in the group.
215         ---Category: Methods to modify the class definition
216     
217         SetPrimitivesAspect ( me    : mutable;
218                               CTX   : AspectText3d from Graphic3d )
219             is static;
220         ---Level: Public
221         ---Purpose: Modifies the current context of the group to give
222         --      another aspect for all the text primitives created
223         --      after this call in the group.
224         ---Category: Methods to modify the class definition
225     
226         SetPrimitivesAspect ( me    : mutable;
227                               CTX   : AspectMarker3d from Graphic3d )
228             is static;
229         ---Level: Public
230         ---Purpose: Modifies the current context of the group to give
231         --      another aspect for all the marker primitives created
232         --      after this call in the group.
233         ---Category: Methods to modify the class definition
234     
235         SetMinMaxValues ( me                : mutable;
236                           XMin, YMin, ZMin  : Real from Standard;
237                           XMax, YMax, ZMax  : Real from Standard )
238             is static;
239         ---Level: Public
240         ---Purpose: Sets the coordinates of the boundary box of the
241         --      group <me>.
242         ---Category: Methods to modify the class definition
243
244         -----------------------------------
245         -- Category: Methods to create Text
246         -----------------------------------
247     
248         --------------------------------------------
249         -- Summary of Texts                       --
250         --                                        --
251         -- Text  has  geometric  and nongeometric --
252         -- attributes.                            --
253         --                                        --
254         -- The geometric text attributes are :    --
255         --                                        --
256         --  Character Height.                 --
257         --  Character Up Vector.              --
258         --  Text Path.                        --
259         --  Text Alignment Horizontal.        --
260         --  Text Alignment Vertical.          --
261         --                                        --
262         -- The nongeometric text attributes are : --
263         --                                        --
264         --  Text Font.                        --
265         --  Character Spacing.                --
266         --  Character Expansion Factor.       --
267         --  Text Color.                       --
268         --------------------------------------------
269     
270         Text (  me  : mutable;
271             AText   : CString from Standard;
272             APoint  : Vertex from Graphic3d;
273             AHeight : Real from Standard;
274             AAngle  : PlaneAngle from Quantity;
275             ATp : TextPath from Graphic3d;
276             AHta    : HorizontalTextAlignment from Graphic3d;
277             AVta    : VerticalTextAlignment from Graphic3d;
278             EvalMinMax  : Boolean from Standard = Standard_True )
279         is virtual;
280         ---Level: Public
281         ---Purpose: Creates the string <AText> at position <APoint>.
282         --      The 3D point of attachment is projected. The text is
283         --      written in the plane of projection.
284         --      The attributes are given with respect to the plane of
285         --      projection.
286         --      AHeight : Height of text.
287         --            (Relative to the Normalized Projection
288         --              Coordinates (NPC) Space).
289         --      AAngle  : Orientation of the text
290         --            (with respect to the horizontal).
291         ---Category: Methods to create Text
292
293         Text ( me   : mutable;
294                AText    : CString from Standard;
295                APoint   : Vertex from Graphic3d;
296                AHeight  : Real from Standard;
297                EvalMinMax   : Boolean from Standard = Standard_True )
298             is static;
299         ---Level: Public
300         ---Purpose: Creates the string <AText> at position <APoint>.
301         --      The 3D point of attachment is projected. The text is
302         --      written in the plane of projection.
303         --      The attributes are given with respect to the plane of
304         --      projection.
305         --      AHeight : Height of text.
306         --            (Relative to the Normalized Projection
307         --              Coordinates (NPC) Space).
308         --      The other attributes have the following default values:
309         --      AAngle  : PI / 2.
310         --      ATp     : TP_RIGHT
311         --      AHta    : HTA_LEFT
312         --      AVta    : VTA_BOTTOM
313         ---Category: Methods to create Text
314     
315         Text (  me          : mutable;
316                 AText       : ExtendedString from TCollection;
317                 APoint      : Vertex from Graphic3d;
318                 AHeight     : Real from Standard;
319                 AAngle      : PlaneAngle from Quantity;
320                 ATp         : TextPath from Graphic3d;
321                 AHta        : HorizontalTextAlignment from Graphic3d;
322                 AVta        : VerticalTextAlignment from Graphic3d;
323                 EvalMinMax  : Boolean from Standard = Standard_True )
324             is static;
325         ---Level: Internal
326         ---Purpose: Creates the string <AText> at position <APoint>.
327         --      The 3D point of attachment is projected. The text is
328         --      written in the plane of projection.
329         --      The attributes are given with respect to the plane of
330         --      projection.
331         --      AHeight : Height of text.
332         --            (Relative to the Normalized Projection
333         --              Coordinates (NPC) Space).
334         --      AAngle  : Orientation of the text
335         --            (with respect to the horizontal).
336         ---Category: Methods to create Text
337     
338         Text ( me           : mutable;
339                AText        : ExtendedString from TCollection;
340                APoint       : Vertex from Graphic3d;
341                AHeight      : Real from Standard;
342                EvalMinMax   : Boolean from Standard = Standard_True )
343             is static;
344         ---Level: Internal
345         ---Purpose: Creates the string <AText> at position <APoint>.
346         --      The 3D point of attachment is projected. The text is
347         --      written in the plane of projection.
348         --      The attributes are given with respect to the plane of
349         --      projection.
350         --      AHeight : Height of text.
351         --            (Relative to the Normalized Projection
352         --              Coordinates (NPC) Space).
353         --      The other attributes have the following default values:
354         --      AAngle  : PI / 2.
355         --      ATp     : TP_RIGHT
356         --      AHta    : HTA_LEFT
357         --      AVta    : VTA_BOTTOM
358         ---Category: Methods to create Text
359     
360         ---------------------------------------
361         ---Category: Methods to create Triangle
362         ---------------------------------------
363
364     AddPrimitiveArray (me              : mutable;
365                        theType         : TypeOfPrimitiveArray from Graphic3d;
366                        theIndices      : IndexBuffer_Handle   from Graphic3d;
367                        theAttribs      : Buffer_Handle        from Graphic3d;
368                        theBounds       : BoundBuffer_Handle   from Graphic3d;
369                        theToEvalMinMax : Boolean from Standard = Standard_True) is virtual;
370     ---Level: Public
371     ---Purpose: Adds an array of primitives for display
372
373     AddPrimitiveArray( me      : mutable;
374                        thePrim : ArrayOfPrimitives from Graphic3d;
375                        theToEvalMinMax : Boolean from Standard = Standard_True );
376     ---Level: Public
377     ---Purpose: Adds an array of primitives for display
378
379     Marker ( me              : mutable;
380              thePoint        : Vertex from Graphic3d;
381              theToEvalMinMax : Boolean from Standard = Standard_True )
382     is static;
383     ---Level: Public
384     ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
385
386     UserDraw ( me               : mutable;
387                theObject        : Address from Standard;
388                theToEvalMinMax  : Boolean from Standard = Standard_True;
389                theContainsFacet : Boolean from Standard = Standard_False )
390     is virtual;
391     ---Level: Public
392     ---Purpose: Creates a UserDraw primitive using obsolete API.
393
394     SetStencilTestOptions (me          : mutable;
395                            theIsEnabled: Boolean from Standard)
396     is deferred;
397     ---Purpose: sets the stencil test to theIsEnabled state;
398
399     SetFlippingOptions (me           : mutable;
400                         theIsEnabled : Boolean from Standard;
401                         theRefPlane  : Ax2 from gp)
402     is deferred;
403     ---Purpose: sets the flipping to theIsEnabled state.
404
405         ----------------------------
406         -- Category: Inquire methods
407         ----------------------------
408
409         IsGroupPrimitivesAspectSet ( me;
410                     theAspect : GroupAspect from Graphic3d )
411             returns Boolean from Standard
412             is static;
413         ---Level: Public
414         ---Purpose: Returns TRUE if aspect is set for the group.
415         ---Category: Inquire methods
416
417         GroupPrimitivesAspect ( me;
418                                 CTXL    : AspectLine3d from Graphic3d;
419                                 CTXT    : AspectText3d from Graphic3d;
420                                 CTXM    : AspectMarker3d from Graphic3d;
421                                 CTXF    : AspectFillArea3d from Graphic3d )
422                 is static;
423         ---Level: Public
424         ---Purpose: Returns the context of all the primitives of the group.
425         ---Category: Inquire methods
426     
427         PrimitivesAspect ( me;
428                            CTXL : AspectLine3d from Graphic3d;
429                            CTXT : AspectText3d from Graphic3d;
430                            CTXM : AspectMarker3d from Graphic3d;
431                            CTXF : AspectFillArea3d from Graphic3d )
432                 is static;
433         ---Level: Public
434         ---Purpose: Returns the last inserted context in the group <me>
435         --          foreach kind of primitives.
436         ---Category: Inquire methods
437
438         ContainsFacet ( me )
439             returns Boolean from Standard
440             is static;
441         ---Level: Internal
442         ---Purpose: Returns Standard_True if the group <me> contains
443         --      Polygons, Triangles or Quadrangles.
444         ---Category: Inquire methods
445     
446         IsDeleted ( me )
447             returns Boolean from Standard
448             is static;
449         ---Level: Public
450         ---Purpose: Returns Standard_True if the group <me> is deleted.
451         --      <me> is deleted after the call Remove (me) or the
452         --      associated structure is deleted.
453         ---Category: Inquire methods
454     
455         IsEmpty ( me )
456             returns Boolean from Standard
457             is static;
458         ---Level: Public
459         ---Purpose: Returns Standard_True if the group <me> is empty.
460         ---Warning: A group is empty if the MinMaxValues method returns :
461         --      XMin = YMin = ZMin = RealFirst ().
462         --      XMax = YMax = ZMax = RealLast ().
463         ---Category: Inquire methods
464     
465         MinMaxValues ( me;
466                        XMin, YMin, ZMin : out Real from Standard;
467                        XMax, YMax, ZMax : out Real from Standard )
468             is static;
469         ---Level: Public
470         ---Purpose: Returns the coordinates of the boundary box of the
471         --      group <me>.
472         ---Warning: If the group <me> is empty then :
473         --      XMin = YMin = ZMin = RealFirst ().
474         --      XMax = YMax = ZMax = RealLast ().
475         ---Category: Inquire methods
476
477         BoundingBox ( me )
478             returns BndBox4f from Graphic3d
479             is static;
480         ---Level: Public
481         ---Purpose: Returns boundary box of the group <me> without transformation applied,
482         ---if it is specified for the structure.
483         ---C++: return const &
484
485         ChangeBoundingBox ( me : mutable )
486             returns BndBox4f from Graphic3d
487             is static;
488         ---Level: Public
489         ---Purpose: Returns non-const boundary box of the group <me> without transformation applied,
490         ---if it is specified for the structure.
491         ---C++: return &
492     
493         Structure ( me )
494             returns Structure from Graphic3d
495             is static;
496         ---Level: Public
497         ---Purpose: Returns the structure containing the group <me>.
498         ---Category: Inquire methods
499     
500         ----------------------------
501         -- Category: Private methods
502         ----------------------------
503         
504         MinMaxCoord ( me;
505                       XMin, YMin, ZMin : out Real from Standard;
506                       XMax, YMax, ZMax : out Real from Standard )
507             is static private;
508         ---Level: Internal
509         ---Purpose: Returns the extreme coordinates found in the group.
510         ---Warning: If the group <me> is empty then :
511         --      XMin = YMin = ZMin = RealFirst ().
512         --      XMax = YMax = ZMax = RealLast ().
513         ---Category: Private methods
514     
515         Update ( me )
516             is static private;
517         ---Level: Internal
518         ---Purpose: Calls the Update method of the StructureManager which
519         --      contains the associated Structure of the Group <me>.
520         ---Category: Private methods
521
522         SetClosed (me: mutable; theIsClosed : Boolean from Standard);
523         ---Purpose: Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
524
525         IsClosed (me) returns Boolean from Standard;
526         ---Purpose: Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
527
528     fields
529     
530     --
531     -- Class    :   Graphic3d_Group
532     --
533     -- Purpose  :   Declaration of variables specific to groups
534     --          of primitives.
535     --
536     -- Reminder :   A group is defined in a structure
537     --          It acts as the smallest editable entity.
538
539   -- the state of the different contexts for primitives
540   myCBitFields   : CBitFields4 from Graphic3d is protected;
541
542   -- the structure contains the group
543   myStructure    : StructurePtr from Graphic3d is protected;
544
545   -- the min-max
546   myBounds        : BndBox4f from Graphic3d is protected;
547
548   -- Identifies group forming closed volume. Used to filter groups for back face culling and capping algorithms.
549   myIsClosed  : Boolean from Standard is protected;
550
551   ContextLine     : CAspectLine     from Graphic3d is protected;
552   ContextFillArea : CAspectFillArea from Graphic3d is protected;
553   ContextMarker   : CAspectMarker   from Graphic3d is protected;
554   ContextText     : CAspectText     from Graphic3d is protected;
555
556 friends
557
558   class Structure from Graphic3d
559
560 end Group;