IPhysicalCamera_BitmapApertureSampler Class Reference

Utility class that provides efficient sampling for a bitmap aperture on the physical camera. More...

#include <IPhysicalCamera_BitmapApertureSampler.h>

Classes
class	IApertureBitmapAccess
	Interface used to provide generic access to the bitmap aperture. More...
struct	RGBValue
	A simple RGB color value. the Max SDK's Color class couldn't be used since we want to remain independent from the rest of the Max SDK. More...

Public Member Functions
	IPhysicalCamera_BitmapApertureSampler (IApertureBitmapAccess &aperture_bitmap_access, const float center_bias, const bool bitmap_affects_exposure)
	Constructs the sampler using the parameter values extracted from IPhysicalCamera and a callback interface used for fetching values from the aperture bitmap. More...
void	sample_aperture (const float sample_u, const float sample_v, float &sampled_position_u, float &sampled_position_v, RGBValue &sample_weight) const
	Samples a location in the aperture bitmap. More...
Access to sampling acceleration structure
These provide access to the internal acceleration structures, useful if the client uses this class for building the structures but wishes to implement its own sampling code Returns whether the sampling acceleration structure was built successfully. May be false, for example, if the aperture bitmap is all black.
bool	is_sampler_valid () const
	Returns the weights to be applied to the outgoing camera ray. More...
const std::vector< RGBValue > &	get_pixel_weights () const
	Returns the weights to be applied to the outgoing camera ray. More...
const std::vector< float > &	get_y_selection_cdf () const
	Returns the cumulative distribution function (CDF) used to select a row in the aperture bitmap. More...
const std::vector< float > &	get_x_selection_cdf () const
	Returns the cumulative distribution function (CDF) used to select a column, within a previously selected row, in the aperture bitmap. More...
const int	get_x_resolution () const
	Returns the resolution of the acceleration structure in X. More...
const int	get_y_resolution () const
	Returns the resolution of the acceleration structure in Y. More...

Detailed Description

Utility class that provides efficient sampling for a bitmap aperture on the physical camera.

When a bitmap aperture is used, uniformly sampling the aperture will result in massively reduced performance or increased noise. This class implements a smarter, weight-based sampling method which will introduce minimal performance degradation from using a bitmap aperture. This class is intended to be used in one of three ways: For directly sampling the bitmap aperture For building the sampling acceleration structures, and then using them in the shading code (e.g. if the shader cannot reference C++ code) As a reference for implementing your own sampler

Remarks

WARNING: This class makes no reference whatsoever to the rest of the Max SDK. This enables it to be used in a renderer's shading code without pulling in the Max SDK.

Constructor & Destructor Documentation

IPhysicalCamera_BitmapApertureSampler()

IPhysicalCamera_BitmapApertureSampler ( IApertureBitmapAccess &  aperture_bitmap_access, const float  center_bias, const bool  bitmap_affects_exposure  )

inline

Constructs the sampler using the parameter values extracted from IPhysicalCamera and a callback interface used for fetching values from the aperture bitmap.

Parameters

