From 444f18c1c8b284f0cb521b9cbd24b0998ca21c29 Mon Sep 17 00:00:00 2001
From: David Rose <david@ddrose.com>
Date: Wed, 19 Nov 2008 16:36:03 +0000
Subject: [PATCH] clarify stereo properties

---
 panda/src/gobj/lens.cxx | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/panda/src/gobj/lens.cxx b/panda/src/gobj/lens.cxx
index a5235416ce..08b97ad028 100644
--- a/panda/src/gobj/lens.cxx
+++ b/panda/src/gobj/lens.cxx
@@ -587,7 +587,11 @@ get_nodal_point() const {
 //               display region.  It only has an effect on a
 //               PerspectiveLens.
 //
-//               Also see set_interocular_distance(), which relates.
+//               The left eye and the right eye are each offset along
+//               the X axis by half of this distance, so that this
+//               parameter specifies the total distance between them.
+//
+//               Also see set_convergence_distance(), which relates.
 ////////////////////////////////////////////////////////////////////
 void Lens::
 set_interocular_distance(float interocular_distance) {
@@ -615,12 +619,22 @@ get_interocular_distance() const {
 ////////////////////////////////////////////////////////////////////
 //     Function: Lens::set_convergence_distance
 //       Access: Published
-//  Description: Sets the distance between the left and right eyes of
-//               a stereo camera.  This distance is used to apply a
-//               stereo effect when the lens is rendered on a stereo
-//               display region.  It only has an effect on a
+//  Description: Sets the distance between between the camera plane
+//               and the point in the distance that the left and right
+//               eyes are both looking at.  This distance is used to
+//               apply a stereo effect when the lens is rendered on a
+//               stereo display region.  It only has an effect on a
 //               PerspectiveLens.
 //
+//               This parameter must be greater than 0, but may be as
+//               large as you like.  It controls the degree to which
+//               the two eyes are directed inwards towards each other,
+//               which is a normal property of stereo vision.
+//               Normally this should be set to the distance from the
+//               camera to the area of interest in your scene.  If you
+//               want to simulate parallel stereo, set this value to a
+//               very large number.
+//
 //               Also see set_interocular_distance(), which relates.
 ////////////////////////////////////////////////////////////////////
 void Lens::