Camera Class Reference

This reference page is linked to from the following overview topics: Kinds of Plug-ins, Mudbox Scenes, Scene Graph, Transformations and Coordinate Space Conversions.



Detailed Description

Represents a camera (point of view) in a Mudbox scene.

Only one is active at one time.

The picture you see in the Mudbox view is "through" the active Camera object. Cameras may be orthographic or perspective.

Examples:

ImmediateModeRenderer/ImmediateModeRenderer.h, and Turntable/Turntable.cpp.

Definition at line 20 of file camera.h.

#include <camera.h>

Inheritance diagram for Camera:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual Vector  Forward (void) const
  Returns a normalized vector indicating the camera's direction of view in world space.
virtual Vector  Up (void) const
  Returns a normalized vector indicating the camera's "up" direction in world space.
virtual Vector  Right (void) const
  Returns a normalized vector indicating the camera's "right" direction in world space.
virtual float  Yaw (void) const
  Returns the yaw of the camera in radians.
virtual float  Pitch (void) const
  Returns the pitch of the current camera in radians.
virtual float  Roll (void) const
  Returns the roll of the current camera in radians.
virtual Vector  Position (void) const
  Returns the position of the camera in world space.
virtual void  SetYawPitchRoll (const Vector &vYPR)
  Sets rotation of the camera, specified as yaw, pitch and roll values.
virtual void  AddYawPitchRoll (const Vector &vYPR)
  Add a rotation to the camera, specified as yaw, pitch and roll values.
virtual void  SetForwardUpRight (const Vector &vForward, const Vector &vUp, const Vector &vRight)
  Sets the rotation of the camera, specified as three vectors.
virtual void  SetTarget (const Vector &vTarget, const Vector &vUpDir=Vector(0, 1, 0))
  Set the rotation of the camera, by telling it what to point at.
virtual void  SetPosition (const Vector &vPosition)
  Set the location of the camera in world space.
virtual void  MoveForward (float fRange)
  Move the camera forward along its view direction. Its rotation remains unchanged.
virtual void  MoveUp (float fRange)
  Move the camera up. Its rotation remains unchanged.
virtual void  MoveRight (float fRange)
  Move the camera right. Its rotation remains unchanged.
virtual void  MoveBackward (float fRange)
  Move the camera backward along its view direction. Its rotation remains unchanged.
virtual void  MoveDown (float fRange)
  Move the camera down. Its rotation remains unchanged.
virtual void  MoveLeft (float fRange)
  Move the camera left. Its rotation remains unchanged.
virtual Vector  Project (const Vector &vWorldPosition) const
  Takes a point in world space and returns its position in screen coordinates.
virtual Vector  UnProject (const Vector &vScreenPosition) const
  Takes a point in screen space and returns its position in world space.
virtual mudbox::Matrix  Matrix (bool bOffscreen=false) const
  Returns the matrix used by the camera to transform world space positions to screen space.
virtual float  FOV (void) const
  Returns the vertical field of view in radians.
virtual float  Near (void) const
  Returns the near clip plane distance from the camera.
virtual float  Far (void) const
  Returns the far clip plane distance from the camera.
virtual float  AspectRatio (void) const
  Returns the current aspect ratio of the viewport.
virtual void  SetFOV (float fFOV)
  Sets the vertical field of view of the camera.
virtual void  SetNear (float fNear)
  Sets the near clip plane for the camera.
virtual void  SetFar (float fFar)
  Sets the far clip plane for the camera.
virtual void  SetAspectRatio (float fAspectRatio)
  Sets the aspect ratio for the camera.
virtual float  Scale2D (void) const
  Returns the 2d scale factor.
virtual float  Angle2D (void) const
  Returns the 2d rotation amount.
virtual Vector  Position2D (void) const
  Returns the 2d offset.
virtual void  SetScale2D (float fScale2D)
  Sets the 2d scale factor.
