I3DExLightsource Struct Reference
[External Interfaces]

Inheritance diagram for I3DExLightsource:


Public Member Functions
virtual MCCOMErr MCCOMAPI	SetTransform (TTransform3D *transform)=0
virtual MCCOMErr MCCOMAPI	GetDirection (const TVector3 &point, TVector3 &resultDirection, real &resultDistance)=0
virtual boolean MCCOMAPI	GetColor (const TVector3 &point, const TVector3 &direction, const real distance, TMCColorRGB &result, real &ShadowIntensity)=0
virtual boolean MCCOMAPI	IsVisibleInPerspective ()=0
virtual uint32 MCCOMAPI	GetPrimitiveID ()=0
virtual MCCOMErr MCCOMAPI	ForEachShadowBuffer (ForEachShadowBufferCallback proc, void *priv)=0
virtual MCCOMErr MCCOMAPI	GetLightParameter (int32 keyword, void *parameter)=0
virtual MCCOMErr MCCOMAPI	GetLightInfo (boolean &hasLightCone, boolean &hasLightSphere, real &halfAngle, TTransform3D &transform)=0
virtual boolean MCCOMAPI	GetUVfromDirection (TVector2 &uv, const TVector3 &direction) const =0
virtual LightTraceElement *MCCOMAPI	GetNewTrace (int16 *nb)=0
virtual MCCOMErr MCCOMAPI	GetStandardLight (TStandardLight &light) const =0
virtual void MCCOMAPI	InitSampling (const TBBox3D &sceneBoundingBox, real &solidAngle, int32 &regionCount)=0
virtual void MCCOMAPI	GetRandomRay (int32 regionIndex, Ray3D &ray) const =0
virtual int32 MCCOMAPI	GetShadowBufferCount () const =0
virtual void MCCOMAPI	GetShadowBuffer (int32 bufferIndex, I3DShCamera **camera, TBBox2D &uvBox) const =0

Detailed Description

Light sources define the lighting in a 3D scene. All kind of light sources can be designed: spot lights, bulb lights, distant lights (sun, moon), etc. Various features can be coded in a Light Source Extension, because the Light Source has complete control of the light intensity returned to the 3D Shell.

Light sources create light that illuminate object surfaces. The user can combine lights with gels to make additional lighting effects (see the I3DExLightsourceGel interface).

The structure of a light is a little bit more complex that the typical component. It is similar to the structure of Cameras and Primitives.

There are 2 COM objects to consider:

The Light Instance that supports I3DShLightsource, I3DShInstance and I3DShTreeElement.
The Light Component that supports IShComponent, I3DExLightsource and I3DShTreeElementMember

For advanced users: You should note that there are actually 3 C++ object (The light instance, the light component and the external light). However the light component and the external light are aggregated by COM which means that you can be considered as one single COM object).

To get a pointer to a I3DShLightsource from a I3DExLightsource, you can use the following code:

    TMCCountedPtr<I3DShTreeElementMember> lightComponent;
    exLight->QueryInterface(IID_I3DShTreeElementMember,(void**)&lightComponent);
    ThrowIfNil(lightComponent);
   
    TMCCountedPtr<I3DShTreeElement> lightTree;
    lightComponent->GetTreeElement(&lightTree);
    ThrowIfNil(lightTree);
   
    TMCCountedPtr<I3DShLightsource> shLight;
    lightTree->QueryInterface(IID_I3DShLightsource.(void**)&shLight);

To access I3DExLightsource from I3DShLightsource, you can use the following code:

    TMCCountedPtr<IShComponent> lightComponent;
    shLight->GetLightComponent(&lightComponent);
    ThrowIfNil(lightComponent);
   
    TMCCountedPtr<I3DExLightsource> exLight;
    lightComponent->QueryInterface(IID_I3DExLightsource,(void**)&exLight);

This code might seem a bit complicated at first but it is actually simple. You have two COM objects that point on each other. I3DShLightsource::GetLightComponent() and I3DShTreeElementMember::GetTreeElement() allow you to get a pointer from one object to the other. The rest is only calling QueryInterface to get the right interface on each object.

Whenever it is possible you should use the Shell interface (I3DShLightsource) to access the light because the Shell will make sure that the parameter map of the external component is valid. This is especially important if the component is animated. For more information on components see the Overview of the SDK.

See also:: I3DExLightsource

Member Function Documentation

virtual MCCOMErr MCCOMAPI I3DExLightsource::ForEachShadowBuffer ( ForEachShadowBufferCallback proc,

void * priv

) [pure virtual]

Deprecated:

Implemented in TBasicLight, and TBasicDistantLight.

virtual boolean MCCOMAPI I3DExLightsource::GetColor ( const TVector3 & point,

const TVector3 & direction,

const real distance,

TMCColorRGB & result,

real & ShadowIntensity

) [pure virtual]

Returns the color of light seen through a given point.
When using a spot, use the position parameter and the light source position and orientation to determine whether a point is in the light beam or not. When using a sun, use the direction parameter to calculate the intensity. When lighting is based on distance, (such as distance fall-off), use the distance parameter.

Parameters:

point The point on the surface for which the lighting is going to be calculated.

direction The direction from which the light arrives on the point (as calculated in GetDirection()).

distance The distance from the point to the light (as calculated in GetDirection()).

result The color of the light that reaches this point

ShadowIntensity The intensity of the shadow cast by that light

Implemented in TBasicLight, and TBasicDistantLight.

