0025624: Visualization - selection is incorrect in perspective mode in a specific...
[occt.git] / src / Select3D / Select3D_Projector.cdl
CommitLineData
b311480e 1-- Created on: 1992-03-12
2-- Created by: Christophe MARION
3-- Copyright (c) 1992-1999 Matra Datavision
973c2be1 4-- Copyright (c) 1999-2014 OPEN CASCADE SAS
b311480e 5--
973c2be1 6-- This file is part of Open CASCADE Technology software library.
b311480e 7--
d5f74e42 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
973c2be1 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.
b311480e 13--
973c2be1 14-- Alternatively, this file may be used under the terms of Open CASCADE
15-- commercial license or contractual agreement.
b311480e 16
4952a30a 17-- <cma@sdsun2> copie quasi exacte de HLRAlgo_Projector
4952a30a 18
19class Projector from Select3D inherits Transient from Standard
20 ---Purpose: A framework to define 3D projectors.
b0f0bd0c
A
21 -- Projector provides services for projecting points from
22 -- world-coordinates to a viewing plane. Projection could be defined by
23 -- corresponding transformation, or coordinate system. The transformation
24 -- could be constructed for a view with transposed view transformation
25 -- matrix ( that represents view-orientation ), including, for perspective
26 -- view, focal distance ( distance from an eye to the view plane ) and
27 -- translational part that represents translation of focal point in
28 -- view-coordinate space. The Select3D_Projector class recognizes the
29 -- predefined set of popular projections: axonometric, top view, front
30 -- view and uses more efficient algorithm for projection computations.
31 -- User-defined transformation could be also defined in constructor.
32 -- Perspective projection consists of two separate parts, that are
33 -- composed together during computation: transformation component and
34 -- focale distance.
35
7fd59977 36uses
37 Real from Standard,
38 Boolean from Standard,
4952a30a 39 Trsf from gp,
7fd59977 40 GTrsf from gp,
41 Lin from gp,
42 Pnt from gp,
43 Vec from gp,
44 Ax2 from gp,
45 Vec2d from gp,
46 Pnt2d from gp,
47 Box from Bnd,
197ac94e 48 View from V3d,
49 Mat4 from Graphic3d,
50 Mat4d from Graphic3d
4952a30a 51
7fd59977 52raises
53 NoSuchObject from Standard
54
55is
56
197ac94e 57 Create (theView : View from V3d) returns Projector from Select3D;
58 --- Purpose: Constructs the 3D projector object from the passed view.
59 -- The projector captures current model-view and projection transformation
60 -- of the passed view.
7fd59977 61
197ac94e 62 Create returns Projector from Select3D;
63 --- Purpose: Constructs identity projector.
64
65 Create (theCS : Ax2 from gp)
66 ---Purpose: Builds the Projector from the model-view transformation specified
67 -- by the passed viewing coordinate system <theCS>. The Projector has
68 -- identity projection transformation, is orthogonal.
69 -- The viewing coordinate system could be constructed from x direction,
70 -- view plane normal direction, and view point location in
71 -- world-coordinate space.
7fd59977 72 returns Projector from Select3D;
73
197ac94e 74 Create (theCS : Ax2 from gp;
75 theFocus : Real from Standard)
76 ---Purpose: Builds the Projector from the model-view transformation specified
77 -- by the passed view coordinate system <theCS> and simplified perspective
78 -- projection transformation defined by <theFocus> parameter.
79 -- The viewing coordinate system could be constructed from x direction,
b0f0bd0c 80 -- view plane normal direction, and focal point location in world-coordinate
197ac94e 81 -- space. <theFocus> should represent distance of an eye from view plane
b0f0bd0c 82 -- in world-coordinate space (focal distance).
7fd59977 83 returns Projector from Select3D;
84
197ac94e 85 Create (theViewTrsf : Trsf from gp;
86 theIsPersp : Boolean from Standard;
87 theFocus : Real from Standard)
88 ---Purpose: Build the Projector from the model-view transformation passed
89 -- as <theViewTrsf> and simplified perspective projection transformation
90 -- parameters passed as <theIsPersp> and <theFocus>.
91 -- In case, when <theViewTrsf> transformation should represent custom view
92 -- projection, it could be constructed from two separate components:
93 -- transposed view orientation matrix and translation of focal point
94 -- in view-coordinate system.
95 -- <theViewTrsf> could be built up from x direction, up direction,
b0f0bd0c
A
96 -- view plane normal direction vectors and translation with SetValues(...)
97 -- method, where first row arguments (a11, a12, a13, a14) are x, y, z
98 -- component of x direction vector, and x value of reversed translation
99 -- vector. Second row arguments, are x y z for up direction and y value of
100 -- reversed translation, and the third row defined in the same manner.
197ac94e 101 -- This also suits for simple perspective view, where <theFocus> is the focale
102 -- distance of an eye from view plane in world-space coordinates.
b0f0bd0c
A
103 -- Note, that in that case amount of perspective distortion (perspective
104 -- angle) should be defined through focal distance.
7fd59977 105 returns Projector from Select3D;
4952a30a 106
197ac94e 107 Create (theViewTrsf : GTrsf from gp;
108 theIsPersp : Boolean from Standard;
109 theFocus : Real from Standard)
110 ---Purpose: Builds the Projector from the model-view transformation passed
111 -- as <theViewTrsf> and projection transformation for <theIsPersp> and
112 -- <theFocus> parameters.
113 -- In case, when <theViewTrsf> transformation should represent custom view
b0f0bd0c
A
114 -- projection, it could be constructed from two separate components:
115 -- transposed view orientation matrix and translation of a focal point
116 -- in view-coordinate system.
197ac94e 117 -- This also suits for perspective view, with <theFocus> that could be
b0f0bd0c
A
118 -- equal to distance from an eye to a view plane in
119 -- world-coordinates (focal distance).
120 -- The 3x3 transformation matrix is built up from three vectors:
121 -- x direction, up direction and view plane normal vectors, where each
197ac94e 122 -- vector is a matrix row. Then <theViewTrsf> is constructed from matrix and
b0f0bd0c
A
123 -- reversed translation with methods SetTranslationPart(..) and
124 -- SetVectorialPart(..).
125 -- Note, that in that case amount of perspective distortion (perspective
126 -- angle) should be defined through focal distance.
7fd59977 127 returns Projector from Select3D;
128
197ac94e 129 Create (theViewTrsf : Mat4d from Graphic3d;
42b96b07 130 theProjTrsf : Mat4d from Graphic3d;
131 theZNear : Real from Standard = 0.0;
132 theZFar : Real from Standard = 10.0)
197ac94e 133 ---Purpose: Builds the Projector from the passed model-view <theViewTrsf>
42b96b07 134 -- and projection <theProjTrsf> transformation matrices. Parameters <theZNear>
135 -- and <theZFar> are passed to define view frustum depth for further projection
136 -- line computation using perspective projection.
197ac94e 137 returns Projector from Select3D;
138
4952a30a 139 Set (me : mutable;
197ac94e 140 theViewTrsf : Trsf from gp;
141 theIsPersp : Boolean from Standard;
142 theFocus : Real from Standard);
143 ---Purpose: Sets new parameters for the Projector.
7fd59977 144
197ac94e 145 Set (me : mutable;
146 theViewTrsf : Mat4d from Graphic3d;
42b96b07 147 theProjTrsf : Mat4d from Graphic3d;
148 theZNear : Real from Standard;
149 theZFar : Real from Standard);
197ac94e 150 ---Purpose: Sets new parameters for the Projector.
151
152 SetView (me : mutable;
153 theView : View from V3d);
154 ---Purpose: Sets new parameters for the Projector
155 -- captured from the passed view.
156
157 Scaled (me : mutable; theToCheckOptimized : Boolean from Standard = Standard_False)
158 ---Purpose: Pre-compute inverse transformation and ensure whether it is possible
159 -- to use optimized transformation for the common view-orientation type or not
160 -- if <theToCheckOptimized> is TRUE.
161 is virtual;
7fd59977 162
197ac94e 163 Perspective (me) returns Boolean
164 ---Purpose: Returns True if there is simplified perspective
165 -- projection approach is used. Distortion defined by Focus.
4952a30a 166 ---C++: inline
7fd59977 167 is virtual;
168
197ac94e 169 Focus (me) returns Real from Standard
170 ---Purpose: Returns the focal length of simplified perspective
171 -- projection approach. Raises program error exception if the
172 -- the projection transformation is not specified as simplified
173 -- Perspective (for example, custom projection transformation is defined
174 -- or the orthogonal Projector is defined).
4952a30a 175 ---C++: inline
7fd59977 176 is virtual;
177
197ac94e 178 Projection (me) returns Mat4d from Graphic3d;
179 ---Purpose: Returns projection transformation. Please note that for
180 -- simplified perspective projection approach, defined by Focus, the
181 -- returned transformation is identity.
4952a30a 182 ---C++: inline
183 ---C++: return const &
7fd59977 184
197ac94e 185 Transformation (me) returns GTrsf from gp
186 ---Purpose: Returns the view transformation.
4952a30a 187 ---C++: inline
188 ---C++: return const &
7fd59977 189 is virtual;
190
197ac94e 191 InvertedTransformation (me) returns GTrsf from gp
192 ---Purpose: Returns the inverted view transformation.
4952a30a 193 ---C++: inline
194 ---C++: return const &
7fd59977 195 is virtual;
196
197ac94e 197 FullTransformation (me) returns Trsf from gp
198 ---Purpose: Returns the uniform-scaled view transformation.
4952a30a 199 ---C++: inline
197ac94e 200 ---C++: return const &
7fd59977 201 is virtual;
4952a30a 202
197ac94e 203 Transform (me; theD : in out Vec from gp)
204 ---Purpose: Transforms the vector into view-coordinate space.
4952a30a 205 ---C++: inline
7fd59977 206 is virtual;
207
197ac94e 208 Transform (me; thePnt : in out Pnt from gp)
209 ---Purpose: Transforms the point into view-coordinate space.
210 ---C++: inline
7fd59977 211 is virtual;
4952a30a 212
197ac94e 213 Project (me; theP : Pnt from gp; thePout : out Pnt2d from gp)
214 ---Purpose: Transforms the point into view-coordinate space
215 -- and applies projection transformation.
7fd59977 216 is virtual;
4952a30a 217
197ac94e 218 Project (me; theP : Pnt from gp; theX, theY, theZ : out Real from Standard)
219 ---Purpose: Transforms the point into view-coordinate space
220 -- and applies projection transformation.
7fd59977 221 is static;
4952a30a 222
197ac94e 223 Project (me; theP : Pnt from gp;
224 theD1 : Vec from gp;
225 thePout : out Pnt2d from gp;
226 theD1out : out Vec2d from gp)
227 ---Purpose: Transforms the point and vector passed from its location
228 -- into view-coordinate space and applies projection transformation.
7fd59977 229 is virtual;
4952a30a 230
197ac94e 231 Shoot (me; theX, theY : Real from Standard) returns Lin from gp
232 ---Purpose: Return projection line going through the 2d point <theX, theY>
4952a30a 233 is virtual;
234
197ac94e 235 Transform(me; thePnt : in out Pnt from gp;
236 theTrsf : GTrsf from gp)
4952a30a 237 ---C++: inline
7fd59977 238 is virtual;
239
197ac94e 240 Transform(me; theLin : in out Lin from gp;
241 theTrsf : GTrsf from gp)
4952a30a 242 ---C++: inline
7fd59977 243 is virtual;
244
245fields
4952a30a 246
197ac94e 247 myType : Integer from Standard;
7fd59977 248 myPersp : Boolean from Standard is protected;
249 myFocus : Real from Standard is protected;
7fd59977 250 myGTrsf : GTrsf from gp is protected;
251 myInvTrsf : GTrsf from gp is protected;
197ac94e 252 myScaledTrsf : Trsf from gp is protected;
253 myProjTrsf : Mat4d from Graphic3d is protected;
42b96b07 254 myZNear : Real from Standard is protected;
255 myZFar : Real from Standard is protected;
7fd59977 256
257end Projector;