camera.h

Go to the documentation of this file.

/*
    toxic - A Global Illumination Renderer
    Copyright (C) 2003-2004 Francois Beaune
    Contact: http://toxicengine.sourceforge.net/

    This file is part of toxic.

    toxic is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    toxic is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with toxic; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef TOXIC_RENDERER_CAMERA_H
#define TOXIC_RENDERER_CAMERA_H

#include "common/math/matrix4.h"
#include "common/math/point2.h"
#include "common/math/point3.h"
#include "common/math/real.h"
#include "common/math/vector3.h"
#include "basis.h"
#include "globals.h"

namespace toxic {

    class Context;
    class Ray;
    class Scene;

    const sheep::Real DEFAULT_CAMERA_HFOV = sheep::dtor(70.0);
    const sheep::Real DEFAULT_CAMERA_ASPECT_RATIO = 4.0 / 3.0;  // 1.33333...

    //! Normalized Device Coordinates (NDC) are normalized pixel coordinates so
    //! that x and y both run from -0.5 to +0.5 across the entire (uncropped)
    //! image, with (-0.5, -0.5) being at the lower left of the image, and
    //! (0.5, 0.5) being at the upper right of the image (regardless of the
    //! aspect ratio).

    //! The camera is located at the origin and looks toward Z-.
    class Camera : public Basis {
    public:
        //! m is the object space to world space transformation matrix.
        Camera(
            const sheep::Matrix4 &m,
            sheep::Real hfov = DEFAULT_CAMERA_HFOV,
            sheep::Real aspect_ratio = DEFAULT_CAMERA_ASPECT_RATIO);

        //! This method must be called only once, after the camera is completely
        //! configured, and before it is used for the first time.
        void Finalize(
            const Context &context,
            const Scene *scene);

        //! Enables depth of field. From "The RenderMan Interface Version 3.2":
        //! 'focal_distance' sets the distance along the direction of view at which objects
        //! will be in focus. 'focal_length' sets the focal length of the camera. These two
        //! parameters should have the units of distance along the view direction in camera
        //! coordinates. 'fstop', or aperture number, determines the lens diameter:
        //! lens_diameter = focal_length / fstop.
        //!\todo Create a new camera class for thin lens camera.
        void EnableDepthOfField(
            sheep::Real fstop,
            sheep::Real focal_length,
            sheep::Real focal_distance);

        //! Enables autofocus. Autofocus computes the right focal distance so that point of
        //! the scene visible through point 'p' is in focus plane. 'p' is a point on the
        //! film plane, expressed in NDC.
        //!\todo Create a new camera class for thin lens camera.
        void EnableAutoFocus(const sheep::Point2 &p);

        //! Returns a ray whose origin is at camera location, and which
        //! is directed toward the point 'p'. 'p' is a point on the film
        //! plane. It is expressed in NDC. The returned ray is expressed
        //! in world space. The direction of the returned ray IS unit-length.
        Ray ComputeRay(const Context &context, const sheep::Point2 &p) const;

        sheep::Point2 Project(const sheep::Point3 &p) const;

    private:
        sheep::Point3 m_location;           //!< Location of the camera, expressed in world space.
        sheep::Vector3 m_ex, m_ey, m_ez;    //!< Basis vectors, expressed in world space. m_ex is scaled by the aspect ratio.
        sheep::Vector3 m_u, m_w;            //!< m_u = m_ex * m_aspect_ratio, m_w = m_ez * (-m_focal_length).

        //! Frustum parameters.
        sheep::Real m_hfov;                 //!< User defined horizontal field of view, expressed in radians.
        sheep::Real m_aspect_ratio;         //!< User defined aspect ratio.
        sheep::Real m_focal_length;         //!< Lens focal length (computed from horizontal field of view and aspect ratio values).

        //! Depth of field parameters.
        bool m_is_dof_enabled;              //!< True if depth of field is enabled, false otherwise.
        sheep::Real m_dof_fstop;            //!< User defined f-stop number.
        sheep::Real m_dof_focal_length;     //!< User defined focal length (distinct from m_focal_length).
        sheep::Real m_dof_focal_distance;   //!< User defined distance of the focus plane from the lens center.
        sheep::Real m_dof_lens_radius;      //!< Lens radius (computed from DOF focal length value and f-stop number).
        bool m_is_autofocus_enabled;        //!< True if autofocus is enabled, false otherwise.
        sheep::Point2 m_autofocus_target;   //!< Focus point, expressed in NDC. Used only by the autofocus mechanism.
    };

#include "camera.inl"

}

#endif  // !TOXIC_RENDERER_CAMERA_H

---