virtual void  SetAngle2D (float fAngle2D)
  Sets the 2d rotation amount.
virtual void  SetPosition2D (const Vector &vPosition2D)
  Sets the 2d offset.
virtual void  CopyFrom (const Camera &cOther)
  Make this camera identical to another one.
virtual bool  IsEqualTo (const Camera &cOther) const
  Returns true if this camera is equal to the other one.
virtual bool  Pick (float fXPosition, float fYPosition, SurfacePoint &sResult)
  Returns the point displayed at the given screen location.
virtual Vector  Aim () const
  Returns the world-space point around which the camera rolls when you navigate in the 3d view.
virtual void  SetAim (const Vector &v)
  Sets the point around which the camera will rotate when you navigate in the 3d view.
virtual bool  Orthographic () const
  Returns true if the camera is orthographic.
virtual void  SetOrthographic (bool isOrtho)
  Sets the camera to be orthographic or perspective.

Protected Member Functions

  Camera (void)
  Constructor.

Constructor & Destructor Documentation

Camera ( void  ) [protected]

Constructor.

Do not use directly.

Instead of constructing cameras directly, you should use CreateInstance() like this:

        Camera *myNewCamera = CreateInstance<Camera>();

Member Function Documentation

virtual Vector Forward ( void  ) const [virtual]

Returns a normalized vector indicating the camera's direction of view in world space.

Examples:
Turntable/Turntable.cpp.
virtual Vector Up ( void  ) const [virtual]

Returns a normalized vector indicating the camera's "up" direction in world space.

Examples:
Turntable/Turntable.cpp.
virtual Vector Right ( void  ) const [virtual]

Returns a normalized vector indicating the camera's "right" direction in world space.

Examples:
Turntable/Turntable.cpp.
virtual float Yaw ( void  ) const [virtual]

Returns the yaw of the camera in radians.

"Yaw" refers to the amount of rotation around the vertical (Y) axis.

virtual float Pitch ( void  ) const [virtual]

Returns the pitch of the current camera in radians.

"Pitch" refers to the amount of rotation around the horizontal axis running perpendicular to the direction of view. (i.e., tilting the camera up and down)

virtual float Roll ( void  ) const [virtual]

Returns the roll of the current camera in radians.

"Roll" refers to the amount of rotation around the camera's direction of view. (i.e., tilting the camera from side to side)

virtual Vector Position ( void  ) const [virtual]

Returns the position of the camera in world space.

Examples:
Turntable/Turntable.cpp.
virtual void SetYawPitchRoll ( const Vector vYPR ) [virtual]

Sets rotation of the camera, specified as yaw, pitch and roll values.

All values are in radians. The position of the camera remains unchanged.

"Yaw" refers to the amount of rotation around the vertical (Y) axis. "Pitch" refers to the amount of rotation around the horizontal axis running perpendicular to the direction of view. (i.e., tilting the camera up and down) "Roll" refers to the amount of rotation around the camera's direction of view. (i.e., tilting the camera from side to side)

Parameters:
[in] vYPR Yaw, Pitch and Roll values in radians
virtual void AddYawPitchRoll ( const Vector vYPR ) [virtual]

Add a rotation to the camera, specified as yaw, pitch and roll values.

All values are in radians. The position of the camera remains unchanged.

"Yaw" refers to the amount of rotation around the vertical (Y) axis. "Pitch" refers to the amount of rotation around the horizontal axis running perpendicular to the direction of view. (i.e., tilting the camera up and down) "Roll" refers to the amount of rotation around the camera's direction of view. (i.e., tilting the camera from side to side)

Parameters:
[in] vYPR Yaw, Pitch and Roll values in radians
virtual void SetForwardUpRight ( const Vector vForward,
const Vector vUp,
const Vector vRight 
) [virtual]

Sets the rotation of the camera, specified as three vectors.

The specified vectors do not need to be normalized, but they do need to be non-zero, and all orthographic to each other. Failure to do this will result in undefined or distorted camera views.

