0022627: Change OCCT memory management defaults
[occt.git] / src / Select3D / Select3D_Projector.cdl
1 -- File:    Select3D_Projector.cdl
2 -- Created:    Thu Mar 12 13:32:28 1992
3 -- Author:    Christophe MARION
4 --        <cma@sdsun2> copie quasi exacte de HLRAlgo_Projector
5 ---Copyright:     Matra Datavision 1992
6
7 class Projector from Select3D inherits Transient from Standard
8     ---Purpose: A framework to define 3D projectors.
9     -- Projector provides services for projecting points from
10     -- world-coordinates to a viewing plane. Projection could be defined by
11     -- corresponding transformation, or coordinate system. The transformation
12     -- could be constructed for a view with transposed view transformation
13     -- matrix ( that represents view-orientation ), including, for perspective
14     -- view, focal distance ( distance from an eye to the view plane ) and
15     -- translational part that represents translation of focal point in
16     -- view-coordinate space. The Select3D_Projector class recognizes the
17     -- predefined set of popular projections: axonometric, top view, front
18     -- view and uses more efficient algorithm for projection computations.
19     -- User-defined transformation could be also defined in constructor.
20     -- Perspective projection consists of two separate parts, that are
21     -- composed together during computation: transformation component and
22     -- focale distance.
23
24 uses
25     Real    from Standard,
26     Boolean from Standard,
27     Trsf    from gp,
28     GTrsf   from gp,
29     Lin     from gp,
30     Pnt     from gp,
31     Vec     from gp,
32     Ax2     from gp,
33     Vec2d   from gp,
34     Pnt2d   from gp,
35     Box     from Bnd,
36     View    from V3d
37
38 raises
39     NoSuchObject from Standard
40
41 is
42
43     Create(aView:View from V3d) returns Projector from Select3D;
44     --- Purpose: Constructs the 3D projector object defined by the 3D view aView.
45     Create returns Projector from Select3D;
46
47     Create(CS : Ax2 from gp)
48     ---Purpose: Creates an axonometric projector. <CS> represents viewing coordinate 
49     -- system and could be constructed from x direction, view plane normal direction, 
50     -- and view point location in world-coordinate space.
51     returns Projector from Select3D;
52
53     Create(CS    : Ax2  from gp;
54            Focus : Real from Standard)
55     ---Purpose: Creates  a  perspective  projector. <CS> represents viewing
56     -- coordinate system and could be constructed from x direction, 
57     -- view plane normal direction, and focal point location in world-coordinate
58     -- space. <Focus> should represent distance of an eye from view plane
59     -- in world-coordinate space (focal distance).
60     returns Projector from Select3D;
61
62     Create(T         : Trsf    from gp;
63            Persp     : Boolean from Standard;
64            Focus     : Real    from Standard)
65     ---Purpose: build a Projector from the given transformation.
66     -- In case, when <T> transformation should represent custom view projection,
67     -- it could be constructed from two separate components: transposed view
68     -- orientation matrix and translation of focal point in view-coordiante
69     -- system. <T> could be built up from x direction, up direction,
70     -- view plane normal direction vectors and translation with SetValues(...)
71     -- method, where first row arguments (a11, a12, a13, a14)  are x, y, z
72     -- component of x direction vector, and x value of reversed translation
73     -- vector. Second row arguments, are x y z for up direction and y value of
74     -- reversed translation, and the third row defined in the same manner.
75     -- This also suits for simple perspective view, where <Focus> is the focale
76     -- distance of an eye from view plane in world-space coordiantes.
77     -- Note, that in that case amount of perspective distortion (perspective
78     -- angle) should be defined through focal distance.
79     returns Projector from Select3D;
80
81     Create(GT        : GTrsf   from gp;
82            Persp     : Boolean from Standard;
83            Focus     : Real    from Standard)
84     ---Purpose: build a Projector from the given transformation.
85     -- In case, when <GT> transformation should represent custom view
86     -- projection, it could be constructed from two separate components:
87     -- transposed view orientation matrix and translation of a focal point
88     -- in view-coordinate system.
89     -- This also suits for perspective view, with <Focus> that could be
90     -- equal to distance from an eye to a view plane in 
91     -- world-coordinates (focal distance).
92     -- The 3x3 transformation matrix is built up from three vectors:
93     -- x direction, up direction and view plane normal vectors, where each
94     -- vector is a matrix row. Then <GT> is constructed from matrix and
95     -- reversed translation with methods SetTranslationPart(..) and
96     -- SetVectorialPart(..).
97     -- Note, that in that case amount of perspective distortion (perspective
98     -- angle) should be defined through focal distance.
99     returns Projector from Select3D;
100
101     Set (me : mutable;
102          T         : Trsf    from gp;
103          Persp     : Boolean from Standard;
104          Focus     : Real    from Standard)
105     is static;
106
107     SetView(me : mutable; V : View from V3d);
108     ---Purpose: Sets the 3D view V used at the time of construction.
109
110     View(me) returns any View from V3d;
111     ---Purpose: Returns the 3D view used at the time of construction.
112     ---C++: return const&
113     ---C++: inline
114
115     Scaled(me : mutable; On : Boolean from Standard = Standard_False)
116     ---Purpose: to compute with the given scale and translation.
117     is virtual;
118
119     Perspective(me) returns Boolean
120     ---Purpose: Returns True if there is a perspective transformation.
121     ---C++: inline
122     is virtual;
123
124     Transformation(me) returns GTrsf from gp
125     ---Purpose: Returns the active transformation.
126     ---C++: inline
127     ---C++: return const &
128     is virtual;
129
130     InvertedTransformation(me) returns GTrsf from gp
131     ---Purpose: Returns the active inverted transformation.
132     ---C++: inline
133     ---C++: return const &
134     is virtual;
135
136     FullTransformation(me) returns Trsf from gp
137     ---Purpose: Returns the original transformation.
138     ---C++: inline
139     ---C++: return const &
140     is virtual;
141
142     Focus(me) returns Real from Standard
143     ---Purpose: Returns the focal length.
144     ---C++: inline
145     raises
146         NoSuchObject from Standard -- if there is no perspective
147     is virtual;
148
149     Transform(me; D : in out Vec from gp)
150     ---C++: inline
151     is virtual;
152
153     Transform(me; Pnt : in out Pnt from gp)
154         ---C++: inline
155     is virtual;
156
157     Project(me; P    :     Pnt   from gp;
158                 Pout : out Pnt2d from gp)
159     ---Purpose: Transform and apply perspective if needed.
160     is virtual;
161
162     Project(me; P     :     Pnt  from gp;
163                 X,Y,Z : out Real from Standard)
164     ---Purpose: Transform and apply perspective if needed.
165     is static;
166
167     Project(me; P     :     Pnt   from gp;
168                 D1    :     Vec   from gp;
169                 Pout  : out Pnt2d from gp;
170         D1out : out Vec2d from gp)
171     ---Purpose: Transform and apply perspective if needed.
172     is virtual;
173
174     Shoot(me; X , Y : Real from Standard)
175     returns Lin from gp
176     ---Purpose: return a line going through the eye towards the
177     --          2d point <X,Y>.
178     is virtual;
179
180     DepthMin(me) returns Real from Standard;
181     ---Purpose: Returns the minimum depth value (if clipping plane defined).
182     ---         Should be used when call ::Shoot() to compute eyeline.
183     ---C++: inline
184
185     DepthMax(me) returns Real from Standard;
186     ---Purpose: Returns the maximum depth value (if clipping plane defined).
187     ---         Should be used when call ::Shoot() to compute eyeline.
188     ---C++: inline
189
190     DepthMinMax(me : mutable;
191                 theDepthMin : in Real from Standard;
192                 theDepthMax : in Real from Standard);
193     ---Purpose: Setup the min/max depth values (doesn't affect
194     ---         projection functionality itself).
195     ---         Should be used when call ::Shoot() to compute eyeline.
196
197     Transform(me; P : in out Pnt from gp;
198                   T : GTrsf from gp)
199     ---C++: inline
200     is virtual;
201
202     Transform(me; D : in out Lin from gp;
203                   T : GTrsf from gp)
204     ---C++: inline
205     is virtual;
206
207 fields
208     myType       : Integer from Standard;
209
210     myPersp      : Boolean from Standard is protected;
211     myFocus      : Real    from Standard is protected;
212     myScaledTrsf : Trsf    from gp is protected;
213     myGTrsf      : GTrsf   from gp is protected;
214     myInvTrsf    : GTrsf   from gp is protected;
215
216     myView       : View    from V3d;
217     myDepthMin   : Real    from Standard;
218     myDepthMax   : Real    from Standard;
219
220 end Projector;