Panda3D
 All Classes Functions Variables Enumerations
lens.I
1 // Filename: lens.I
2 // Created by: drose (29Nov01)
3 //
4 ////////////////////////////////////////////////////////////////////
5 //
6 // PANDA 3D SOFTWARE
7 // Copyright (c) Carnegie Mellon University. All rights reserved.
8 //
9 // All use of this software is subject to the terms of the revised BSD
10 // license. You should have received a copy of this license along
11 // with this source code in a file named "LICENSE."
12 //
13 ////////////////////////////////////////////////////////////////////
14 
15 
16 ////////////////////////////////////////////////////////////////////
17 // Function: Lens::extrude
18 // Access: Published
19 // Description: Given a 2-d point in the range (-1,1) in both
20 // dimensions, where (0,0) is the center of the
21 // lens and (-1,-1) is the lower-left corner,
22 // compute the corresponding vector in space that maps
23 // to this point, if such a vector can be determined.
24 // The vector is returned by indicating the points on
25 // the near plane and far plane that both map to the
26 // indicated 2-d point.
27 //
28 // Returns true if the vector is defined, or false
29 // otherwise.
30 ////////////////////////////////////////////////////////////////////
31 INLINE bool Lens::
32 extrude(const LPoint2 &point2d, LPoint3 &near_point, LPoint3 &far_point) const {
33  CDReader cdata(_cycler);
34  return do_extrude(cdata, LPoint3(point2d[0], point2d[1], 0.0f),
35  near_point, far_point);
36 }
37 
38 ////////////////////////////////////////////////////////////////////
39 // Function: Lens::extrude
40 // Access: Published
41 // Description: Given a 2-d point in the range (-1,1) in both
42 // dimensions, where (0,0) is the center of the
43 // lens and (-1,-1) is the lower-left corner,
44 // compute the corresponding vector in space that maps
45 // to this point, if such a vector can be determined.
46 // The vector is returned by indicating the points on
47 // the near plane and far plane that both map to the
48 // indicated 2-d point.
49 //
50 // The z coordinate of the 2-d point is ignored.
51 //
52 // Returns true if the vector is defined, or false
53 // otherwise.
54 ////////////////////////////////////////////////////////////////////
55 INLINE bool Lens::
56 extrude(const LPoint3 &point2d, LPoint3 &near_point, LPoint3 &far_point) const {
57  CDReader cdata(_cycler);
58  return do_extrude(cdata, point2d, near_point, far_point);
59 }
60 
61 ////////////////////////////////////////////////////////////////////
62 // Function: Lens::extrude_depth
63 // Access: Published
64 // Description: Uses the depth component of the 3-d result from
65 // project() to compute the original point in 3-d space
66 // corresponding to a particular point on the lens.
67 // This exactly reverses project(), assuming the point
68 // does fall legitimately within the lens.
69 ////////////////////////////////////////////////////////////////////
70 INLINE bool Lens::
71 extrude_depth(const LPoint3 &point2d, LPoint3 &point3d) const {
72  CDReader cdata(_cycler);
73  return do_extrude_depth(cdata, point2d, point3d);
74 }
75 
76 ////////////////////////////////////////////////////////////////////
77 // Function: Lens::extrude_vec
78 // Access: Published
79 // Description: Given a 2-d point in the range (-1,1) in both
80 // dimensions, where (0,0) is the center of the
81 // lens and (-1,-1) is the lower-left corner,
82 // compute the vector that corresponds to the view
83 // direction. This will be parallel to the normal on
84 // the surface (the far plane) corresponding to the lens
85 // shape at this point.
86 //
87 // See the comment block on Lens::extrude_vec_impl() for
88 // a more in-depth comment on the meaning of this
89 // vector.
90 //
91 // Returns true if the vector is defined, or false
92 // otherwise.
93 ////////////////////////////////////////////////////////////////////
94 INLINE bool Lens::
95 extrude_vec(const LPoint2 &point2d, LVector3 &vec) const {
96  CDReader cdata(_cycler);
97  return do_extrude_vec(cdata, LPoint3(point2d[0], point2d[1], 0.0f), vec);
98 }
99 
100 ////////////////////////////////////////////////////////////////////
101 // Function: Lens::extrude_vec
102 // Access: Published
103 // Description: Given a 2-d point in the range (-1,1) in both
104 // dimensions, where (0,0) is the center of the
105 // lens and (-1,-1) is the lower-left corner,
106 // compute the vector that corresponds to the view
107 // direction. This will be parallel to the normal on
108 // the surface (the far plane) corresponding to the lens
109 // shape at this point.
110 //
111 // See the comment block on Lens::extrude_vec_impl() for
112 // a more in-depth comment on the meaning of this
113 // vector.
114 //
115 // The z coordinate of the 2-d point is ignored.
116 //
117 // Returns true if the vector is defined, or false
118 // otherwise.
119 ////////////////////////////////////////////////////////////////////
120 INLINE bool Lens::
121 extrude_vec(const LPoint3 &point2d, LVector3 &vec) const {
122  CDReader cdata(_cycler);
123  return do_extrude_vec(cdata, point2d, vec);
124 }
125 
126 ////////////////////////////////////////////////////////////////////
127 // Function: Lens::project
128 // Access: Published
129 // Description: Given a 3-d point in space, determine the 2-d point
130 // this maps to, in the range (-1,1) in both dimensions,
131 // where (0,0) is the center of the lens and
132 // (-1,-1) is the lower-left corner.
133 //
134 // Returns true if the 3-d point is in front of the lens
135 // and within the viewing frustum (in which case point2d
136 // is filled in), or false otherwise (in which case
137 // point2d will be filled in with something, which may
138 // or may not be meaningful).
139 ////////////////////////////////////////////////////////////////////
140 INLINE bool Lens::
141 project(const LPoint3 &point3d, LPoint2 &point2d) const {
142  CDReader cdata(_cycler);
143  LPoint3 result;
144  bool okflag = do_project(cdata, point3d, result);
145  point2d.set(result[0], result[1]);
146  return okflag;
147 }
148 
149 ////////////////////////////////////////////////////////////////////
150 // Function: Lens::project
151 // Access: Published
152 // Description: Given a 3-d point in space, determine the 2-d point
153 // this maps to, in the range (-1,1) in both dimensions,
154 // where (0,0) is the center of the lens and
155 // (-1,-1) is the lower-left corner.
156 //
157 // The z coordinate will also be set to a value in the
158 // range (-1, 1), where 1 represents a point on the near
159 // plane, and -1 represents a point on the far plane.
160 //
161 // Returns true if the 3-d point is in front of the lens
162 // and within the viewing frustum (in which case point2d
163 // is filled in), or false otherwise (in which case
164 // point2d will be filled in with something, which may
165 // or may not be meaningful).
166 ////////////////////////////////////////////////////////////////////
167 INLINE bool Lens::
168 project(const LPoint3 &point3d, LPoint3 &point2d) const {
169  CDReader cdata(_cycler);
170  return do_project(cdata, point3d, point2d);
171 }
172 
173 ////////////////////////////////////////////////////////////////////
174 // Function: Lens::set_change_event
175 // Access: Published
176 // Description: Sets the name of the event that will be generated
177 // whenever any properties of the Lens have
178 // changed. If this is not set for a particular lens,
179 // no event will be generated.
180 //
181 // The event is thrown with one parameter, the lens
182 // itself. This can be used to automatically track
183 // changes to camera fov, etc. in the application.
184 ////////////////////////////////////////////////////////////////////
185 INLINE void Lens::
186 set_change_event(const string &event) {
187  CDWriter cdata(_cycler, true);
188  cdata->_change_event = event;
189 }
190 
191 ////////////////////////////////////////////////////////////////////
192 // Function: Lens::get_change_event
193 // Access: Published
194 // Description: Returns the name of the event that will be generated
195 // whenever any properties of this particular Lens have
196 // changed.
197 ////////////////////////////////////////////////////////////////////
198 INLINE const string &Lens::
200  CDReader cdata(_cycler);
201  return cdata->_change_event;
202 }
203 
204 ////////////////////////////////////////////////////////////////////
205 // Function: Lens::get_coordinate_system
206 // Access: Published
207 // Description: Returns the coordinate system that all 3-d
208 // computations are performed within for this
209 // Lens. Normally, this is CS_default.
210 ////////////////////////////////////////////////////////////////////
211 INLINE CoordinateSystem Lens::
213  CDReader cdata(_cycler);
214  return cdata->_cs;
215 }
216 
217 ////////////////////////////////////////////////////////////////////
218 // Function: Lens::set_film_size
219 // Access: Published
220 // Description: Sets the horizontal size of the film without changing
221 // its shape. The aspect ratio remains unchanged; this
222 // computes the vertical size of the film to
223 // automatically maintain the aspect ratio.
224 ////////////////////////////////////////////////////////////////////
225 INLINE void Lens::
226 set_film_size(PN_stdfloat width) {
227  CDWriter cdata(_cycler, true);
228  do_set_film_size(cdata, width);
229 }
230 
231 ////////////////////////////////////////////////////////////////////
232 // Function: Lens::set_film_size
233 // Access: Published
234 // Description: Sets the size and shape of the "film" within the
235 // lens. This both establishes the units used by
236 // calls like set_focal_length(), and establishes the
237 // aspect ratio of the frame.
238 //
239 // In a physical camera, the field of view of a lens is
240 // determined by the lens' focal length and by the size
241 // of the film area exposed by the lens. For instance,
242 // a 35mm camera exposes a rectangle on the film about
243 // 24mm x 36mm, which means a 50mm lens gives about a
244 // 40-degree horizontal field of view.
245 //
246 // In the virtual camera, you may set the film size to
247 // any units here, and specify a focal length in the
248 // same units to simulate the same effect. Or, you may
249 // ignore this parameter, and specify the field of view
250 // and aspect ratio of the lens directly.
251 ////////////////////////////////////////////////////////////////////
252 INLINE void Lens::
253 set_film_size(PN_stdfloat width, PN_stdfloat height) {
254  set_film_size(LVecBase2(width, height));
255 }
256 
257 ////////////////////////////////////////////////////////////////////
258 // Function: Lens::set_film_size
259 // Access: Published
260 // Description: Sets the size and shape of the "film" within the
261 // lens. This both establishes the units used by
262 // calls like set_focal_length(), and establishes the
263 // aspect ratio of the frame.
264 //
265 // In a physical camera, the field of view of a lens is
266 // determined by the lens' focal length and by the size
267 // of the film area exposed by the lens. For instance,
268 // a 35mm camera exposes a rectangle on the film about
269 // 24mm x 36mm, which means a 50mm lens gives about a
270 // 40-degree horizontal field of view.
271 //
272 // In the virtual camera, you may set the film size to
273 // any units here, and specify a focal length in the
274 // same units to simulate the same effect. Or, you may
275 // ignore this parameter, and specify the field of view
276 // and aspect ratio of the lens directly.
277 ////////////////////////////////////////////////////////////////////
278 INLINE void Lens::
279 set_film_size(const LVecBase2 &film_size) {
280  CDWriter cdata(_cycler, true);
281  do_set_film_size(cdata, film_size);
282 }
283 
284 ////////////////////////////////////////////////////////////////////
285 // Function: Lens::get_film_size
286 // Access: Published
287 // Description: Returns the horizontal and vertical film size of
288 // the virtual film. See set_film_size().
289 ////////////////////////////////////////////////////////////////////
290 INLINE const LVecBase2 &Lens::
291 get_film_size() const {
292  CDReader cdata(_cycler);
293  return do_get_film_size(cdata);
294 }
295 
296 ////////////////////////////////////////////////////////////////////
297 // Function: Lens::set_film_offset
298 // Access: Published
299 // Description: Sets the horizontal and vertical offset amounts of
300 // this Lens. These are both in the same units
301 // specified in set_film_size().
302 //
303 // This can be used to establish an off-axis lens.
304 ////////////////////////////////////////////////////////////////////
305 INLINE void Lens::
306 set_film_offset(PN_stdfloat x, PN_stdfloat y) {
307  set_film_offset(LVecBase2(x, y));
308 }
309 
310 ////////////////////////////////////////////////////////////////////
311 // Function: Lens::set_film_offset
312 // Access: Published
313 // Description: Sets the horizontal and vertical offset amounts of
314 // this Lens. These are both in the same units
315 // specified in set_film_size().
316 //
317 // This can be used to establish an off-axis lens.
318 ////////////////////////////////////////////////////////////////////
319 INLINE void Lens::
320 set_film_offset(const LVecBase2 &film_offset) {
321  CDWriter cdata(_cycler, true);
322  do_set_film_offset(cdata, film_offset);
323 }
324 
325 ////////////////////////////////////////////////////////////////////
326 // Function: Lens::get_film_offset
327 // Access: Published
328 // Description: Returns the horizontal and vertical offset amounts of
329 // this Lens. See set_film_offset().
330 ////////////////////////////////////////////////////////////////////
331 INLINE const LVector2 &Lens::
333  CDReader cdata(_cycler);
334  return do_get_film_offset(cdata);
335 }
336 
337 ////////////////////////////////////////////////////////////////////
338 // Function: Lens::set_focal_length
339 // Access: Published
340 // Description: Sets the focal length of the lens. This may adjust
341 // the field-of-view correspondingly, and is an
342 // alternate way to specify field of view.
343 //
344 // For certain kinds of lenses (e.g. OrthographicLens),
345 // the focal length has no meaning.
346 ////////////////////////////////////////////////////////////////////
347 INLINE void Lens::
348 set_focal_length(PN_stdfloat focal_length) {
349  CDWriter cdata(_cycler, true);
350  do_set_focal_length(cdata, focal_length);
351 }
352 
353 ////////////////////////////////////////////////////////////////////
354 // Function: Lens::get_focal_length
355 // Access: Published
356 // Description: Returns the focal length of the lens. This may have
357 // been set explicitly by a previous call to
358 // set_focal_length(), or it may be computed based on
359 // the lens' fov and film_size. For certain kinds of
360 // lenses, the focal length has no meaning.
361 ////////////////////////////////////////////////////////////////////
362 INLINE PN_stdfloat Lens::
364  CDReader cdata(_cycler);
365  return do_get_focal_length(cdata);
366 }
367 
368 ////////////////////////////////////////////////////////////////////
369 // Function: Lens::set_fov
370 // Access: Published
371 // Description: Sets the horizontal field of view of the lens without
372 // changing the aspect ratio. The vertical field of
373 // view is adjusted to maintain the same aspect ratio.
374 ////////////////////////////////////////////////////////////////////
375 INLINE void Lens::
376 set_fov(PN_stdfloat hfov) {
377  CDWriter cdata(_cycler, true);
378  do_set_fov(cdata, hfov);
379 }
380 
381 ////////////////////////////////////////////////////////////////////
382 // Function: Lens::set_fov
383 // Access: Published
384 // Description: Sets the field of view of the lens in both
385 // dimensions. This establishes both the field of view
386 // and the aspect ratio of the lens. This is one way to
387 // specify the field of view of a lens;
388 // set_focal_length() is another way.
389 //
390 // For certain kinds of lenses (like OrthoLens),
391 // the field of view has no meaning.
392 ////////////////////////////////////////////////////////////////////
393 INLINE void Lens::
394 set_fov(PN_stdfloat hfov, PN_stdfloat vfov) {
395  set_fov(LVecBase2(hfov, vfov));
396 }
397 
398 ////////////////////////////////////////////////////////////////////
399 // Function: Lens::set_fov
400 // Access: Published
401 // Description: Sets the field of view of the lens in both
402 // dimensions. This establishes both the field of view
403 // and the aspect ratio of the lens. This is one way to
404 // specify the field of view of a lens;
405 // set_focal_length() is another way.
406 //
407 // For certain kinds of lenses (like OrthographicLens),
408 // the field of view has no meaning.
409 ////////////////////////////////////////////////////////////////////
410 INLINE void Lens::
411 set_fov(const LVecBase2 &fov) {
412  CDWriter cdata(_cycler, true);
413  do_set_fov(cdata, fov);
414 }
415 
416 ////////////////////////////////////////////////////////////////////
417 // Function: Lens::get_fov
418 // Access: Published
419 // Description: Returns the horizontal and vertical film size of
420 // the virtual film. See set_fov().
421 ////////////////////////////////////////////////////////////////////
422 INLINE const LVecBase2 &Lens::
423 get_fov() const {
424  CDReader cdata(_cycler);
425  return do_get_fov(cdata);
426 }
427 
428 ////////////////////////////////////////////////////////////////////
429 // Function: Lens::get_hfov
430 // Access: Published
431 // Description: Returns the horizontal component of fov only. See
432 // get_fov().
433 ////////////////////////////////////////////////////////////////////
434 INLINE PN_stdfloat Lens::
435 get_hfov() const {
436  return get_fov()[0];
437 }
438 
439 ////////////////////////////////////////////////////////////////////
440 // Function: Lens::get_vfov
441 // Access: Published
442 // Description: Returns the vertical component of fov only. See
443 // get_fov().
444 ////////////////////////////////////////////////////////////////////
445 INLINE PN_stdfloat Lens::
446 get_vfov() const {
447  return get_fov()[1];
448 }
449 
450 ////////////////////////////////////////////////////////////////////
451 // Function: Lens::set_aspect_ratio
452 // Access: Published
453 // Description: Sets the aspect ratio of the lens. This is the ratio
454 // of the height to the width of the generated image.
455 // Setting this overrides the two-parameter fov or film
456 // size setting.
457 ////////////////////////////////////////////////////////////////////
458 INLINE void Lens::
459 set_aspect_ratio(PN_stdfloat aspect_ratio) {
460  CDWriter cdata(_cycler, true);
461  do_set_aspect_ratio(cdata, aspect_ratio);
462 }
463 
464 ////////////////////////////////////////////////////////////////////
465 // Function: Lens::get_aspect_ratio
466 // Access: Published
467 // Description: Returns the aspect ratio of the Lens. This is
468 // determined based on the indicated film size; see
469 // set_film_size().
470 ////////////////////////////////////////////////////////////////////
471 INLINE PN_stdfloat Lens::
473  CDReader cdata(_cycler);
474  return do_get_aspect_ratio(cdata);
475 }
476 
477 ////////////////////////////////////////////////////////////////////
478 // Function: Lens::set_near
479 // Access: Published
480 // Description: Defines the position of the near plane (or cylinder,
481 // sphere, whatever). Points closer to the lens than
482 // this may not be rendered.
483 ////////////////////////////////////////////////////////////////////
484 INLINE void Lens::
485 set_near(PN_stdfloat near_distance) {
486  CDWriter cdata(_cycler, true);
487  do_set_near(cdata, near_distance);
488 }
489 
490 ////////////////////////////////////////////////////////////////////
491 // Function: Lens::get_near
492 // Access: Published
493 // Description: Returns the position of the near plane (or cylinder,
494 // sphere, whatever).
495 ////////////////////////////////////////////////////////////////////
496 INLINE PN_stdfloat Lens::
497 get_near() const {
498  CDReader cdata(_cycler);
499  return do_get_near(cdata);
500 }
501 
502 ////////////////////////////////////////////////////////////////////
503 // Function: Lens::set_far
504 // Access: Published
505 // Description: Defines the position of the far plane (or cylinder,
506 // sphere, whatever). Points farther from the lens than
507 // this may not be rendered.
508 ////////////////////////////////////////////////////////////////////
509 INLINE void Lens::
510 set_far(PN_stdfloat far_distance) {
511  CDWriter cdata(_cycler, true);
512  do_set_far(cdata, far_distance);
513 }
514 
515 ////////////////////////////////////////////////////////////////////
516 // Function: Lens::get_far
517 // Access: Published
518 // Description: Returns the position of the far plane (or cylinder,
519 // sphere, whatever).
520 ////////////////////////////////////////////////////////////////////
521 INLINE PN_stdfloat Lens::
522 get_far() const {
523  CDReader cdata(_cycler);
524  return do_get_far(cdata);
525 }
526 
527 ////////////////////////////////////////////////////////////////////
528 // Function: Lens::set_near_far
529 // Access: Published
530 // Description: Simultaneously changes the near and far planes.
531 ////////////////////////////////////////////////////////////////////
532 INLINE void Lens::
533 set_near_far(PN_stdfloat near_distance, PN_stdfloat far_distance) {
534  CDWriter cdata(_cycler, true);
535  do_set_near_far(cdata, near_distance, far_distance);
536 }
537 
538 ////////////////////////////////////////////////////////////////////
539 // Function: Lens::set_view_hpr
540 // Access: Published
541 // Description: Sets the direction in which the lens is facing.
542 // Normally, this is down the forward axis (usually the
543 // Y axis), but it may be rotated. This is only one way
544 // of specifying the rotation; you may also specify an
545 // explicit vector in which to look, or you may give a
546 // complete transformation matrix.
547 ////////////////////////////////////////////////////////////////////
548 INLINE void Lens::
549 set_view_hpr(PN_stdfloat h, PN_stdfloat p, PN_stdfloat r) {
550  set_view_hpr(LVecBase3(h, p, r));
551 }
552 
553 ////////////////////////////////////////////////////////////////////
554 // Function: Lens::set_view_vector
555 // Access: Published
556 // Description: Specifies the direction in which the lens is facing
557 // by giving an axis to look along, and a perpendicular
558 // (or at least non-parallel) up axis.
559 //
560 // See also set_view_hpr().
561 ////////////////////////////////////////////////////////////////////
562 INLINE void Lens::
563 set_view_vector(PN_stdfloat x, PN_stdfloat y, PN_stdfloat z, PN_stdfloat i, PN_stdfloat j, PN_stdfloat k) {
564  set_view_vector(LVector3(x, y, z), LVector3(i, j, k));
565 }
566 
567 ////////////////////////////////////////////////////////////////////
568 // Function: Lens::set_interocular_distance
569 // Access: Published
570 // Description: Sets the distance between the left and right eyes of
571 // a stereo camera. This distance is used to apply a
572 // stereo effect when the lens is rendered on a stereo
573 // display region. It only has an effect on a
574 // PerspectiveLens.
575 //
576 // The left eye and the right eye are each offset along
577 // the X axis by half of this distance, so that this
578 // parameter specifies the total distance between them.
579 //
580 // Also see set_convergence_distance(), which relates.
581 ////////////////////////////////////////////////////////////////////
582 INLINE void Lens::
583 set_interocular_distance(PN_stdfloat interocular_distance) {
584  CDWriter cdata(_cycler, true);
585  do_set_interocular_distance(cdata, interocular_distance);
586  do_throw_change_event(cdata);
587 }
588 
589 ////////////////////////////////////////////////////////////////////
590 // Function: Lens::get_interocular_distance
591 // Access: Published
592 // Description: See set_interocular_distance().
593 ////////////////////////////////////////////////////////////////////
594 INLINE PN_stdfloat Lens::
596  CDReader cdata(_cycler);
597  return cdata->_interocular_distance;
598 }
599 
600 ////////////////////////////////////////////////////////////////////
601 // Function: Lens::set_convergence_distance
602 // Access: Published
603 // Description: Sets the distance between between the camera plane
604 // and the point in the distance that the left and right
605 // eyes are both looking at. This distance is used to
606 // apply a stereo effect when the lens is rendered on a
607 // stereo display region. It only has an effect on a
608 // PerspectiveLens.
609 //
610 // This parameter must be greater than 0, but may be as
611 // large as you like. It controls the distance at
612 // which the two stereo images will appear to converge,
613 // which is a normal property of stereo vision. Normally
614 // this should be set to the distance from the camera to
615 // the area of interest in your scene. Anything beyond
616 // this distance will appear to go into the screen, and
617 // anything closer will appear to come out of the screen.
618 // If you want to simulate parallel stereo, set this
619 // to infinity.
620 //
621 // Note that this creates an off-axis frustum, which
622 // means that the lenses are still pointing in the
623 // same direction, which is usually more desirable
624 // than the more naive toe-in approach, where the
625 // two lenses are simply tilted toward each other.
626 //
627 // Prior to Panda3D 1.9.0, the convergence was being
628 // calculated incorrectly. It has since been corrected.
629 // To restore the legacy behavior you can set the
630 // stereo-lens-old-convergence variable to true.
631 //
632 // Also see set_interocular_distance(), which relates.
633 ////////////////////////////////////////////////////////////////////
634 INLINE void Lens::
635 set_convergence_distance(PN_stdfloat convergence_distance) {
636  CDWriter cdata(_cycler, true);
637  do_set_convergence_distance(cdata, convergence_distance);
638  do_throw_change_event(cdata);
639 }
640 
641 ////////////////////////////////////////////////////////////////////
642 // Function: Lens::get_convergence_distance
643 // Access: Published
644 // Description: See set_convergence_distance().
645 ////////////////////////////////////////////////////////////////////
646 INLINE PN_stdfloat Lens::
648  CDReader cdata(_cycler);
649  return cdata->_convergence_distance;
650 }
651 
652 ////////////////////////////////////////////////////////////////////
653 // Function: Lens::set_view_mat
654 // Access: Published
655 // Description: Sets an arbitrary transformation on the lens. This
656 // replaces the individual transformation components
657 // like set_view_hpr().
658 //
659 // Setting a transformation here will have a slightly
660 // different effect than putting one on the LensNode
661 // that contains this lens. In particular, lighting and
662 // other effects computations will still be performed on
663 // the lens in its untransformed (facing forward)
664 // position, but the actual projection matrix will be
665 // transformed by this matrix.
666 ////////////////////////////////////////////////////////////////////
667 INLINE void Lens::
668 set_view_mat(const LMatrix4 &view_mat) {
669  CDWriter cdata(_cycler, true);
670  do_set_view_mat(cdata, view_mat);
671 }
672 
673 ////////////////////////////////////////////////////////////////////
674 // Function: Lens::get_view_mat
675 // Access: Published
676 // Description: Returns the direction in which the lens is facing.
677 ////////////////////////////////////////////////////////////////////
678 INLINE const LMatrix4 &Lens::
679 get_view_mat() const {
680  CDReader cdata(_cycler);
681  return do_get_view_mat(cdata);
682 }
683 
684 ////////////////////////////////////////////////////////////////////
685 // Function: Lens::get_keystone
686 // Access: Published
687 // Description: Returns the keystone correction specified for the
688 // lens.
689 ////////////////////////////////////////////////////////////////////
690 INLINE const LVecBase2 &Lens::
691 get_keystone() const {
692  CDReader cdata(_cycler);
693  return cdata->_keystone;
694 }
695 
696 ////////////////////////////////////////////////////////////////////
697 // Function: Lens::get_custom_film_mat
698 // Access: Published
699 // Description: Returns the custom_film_mat specified for the
700 // lens.
701 ////////////////////////////////////////////////////////////////////
702 INLINE const LMatrix4 &Lens::
704  CDReader cdata(_cycler);
705  return cdata->_custom_film_mat;
706 }
707 
708 ////////////////////////////////////////////////////////////////////
709 // Function: Lens::get_projection_mat
710 // Access: Published
711 // Description: Returns the complete transformation matrix from a 3-d
712 // point in space to a point on the film, if such a
713 // matrix exists, or the identity matrix if the lens is
714 // nonlinear.
715 ////////////////////////////////////////////////////////////////////
716 INLINE const LMatrix4 &Lens::
717 get_projection_mat(StereoChannel channel) const {
718  CDReader cdata(_cycler);
719  return do_get_projection_mat(cdata, channel);
720 }
721 
722 ////////////////////////////////////////////////////////////////////
723 // Function: Lens::get_projection_mat_inv
724 // Access: Published
725 // Description: Returns the matrix that transforms from a 2-d point
726 // on the film to a 3-d vector in space, if such a
727 // matrix exists.
728 ////////////////////////////////////////////////////////////////////
729 INLINE const LMatrix4 &Lens::
730 get_projection_mat_inv(StereoChannel stereo_channel) const {
731  CDReader cdata(_cycler);
732  return do_get_projection_mat_inv(cdata, stereo_channel);
733 }
734 
735 ////////////////////////////////////////////////////////////////////
736 // Function: Lens::get_film_mat
737 // Access: Published
738 // Description: Returns the matrix that transforms from a point
739 // behind the lens to a point on the film.
740 ////////////////////////////////////////////////////////////////////
741 INLINE const LMatrix4 &Lens::
742 get_film_mat() const {
743  CDReader cdata(_cycler);
744  return do_get_film_mat(cdata);
745 }
746 
747 ////////////////////////////////////////////////////////////////////
748 // Function: Lens::get_film_mat_inv
749 // Access: Published
750 // Description: Returns the matrix that transforms from a point on
751 // the film to a point behind the lens.
752 ////////////////////////////////////////////////////////////////////
753 INLINE const LMatrix4 &Lens::
755  CDReader cdata(_cycler);
756  return do_get_film_mat_inv(cdata);
757 }
758 
759 ////////////////////////////////////////////////////////////////////
760 // Function: Lens::get_lens_mat
761 // Access: Published
762 // Description: Returns the matrix that transforms from a point
763 // in front of the lens to a point in space.
764 ////////////////////////////////////////////////////////////////////
765 INLINE const LMatrix4 &Lens::
766 get_lens_mat() const {
767  CDReader cdata(_cycler);
768  return do_get_lens_mat(cdata);
769 }
770 
771 ////////////////////////////////////////////////////////////////////
772 // Function: Lens::get_lens_mat_inv
773 // Access: Published
774 // Description: Returns the matrix that transforms from a point in
775 // space to a point in front of the lens.
776 ////////////////////////////////////////////////////////////////////
777 INLINE const LMatrix4 &Lens::
779  CDReader cdata(_cycler);
780  return do_get_lens_mat_inv(cdata);
781 }
782 
783 ////////////////////////////////////////////////////////////////////
784 // Function: Lens::get_last_change
785 // Access: Published
786 // Description: Returns the UpdateSeq that is incremented whenever
787 // the lens properties are changed. As long as this
788 // number remains the same, you may assume the lens
789 // properties are unchanged.
790 ////////////////////////////////////////////////////////////////////
791 INLINE UpdateSeq Lens::
793  CDReader cdata(_cycler);
794  return cdata->_last_change;
795 }
796 
797 ////////////////////////////////////////////////////////////////////
798 // Function: Lens::do_adjust_user_flags
799 // Access: Protected
800 // Description: Clears from _user_flags the bits in the first
801 // parameter, and sets the bits in the second parameter.
802 ////////////////////////////////////////////////////////////////////
803 INLINE void Lens::
804 do_adjust_user_flags(CData *cdata, int clear_flags, int set_flags) {
805  cdata->_user_flags = (cdata->_user_flags & ~clear_flags) | set_flags;
806 }
807 
808 ////////////////////////////////////////////////////////////////////
809 // Function: Lens::do_adjust_comp_flags
810 // Access: Protected
811 // Description: Clears from _comp_flags the bits in the first
812 // parameter, and sets the bits in the second parameter.
813 ////////////////////////////////////////////////////////////////////
814 INLINE void Lens::
815 do_adjust_comp_flags(CData *cdata, int clear_flags, int set_flags) {
816  cdata->_comp_flags = (cdata->_comp_flags & ~clear_flags) | set_flags;
817 }
818 
819 ////////////////////////////////////////////////////////////////////
820 // Function: Lens::do_set_film_offset
821 // Access: Protected
822 // Description:
823 ////////////////////////////////////////////////////////////////////
824 INLINE void Lens::
825 do_set_film_offset(CData *cdata, const LVecBase2 &film_offset) {
826  cdata->_film_offset = film_offset;
827  do_adjust_comp_flags(cdata, CF_mat, 0);
828  do_throw_change_event(cdata);
829 }
830 
831 ////////////////////////////////////////////////////////////////////
832 // Function: Lens::do_get_film_offset
833 // Access: Protected
834 // Description:
835 ////////////////////////////////////////////////////////////////////
836 INLINE const LVector2 &Lens::
837 do_get_film_offset(const CData *cdata) const {
838  return cdata->_film_offset;
839 }
840 
841 ////////////////////////////////////////////////////////////////////
842 // Function: Lens::do_set_near
843 // Access: Protected
844 // Description:
845 ////////////////////////////////////////////////////////////////////
846 INLINE void Lens::
847 do_set_near(CData *cdata, PN_stdfloat near_distance) {
848  cdata->_near_distance = near_distance;
849  do_adjust_comp_flags(cdata, CF_projection_mat | CF_projection_mat_inv, 0);
850  do_throw_change_event(cdata);
851 }
852 
853 ////////////////////////////////////////////////////////////////////
854 // Function: Lens::do_get_near
855 // Access: Protected
856 // Description:
857 ////////////////////////////////////////////////////////////////////
858 INLINE PN_stdfloat Lens::
859 do_get_near(const CData *cdata) const {
860  return cdata->_near_distance;
861 }
862 
863 ////////////////////////////////////////////////////////////////////
864 // Function: Lens::do_set_far
865 // Access: Protected
866 // Description:
867 ////////////////////////////////////////////////////////////////////
868 INLINE void Lens::
869 do_set_far(CData *cdata, PN_stdfloat far_distance) {
870  cdata->_far_distance = far_distance;
871  do_adjust_comp_flags(cdata, CF_projection_mat | CF_projection_mat_inv, 0);
872  do_throw_change_event(cdata);
873 }
874 
875 ////////////////////////////////////////////////////////////////////
876 // Function: Lens::do_get_far
877 // Access: Protected
878 // Description:
879 ////////////////////////////////////////////////////////////////////
880 INLINE PN_stdfloat Lens::
881 do_get_far(const CData *cdata) const {
882  return cdata->_far_distance;
883 }
884 
885 ////////////////////////////////////////////////////////////////////
886 // Function: Lens::do_set_near_far
887 // Access: Protected
888 // Description:
889 ////////////////////////////////////////////////////////////////////
890 INLINE void Lens::
891 do_set_near_far(CData *cdata, PN_stdfloat near_distance, PN_stdfloat far_distance) {
892  cdata->_near_distance = near_distance;
893  cdata->_far_distance = far_distance;
894  do_adjust_comp_flags(cdata, CF_projection_mat | CF_projection_mat_inv, 0);
895  do_throw_change_event(cdata);
896 }
897 
898 INLINE ostream &
899 operator << (ostream &out, const Lens &lens) {
900  lens.output(out);
901  return out;
902 }
903 
This is the base class for all three-component vectors and points.
Definition: lvecBase3.h:105
void set_focal_length(PN_stdfloat focal_length)
Sets the focal length of the lens.
Definition: lens.I:348
void set_convergence_distance(PN_stdfloat convergence_distance)
Sets the distance between between the camera plane and the point in the distance that the left and ri...
Definition: lens.I:635
A base class for any number of different kinds of lenses, linear and otherwise.
Definition: lens.h:45
bool extrude_vec(const LPoint2 &point2d, LVector3 &vec3d) const
Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (...
Definition: lens.I:95
void set_change_event(const string &event)
Sets the name of the event that will be generated whenever any properties of the Lens have changed...
Definition: lens.I:186
PN_stdfloat get_vfov() const
Returns the vertical component of fov only.
Definition: lens.I:446
const LVector2 & get_film_offset() const
Returns the horizontal and vertical offset amounts of this Lens.
Definition: lens.I:332
const string & get_change_event() const
Returns the name of the event that will be generated whenever any properties of this particular Lens ...
Definition: lens.I:199
void set_far(PN_stdfloat far_distance)
Defines the position of the far plane (or cylinder, sphere, whatever).
Definition: lens.I:510
void set_film_size(PN_stdfloat width)
Sets the horizontal size of the film without changing its shape.
Definition: lens.I:226
void set_interocular_distance(PN_stdfloat interocular_distance)
Sets the distance between the left and right eyes of a stereo camera.
Definition: lens.I:583
const LMatrix4 & get_view_mat() const
Returns the direction in which the lens is facing.
Definition: lens.I:679
PN_stdfloat get_focal_length() const
Returns the focal length of the lens.
Definition: lens.I:363
This is a three-component vector distance (as opposed to a three-component point, which represents a ...
Definition: lvector3.h:100
const LVecBase2 & get_fov() const
Returns the horizontal and vertical film size of the virtual film.
Definition: lens.I:423
This is a three-component point in space (as opposed to a three-component vector, which represents a ...
Definition: lpoint3.h:99
void set_view_mat(const LMatrix4 &view_mat)
Sets an arbitrary transformation on the lens.
Definition: lens.I:668
This template class calls PipelineCycler::read_unlocked(), and then provides a transparent read-only ...
PN_stdfloat get_hfov() const
Returns the horizontal component of fov only.
Definition: lens.I:435
void set_aspect_ratio(PN_stdfloat aspect_ratio)
Sets the aspect ratio of the lens.
Definition: lens.I:459
void set_near_far(PN_stdfloat near_distance, PN_stdfloat far_distance)
Simultaneously changes the near and far planes.
Definition: lens.I:533
const LMatrix4 & get_lens_mat() const
Returns the matrix that transforms from a point in front of the lens to a point in space...
Definition: lens.I:766
bool extrude(const LPoint2 &point2d, LPoint3 &near_point, LPoint3 &far_point) const
Given a 2-d point in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (...
Definition: lens.I:32
void set_view_hpr(PN_stdfloat h, PN_stdfloat p, PN_stdfloat r)
Sets the direction in which the lens is facing.
Definition: lens.I:549
PN_stdfloat get_convergence_distance() const
See set_convergence_distance().
Definition: lens.I:647
const LMatrix4 & get_lens_mat_inv() const
Returns the matrix that transforms from a point in space to a point in front of the lens...
Definition: lens.I:778
const LVecBase2 & get_keystone() const
Returns the keystone correction specified for the lens.
Definition: lens.I:691
const LMatrix4 & get_custom_film_mat() const
Returns the custom_film_mat specified for the lens.
Definition: lens.I:703
This is a 4-by-4 transform matrix.
Definition: lmatrix.h:451
UpdateSeq get_last_change() const
Returns the UpdateSeq that is incremented whenever the lens properties are changed.
Definition: lens.I:792
bool project(const LPoint3 &point3d, LPoint3 &point2d) const
Given a 3-d point in space, determine the 2-d point this maps to, in the range (-1,1) in both dimensions, where (0,0) is the center of the lens and (-1,-1) is the lower-left corner.
Definition: lens.I:168
This is the base class for all two-component vectors and points.
Definition: lvecBase2.h:105
This template class calls PipelineCycler::write() in the constructor and PipelineCycler::release_writ...
PN_stdfloat get_aspect_ratio() const
Returns the aspect ratio of the Lens.
Definition: lens.I:472
PN_stdfloat get_interocular_distance() const
See set_interocular_distance().
Definition: lens.I:595
const LMatrix4 & get_projection_mat_inv(StereoChannel channel=SC_mono) const
Returns the matrix that transforms from a 2-d point on the film to a 3-d vector in space...
Definition: lens.I:730
void set_film_offset(PN_stdfloat x, PN_stdfloat y)
Sets the horizontal and vertical offset amounts of this Lens.
Definition: lens.I:306
bool extrude_depth(const LPoint3 &point2d, LPoint3 &point3d) const
Uses the depth component of the 3-d result from project() to compute the original point in 3-d space ...
Definition: lens.I:71
This is a two-component vector offset.
Definition: lvector2.h:91
const LVecBase2 & get_film_size() const
Returns the horizontal and vertical film size of the virtual film.
Definition: lens.I:291
const LMatrix4 & get_film_mat() const
Returns the matrix that transforms from a point behind the lens to a point on the film...
Definition: lens.I:742
const LMatrix4 & get_film_mat_inv() const
Returns the matrix that transforms from a point on the film to a point behind the lens...
Definition: lens.I:754
const LMatrix4 & get_projection_mat(StereoChannel channel=SC_mono) const
Returns the complete transformation matrix from a 3-d point in space to a point on the film...
Definition: lens.I:717
This is a two-component point in space.
Definition: lpoint2.h:92
This is a sequence number that increments monotonically.
Definition: updateSeq.h:43
void set_view_vector(PN_stdfloat x, PN_stdfloat y, PN_stdfloat z, PN_stdfloat i, PN_stdfloat j, PN_stdfloat k)
Specifies the direction in which the lens is facing by giving an axis to look along, and a perpendicular (or at least non-parallel) up axis.
Definition: lens.I:563
CoordinateSystem get_coordinate_system() const
Returns the coordinate system that all 3-d computations are performed within for this Lens...
Definition: lens.I:212
void set_fov(PN_stdfloat fov)
Sets the horizontal field of view of the lens without changing the aspect ratio.
Definition: lens.I:376
void set_near(PN_stdfloat near_distance)
Defines the position of the near plane (or cylinder, sphere, whatever).
Definition: lens.I:485
PN_stdfloat get_far() const
Returns the position of the far plane (or cylinder, sphere, whatever).
Definition: lens.I:522
PN_stdfloat get_near() const
Returns the position of the near plane (or cylinder, sphere, whatever).
Definition: lens.I:497