0024927: Getting rid of "Persistent" functionality -- Storable
[occt.git] / src / gp / gp_Vec.cdl
1 -- Copyright (c) 1991-1999 Matra Datavision
2 -- Copyright (c) 1999-2014 OPEN CASCADE SAS
3 --
4 -- This file is part of Open CASCADE Technology software library.
5 --
6 -- This library is free software; you can redistribute it and/or modify it under
7 -- the terms of the GNU Lesser General Public License version 2.1 as published
8 -- by the Free Software Foundation, with special exception defined in the file
9 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 -- distribution for complete text of the license and disclaimer of any warranty.
11 --
12 -- Alternatively, this file may be used under the terms of Open CASCADE
13 -- commercial license or contractual agreement.
14
15 class Vec   from gp
16
17         --- Purpose :
18         --  Defines a non-persistent vector in 3D space.
19
20
21 uses Ax1  from gp, 
22      Ax2  from gp, 
23      Dir  from gp, 
24      Pnt  from gp,
25      Trsf from gp,
26      XYZ  from gp
27
28 raises ConstructionError        from Standard,
29        DomainError              from Standard,
30        OutOfRange               from Standard,
31        VectorWithNullMagnitude  from gp
32
33 is
34  
35   Create   returns Vec;
36         ---C++: inline
37         --- Purpose : Creates a zero vector.
38
39
40   Create (V : Dir)  returns Vec;
41         ---C++: inline
42         --- Purpose : Creates a unitary vector from a direction V.
43
44   Create (Coord : XYZ)  returns Vec;
45         ---C++: inline
46         --- Purpose : Creates a vector with a triplet of coordinates.
47
48   Create (Xv, Yv, Zv : Real)  returns Vec;
49         ---C++: inline
50         --- Purpose : Creates a point with its three cartesian coordinates.
51
52   Create (P1, P2 : Pnt)  returns Vec;
53         ---C++: inline
54         --- Purpose :
55         --  Creates a vector from two points. The length of the vector
56         --  is the distance between P1 and P2
57
58   SetCoord(me: in out; Index : Integer; Xi : Real)
59         ---C++: inline
60         --- Purpose : Changes the coordinate of range Index 
61         --  Index = 1 => X is modified
62         --  Index = 2 => Y is modified
63         --  Index = 3 => Z is modified
64      raises OutOfRange
65         --- Purpose : Raised if Index != {1, 2, 3}.
66      is static;
67
68   SetCoord (me : in out; Xv, Yv, Zv : Real)   is static;
69         ---C++: inline  
70         ---Purpose: For this vector, assigns
71         -- -   the values Xv, Yv and Zv to its three coordinates.
72
73   SetX (me: in out; X : Real)                 is static;
74         ---Purpose: Assigns the given value to the X coordinate of this vector.
75         ---C++: inline
76         
77   SetY (me: in out; Y : Real)                 is static;
78         ---Purpose: Assigns the given value to the X coordinate of this vector.  
79         ---C++: inline
80         
81   SetZ (me: in out; Z : Real)                 is static;
82          ---Purpose: Assigns the given value to the X coordinate of this vector. 
83         ---C++: inline
84         
85   SetXYZ (me: in out; Coord : XYZ)            is static;
86         ---Purpose: Assigns the three coordinates of Coord to this vector.
87         ---C++: inline
88         
89   Coord (me; Index : Integer)   returns Real
90         ---C++: inline
91         --- Purpose :
92         --  Returns the coordinate of range Index :
93         --  Index = 1 => X is returned
94         --  Index = 2 => Y is returned
95         --  Index = 3 => Z is returned
96       raises OutOfRange
97         --- Purpose : Raised if Index != {1, 2, 3}.
98       is static;
99
100   Coord (me; Xv, Yv, Zv : out Real)   is static;
101         ---Purpose: For this vector returns its three coordinates Xv, Yv, and Zvinline
102         ---C++: inline
103         
104   X (me)  returns Real                is static;
105         ---Purpose: For this vector, returns its X coordinate.
106         ---C++: inline
107         
108   Y (me)  returns Real                is static;
109         ---Purpose: For this vector, returns its Y coordinate.
110         ---C++: inline 
111         
112   Z (me)  returns Real                is static;
113         ---Purpose: For this vector, returns its Z  coordinate.
114         ---C++: inline   
115         
116   XYZ (me)  returns XYZ               is static;
117         ---Purpose:    For this vector, returns
118         -- -   its three coordinates as a number triple  
119         ---C++: inline
120         ---C++: return const&
121  
122   IsEqual (me; Other : Vec; LinearTolerance, AngularTolerance : Real)
123      returns Boolean
124        --- Purpose :
125        --  Returns True if the two vectors have the same magnitude value
126        --  and the same direction. The precision values are LinearTolerance
127        --  for the magnitude and AngularTolerance for the direction.
128      is static;
129
130   IsNormal (me; Other : Vec; AngularTolerance : Real)     returns Boolean
131         --- Purpose :
132         --  Returns True if abs(<me>.Angle(Other) - PI/2.) <= AngularTolerance 
133         --   Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
134         --  Other.Magnitude() <= Resolution from gp
135         ---C++: inline  
136      raises VectorWithNullMagnitude
137      
138      is static;
139
140   IsOpposite (me; Other : Vec; AngularTolerance : Real)   returns Boolean
141         --- Purpose :
142         --  Returns True if PI - <me>.Angle(Other) <= AngularTolerance 
143         --  Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
144         --  Other.Magnitude() <= Resolution from gp
145         ---C++: inline    
146      raises VectorWithNullMagnitude
147       
148      is static;
149      
150   IsParallel (me; Other : Vec; AngularTolerance : Real)   returns Boolean
151         --- Purpose :
152         --  Returns True if Angle(<me>, Other) <= AngularTolerance or
153         --  PI - Angle(<me>, Other) <= AngularTolerance
154         --  This definition means that two parallel vectors cannot define
155         --  a plane but two vectors with opposite directions are considered
156         --  as parallel. Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution or
157         --  Other.Magnitude() <= Resolution from gp
158         ---C++: inline  
159      raises VectorWithNullMagnitude
160      
161      is static;
162      
163   Angle (me; Other : Vec)  returns Real
164         --- Purpose :
165         --  Computes the angular value between <me> and <Other>
166         --  Returns the angle value between 0 and PI in radian.
167         --    Raises VectorWithNullMagnitude if <me>.Magnitude() <= Resolution from gp or
168         --  Other.Magnitude() <= Resolution because the angular value is
169         --  indefinite if one of the vectors has a null magnitude.
170         ---C++: inline  
171      raises VectorWithNullMagnitude
172        
173      is static;
174
175
176   AngleWithRef (me; Other , VRef : Vec)   returns Real
177         ---C++: inline  
178         --- Purpose : Computes the angle, in radians, between this vector and
179         -- vector Other. The result is a value between -Pi and Pi.
180         -- For this, VRef defines the positive sense of rotation: the
181         -- angular value is positive, if the cross product this ^ Other
182         -- has the same orientation as VRef relative to the plane
183         -- defined by the vectors this and Other. Otherwise, the
184         -- angular value is negative.
185         -- Exceptions
186         -- gp_VectorWithNullMagnitude if the magnitude of this
187         -- vector, the vector Other, or the vector VRef is less than or
188         -- equal to gp::Resolution().
189         -- Standard_DomainError if this vector, the vector Other,
190         -- and the vector VRef are coplanar, unless this vector and
191         -- the vector Other are parallel.
192        
193      raises VectorWithNullMagnitude,
194           
195             DomainError
196        
197      is static;
198
199   Magnitude (me)   returns Real        is static;
200         ---Purpose: Computes the magnitude of this vector.
201         ---C++: inline
202         
203   SquareMagnitude (me)   returns Real  is static;
204          ---Purpose: Computes the square magnitude of this vector.
205          ---C++: inline
206
207         --- Purpose : Adds two vectors
208
209   Add (me : in out; Other : Vec)          is static;
210         ---C++: inline
211         ---C++: alias operator +=
212
213   Added (me; Other : Vec)  returns Vec    is static;
214         ---C++: inline
215         ---C++: alias operator +
216   --- Purpose : Adds two vectors
217         --- Purpose : Subtracts two vectors
218
219   Subtract (me : in out; Right : Vec)       is static;
220         ---C++: inline
221         ---C++: alias operator -=
222
223   Subtracted (me; Right : Vec)  returns Vec  is static;
224         ---C++: inline
225         ---C++: alias operator -
226         --- Purpose : Subtracts two vectors
227         --- Purpose : Multiplies a vector by a scalar
228
229   Multiply (me : in out; Scalar : Real)           is static;
230         ---C++: inline  
231         ---C++: alias operator *=
232
233   Multiplied (me; Scalar : Real)   returns Vec   is static;
234         ---C++: inline  
235         ---C++: alias operator *
236     --- Purpose : Multiplies a vector by a scalar
237         --- Purpose : Divides a vector by a scalar
238
239   Divide (me : in out; Scalar : Real)             is static;
240         ---C++: inline  
241         ---C++: alias operator /=
242
243   Divided (me; Scalar : Real)   returns Vec      is static;
244         ---C++: inline  
245         ---C++: alias operator /
246         --- Purpose : Divides a vector by a scalar
247
248         --- Purpose : computes the cross product between two vectors
249    
250   Cross (me : in out; Right : Vec)                     is static;
251         ---C++: inline  
252         ---C++: alias operator ^=
253
254   Crossed (me; Right : Vec)  returns Vec               is static;
255         --- Purpose : computes the cross product between two vectors
256         ---C++: inline  
257         ---C++: alias operator ^
258         
259   CrossMagnitude (me; Right : Vec) returns Real        is static;
260         --- Purpose :
261         --  Computes the magnitude of the cross 
262         --  product between <me> and Right. 
263         --  Returns || <me> ^ Right ||
264         ---C++: inline
265         
266   CrossSquareMagnitude (me; Right : Vec) returns Real  is static;
267         --- Purpose :
268         --  Computes the square magnitude of
269         --  the cross product between <me> and Right.
270         --  Returns || <me> ^ Right ||**2
271         ---C++: inline
272
273         --- Purpose : Computes the triple vector product.
274         --  <me> ^ (V1 ^ V2)
275
276   CrossCross (me : in out; V1, V2 : Vec)          is static;
277         ---C++: inline  
278
279   CrossCrossed (me; V1, V2 : Vec)   returns Vec   is static;
280         ---C++: inline  
281
282         --- Purpose : Computes the triple vector product.
283         --  <me> ^ (V1 ^ V2)
284     
285   Dot (me; Other : Vec)  returns Real            is static;
286         ---C++: inline  
287         ---C++: alias operator *
288         --- Purpose : computes the scalar product
289
290   DotCross (me; V1, V2 : Vec)  returns Real      is static;
291         ---C++: inline  
292         --- Purpose : Computes the triple scalar product <me> * (V1 ^ V2).
293
294
295         --- Purpose : normalizes a vector
296         --  Raises an exception if the magnitude of the vector is 
297         --  lower or equal to Resolution from gp.
298
299   Normalize (me : in out)       raises ConstructionError   is static;
300         ---C++: inline  
301
302   Normalized (me)  returns Vec  raises ConstructionError   is static;
303         --- Purpose : normalizes a vector
304         --  Raises an exception if the magnitude of the vector is 
305         --  lower or equal to Resolution from gp.
306         ---C++: inline
307         
308         --- Purpose : Reverses the direction of a vector
309
310   Reverse (me : in out)        is static;
311         ---C++: inline  
312
313   Reversed (me)  returns Vec   is static;
314         --- Purpose : Reverses the direction of a vector
315         ---C++: inline  
316         ---C++: alias operator -
317
318    SetLinearForm (me : in out;
319                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec;
320                  A3 : Real; V3 : Vec; V4 : Vec)
321      is static;
322         --- Purpose :
323         --  <me> is setted to the following linear form :
324         --  A1 * V1 + A2 * V2 + A3 * V3 + V4
325         ---C++: inline
326
327   SetLinearForm (me : in out; 
328                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec; A3 : Real; V3 : Vec)
329      is static;
330         --- Purpose :
331         --  <me> is setted to the following linear form :
332         --  A1 * V1 + A2 * V2 + A3 * V3
333         ---C++: inline
334
335   SetLinearForm (me : in out;
336                  A1 : Real; V1 : Vec; A2 : Real; V2 : Vec; V3 : Vec)
337      is static;
338         --- Purpose :
339         --  <me> is setted to the following linear form :
340         --  A1 * V1 + A2 * V2 + V3
341         ---C++: inline
342
343   SetLinearForm (me : in out; A1 : Real; V1 : Vec; A2 : Real; V2 : Vec)
344      is static;
345         --- Purpose :
346         --  <me> is setted to the following linear form :
347         --  A1 * V1 + A2 * V2
348         ---C++: inline
349
350   SetLinearForm (me : in out; A1 : Real; V1, V2 : Vec)
351      is static;
352         --- Purpose :
353         --  <me> is setted to the following linear form : A1 * V1 + V2
354         ---C++: inline
355
356   SetLinearForm (me : in out; V1, V2 : Vec)
357      is static;
358         --- Purpose :
359         --  <me> is setted to the following linear form : V1 + V2
360         ---C++: inline 
361
362   Mirror (me : in out; V : Vec)          is static;
363
364   Mirrored (me; V : Vec) returns Vec     is static;
365         --- Purpose :
366         --  Performs the symmetrical transformation of a vector
367         --  with respect to the vector V which is the center of 
368         --  the  symmetry.
369        
370   Mirror (me : in out; A1 : Ax1)         is static;
371
372   Mirrored (me; A1 : Ax1)  returns Vec   is static;
373         --- Purpose :
374         --  Performs the symmetrical transformation of a vector
375         --  with respect to an axis placement which is the axis
376         --  of the symmetry.
377       
378   Mirror (me : in out; A2 : Ax2)         is static;
379
380   Mirrored (me; A2 : Ax2)   returns Vec  is static;
381  --- Purpose :
382         --  Performs the symmetrical transformation of a vector
383         --  with respect to a plane. The axis placement A2 locates 
384         --  the plane of the symmetry : (Location, XDirection, YDirection).
385
386      
387   Rotate (me : in out; A1 : Ax1; Ang : Real)       is static;
388        ---C++: inline
389
390   Rotated (me; A1 : Ax1; Ang : Real)  returns Vec  is static;
391         --- Purpose :
392         --  Rotates a vector. A1 is the axis of the rotation.
393         --  Ang is the angular value of the rotation in radians.
394         ---C++: inline
395        
396     Scale (me : in out; S : Real)       is static;
397        ---C++: inline
398        
399     Scaled (me; S : Real)  returns Vec  is static;
400         --- Purpose : Scales a vector. S is the scaling value.
401         ---C++: inline
402         --- Purpose : Transforms a vector with the transformation T.
403
404   Transform (me : in out; T : Trsf)         is static;
405
406   Transformed (me; T : Trsf)   returns Vec  is static;
407        ---C++: inline  
408        --- Purpose : Transforms a vector with the transformation T.      
409 fields
410
411   coord : XYZ;
412
413 end;