function retIrradiance_PowerPerArea = RadianceAndPupilAreaEyeLengthToRetIrradiance(radiance_PowerPerAreaSr,radianceS,pupilArea,eyeLength)
% retIrradiance_PowerPerArea = RadianceAndPupilAreaEyeLengthToRetIrradiance(radiance_PowerPerAreaSr,radianceS,pupilArea,eyeLength)
%
% Perform the geometric calculations necessary to convert a measurement of source
% radiance to corresponding retinal irradiance. 
%
% Let x be the units of distance (m, cm, mm, um, etc.)
%
%   Input radiance_PowerPerAreaSr should be in units of power/x^2-sr-wlinterval.
%   Input radianceS gives the wavelength sampling information (nm).
%   Input pupilArea should be in units of x^2.
%   Input eyeLength should be the length of the eye in units of x
%
%   Output retIrradiance_PowerPerArea is in units of power/x^2-wlinterval.
%
%   Light power may be expressed in watts or quanta-sec or in your
%   favorite units.  Indeed, it may also be passed as energy rather
%   than power.  
%
% This conversion does not take absorption in the eye into account,
% as this is more conveniently foldeded into the spectral absorptance.
%
% The wavelength sampling is not needed or used, and the world would be a
% better place if it were not passed.  But taking it out of the arg list
% now would probably break a number of calling programs in an irritating
% manner.
%
% See also: PsychRadiometric, RetIrradianceAndPupilAreaEyeLengthToRadiance, PupilAreaFromLum, EyeLength.
%
% 3/6/13  dhb  Wrote it.

% Define factor to convert radiance spectrum to retinal irradiance
% Commented out code shows the logic, which is short circuited by actual code.
% but is conceptually convenient for doing the calculation.
%  distanceToSource = 100;
%  fractionfSphere = pupilArea/4*pi*distanceToSource^2;
%  pupilAreaSR = 4*pi*fractionOfSphere;
%  sourceArea = (distanceToSource^2)/(eyeLength^2);
%  conversionFactor = pupilAreaSR*sourceArea;
conversionFactor = pupilArea/(eyeLength^2);
retIrradiance_PowerPerArea = conversionFactor*radiance_PowerPerAreaSr;