# lens.I

```00001 // Filename: lens.I
00002 // Created by:  drose (29Nov01)
00003 //
00004 ////////////////////////////////////////////////////////////////////
00005 //
00006 // PANDA 3D SOFTWARE
00008 //
00009 // All use of this software is subject to the terms of the revised BSD
00011 // with this source code in a file named "LICENSE."
00012 //
00013 ////////////////////////////////////////////////////////////////////
00014
00015
00016 ////////////////////////////////////////////////////////////////////
00017 //     Function: Lens::extrude
00018 //       Access: Published
00019 //  Description: Given a 2-d point in the range (-1,1) in both
00020 //               dimensions, where (0,0) is the center of the
00021 //               lens and (-1,-1) is the lower-left corner,
00022 //               compute the corresponding vector in space that maps
00023 //               to this point, if such a vector can be determined.
00024 //               The vector is returned by indicating the points on
00025 //               the near plane and far plane that both map to the
00026 //               indicated 2-d point.
00027 //
00028 //               Returns true if the vector is defined, or false
00029 //               otherwise.
00030 ////////////////////////////////////////////////////////////////////
00031 INLINE bool Lens::
00032 extrude(const LPoint2f &point2d, LPoint3f &near_point, LPoint3f &far_point) const {
00033   return extrude_impl(LPoint3f(point2d[0], point2d[1], 0.0f),
00034                       near_point, far_point);
00035 }
00036
00037 ////////////////////////////////////////////////////////////////////
00038 //     Function: Lens::extrude
00039 //       Access: Published
00040 //  Description: Given a 2-d point in the range (-1,1) in both
00041 //               dimensions, where (0,0) is the center of the
00042 //               lens and (-1,-1) is the lower-left corner,
00043 //               compute the corresponding vector in space that maps
00044 //               to this point, if such a vector can be determined.
00045 //               The vector is returned by indicating the points on
00046 //               the near plane and far plane that both map to the
00047 //               indicated 2-d point.
00048 //
00049 //               The z coordinate of the 2-d point is ignored.
00050 //
00051 //               Returns true if the vector is defined, or false
00052 //               otherwise.
00053 ////////////////////////////////////////////////////////////////////
00054 INLINE bool Lens::
00055 extrude(const LPoint3f &point2d, LPoint3f &near_point, LPoint3f &far_point) const {
00056   return extrude_impl(point2d, near_point, far_point);
00057 }
00058
00059 ////////////////////////////////////////////////////////////////////
00060 //     Function: Lens::extrude_vec
00061 //       Access: Published
00062 //  Description: Given a 2-d point in the range (-1,1) in both
00063 //               dimensions, where (0,0) is the center of the
00064 //               lens and (-1,-1) is the lower-left corner,
00065 //               compute the vector that corresponds to the view
00066 //               direction.  This will be parallel to the normal on
00067 //               the surface (the far plane) corresponding to the lens
00068 //               shape at this point.
00069 //
00070 //               See the comment block on Lens::extrude_vec_impl() for
00071 //               a more in-depth comment on the meaning of this
00072 //               vector.
00073 //
00074 //               Returns true if the vector is defined, or false
00075 //               otherwise.
00076 ////////////////////////////////////////////////////////////////////
00077 INLINE bool Lens::
00078 extrude_vec(const LPoint2f &point2d, LVector3f &vec) const {
00079   return extrude_vec_impl(LPoint3f(point2d[0], point2d[1], 0.0f), vec);
00080 }
00081
00082 ////////////////////////////////////////////////////////////////////
00083 //     Function: Lens::extrude_vec
00084 //       Access: Published
00085 //  Description: Given a 2-d point in the range (-1,1) in both
00086 //               dimensions, where (0,0) is the center of the
00087 //               lens and (-1,-1) is the lower-left corner,
00088 //               compute the vector that corresponds to the view
00089 //               direction.  This will be parallel to the normal on
00090 //               the surface (the far plane) corresponding to the lens
00091 //               shape at this point.
00092 //
00093 //               See the comment block on Lens::extrude_vec_impl() for
00094 //               a more in-depth comment on the meaning of this
00095 //               vector.
00096 //
00097 //               The z coordinate of the 2-d point is ignored.
00098 //
00099 //               Returns true if the vector is defined, or false
00100 //               otherwise.
00101 ////////////////////////////////////////////////////////////////////
00102 INLINE bool Lens::
00103 extrude_vec(const LPoint3f &point2d, LVector3f &vec) const {
00104   return extrude_vec_impl(point2d, vec);
00105 }
00106
00107 ////////////////////////////////////////////////////////////////////
00108 //     Function: Lens::project
00109 //       Access: Published
00110 //  Description: Given a 3-d point in space, determine the 2-d point
00111 //               this maps to, in the range (-1,1) in both dimensions,
00112 //               where (0,0) is the center of the lens and
00113 //               (-1,-1) is the lower-left corner.
00114 //
00115 //               Returns true if the 3-d point is in front of the lens
00116 //               and within the viewing frustum (in which case point2d
00117 //               is filled in), or false otherwise (in which case
00118 //               point2d will be filled in with something, which may
00119 //               or may not be meaningful).
00120 ////////////////////////////////////////////////////////////////////
00121 INLINE bool Lens::
00122 project(const LPoint3f &point3d, LPoint2f &point2d) const {
00123   LPoint3f result;
00124   bool okflag = project_impl(point3d, result);
00125   point2d.set(result[0], result[1]);
00126   return okflag;
00127 }
00128
00129 ////////////////////////////////////////////////////////////////////
00130 //     Function: Lens::project
00131 //       Access: Published
00132 //  Description: Given a 3-d point in space, determine the 2-d point
00133 //               this maps to, in the range (-1,1) in both dimensions,
00134 //               where (0,0) is the center of the lens and
00135 //               (-1,-1) is the lower-left corner.
00136 //
00137 //               The z coordinate will also be set to a value in the
00138 //               range (-1, 1), where 1 represents a point on the near
00139 //               plane, and -1 represents a point on the far plane.
00140 //
00141 //               Returns true if the 3-d point is in front of the lens
00142 //               and within the viewing frustum (in which case point2d
00143 //               is filled in), or false otherwise (in which case
00144 //               point2d will be filled in with something, which may
00145 //               or may not be meaningful).
00146 ////////////////////////////////////////////////////////////////////
00147 INLINE bool Lens::
00148 project(const LPoint3f &point3d, LPoint3f &point2d) const {
00149   return project_impl(point3d, point2d);
00150 }
00151
00152 ////////////////////////////////////////////////////////////////////
00153 //     Function: Lens::set_change_event
00154 //       Access: Published
00155 //  Description: Sets the name of the event that will be generated
00156 //               whenever any properties of the Lens have
00157 //               changed.  If this is not set for a particular lens,
00158 //               no event will be generated.
00159 //
00160 //               The event is thrown with one parameter, the lens
00161 //               itself.  This can be used to automatically track
00162 //               changes to camera fov, etc. in the application.
00163 ////////////////////////////////////////////////////////////////////
00164 INLINE void Lens::
00165 set_change_event(const string &event) {
00166   _change_event = event;
00167 }
00168
00169 ////////////////////////////////////////////////////////////////////
00170 //     Function: Lens::get_change_event
00171 //       Access: Published
00172 //  Description: Returns the name of the event that will be generated
00173 //               whenever any properties of this particular Lens have
00174 //               changed.
00175 ////////////////////////////////////////////////////////////////////
00176 INLINE const string &Lens::
00177 get_change_event() const {
00178   return _change_event;
00179 }
00180
00181 ////////////////////////////////////////////////////////////////////
00182 //     Function: Lens::get_coordinate_system
00183 //       Access: Published
00184 //  Description: Returns the coordinate system that all 3-d
00185 //               computations are performed within for this
00186 //               Lens.  Normally, this is CS_default.
00187 ////////////////////////////////////////////////////////////////////
00188 INLINE CoordinateSystem Lens::
00189 get_coordinate_system() const {
00190   return _cs;
00191 }
00192
00193 ////////////////////////////////////////////////////////////////////
00194 //     Function: Lens::set_film_size
00195 //       Access: Published
00196 //  Description: Sets the size and shape of the "film" within the
00197 //               lens.  This both establishes the units used by
00198 //               calls like set_focal_length(), and establishes the
00199 //               aspect ratio of the frame.
00200 //
00201 //               In a physical camera, the field of view of a lens is
00202 //               determined by the lens' focal length and by the size
00203 //               of the film area exposed by the lens.  For instance,
00204 //               a 35mm camera exposes a rectangle on the film about
00205 //               24mm x 36mm, which means a 50mm lens gives about a
00206 //               40-degree horizontal field of view.
00207 //
00208 //               In the virtual camera, you may set the film size to
00209 //               any units here, and specify a focal length in the
00210 //               same units to simulate the same effect.  Or, you may
00211 //               ignore this parameter, and specify the field of view
00212 //               and aspect ratio of the lens directly.
00213 ////////////////////////////////////////////////////////////////////
00214 INLINE void Lens::
00215 set_film_size(float width, float height) {
00216   set_film_size(LVecBase2f(width, height));
00217 }
00218
00219 ////////////////////////////////////////////////////////////////////
00220 //     Function: Lens::set_film_offset
00221 //       Access: Published
00222 //  Description: Sets the horizontal and vertical offset amounts of
00223 //               this Lens.  These are both in the same units
00224 //               specified in set_film_size().
00225 //
00226 //               This can be used to establish an off-axis lens.
00227 ////////////////////////////////////////////////////////////////////
00228 INLINE void Lens::
00229 set_film_offset(float x, float y) {
00230   set_film_offset(LVecBase2f(x, y));
00231 }
00232
00233 ////////////////////////////////////////////////////////////////////
00234 //     Function: Lens::set_film_offset
00235 //       Access: Published
00236 //  Description: Sets the horizontal and vertical offset amounts of
00237 //               this Lens.  These are both in the same units
00238 //               specified in set_film_size().
00239 //
00240 //               This can be used to establish an off-axis lens.
00241 ////////////////////////////////////////////////////////////////////
00242 INLINE void Lens::
00243 set_film_offset(const LVecBase2f &film_offset) {
00244   _film_offset = film_offset;
00246   throw_change_event();
00247 }
00248
00249 ////////////////////////////////////////////////////////////////////
00250 //     Function: Lens::get_film_offset
00251 //       Access: Published
00252 //  Description: Returns the horizontal and vertical offset amounts of
00253 //               this Lens.  See set_film_offset().
00254 ////////////////////////////////////////////////////////////////////
00255 INLINE const LVector2f &Lens::
00256 get_film_offset() const {
00257   return _film_offset;
00258 }
00259
00260 ////////////////////////////////////////////////////////////////////
00261 //     Function: Lens::set_fov
00262 //       Access: Published
00263 //  Description: Sets the field of view of the lens in both
00264 //               dimensions.  This establishes both the field of view
00265 //               and the aspect ratio of the lens.  This is one way to
00266 //               specify the field of view of a lens;
00267 //               set_focal_length() is another way.
00268 //
00269 //               For certain kinds of lenses (like OrthoLens),
00270 //               the field of view has no meaning.
00271 ////////////////////////////////////////////////////////////////////
00272 INLINE void Lens::
00273 set_fov(float hfov, float vfov) {
00274   set_fov(LVecBase2f(hfov, vfov));
00275 }
00276
00277 ////////////////////////////////////////////////////////////////////
00278 //     Function: Lens::get_hfov
00279 //       Access: Published
00280 //  Description: Returns the horizontal component of fov only.  See
00281 //               get_fov().
00282 ////////////////////////////////////////////////////////////////////
00283 INLINE float Lens::
00284 get_hfov() const {
00285   return get_fov()[0];
00286 }
00287
00288 ////////////////////////////////////////////////////////////////////
00289 //     Function: Lens::get_vfov
00290 //       Access: Published
00291 //  Description: Returns the vertical component of fov only.  See
00292 //               get_fov().
00293 ////////////////////////////////////////////////////////////////////
00294 INLINE float Lens::
00295 get_vfov() const {
00296   return get_fov()[1];
00297 }
00298
00299 ////////////////////////////////////////////////////////////////////
00300 //     Function: Lens::set_near
00301 //       Access: Published
00302 //  Description: Defines the position of the near plane (or cylinder,
00303 //               sphere, whatever).  Points closer to the lens than
00304 //               this may not be rendered.
00305 ////////////////////////////////////////////////////////////////////
00306 INLINE void Lens::
00307 set_near(float near_distance) {
00308   _near_distance = near_distance;
00310   throw_change_event();
00311 }
00312
00313 ////////////////////////////////////////////////////////////////////
00314 //     Function: Lens::get_near
00315 //       Access: Published
00316 //  Description: Returns the position of the near plane (or cylinder,
00317 //               sphere, whatever).
00318 ////////////////////////////////////////////////////////////////////
00319 INLINE float Lens::
00320 get_near() const {
00321   return _near_distance;
00322 }
00323
00324 ////////////////////////////////////////////////////////////////////
00325 //     Function: Lens::set_far
00326 //       Access: Published
00327 //  Description: Defines the position of the far plane (or cylinder,
00328 //               sphere, whatever).  Points farther from the lens than
00329 //               this may not be rendered.
00330 ////////////////////////////////////////////////////////////////////
00331 INLINE void Lens::
00332 set_far(float far_distance) {
00333   _far_distance = far_distance;
00335   throw_change_event();
00336 }
00337
00338 ////////////////////////////////////////////////////////////////////
00339 //     Function: Lens::get_far
00340 //       Access: Published
00341 //  Description: Returns the position of the far plane (or cylinder,
00342 //               sphere, whatever).
00343 ////////////////////////////////////////////////////////////////////
00344 INLINE float Lens::
00345 get_far() const {
00346   return _far_distance;
00347 }
00348
00349 ////////////////////////////////////////////////////////////////////
00350 //     Function: Lens::set_near_far
00351 //       Access: Published
00352 //  Description: Simultaneously changes the near and far planes.
00353 ////////////////////////////////////////////////////////////////////
00354 INLINE void Lens::
00355 set_near_far(float near_distance, float far_distance) {
00356   _near_distance = near_distance;
00357   _far_distance = far_distance;
00359   throw_change_event();
00360 }
00361
00362 ////////////////////////////////////////////////////////////////////
00363 //     Function: Lens::set_view_hpr
00364 //       Access: Published
00365 //  Description: Sets the direction in which the lens is facing.
00366 //               Normally, this is down the forward axis (usually the
00367 //               Y axis), but it may be rotated.  This is only one way
00368 //               of specifying the rotation; you may also specify an
00369 //               explicit vector in which to look, or you may give a
00370 //               complete transformation matrix.
00371 ////////////////////////////////////////////////////////////////////
00372 INLINE void Lens::
00373 set_view_hpr(float h, float p, float r) {
00374   set_view_hpr(LVecBase3f(h, p, r));
00375 }
00376 ////////////////////////////////////////////////////////////////////
00377 //     Function: Lens::set_view_vector
00378 //       Access: Published
00379 //  Description: Specifies the direction in which the lens is facing
00380 //               by giving an axis to look along, and a perpendicular
00381 //               (or at least non-parallel) up axis.
00382 //
00384 ////////////////////////////////////////////////////////////////////
00385 INLINE void Lens::
00386 set_view_vector(float x, float y, float z, float i, float j, float k) {
00387   set_view_vector(LVector3f(x, y, z), LVector3f(i, j, k));
00388 }
00389
00390 ////////////////////////////////////////////////////////////////////
00391 //     Function: Lens::get_keystone
00392 //       Access: Published
00393 //  Description: Returns the keystone correction specified for the
00394 //               lens.
00395 ////////////////////////////////////////////////////////////////////
00396 INLINE const LVecBase2f &Lens::
00397 get_keystone() const {
00398   return _keystone;
00399 }
00400
00401 ////////////////////////////////////////////////////////////////////
00402 //     Function: Lens::get_last_change
00403 //       Access: Public
00404 //  Description: Returns the UpdateSeq that is incremented whenever
00405 //               the lens properties are changed.  As long as this
00406 //               number remains the same, you may assume the lens
00407 //               properties are unchanged.
00408 ////////////////////////////////////////////////////////////////////
00410 get_last_change() const {
00411   return _last_change;
00412 }
00413
00414 ////////////////////////////////////////////////////////////////////
00416 //       Access: Protected
00417 //  Description: Clears from _user_flags the bits in the first
00418 //               parameter, and sets the bits in the second parameter.
00419 ////////////////////////////////////////////////////////////////////
00420 INLINE void Lens::
00421 adjust_user_flags(int clear_flags, int set_flags) {
00422   _user_flags = (_user_flags & ~clear_flags) | set_flags;
00423 }
00424
00425 ////////////////////////////////////////////////////////////////////
00427 //       Access: Protected
00428 //  Description: Clears from _comp_flags the bits in the first
00429 //               parameter, and sets the bits in the second parameter.
00430 ////////////////////////////////////////////////////////////////////
00431 INLINE void Lens::
00432 adjust_comp_flags(int clear_flags, int set_flags) {
00433   _comp_flags = (_comp_flags & ~clear_flags) | set_flags;
00434 }
00435
00436 INLINE ostream &
00437 operator << (ostream &out, const Lens &lens) {
00438   lens.output(out);
00439   return out;
00440 }
00441
```