photonmap.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_PHOTONMAP_H
#define TOXIC_RENDERER_PHOTONMAP_H

#include "common/math/aabb3.h"
#include "common/math/real.h"
#include "common/math/vector3.h"
#include "common/misc/progressmonitor.h"
#include "common/misc/types.h"
#include "color3.h"
#include "globals.h"
#include "photon.h"

#include <cassert>
#include <string>
#include <vector>

namespace toxic {

    class Context;
    class ShadingData;
    class SurfaceBasis;

    //! The photon map implementation is based on the reference implementation
    //! provided by Henrik Wann Jensen in his book "Realistic Image Synthesis
    //! Using Photon Mapping".

    class PhotonMap {
    public:
        PhotonMap();
        ~PhotonMap();

        //! Returns the size (in bytes) of the photon map in memory.
        int GetSizeInMemory() const;

        //! Creates and stores a photon into the photon map. 'direction' must
        //! be unit-length. Both 'position' and 'direction' must be expressed
        //! in world space. The power is expressed in W.
        void StorePhoton(
            const sheep::Point3 &position,
            const Color3 &power,
            const sheep::Vector3 &direction
#ifdef ENABLE_RADIANCES_PRECOMPUTATION
            , const sheep::Vector3 &normal
#endif  // ENABLE_RADIANCES_PRECOMPUTATION
            );

        //! This method is used to scale the power of all photons once they have
        //! been emitted from the light source.
        //! scale = 1 / (#emitted photons)
        //! Call this function after each light source is processed.
        void ScalePhotonPower(sheep::Real scale);

        //! Creates a left-balanced kd-tree from the flat array of photons.
        //! This function must be called prior to calling any of the ComputeRadiance(),
        //! ApproximateRadiance(), PrecomputeRadiances() and GetPrecomputedRadiance()
        //! methods.
        void Balance();

        //! Computes the radiance reflected toward a given direction due to the
        //! photon density on a given surface, around a given point. This is the
        //! slowest but the most accurate method to compute the reflected radiance
        //! in a given direction. The point, the surface normal and the outgoing
        //! direction are expressed in world space. The outgoing direction is such
        //! that it leaves the surface, and it is unit-length. The returned value
        //! is a radiance (W.m^-2.sr^-1).
        Color3 ComputeRadiance(
            const Context &context,
            const sheep::Point3 &point,
            const sheep::Vector3 &normal,
            const sheep::Vector3 &outgoing,
            const ShadingData &shadingdata,
            sheep::Real max_dist,
            int max_photons) const;

        //! Same as the ComputeRadiance() method, except that the surface is
        //! considered as a perfect lambertian surface. This method is faster
        //! than the ComputeRadiance() method, but it is also less accurate.
        //! The point and the surface normal are expressed in world space. The
        //! returned value is a radiance (W.m^-2.sr^-1).
        Color3 ApproximateRadiance(
            const sheep::Point3 &point,
            const sheep::Vector3 &normal,
            const ShadingData &shadingdata,
            sheep::Real max_dist,
            int max_photons) const;

#ifdef ENABLE_RADIANCES_PRECOMPUTATION

        //! Precomputes the reflected radiance at photons location. This method
        //! calls the ApproximateRadiance() to compute the reflected radiance at
        //! a given photon's location, thus the surface carrying the photon is
        //! considered as a perfect lambertian surface. Be sure to call the
        //! Balance() method prior to calling this method, and be sure to call this
        //! method prior to the first call of the GetPrecomputedRadiance() method.
        void PrecomputeRadiances(
            int spacing,
            sheep::Real max_dist,
            int max_photons,
            sheep::ProgressMonitor *progmon = 0);

        //! Same as the ApproximateRadiance() method, but several times faster.
        //! The point and the surface normal are expressed in world space. The
        //! returned value is a radiance (W.m^-2.sr^-1). Be sure to call the
        //! PrecomputeRadiances() method prior to calling this method.
        Color3 GetPrecomputedRadiance(
            const sheep::Point3 &point,
            const sheep::Vector3 &normal,
            const ShadingData &shadingdata,
            sheep::Real max_dist) const;

#endif  // ENABLE_RADIANCES_PRECOMPUTATION

        void BuildPhotonDirectionHistogram(
            const sheep::Point3 &position,
            const SurfaceBasis &surfacebasis,
            sheep::Real max_dist,
            int max_photons,
            sheep::Real *histogram,
            int m, int n,
            sheep::Real *total_power) const;

        //! Writes the photon map to disk. Returns true if writing was successful.
        bool WriteToFile(
            const std::string &filename,
            sheep::ProgressMonitor *progmon = 0) const;

        //! Creates a photon map by reading it from disk. Returns a pointer to the
        //! newly created photon map if successful, and 0 otherwise.
        static PhotonMap *CreateFromFile(
            const std::string &filename,
            sheep::ProgressMonitor *progmon = 0);

        int GetPhotonCount() const;
        const Photon &GetPhoton(int i) const;

    private:
        int m_stored_photons;
        int m_half_stored_photons;
        int m_prev_scale;

        //! The array of photons.
        std::vector<Photon> m_photons;

        //! Bounding box of the photon array.
        sheep::float32 m_bbox_min[3];
        sheep::float32 m_bbox_max[3];

        //! Some buffers used by the IrradianceEstimate() method.
        enum { BUF_SIZE = 10000 };
        sheep::float32 *m_dist2_buf;
        const Photon **m_index_buf;

        //! Signature string identifying photon map files.
        static const std::string m_photon_map_sig;

        //! median_split() splits the photon array into two separate pieces
        //! around the median, with all photons below the median in the
        //! lower half and all photons above the median in the upper half.
        //! The comparison criteria is the axis (indicated by the axis
        //! parameter). Inspired by routine in "Algorithms in C++" by
        //! Sedgewick.
        void median_split(
            Photon **p,
            int start, int end,
            int median,
            int axis) const;

        //! See "Realistic Image Synthesis Using Photon Mapping" chapter 6
        //! for an explanation of this function.
        void balance_segment(
            Photon **pbal,
            Photon **porg,
            int index,
            int start, int end);

        //! This structure is used only to locate the nearest photons.
        struct nearest_photons {
            int m_max;
            int m_found;
            int m_got_heap;
            sheep::float32 m_position[3];
            sheep::float32 *m_dist2;
            const Photon **m_index;
        };

        //! locate_photons() finds the nearest photons in the photon map
        //! given the parameters in np.
        void locate_photons(nearest_photons *np, int index) const;

#ifdef ENABLE_RADIANCES_PRECOMPUTATION

        void locate_nearest_photon_with_irradiance(
            const sheep::Vector3 &normal,
            nearest_photons *np,
            int index) const;

#endif  // ENABLE_RADIANCES_PRECOMPUTATION
    };

#include "photonmap.inl"

}

#endif  // !TOXIC_RENDERER_PHOTONMAP_H

---