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