aperture_bitmap_access	The interface which provides access to contents of the aperture bitmap.
center_bias	The physical camera's aperture center bias, as returned by IPhysicalCamera::GetBokehCenterBias().
bitmap_affects_exposure	Whether the aperture bitmap affects exposure, as returned by IPhysicalCamera::GetBokehTextureAffectExposure().

    : m_sampler_valid(false),
    m_x_resolution(0),
    m_y_resolution(0)
{
    m_x_resolution = aperture_bitmap_access.get_x_resolution();
    m_y_resolution = aperture_bitmap_access.get_y_resolution();
 
    if((m_x_resolution > 0) && (m_y_resolution > 0))
    {
        const size_t num_pixels = size_t(m_x_resolution) * size_t(m_y_resolution);
        m_pixel_weight.resize(num_pixels);
        m_y_selection_cdf.resize(m_y_resolution);
        m_x_selection_cdf.resize(num_pixels);
 
        double original_bitmap_weight = 0.0f;   // use double as additions are terrible on floating-point precision
 
        // Accumulate the CDF for the entire bitmap
        double cdf_entire_bitmap = 0.0;     // use double as additions are terrible on floating-point precision
        for(size_t y = 0, pixel_index = 0; y < m_y_resolution; ++y)
        {
            // Accumulate the CDF for the current row
            double cdf_current_row = 0.0;       // use double as additions are terrible on floating-point precision
            for(unsigned int x = 0; x < m_x_resolution; ++x, ++pixel_index)
            {
                // Evaluate the pixel value
                const RGBValue original_pixel_value = aperture_bitmap_access.get_pixel_value(x, static_cast<unsigned int>(y));
                // Apply the center bias
                const RGBValue pixel_value_with_bias = apply_center_bias(original_pixel_value, center_bias, x, static_cast<unsigned int>(y), m_x_resolution, m_y_resolution);
 
                // Accumulate CDF using pixel value that has the center bias applied (sampling takes this bias into account)
                const float pixel_sampling_weight = get_sampling_weight(pixel_value_with_bias);
                cdf_current_row += pixel_sampling_weight;
                m_x_selection_cdf[pixel_index] = static_cast<float>(cdf_current_row);
                m_pixel_weight[pixel_index] = pixel_value_with_bias;
 
                // The original pixel value, without center bias, is accumulated such that we may undo its effect if "affect exposure" is disabled
                original_bitmap_weight += get_sampling_weight(original_pixel_value);
            }
 
            // Accumulate the CDF for the entire row
            cdf_entire_bitmap += cdf_current_row;
            m_y_selection_cdf[y] = static_cast<float>(cdf_entire_bitmap);
        }
 
        // Check whether the bitmap wasn't entirely black
        if(cdf_entire_bitmap > 0.0f)
        {
            // Normalize the CDFs
            for(size_t y = 0; y < m_y_resolution; ++y)
            {
                if(m_y_selection_cdf[y] > 0.0f)
                {
                    const float row_total_cdf = m_x_selection_cdf[(y * m_x_resolution) + m_x_resolution - 1];
                    if(row_total_cdf > 0.0f)
                    {
                        for(size_t x = 0, pixel_index = y * m_x_resolution; x < m_x_resolution; ++x, ++pixel_index)
                        {
                            m_x_selection_cdf[pixel_index] /= row_total_cdf;
                            assert(m_x_selection_cdf[pixel_index] <= 1.0f);
                        }
                    }
 
                    m_y_selection_cdf[y] /= m_y_selection_cdf[m_y_resolution - 1];
                    assert(m_y_selection_cdf[y] <= 1.0f);
                }
            }
 
            // Calculate the global weight to be applied to every pixel of the bitmap
            double global_bitmap_weight = 1.0;
            if(bitmap_affects_exposure)
            {
                // The bitmap's contents implicitly affect the the exposure since we multiply the ray result by the bitmap's pixel value.
                // Here we scale the bitmap's contents such that a bitmap containing a white circle would render identically 
                // to a circular aperture.
                global_bitmap_weight *= 1.0 / (M_PI * (0.5 * 0.5));        // one over the area of a disc with radius 0.5
 
                // If center bias is present, it has modified the texture but we don't want to let this affect exposure. We therefore
                // counteract the effect.
                global_bitmap_weight *= original_bitmap_weight / cdf_entire_bitmap;
            }
            else
            {
                // Because the bitmap's contents implicitly affect the exposure, here we counteract this such that the average
                // pixel value gets normalized to 1.0.
                const double bitmap_average_pixel_value = cdf_entire_bitmap / num_pixels;
                global_bitmap_weight /= bitmap_average_pixel_value;
            }
 
            // Calculate the final weight of every pixel in the bitmap
            for(size_t y = 0, pixel_index = 0; y < m_y_resolution; ++y)
            {
                // Probability of sampling this y coordinate
                const float previous_y_cdf = (y > 0) ? m_y_selection_cdf[y - 1] : 0.0f;
                const float y_sampling_prob = m_y_selection_cdf[y] - previous_y_cdf;
 
                for(unsigned int x = 0; x < m_x_resolution; ++x, ++pixel_index)
                {
                    // Apply the global weight (results from how we want exposure to be affected)
                    m_pixel_weight[pixel_index] *= static_cast<const float>(global_bitmap_weight);
                    
                    // Probability of sampling this x coordinate within the current row
                    const float previous_x_cdf = (x > 0) ? m_x_selection_cdf[pixel_index - 1] : 0.0f;
                    const float x_sampling_prob = m_x_selection_cdf[pixel_index] - previous_x_cdf;
 
                    // Probability of sampling this pixel overall
                    const double pixel_sampling_prob = double(x_sampling_prob) * double(y_sampling_prob);
 
                    // Compensate for the sampling probability of the pixel. Pixels should all have equal weight on the final result (photons
                    // have an equal likelihood of passing through any location on the aperture), but since we sample the aperture non-uniformly
                    // we need to compensate.
                    const double uniform_sampling_probability = (1.0 / num_pixels);
                    const double sample_compensation = (pixel_sampling_prob > 0.0f) ? (uniform_sampling_probability / pixel_sampling_prob) : 0.0;
                    m_pixel_weight[pixel_index] *= static_cast<const float>(sample_compensation);
                }
            }
 
            m_sampler_valid = true;
        }
    }
}

