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 Array1OfEdge from Aspect,
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,
98 GroupDefinitionError from Graphic3d,
100 OutOfRange from Standard
103 Initialize (theStructure : Structure from Graphic3d)
104 returns Group from Graphic3d;
106 ---Purpose: Creates a group in the structure <AStructure>.
108 ---------------------------------------------------
109 -- Category: Methods to modify the class definition
110 ---------------------------------------------------
112 Clear ( me : mutable;
113 theUpdateStructureMgr : Boolean from Standard = Standard_True )
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
123 ---Category: Methods to modify the class definition
125 UpdateAspectLine ( me : mutable;
126 theIsGlobal : Boolean from Standard )
129 UpdateAspectFace ( me : mutable;
130 theIsGlobal : Boolean from Standard )
133 UpdateAspectMarker ( me : mutable;
134 theIsGlobal : Boolean from Standard )
137 UpdateAspectText ( me : mutable;
138 theIsGlobal : Boolean from Standard )
141 Destroy ( me : mutable )
144 ---Purpose: Supress the group <me> in the structure.
145 ---Category: Methods to modify the class definition
148 Remove ( me : mutable )
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
155 --SetTransformPersistence( me : mutable;
156 -- AFlag : TransModeFlags from Graphic3d )
158 ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
161 --TransformPersistence( me )
162 -- returns TransModeFlags from Graphic3d
164 ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
167 SetGroupPrimitivesAspect ( me : mutable )
170 ---Purpose: Removes the context for all the line primitives
172 ---Category: Methods to modify the class definition
174 SetGroupPrimitivesAspect ( me : mutable;
175 CTX : AspectLine3d from Graphic3d )
178 ---Purpose: Modifies the context for all the line primitives
180 ---Category: Methods to modify the class definition
182 SetGroupPrimitivesAspect ( me : mutable;
183 CTX : AspectFillArea3d from Graphic3d )
186 ---Purpose: Modifies the context for all the face primitives
188 ---Category: Methods to modify the class definition
190 SetGroupPrimitivesAspect ( me : mutable;
191 CTX : AspectText3d from Graphic3d )
194 ---Purpose: Modifies the context for all the text primitives
196 ---Category: Methods to modify the class definition
198 SetGroupPrimitivesAspect ( me : mutable;
199 CTX : AspectMarker3d from Graphic3d )
202 ---Purpose: Modifies the context for all the marker primitives
204 ---Category: Methods to modify the class definition
206 SetPrimitivesAspect ( me : mutable;
207 CTX : AspectLine3d from Graphic3d )
210 ---Purpose: Modifies the current context of the group to give
211 -- another aspect for all the line primitives created
212 -- after this call in the group.
213 ---Category: Methods to modify the class definition
215 SetPrimitivesAspect ( me : mutable;
216 CTX : AspectFillArea3d from Graphic3d )
219 ---Purpose: Modifies the current context of the group to give
220 -- another aspect for all the face primitives created
221 -- after this call in the group.
222 ---Category: Methods to modify the class definition
224 SetPrimitivesAspect ( me : mutable;
225 CTX : AspectText3d from Graphic3d )
228 ---Purpose: Modifies the current context of the group to give
229 -- another aspect for all the text primitives created
230 -- after this call in the group.
231 ---Category: Methods to modify the class definition
233 SetPrimitivesAspect ( me : mutable;
234 CTX : AspectMarker3d from Graphic3d )
237 ---Purpose: Modifies the current context of the group to give
238 -- another aspect for all the marker primitives created
239 -- after this call in the group.
240 ---Category: Methods to modify the class definition
242 SetMinMaxValues ( me : mutable;
243 XMin, YMin, ZMin : Real from Standard;
244 XMax, YMax, ZMax : Real from Standard )
247 ---Purpose: Sets the coordinates of the boundary box of the
249 ---Category: Methods to modify the class definition
251 -----------------------------------
252 -- Category: Methods to create Text
253 -----------------------------------
255 --------------------------------------------
256 -- Summary of Texts --
258 -- Text has geometric and nongeometric --
261 -- The geometric text attributes are : --
263 -- Character Height. --
264 -- Character Up Vector. --
266 -- Text Alignment Horizontal. --
267 -- Text Alignment Vertical. --
269 -- The nongeometric text attributes are : --
272 -- Character Spacing. --
273 -- Character Expansion Factor. --
275 --------------------------------------------
278 AText : CString from Standard;
279 APoint : Vertex from Graphic3d;
280 AHeight : Real from Standard;
281 AAngle : PlaneAngle from Quantity;
282 ATp : TextPath from Graphic3d;
283 AHta : HorizontalTextAlignment from Graphic3d;
284 AVta : VerticalTextAlignment from Graphic3d;
285 EvalMinMax : Boolean from Standard = Standard_True )
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
293 -- AHeight : Height of text.
294 -- (Relative to the Normalized Projection
295 -- Coordinates (NPC) Space).
296 -- AAngle : Orientation of the text
297 -- (with respect to the horizontal).
298 ---Category: Methods to create Text
301 AText : CString from Standard;
302 APoint : Vertex from Graphic3d;
303 AHeight : Real from Standard;
304 EvalMinMax : Boolean from Standard = Standard_True )
307 ---Purpose: Creates the string <AText> at position <APoint>.
308 -- The 3D point of attachment is projected. The text is
309 -- written in the plane of projection.
310 -- The attributes are given with respect to the plane of
312 -- AHeight : Height of text.
313 -- (Relative to the Normalized Projection
314 -- Coordinates (NPC) Space).
315 -- The other attributes have the following default values:
320 ---Category: Methods to create Text
323 AText : ExtendedString from TCollection;
324 APoint : Vertex from Graphic3d;
325 AHeight : Real from Standard;
326 AAngle : PlaneAngle from Quantity;
327 ATp : TextPath from Graphic3d;
328 AHta : HorizontalTextAlignment from Graphic3d;
329 AVta : VerticalTextAlignment from Graphic3d;
330 EvalMinMax : Boolean from Standard = Standard_True )
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
338 -- AHeight : Height of text.
339 -- (Relative to the Normalized Projection
340 -- Coordinates (NPC) Space).
341 -- AAngle : Orientation of the text
342 -- (with respect to the horizontal).
343 ---Category: Methods to create Text
346 AText : ExtendedString from TCollection;
347 APoint : Vertex from Graphic3d;
348 AHeight : Real from Standard;
349 EvalMinMax : Boolean from Standard = Standard_True )
352 ---Purpose: Creates the string <AText> at position <APoint>.
353 -- The 3D point of attachment is projected. The text is
354 -- written in the plane of projection.
355 -- The attributes are given with respect to the plane of
357 -- AHeight : Height of text.
358 -- (Relative to the Normalized Projection
359 -- Coordinates (NPC) Space).
360 -- The other attributes have the following default values:
365 ---Category: Methods to create Text
367 ---------------------------------------
368 ---Category: Methods to create Triangle
369 ---------------------------------------
371 AddPrimitiveArray (me : mutable;
372 theType : TypeOfPrimitiveArray from Graphic3d;
373 theIndices : IndexBuffer_Handle from Graphic3d;
374 theAttribs : Buffer_Handle from Graphic3d;
375 theBounds : BoundBuffer_Handle from Graphic3d;
376 theToEvalMinMax : Boolean from Standard = Standard_True) is virtual;
378 ---Purpose: Adds an array of primitives for display
380 AddPrimitiveArray( me : mutable;
381 thePrim : ArrayOfPrimitives from Graphic3d;
382 theToEvalMinMax : Boolean from Standard = Standard_True );
384 ---Purpose: Adds an array of primitives for display
386 Marker ( me : mutable;
387 thePoint : Vertex from Graphic3d;
388 theToEvalMinMax : Boolean from Standard = Standard_True )
391 ---Purpose: Creates a primitive array with single marker using AddPrimitiveArray().
393 UserDraw ( me : mutable;
394 theObject : Address from Standard;
395 theToEvalMinMax : Boolean from Standard = Standard_True;
396 theContainsFacet : Boolean from Standard = Standard_False )
399 ---Purpose: Creates a UserDraw primitive using obsolete API.
401 SetStencilTestOptions (me : mutable;
402 theIsEnabled: Boolean from Standard)
404 ---Purpose: sets the stencil test to theIsEnabled state;
406 SetFlippingOptions (me : mutable;
407 theIsEnabled : Boolean from Standard;
408 theRefPlane : Ax2 from gp)
410 ---Purpose: sets the flipping to theIsEnabled state.
412 ----------------------------
413 -- Category: Inquire methods
414 ----------------------------
416 IsGroupPrimitivesAspectSet ( me;
417 theAspect : GroupAspect from Graphic3d )
418 returns Boolean from Standard
421 ---Purpose: Returns TRUE if aspect is set for the group.
422 ---Category: Inquire methods
424 GroupPrimitivesAspect ( 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 context of all the primitives of the group.
432 ---Category: Inquire methods
434 PrimitivesAspect ( me;
435 CTXL : AspectLine3d from Graphic3d;
436 CTXT : AspectText3d from Graphic3d;
437 CTXM : AspectMarker3d from Graphic3d;
438 CTXF : AspectFillArea3d from Graphic3d )
441 ---Purpose: Returns the last inserted context in the group <me>
442 -- foreach kind of primitives.
443 ---Category: Inquire methods
446 returns Boolean from Standard
449 ---Purpose: Returns Standard_True if the group <me> contains
450 -- Polygons, Triangles or Quadrangles.
451 ---Category: Inquire methods
454 returns Boolean from Standard
457 ---Purpose: Returns Standard_True if the group <me> is deleted.
458 -- <me> is deleted after the call Remove (me) or the
459 -- associated structure is deleted.
460 ---Category: Inquire methods
463 returns Boolean from Standard
466 ---Purpose: Returns Standard_True if the group <me> is empty.
467 ---Warning: A group is empty if the MinMaxValues method returns :
468 -- XMin = YMin = ZMin = RealFirst ().
469 -- XMax = YMax = ZMax = RealLast ().
470 ---Category: Inquire methods
473 XMin, YMin, ZMin : out Real from Standard;
474 XMax, YMax, ZMax : out Real from Standard )
477 ---Purpose: Returns the coordinates of the boundary box of the
479 ---Warning: If the group <me> is empty then :
480 -- XMin = YMin = ZMin = RealFirst ().
481 -- XMax = YMax = ZMax = RealLast ().
482 ---Category: Inquire methods
485 returns BndBox4f from Graphic3d
488 ---Purpose: Returns boundary box of the group <me> without transformation applied,
489 ---if it is specified for the structure.
490 ---C++: return const &
492 ChangeBoundingBox ( me : mutable )
493 returns BndBox4f from Graphic3d
496 ---Purpose: Returns non-const boundary box of the group <me> without transformation applied,
497 ---if it is specified for the structure.
501 returns Structure from Graphic3d
504 ---Purpose: Returns the structure containing the group <me>.
505 ---Category: Inquire methods
507 ----------------------------
508 -- Category: Private methods
509 ----------------------------
512 XMin, YMin, ZMin : out Real from Standard;
513 XMax, YMax, ZMax : out Real from Standard )
516 ---Purpose: Returns the extreme coordinates found in the group.
517 ---Warning: If the group <me> is empty then :
518 -- XMin = YMin = ZMin = RealFirst ().
519 -- XMax = YMax = ZMax = RealLast ().
520 ---Category: Private methods
525 ---Purpose: Calls the Update method of the StructureManager which
526 -- contains the associated Structure of the Group <me>.
527 ---Category: Private methods
529 SetClosed (me: mutable; theIsClosed : Boolean from Standard);
530 ---Purpose: Changes property shown that primitive arrays within this group form closed volume (do no contain open shells).
532 IsClosed (me) returns Boolean from Standard;
533 ---Purpose: Return true if primitive arrays within this graphic group form closed volume (do no contain open shells).
538 -- Class : Graphic3d_Group
540 -- Purpose : Declaration of variables specific to groups
543 -- Reminder : A group is defined in a structure
544 -- It acts as the smallest editable entity.
546 -- the state of the different contexts for primitives
547 myCBitFields : CBitFields4 from Graphic3d is protected;
549 -- the structure contains the group
550 myStructure : StructurePtr from Graphic3d is protected;
553 myBounds : BndBox4f from Graphic3d is protected;
555 -- Identifies group forming closed volume. Used to filter groups for back face culling and capping algorithms.
556 myIsClosed : Boolean from Standard is protected;
558 ContextLine : CAspectLine from Graphic3d is protected;
559 ContextFillArea : CAspectFillArea from Graphic3d is protected;
560 ContextMarker : CAspectMarker from Graphic3d is protected;
561 ContextText : CAspectText from Graphic3d is protected;
565 class Structure from Graphic3d