Camera Control

== Feature Documentation: Camera Controls ==
Document to describe and explain the Camera Control feature and expected behavior.
=== The Camera ===
Think of the camera as an actual object. It has some volume as it moves through space that is preserved. This is why when zooming in on land, the camera occasionally pushes up. The "camera" is essentially hitting the ground and being deflected.
Alt + Left mouse click is commonly referred to as "alt-zoom"
=== Camera Behavior ===
Alt + Left mouse click centers the camera to the cursor (unless pointing to the sky)
What part of the object is the camera focused on?
--At distance, to a point behind your cursor in the center of the object
Why?
So that when the camera rotates around the object, it spins the camera in a more natural way, instead of "tumbling" it.
--If sufficiently close to an object, the camera will change to focus on the surface of said object.
Why?
For ease of focusing on and/ or editing specific parts of an object.
Why can't I zoom in on the sky"
The sky has no focal point. 
*All if this is based on where the camera initially points (Alt + Left mouse click ) unless you Alt + Left mouse click again to change
=== Camera & Objects ===
At a tenth of a meter the camera ceases advancement towards an object as to not cut into it. From there, further zooming instead decreases the field of vision and zooms. It stops when the FOV limit is hit (this is arbitrary - when no more detail is to be gained).
Alpha Textures. If you can see an item beyond another (view and item through an alpha textured object) you can alt-zoom to the object beyond. The camera "sees through" the alpha texture and allows clicking beyond itself.
=== Camera & Avatar ===
Avatar / camera distances are designed to be user friendly for the average user, and to not clip avatars and confuse the user.
When objects are attached to an avatar, they act as part of the avatar and adopt the behavior of the avatar rather than the "normal" behavior for an object.
Why is the camera constrained to the avatar?
Your avatar needs to be "seen" in the same set of simulators as your camera (the sim you are in or adjacent to)
From a user standpoint, the view is more realistic having the camera stop short of the end of it's viewable path. This way there is still a horizon (data past the camera) and not just a blank screen.
Voyeurism. With a limited field of vision, it is easier as a user to look at the map and distinguish who may or may not be able to view you and your activities.
Latching. "Alt-zoom" on a moving object pulls the camera with it so you do not have to struggle to keep up with something you wish to view that happens to be moving. Latching only tracks an object. Rotating on a latched object is not a functionality as it would be unpleasant to the viewer.
=== Camera Tools ===
alt-zoom mousewheel can be used to zoom into objects.
Build menu Focus tool has a zoom slider
View> Camera Controls provides an on screen clickable camera interface.
Control + 8 = Increase FOV (fisheye)
Control + 9 = Reset camera
Control + 0 = Telephoto
Click on avatar and mouse around will look around and show your avatar looking around.
(If flying this only steers the avatar)
Camera resets when avatar moves. The assumption is that you want to see / know where you are going.
Control-alt-arrow keys rotate up down and around an object
Alt-arrow keys pan right, left and zoom in and out
While Avatar is sitting = Alt+Page up / Page Down will pan, arrow keys to look around.
Mouselook= Camera will take orientation of the avatar. This feature helps make vehicles more compelling.
=== avatar-anti-occlusion (Keep your avatar visible) ===
* When you're walking around with the camera unlocked (not alt-zoomed on something), the camera will dolly in (move closer to your avatar) if something comes between the camera and your avatar. 
* In Havok 1, the camera would dolly in if your avatar's head was obscured by an object.
* In Havok 4, the camera dollies in if your avatar's waist, torso, or head is obscured by an object.
Test: Back up to a solid prim that is tall as your avatar. Note which part of your avatar became obscured when the camera dollied in.
Test: Back up to a cliff of terrain. Verify that your camera moves forward.
Test: Back up to a 10x10x10 prim. Verify the camera dollies in until it's right above your head.
Test: Back up to a 10 x 1x 10m wall. Verify your camera stays on the same side of the wall as the avatar, and does not pop through to the other side.
Test: Stand back to back with an avatar that is the same height as you. Verify the camera behavior isn't annoying.
* Phantom object have no effect on the camera.
Test: Walk through a 10x10x10m Phantom box. Verify your camera follows your avatar through the box without any automatic dollying.
*Alpha textured or transparent objects has no effect on the camera occlusion. The camera treats tranparent objects the same way it treats visible objects.
Test: Add the following script to a 10x10x10m box, then back up to it. Verify the camera dollies in until it's right above your head.
default{state_entry(){llSetAlpha(0, ALL_SIDES);} }