virtual MCCOMErr MCCOMAPI I3DExLightsource::GetDirection ( const TVector3 & point,

TVector3 & resultDirection,

real & resultDistance

) [pure virtual]

Returns the direction from the point to the light source as well as the distance between the surface point and light source. GetDirection() is called prior to GetColor() to perform preliminary calculations. The surface point is the point on the object where the light is about to be calculated.
A light bulb typically calculates resultDirection by subtracting the postion point to the light source origin, then normalizes the results. A simulated sun light returns its light direction in resultDirection, and the maximum possible value in resultDistance.

Parameters:

point The point on the surface for which the lighting is going to be calculated

resultDirection The direction from which the light arrives on the point

resultDistance The distance from the point to the light

Implemented in TBasicLight, and TBasicDistantLight.

virtual MCCOMErr MCCOMAPI I3DExLightsource::GetLightInfo ( boolean & hasLightCone,

boolean & hasLightSphere,

real & halfAngle,

TTransform3D & transform

) [pure virtual]

Returns information about light cones and sphere...

Parameters:

hasLightCone True on exit if the light supports a light cone (spot lights)

hasLightSphere True on ext if the light supports a light sphere (bulb lights)

halfAngle Half angle of the light cone if there is one

transform Global Transform of the light.

Implemented in TBasicLight.

virtual MCCOMErr MCCOMAPI I3DExLightsource::GetLightParameter ( int32 keyword,

void * parameter

) [pure virtual]

Deprecated:

Implemented in TBasicLight.

virtual LightTraceElement* MCCOMAPI I3DExLightsource::GetNewTrace ( int16 * nb ) [pure virtual]

Deprecated:

Parameters:

nb not used

Implemented in TBasicLight.

virtual uint32 MCCOMAPI I3DExLightsource::GetPrimitiveID ( ) [pure virtual]

Returns the ID of the primitive that is display in place of the light.
Implemented in TBasicLight, and TBasicDistantLight.

virtual void MCCOMAPI I3DExLightsource::GetRandomRay ( int32 regionIndex,

Ray3D & ray

) const [pure virtual]

Returns a random ray starting from the light The rays should sample uniformly a solid angle that contains at least the intersection of the light cone (or sphere) and the scene.

Note:
Must be called after InitSampling

Parameters:

ray A reference to the ray that should be returned

regionIndex Index of the region in which the ray should be picked

Implemented in TBasicLight, and TBasicDistantLight.

virtual void MCCOMAPI I3DExLightsource::GetShadowBuffer ( int32 bufferIndex,

I3DShCamera ** camera,

TBBox2D & uvBox

) const [pure virtual]

Returns a camera equivalent to a shadow buffer

Parameters:

bufferIndex index of the shadow buffer (0 based)

camera returns a pointer to the camera corresponding to the shadow buffer

uvBox returns the box in screen coordinates corresponding to the shadow buffer

Implemented in TBasicLight, and TBasicDistantLight.

virtual int32 MCCOMAPI I3DExLightsource::GetShadowBufferCount ( ) const [pure virtual]

Returns the number of shadow buffer needed for this light
Implemented in TBasicLight, and TBasicDistantLight.

virtual MCCOMErr MCCOMAPI I3DExLightsource::GetStandardLight ( TStandardLight & light ) const [pure virtual]

Retrieves a standard description of the light for use in the interactive renderer.

Parameters:

light A reference to the simplified description of the light for the interactive rendering

Implemented in TBasicLight, and TBasicDistantLight.

virtual boolean MCCOMAPI I3DExLightsource::GetUVfromDirection ( TVector2 & uv,

const TVector3 & direction

) const [pure virtual]

returns the uv for the gel given a direction

Parameters:

uv The uv that are returned.

direction The direction as calculated in GetDirection()

Implemented in TBasicLight, and TBasicDistantLight.

virtual void MCCOMAPI I3DExLightsource::InitSampling ( const TBBox3D & sceneBoundingBox,

real & solidAngle,

int32 & regionCount

) [pure virtual]

Initialize sampling of the light and returns the solid angle containing the sampling rays. It must be called before GetRandomRay

Parameters:

sceneBoundingBox The bounding box of the scene

solidAngle Returns the solid Angle of the sampling rays

regionCount Returns the number of region for ray sampling (each region represent an equal number of rays)

Implemented in TBasicLight, and TBasicDistantLight.

virtual boolean MCCOMAPI I3DExLightsource::IsVisibleInPerspective ( ) [pure virtual]

Returns true if the light should be displayed in the 3D View. In this case, the lights is displayed with the geometry of the primitive given by GetPrimitiveID().
If it returns false, then the light is not displayed, this is used for sun lights for example.
Implemented in TBasicLight, and TBasicDistantLight.

virtual MCCOMErr MCCOMAPI I3DExLightsource::SetTransform ( TTransform3D * transform ) [pure virtual]

Called to tell a light source its position and orientation in space. This function is used to cache transform information to speed up GetDirection() and GetColor().

Parameters:

transform A pointer to the Global Transform of the light

Implemented in TBasicLight, and TBasicDistantLight.

The documentation for this struct was generated from the following file:

I3dExLight.h

Generated on Mon Mar 14 12:29:01 2005 for Carrara SDK Doc by

1.3.9.1

I3DExLightsource Struct Reference [External Interfaces]

Public Member Functions

Detailed Description

Member Function Documentation

I3DExLightsource Struct Reference
[External Interfaces]