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
6 -- This file is part of Open CASCADE Technology software library.
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.
14 -- Alternatively, this file may be used under the terms of Open CASCADE
15 -- commercial license or contractual agreement.
17 deferred class Group from Graphic3d inherits TShared
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.
27 -- There are two main group usage models:
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.
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.
55 Array1OfInteger from TColStd,
56 Array1OfReal from TColStd,
57 HArray1OfByte from TColStd,
59 ExtendedString from TCollection,
61 PlaneAngle from Quantity,
63 GroupAspect from Graphic3d,
64 AspectLine3d from Graphic3d,
65 AspectMarker3d from Graphic3d,
66 AspectText3d from Graphic3d,
67 AspectFillArea3d from Graphic3d,
68 CAspectLine from Graphic3d,
69 CAspectFillArea from Graphic3d,
70 CAspectMarker from Graphic3d,
71 CAspectText from Graphic3d,
72 CStructurePtr from Graphic3d,
73 HorizontalTextAlignment from Graphic3d,
74 CBitFields4 from Graphic3d,
75 GraphicDriver from Graphic3d,
76 Structure from Graphic3d,
77 StructurePtr from Graphic3d,
78 TextPath from Graphic3d,
79 Vector from Graphic3d,
80 Array1OfVertex from Graphic3d,
81 Array2OfVertex from Graphic3d,
82 Vertex from Graphic3d,
83 VerticalTextAlignment from Graphic3d,
84 ArrayOfPrimitives from Graphic3d,
85 TypeOfPrimitiveArray from Graphic3d,
86 IndexBuffer_Handle from Graphic3d,
87 Buffer_Handle from Graphic3d,
88 BoundBuffer_Handle from Graphic3d,
89 TransModeFlags from Graphic3d,
90 BndBox4f from Graphic3d,
95 GroupDefinitionError from Graphic3d,
97 OutOfRange from Standard
100 Initialize (theStructure : Structure from Graphic3d)
101 returns Group from Graphic3d;
103 ---Purpose: Creates a group in the structure <AStructure>.
105 ---------------------------------------------------
106 -- Category: Methods to modify the class definition
107 ---------------------------------------------------
109 Clear ( me : mutable;
110 theUpdateStructureMgr : Boolean from Standard = Standard_True )
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
120 ---Category: Methods to modify the class definition
122 UpdateAspectLine ( me : mutable;
123 theIsGlobal : Boolean from Standard )
126 UpdateAspectFace ( me : mutable;
127 theIsGlobal : Boolean from Standard )
130 UpdateAspectMarker ( me : mutable;
131 theIsGlobal : Boolean from Standard )
134 UpdateAspectText ( me : mutable;
135 theIsGlobal : Boolean from Standard )
138 Destroy ( me : mutable )
141 ---Purpose: Supress the group <me> in the structure.
142 ---Category: Methods to modify the class definition
145 Remove ( me : mutable )
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
152 --SetTransformPersistence( me : mutable;
153 -- AFlag : TransModeFlags from Graphic3d )
155 ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
158 --TransformPersistence( me )
159 -- returns TransModeFlags from Graphic3d
161 ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
164 SetGroupPrimitivesAspect ( me : mutable;
165 CTX : AspectLine3d from Graphic3d )
168 ---Purpose: Modifies the context for all the line primitives
170 ---Category: Methods to modify the class definition
172 SetGroupPrimitivesAspect ( me : mutable;
173 CTX : AspectFillArea3d from Graphic3d )
176 ---Purpose: Modifies the context for all the face primitives
178 ---Category: Methods to modify the class definition
180 SetGroupPrimitivesAspect ( me : mutable;
181 CTX : AspectText3d from Graphic3d )
184 ---Purpose: Modifies the context for all the text primitives
186 ---Category: Methods to modify the class definition
188 SetGroupPrimitivesAspect ( me : mutable;
189 CTX : AspectMarker3d from Graphic3d )
192 ---Purpose: Modifies the context for all the marker primitives
194 ---Category: Methods to modify the class definition
196 SetPrimitivesAspect ( me : mutable;
197 CTX : AspectLine3d from Graphic3d )
200 ---Purpose: Modifies the current context of the group to give
201 -- another aspect for all the line primitives created
202 -- after this call in the group.
203 ---Category: Methods to modify the class definition
205 SetPrimitivesAspect ( me : mutable;
206 CTX : AspectFillArea3d from Graphic3d )
209 ---Purpose: Modifies the current context of the group to give
210 -- another aspect for all the face primitives created
211 -- after this call in the group.
212 ---Category: Methods to modify the class definition
214 SetPrimitivesAspect ( me : mutable;
215 CTX : AspectText3d from Graphic3d )
218 ---Purpose: Modifies the current context of the group to give
219 -- another aspect for all the text primitives created
220 -- after this call in the group.
221 ---Category: Methods to modify the class definition
223 SetPrimitivesAspect ( me : mutable;
224 CTX : AspectMarker3d from Graphic3d )
227 ---Purpose: Modifies the current context of the group to give
228 -- another aspect for all the marker primitives created
229 -- after this call in the group.
230 ---Category: Methods to modify the class definition
232 SetMinMaxValues ( me : mutable;
233 XMin, YMin, ZMin : Real from Standard;
234 XMax, YMax, ZMax : Real from Standard )
237 ---Purpose: Sets the coordinates of the boundary box of the
239 ---Category: Methods to modify the class definition
241 -----------------------------------
242 -- Category: Methods to create Text
243 -----------------------------------
245 --------------------------------------------
246 -- Summary of Texts --
248 -- Text has geometric and nongeometric --
251 -- The geometric text attributes are : --
253 -- Character Height. --
254 -- Character Up Vector. --
256 -- Text Alignment Horizontal. --
257 -- Text Alignment Vertical. --
259 -- The nongeometric text attributes are : --
262 -- Character Spacing. --
263 -- Character Expansion Factor. --
265 --------------------------------------------
268 AText : CString from Standard;
269 APoint : Vertex from Graphic3d;
270 AHeight : Real from Standard;
271 AAngle : PlaneAngle from Quantity;
272 ATp : TextPath from Graphic3d;
273 AHta : HorizontalTextAlignment from Graphic3d;
274 AVta : VerticalTextAlignment from Graphic3d;
275 EvalMinMax : Boolean from Standard = Standard_True )
278 ---Purpose: Creates the string <AText> at position <APoint>.
279 -- The 3D point of attachment is projected. The text is
280 -- written in the plane of projection.
281 -- The attributes are given with respect to the plane of
283 -- AHeight : Height of text.
284 -- (Relative to the Normalized Projection
285 -- Coordinates (NPC) Space).
286 -- AAngle : Orientation of the text
287 -- (with respect to the horizontal).
288 ---Category: Methods to create Text
291 AText : CString from Standard;
292 APoint : Vertex from Graphic3d;
293 AHeight : Real from Standard;
294 EvalMinMax : Boolean from Standard = Standard_True )
297 ---Purpose: Creates the string <AText> at position <APoint>.
298 -- The 3D point of attachment is projected. The text is
299 -- written in the plane of projection.
300 -- The attributes are given with respect to the plane of
302 -- AHeight : Height of text.
303 -- (Relative to the Normalized Projection
304 -- Coordinates (NPC) Space).
305 -- The other attributes have the following default values:
310 ---Category: Methods to create Text
313 AText : ExtendedString from TCollection;
314 APoint : Vertex from Graphic3d;
315 AHeight : Real from Standard;
316 AAngle : PlaneAngle from Quantity;
317 ATp : TextPath from Graphic3d;
318 AHta : HorizontalTextAlignment from Graphic3d;
319 AVta : VerticalTextAlignment from Graphic3d;
320 EvalMinMax : Boolean from Standard = Standard_True )
323 ---Purpose: Creates the string <AText> at position <APoint>.
324 -- The 3D point of attachment is projected. The text is
325 -- written in the plane of projection.
326 -- The attributes are given with respect to the plane of
328 -- AHeight : Height of text.
329 -- (Relative to the Normalized Projection
330 -- Coordinates (NPC) Space).
331 -- AAngle : Orientation of the text
332 -- (with respect to the horizontal).
333 ---Category: Methods to create Text
336 AText : ExtendedString from TCollection;
337 APoint : Vertex from Graphic3d;
338 AHeight : Real from Standard;
339 EvalMinMax : Boolean from Standard = Standard_True )
342 ---Purpose: Creates the string <AText> at position <APoint>.
343 -- The 3D point of attachment is projected. The text is
344 -- written in the plane of projection.
345 -- The attributes are given with respect to the plane of
347 -- AHeight : Height of text.
348 -- (Relative to the Normalized Projection
349 -- Coordinates (NPC) Space).
350 -- The other attributes have the following default values:
355 ---Category: Methods to create Text
357 ---------------------------------------
358 ---Category: Methods to create Triangle
359 ---------------------------------------
361 AddPrimitiveArray (me : mutable;
362 theType : TypeOfPrimitiveArray from Graphic3d;
363 theIndices : IndexBuffer_Handle from Graphic3d;
364 theAttribs : Buffer_Handle from Graphic3d;
365 theBounds : BoundBuffer_Handle from Graphic3d;
366 theToEvalMinMax : Boolean from Standard = Standard_True) is virtual;
368 ---Purpose: Adds an array of primitives for display
370 AddPrimitiveArray( me : mutable;
371 thePrim : ArrayOfPrimitives from Graphic3d;
372 theToEvalMinMax : Boolean from Standard = Standard_True );
374 ---Purpose: Adds an array of primitives for display
376 Marker ( me : mutable;
377 thePoint : Vertex from Graphic3d;
378 theToEvalMinMax : Boolean from Standard = Standard_True )
381 ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
383 UserDraw ( me : mutable;
384 theObject : Address from Standard;
385 theToEvalMinMax : Boolean from Standard = Standard_True;
386 theContainsFacet : Boolean from Standard = Standard_False )
389 ---Purpose: Creates a UserDraw primitive using obsolete API.
391 SetStencilTestOptions (me : mutable;
392 theIsEnabled: Boolean from Standard)
394 ---Purpose: sets the stencil test to theIsEnabled state;
396 SetFlippingOptions (me : mutable;
397 theIsEnabled : Boolean from Standard;
398 theRefPlane : Ax2 from gp)
400 ---Purpose: sets the flipping to theIsEnabled state.
402 ----------------------------
403 -- Category: Inquire methods
404 ----------------------------
406 IsGroupPrimitivesAspectSet ( me;
407 theAspect : GroupAspect from Graphic3d )
408 returns Boolean from Standard
411 ---Purpose: Returns TRUE if aspect is set for the group.
412 ---Category: Inquire methods
414 GroupPrimitivesAspect ( me;
415 CTXL : AspectLine3d from Graphic3d;
416 CTXT : AspectText3d from Graphic3d;
417 CTXM : AspectMarker3d from Graphic3d;
418 CTXF : AspectFillArea3d from Graphic3d )
421 ---Purpose: Returns the context of all the primitives of the group.
422 ---Category: Inquire methods
424 PrimitivesAspect ( me;
425 CTXL : AspectLine3d from Graphic3d;
426 CTXT : AspectText3d from Graphic3d;
427 CTXM : AspectMarker3d from Graphic3d;
428 CTXF : AspectFillArea3d from Graphic3d )
431 ---Purpose: Returns the last inserted context in the group <me>
432 -- foreach kind of primitives.
433 ---Category: Inquire methods
436 returns Boolean from Standard
439 ---Purpose: Returns Standard_True if the group <me> contains
440 -- Polygons, Triangles or Quadrangles.
441 ---Category: Inquire methods
444 returns Boolean from Standard
447 ---Purpose: Returns Standard_True if the group <me> is deleted.
448 -- <me> is deleted after the call Remove (me) or the
449 -- associated structure is deleted.
450 ---Category: Inquire methods
453 returns Boolean from Standard
456 ---Purpose: Returns Standard_True if the group <me> is empty.
457 ---Warning: A group is empty if the MinMaxValues method returns :
458 -- XMin = YMin = ZMin = RealFirst ().
459 -- XMax = YMax = ZMax = RealLast ().
460 ---Category: Inquire methods
463 XMin, YMin, ZMin : out Real from Standard;
464 XMax, YMax, ZMax : out Real from Standard )
467 ---Purpose: Returns the coordinates of the boundary box of the
469 ---Warning: If the group <me> is empty then :
470 -- XMin = YMin = ZMin = RealFirst ().
471 -- XMax = YMax = ZMax = RealLast ().
472 ---Category: Inquire methods
475 returns BndBox4f from Graphic3d
478 ---Purpose: Returns boundary box of the group <me> without transformation applied,
479 ---if it is specified for the structure.
480 ---C++: return const &
482 ChangeBoundingBox ( me : mutable )
483 returns BndBox4f from Graphic3d
486 ---Purpose: Returns non-const boundary box of the group <me> without transformation applied,
487 ---if it is specified for the structure.
491 returns Structure from Graphic3d
494 ---Purpose: Returns the structure containing the group <me>.
495 ---Category: Inquire methods
497 ----------------------------
498 -- Category: Private methods
499 ----------------------------
502 XMin, YMin, ZMin : out Real from Standard;
503 XMax, YMax, ZMax : out Real from Standard )
506 ---Purpose: Returns the extreme coordinates found in the group.
507 ---Warning: If the group <me> is empty then :
508 -- XMin = YMin = ZMin = RealFirst ().
509 -- XMax = YMax = ZMax = RealLast ().
510 ---Category: Private methods
515 ---Purpose: Calls the Update method of the StructureManager which
516 -- contains the associated Structure of the Group <me>.
517 ---Category: Private methods
519 SetClosed (me: mutable; theIsClosed : Boolean from Standard);
520 ---Purpose: Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
522 IsClosed (me) returns Boolean from Standard;
523 ---Purpose: Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
528 -- Class : Graphic3d_Group
530 -- Purpose : Declaration of variables specific to groups
533 -- Reminder : A group is defined in a structure
534 -- It acts as the smallest editable entity.
536 -- the state of the different contexts for primitives
537 myCBitFields : CBitFields4 from Graphic3d is protected;
539 -- the structure contains the group
540 myStructure : StructurePtr from Graphic3d is protected;
543 myBounds : BndBox4f from Graphic3d is protected;
545 -- Identifies group forming closed volume. Used to filter groups for back face culling and capping algorithms.
546 myIsClosed : Boolean from Standard is protected;
548 ContextLine : CAspectLine from Graphic3d is protected;
549 ContextFillArea : CAspectFillArea from Graphic3d is protected;
550 ContextMarker : CAspectMarker from Graphic3d is protected;
551 ContextText : CAspectText from Graphic3d is protected;
555 class Structure from Graphic3d