Member Function Documentation

sample_aperture()

void sample_aperture ( const float  sample_u, const float  sample_v, float &  sampled_position_u, float &  sampled_position_v, RGBValue &  sample_weight  ) const

inline

Samples a location in the aperture bitmap.

Parameters

	sample_u	The first random sample value, in [0,1)
	sample_v	The second random sample value, in [0,1)
[out]	sampled_position_u	Returns the the sampled position in U on the aperture in [-1,1]
[out]	sampled_position_v	Returns the the sampled position in V on the aperture in [-1,1]
[out]	sample_weight	Returns the weight of the sample that needs to be applied to the outgoing camera ray

{
    if(m_sampler_valid)
    {
        // Sample a row
        const float y_coord = sample_cdf_pixel(sample_v, m_y_selection_cdf.begin(), m_y_selection_cdf.end());
        assert(y_coord < m_y_resolution);
 
        // Sample a x coordinate within the selected row
        const std::vector<float>::const_iterator cdf_row_begin = m_x_selection_cdf.begin() + (size_t(y_coord) * m_x_resolution);
        const float x_coord = sample_cdf_pixel(sample_u, cdf_row_begin, cdf_row_begin + m_x_resolution);
        assert(x_coord < m_x_resolution);
 
        // Rescale sampled coordinate in [-1,1]
        sampled_position_u = ((x_coord / m_x_resolution) * 2.0f) - 1.0f;
        sampled_position_v = ((y_coord / m_y_resolution) * 2.0f) - 1.0f;
        assert((sampled_position_u >= -1.0f) && (sampled_position_u <= 1.0f) && (sampled_position_v >= -1.0f) && (sampled_position_v <= 1.0f));
 
        // Evaluate the aperture bitmap weight
        sample_weight = get_aperture_bitmap_weight(x_coord, y_coord);
        assert((sample_weight.r > 0.0f) || (sample_weight.g > 0.0f) || (sample_weight.b > 0.0f));
    }
    else
    {
        // Sampler not valid: sample center point only
        sampled_position_u = 0.0f;
        sampled_position_v = 0.0f;
        sample_weight = RGBValue(1.0f, 1.0f, 1.0f);
    }
}

is_sampler_valid()

bool is_sampler_valid ( ) const

inline

Returns the weights to be applied to the outgoing camera ray.

{
    return m_sampler_valid;
}

get_pixel_weights()

const std::vector< IPhysicalCamera_BitmapApertureSampler::RGBValue > & get_pixel_weights ( ) const

inline

Returns the weights to be applied to the outgoing camera ray.

{
    return m_pixel_weight;
}

get_y_selection_cdf()

const std::vector< float > & get_y_selection_cdf ( ) const

inline

Returns the cumulative distribution function (CDF) used to select a row in the aperture bitmap.

{
    return m_y_selection_cdf;
}

get_x_selection_cdf()

const std::vector< float > & get_x_selection_cdf ( ) const

inline

Returns the cumulative distribution function (CDF) used to select a column, within a previously selected row, in the aperture bitmap.

{
    return m_x_selection_cdf;
}

get_x_resolution()

const int get_x_resolution ( ) const

inline

Returns the resolution of the acceleration structure in X.

{
    return m_x_resolution;
}

get_y_resolution()

const int get_y_resolution ( ) const

inline

Returns the resolution of the acceleration structure in Y.

{
    return m_y_resolution;
}