Parameters:
[in] vForward A vector pointing in the direction that the camera is to be facing
[in] vUp A vector pointing "up" relative to the camera.
[in] vRight A vector pointing "right" relative to the camera.
Examples:
Turntable/Turntable.cpp.
virtual void SetTarget ( const Vector vTarget,
const Vector vUpDir = Vector(0, 1, 0) 
) [virtual]

Set the rotation of the camera, by telling it what to point at.

The camera stays in its current position, but rotates so that the view direction points at the specified target. By default, the new "up" vector will be as close to vertical as possible, but you can override this to specify another up vector.

Parameters:
[in] vTarget A point in world space that the camera should face
[in] vUpDir The "up" vector for the new rotation.
Examples:
Turntable/Turntable.cpp.
virtual void SetPosition ( const Vector vPosition ) [virtual]

Set the location of the camera in world space.

Parameters:
[in] vPosition The camera's new position in world space.
Examples:
Turntable/Turntable.cpp.
virtual void MoveForward ( float  fRange ) [virtual]

Move the camera forward along its view direction. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual void MoveUp ( float  fRange ) [virtual]

Move the camera up. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual void MoveRight ( float  fRange ) [virtual]

Move the camera right. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual void MoveBackward ( float  fRange ) [virtual]

Move the camera backward along its view direction. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual void MoveDown ( float  fRange ) [virtual]

Move the camera down. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual void MoveLeft ( float  fRange ) [virtual]

Move the camera left. Its rotation remains unchanged.

Parameters:
[in] fRange The (world-space) distance to move the camera.
virtual Vector Project ( const Vector vWorldPosition ) const [virtual]

Takes a point in world space and returns its position in screen coordinates.

The X and Y values of the vector give the location in screen space. Screen space goes from (-1,-1) in the lower-left to (1,1) in the upper right, with (0,0) being the center of the screen.

The returned Z value represents the distance from the camera to the point. A value of 0.0 indicates the point is at the near clip plane, and a value of 1.0 places it at the far clip plane. Values outside the range 0 to 1 will not be visible (they would be clipped).

Parameters:
[in] vWorldPosition A point in world-space.
virtual Vector UnProject ( const Vector vScreenPosition ) const [virtual]

Takes a point in screen space and returns its position in world space.

Screen space goes from (-1,-1) in the lower-left to (1,1) in the upper right. The center of the screen is (0,0). The Z value in your specified screen-space point should be in the range 0.0 to 1.0. This will control the depth of the point. If you specify 0.0, the returned world space point will be on the near clipping plane. If you specifiy 1.0, the returned world space point will be on the far clipping plane.

Parameters:
[in] vScreenPosition The screen-space point to be transformed.
virtual mudbox::Matrix Matrix ( bool  bOffscreen = false ) const [virtual]

Returns the matrix used by the camera to transform world space positions to screen space.

Parameters:
[in] bOffscreen Used internally. Always set this to false.
virtual float FOV ( void  ) const [virtual]

Returns the vertical field of view in radians.

You can calculate the horizontal field of view like this:

     hFOV = atan( aspectRatio * tan(vFOV) );
Examples:
SampleViewportFilter/SampleViewportFilter.cpp.
virtual float Near ( void  ) const [virtual]

Returns the near clip plane distance from the camera.

Examples:
SampleViewportFilter/SampleViewportFilter.cpp.
virtual float Far ( void  ) const [virtual]

Returns the far clip plane distance from the camera.

Examples:
SampleViewportFilter/SampleViewportFilter.cpp.
virtual float AspectRatio ( void  ) const [virtual]

Returns the current aspect ratio of the viewport.

Aspect ratio is the width of the viewport divided by its height.

Examples:
SampleViewportFilter/SampleViewportFilter.cpp.
virtual void SetFOV ( float  fFOV ) [virtual]

Sets the vertical field of view of the camera.

