/****************************************************************************************************

		I3DExVolumetricEffect.h
		Copyright: (c) 2001 Eovia Corp. All rights reserved.

		Author:	Charles
		Date:	10/10/2002

****************************************************************************************************/

#ifndef __I3DExVolumetricEffect__
#define __I3DExVolumetricEffect__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "MCCompObj.h"
#include "InterfaceIDs.h"
#include "Vector3Fwd.h"

struct I3DShScene;
struct I3DExRaytracer;

class TMCColorRGBA;

//****** Globally Unique Ids **************************************************

MCDEFINE_GUID2(IID_I3DExVolumetricEffect, R_IID_I3DExVolumetricEffect);

//*****************************************************************************

/// \addtogroup ExternalInterface
///
/// \{


/// <P>A volumetric effect is an effect that is applied to simulate volume effects
/// such as light cones, light spheres, volumetric aura that are attached to an
/// object, a light or a camera...</P>
///
/// <P>At the beginning of the rendering of a frame, the shell go through all the 
/// data components (see I3DExDataComponent) of the lights, cameras and primitives 
/// and ask them if a volumetric effect should be created by calling GetVolumetricList().</P>
///
/// <P>It then creates one volumetric effect of each kind. The volumetric effects are
/// then called for each ray to determine its effects on the light going through
/// the ray.</P>
///
struct I3DExVolumetricEffect: public IMCUnknown
{	
	/// This function is called at the beginning of the rendering of a frame.
	/// It allows you to create caches for your effect
	///
	/// \param scene		A pointer to the scene to which the effect belongs
	///
	virtual void MCCOMAPI Initialise(I3DShScene* scene)=0;
	
	/// OBSOLETE: use DirectionFilter2 instead. Only left for compatibility between
	/// Carrara 5.0.1 and 5.1, should be removed in Carrara 6.
	///
	virtual void MCCOMAPI DirectionFilter(const TVector3&	origin,
										  const TVector3&	direction,
										  real				maxt,
										  TMCColorRGBA&		inOutFilter,
										  boolean			isShadowCasting) = 0;


	// ****************************************************************************
	//								DirectionFilter2
	// 
	/// 
	/// This function should filter a color with the volumetricEffect. When the function
	/// is called, inOutFilter contains the color of an object at the end point. When it
	/// returns inOutFilter should have been modified to include the filtering effect.
	///
	/// \param raytracer        a pointer to the current raytracer
	/// \param origin			point from which we see
	/// \param direction		direction in which we look
	/// \param maxt				the parametric coordinate of the end point on the ray: endpoint = origin + maxt * direction
	/// \param inOutFilter		color of the end point (when called), color after filtering (when returning)
	/// \param isShadowCasting	True if this is a shadow ray
	/// 
	virtual void MCCOMAPI DirectionFilter2(I3DExRaytracer*	raytracer,
										  const TVector3&	origin,
										  const TVector3&	direction,
										  real				maxt,
										  TMCColorRGBA&		inOutFilter,
										  boolean			isShadowCasting) = 0;

};

/// \}



#endif
