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
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.
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.
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.
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
26 class Group from Graphic3d inherits TShared
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.
36 -- There are two main group usage models:
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.
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.
64 Array1OfInteger from TColStd,
65 Array1OfReal from TColStd,
66 HArray1OfByte from TColStd,
68 ExtendedString from TCollection,
70 PlaneAngle from Quantity,
72 Array1OfEdge from Aspect,
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,
86 Vector from Graphic3d,
87 Array1OfVertex from Graphic3d,
88 Array2OfVertex from Graphic3d,
89 Vertex from Graphic3d,
90 VerticalTextAlignment from Graphic3d,
91 ArrayOfPrimitives from Graphic3d,
92 ListOfPArray from Graphic3d,
93 TransModeFlags from Graphic3d,
94 CBounds from Graphic3d
98 GroupDefinitionError from Graphic3d,
99 PickIdDefinitionError from Graphic3d,
100 OutOfRange from Standard
103 Create ( AStructure : Structure from Graphic3d )
104 returns mutable 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 Destroy ( me : mutable )
128 ---Purpose: Supress the group <me> in the structure.
129 ---Category: Methods to modify the class definition
132 Remove ( me : mutable )
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
139 --SetTransformPersistence( me : mutable;
140 -- AFlag : TransModeFlags from Graphic3d )
142 ---Purpose: Modifies the current modelling transform persistence (pan, zoom or rotate)
145 --TransformPersistence( me )
146 -- returns TransModeFlags from Graphic3d
148 ---Purpose: Get the current modelling transform persistence (pan, zoom or rotate)
151 SetGroupPrimitivesAspect ( me : mutable )
154 ---Purpose: Removes the context for all the line primitives
156 ---Category: Methods to modify the class definition
158 SetGroupPrimitivesAspect ( me : mutable;
159 CTX : AspectLine3d from Graphic3d )
162 ---Purpose: Modifies the context for all the line primitives
164 ---Category: Methods to modify the class definition
166 SetGroupPrimitivesAspect ( me : mutable;
167 CTX : AspectFillArea3d from Graphic3d )
170 ---Purpose: Modifies the context for all the face primitives
172 ---Category: Methods to modify the class definition
174 SetGroupPrimitivesAspect ( me : mutable;
175 CTX : AspectText3d from Graphic3d )
178 ---Purpose: Modifies the context for all the text primitives
180 ---Category: Methods to modify the class definition
182 SetGroupPrimitivesAspect ( me : mutable;
183 CTX : AspectMarker3d from Graphic3d )
186 ---Purpose: Modifies the context for all the marker primitives
188 ---Category: Methods to modify the class definition
190 SetPrimitivesAspect ( me : mutable;
191 CTX : AspectLine3d from Graphic3d )
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
199 SetPrimitivesAspect ( me : mutable;
200 CTX : AspectFillArea3d from Graphic3d )
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
208 SetPrimitivesAspect ( me : mutable;
209 CTX : AspectText3d from Graphic3d )
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
217 SetPrimitivesAspect ( me : mutable;
218 CTX : AspectMarker3d from Graphic3d )
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
226 SetMinMaxValues ( me : mutable;
227 XMin, YMin, ZMin : Real from Standard;
228 XMax, YMax, ZMax : Real from Standard )
231 ---Purpose: Sets the coordinates of the boundary box of the
233 ---Category: Methods to modify the class definition
235 -----------------------------------
236 -- Category: Methods to create Text
237 -----------------------------------
239 --------------------------------------------
240 -- Summary of Texts --
242 -- Text has geometric and nongeometric --
245 -- The geometric text attributes are : --
247 -- Character Height. --
248 -- Character Up Vector. --
250 -- Text Alignment Horizontal. --
251 -- Text Alignment Vertical. --
253 -- The nongeometric text attributes are : --
256 -- Character Spacing. --
257 -- Character Expansion Factor. --
259 --------------------------------------------
262 AText : CString from Standard;
263 APoint : Vertex from Graphic3d;
264 AHeight : Real from Standard;
265 AAngle : PlaneAngle from Quantity;
266 ATp : TextPath from Graphic3d;
267 AHta : HorizontalTextAlignment from Graphic3d;
268 AVta : VerticalTextAlignment from Graphic3d;
269 EvalMinMax : Boolean from Standard = Standard_True )
272 ---Purpose: Creates the string <AText> at position <APoint>.
273 -- The 3D point of attachment is projected. The text is
274 -- written in the plane of projection.
275 -- The attributes are given with respect to the plane of
277 -- AHeight : Height of text.
278 -- (Relative to the Normalized Projection
279 -- Coordinates (NPC) Space).
280 -- AAngle : Orientation of the text
281 -- (with respect to the horizontal).
282 ---Category: Methods to create Text
285 AText : CString from Standard;
286 APoint : Vertex from Graphic3d;
287 AHeight : Real from Standard;
288 EvalMinMax : Boolean from Standard = Standard_True )
291 ---Purpose: Creates the string <AText> at position <APoint>.
292 -- The 3D point of attachment is projected. The text is
293 -- written in the plane of projection.
294 -- The attributes are given with respect to the plane of
296 -- AHeight : Height of text.
297 -- (Relative to the Normalized Projection
298 -- Coordinates (NPC) Space).
299 -- The other attributes have the following default values:
304 ---Category: Methods to create Text
307 AText : ExtendedString from TCollection;
308 APoint : Vertex from Graphic3d;
309 AHeight : Real from Standard;
310 AAngle : PlaneAngle from Quantity;
311 ATp : TextPath from Graphic3d;
312 AHta : HorizontalTextAlignment from Graphic3d;
313 AVta : VerticalTextAlignment from Graphic3d;
314 EvalMinMax : Boolean from Standard = Standard_True )
317 ---Purpose: Creates the string <AText> at position <APoint>.
318 -- The 3D point of attachment is projected. The text is
319 -- written in the plane of projection.
320 -- The attributes are given with respect to the plane of
322 -- AHeight : Height of text.
323 -- (Relative to the Normalized Projection
324 -- Coordinates (NPC) Space).
325 -- AAngle : Orientation of the text
326 -- (with respect to the horizontal).
327 ---Category: Methods to create Text
330 AText : ExtendedString from TCollection;
331 APoint : Vertex from Graphic3d;
332 AHeight : Real from Standard;
333 EvalMinMax : Boolean from Standard = Standard_True )
336 ---Purpose: Creates the string <AText> at position <APoint>.
337 -- The 3D point of attachment is projected. The text is
338 -- written in the plane of projection.
339 -- The attributes are given with respect to the plane of
341 -- AHeight : Height of text.
342 -- (Relative to the Normalized Projection
343 -- Coordinates (NPC) Space).
344 -- The other attributes have the following default values:
349 ---Category: Methods to create Text
351 ---------------------------------------
352 ---Category: Methods to create Triangle
353 ---------------------------------------
355 AddPrimitiveArray( me : mutable;
356 elem : ArrayOfPrimitives from Graphic3d;
357 EvalMinMax: Boolean from Standard = Standard_True );
359 ---Purpose: Adds an array of primitives for display
361 UserDraw ( me : mutable;
362 AnObject : Address from Standard;
363 EvalMinMax : Boolean from Standard = Standard_True;
364 ContainsFacet: Boolean from Standard = Standard_False
367 ---Purpose: Creates an UserDraw primitive
368 -- Category: Methods to create UserDraw
369 -- Warning: Raises GroupDefinitionError if ...
370 raises GroupDefinitionError from Graphic3d is static;
372 ----------------------------
373 -- Category: Inquire methods
374 ----------------------------
376 IsGroupPrimitivesAspectSet ( me;
377 theAspect : GroupAspect from Graphic3d )
378 returns Boolean from Standard
381 ---Purpose: Returns TRUE if aspect is set for the group.
382 ---Category: Inquire methods
384 GroupPrimitivesAspect ( me;
385 CTXL : AspectLine3d from Graphic3d;
386 CTXT : AspectText3d from Graphic3d;
387 CTXM : AspectMarker3d from Graphic3d;
388 CTXF : AspectFillArea3d from Graphic3d )
391 ---Purpose: Returns the context of all the primitives of the group.
392 ---Category: Inquire methods
394 PrimitivesAspect ( me;
395 CTXL : AspectLine3d from Graphic3d;
396 CTXT : AspectText3d from Graphic3d;
397 CTXM : AspectMarker3d from Graphic3d;
398 CTXF : AspectFillArea3d from Graphic3d )
401 ---Purpose: Returns the last inserted context in the group <me>
402 -- foreach kind of primitives.
403 ---Category: Inquire methods
406 returns Boolean from Standard
409 ---Purpose: Returns Standard_True if the group <me> contains
410 -- Polygons, Triangles or Quadrangles.
411 ---Category: Inquire methods
414 returns Boolean from Standard
417 ---Purpose: Returns Standard_True if the group <me> is deleted.
418 -- <me> is deleted after the call Remove (me) or the
419 -- associated structure is deleted.
420 ---Category: Inquire methods
423 returns Boolean from Standard
426 ---Purpose: Returns Standard_True if the group <me> is empty.
427 ---Warning: A group is empty if the MinMaxValues method returns :
428 -- XMin = YMin = ZMin = RealFirst ().
429 -- XMax = YMax = ZMax = RealLast ().
430 ---Category: Inquire methods
433 XMin, YMin, ZMin : out Real from Standard;
434 XMax, YMax, ZMax : out Real from Standard )
437 ---Purpose: Returns the coordinates of the boundary box of the
439 ---Warning: If the group <me> is empty then :
440 -- XMin = YMin = ZMin = RealFirst ().
441 -- XMax = YMax = ZMax = RealLast ().
442 ---Category: Inquire methods
445 returns mutable Structure from Graphic3d
448 ---Purpose: Returns the structure containing the group <me>.
449 ---Category: Inquire methods
451 ----------------------------
452 -- Category: Private methods
453 ----------------------------
456 XMin, YMin, ZMin : out Real from Standard;
457 XMax, YMax, ZMax : out Real from Standard )
460 ---Purpose: Returns the extreme coordinates found in the group.
461 ---Warning: If the group <me> is empty then :
462 -- XMin = YMin = ZMin = RealFirst ().
463 -- XMax = YMax = ZMax = RealLast ().
464 ---Category: Private methods
469 ---Purpose: Calls the Update method of the StructureManager which
470 -- contains the associated Structure of the Group <me>.
471 ---Category: Private methods
476 -- Class : Graphic3d_Group
478 -- Purpose : Declaration of variables specific to groups
481 -- Reminder : A group is defined in a structure
482 -- It acts as the smallest editable entity.
484 -- the associated C structure
485 MyCGroup : CGroup from Graphic3d;
487 -- the graphic driver used
488 MyGraphicDriver : GraphicDriver from Graphic3d;
490 -- the state of the different contexts for primitives
491 MyCBitFields : CBitFields4 from Graphic3d;
493 -- the structure contains the group
494 MyPtrStructure : Address from Standard;
497 MyBounds : CBounds from Graphic3d;
499 MyListOfPArray : ListOfPArray from Graphic3d;
501 MyMarkArray : HArray1OfByte from TColStd;
502 MyMarkWidth : Integer from Standard;
503 MyMarkHeight : Integer from Standard;
507 Remove from class Structure from Graphic3d
508 ( me : mutable; AGroup : Group from Graphic3d )