Parameters:
[in] fFOV New vertical field of view in radians.
virtual void SetNear ( float  fNear ) [virtual]

Sets the near clip plane for the camera.

Parameters:
[in] fNear Distance from the camera in world units.
virtual void SetFar ( float  fFar ) [virtual]

Sets the far clip plane for the camera.

Parameters:
[in] fFar Distance from the camera in world units.
virtual void SetAspectRatio ( float  fAspectRatio ) [virtual]

Sets the aspect ratio for the camera.

The aspect ratio is the width of the viewport divided by the height.

Parameters:
[in] fAspectRatio the new aspect ratio for the camers (width/height)
virtual float Scale2D ( void  ) const [virtual]

Returns the 2d scale factor.

This is a scale factor that is applied to the scene after it is projected from world space into screen space. Normally this is 1.0.

virtual float Angle2D ( void  ) const [virtual]

Returns the 2d rotation amount.

This is a rotation that is applied to the scene after it is projected from world space into screen space. Rotation is around the point 0,0 in screen space. Positive values rotate clockwise. Returns the angle in radians.

virtual Vector Position2D ( void  ) const [virtual]

Returns the 2d offset.

This is an offset that is applied to the scene after it is projected from world space into screen space.

virtual void SetScale2D ( float  fScale2D ) [virtual]

Sets the 2d scale factor.

This is a scale factor that is applied to the scene after it is projected from world space into screen space. Changing this makes the image smaller or larger without affecting perspective in any way.

Parameters:
[in] fScale2D Amount by which to scale the screen image
virtual void SetAngle2D ( float  fAngle2D ) [virtual]

Sets the 2d rotation amount.

This is a rotation that is applied to the scene after it is projected from world space into screen space. Rotation is around the point 0,0 in screen space. Positive values rotate clockwise.

Parameters:
[in] fAngle2D Angle, in radians, by which to rotate the screen image
virtual void SetPosition2D ( const Vector vPosition2D ) [virtual]

Sets the 2d offset.

This is an offset that is applied to the scene after it is projected from world space into screen space. Applying a 2d offset lets you move the screen image around without changing perspective at all.

Parameters:
[in] vPosition2D New screen space position for the center of the screen image
virtual void CopyFrom ( const Camera cOther ) [virtual]

Make this camera identical to another one.

Parameters:
[in] cOther Camera to copy values from
virtual bool IsEqualTo ( const Camera cOther ) const [virtual]

Returns true if this camera is equal to the other one.

Parameters:
[in] cOther Camera to compare
virtual bool Pick ( float  fXPosition,
float  fYPosition,
SurfacePoint sResult 
) [virtual]

Returns the point displayed at the given screen location.

Given X and Y coordinates in screen space, this method sees if any geometry is displayed at those coordinates. If not, false is returned. If there is geometry there, true is returned, and sResult is set to contain information about the found geometry. SurfacePoint is defined in mesh.h

Parameters:
[in] fXPosition The X coordinate in screen space
[in] fYPosition The Y coordinate in screen space
[out] sResult Information about the picked point
virtual Vector Aim ( ) const [virtual]

Returns the world-space point around which the camera rolls when you navigate in the 3d view.

virtual void SetAim ( const Vector v ) [virtual]

Sets the point around which the camera will rotate when you navigate in the 3d view.

This point is changed by various navigation actions, such as panning the camera or using the F or A keys to reposition the camera.

Parameters:
[in] v World-space point around which the camera will rotate
virtual bool Orthographic ( ) const [virtual]

Returns true if the camera is orthographic.

virtual void SetOrthographic ( bool  isOrtho ) [virtual]

Sets the camera to be orthographic or perspective.

Parameters:
[in] isOrtho Set to make the camera orthographic, false to make it perspective

The documentation for this class was generated from the following file:

Camera Camera Camera Camera Camera Camera Camera Camera Camera Camera
Camera Camera Camera Camera Camera Camera Camera Camera Camera Camera