I3DShLightsource Struct Reference
[Shell Interfaces]

Inheritance diagram for I3DShLightsource:
IMCUnknown

List of all members.

Public Member Functions

virtual MCCOMErr MCCOMAPI GetLightGlobalTransform (TTransform3D *transform)=0
virtual MCCOMErr MCCOMAPI ForEachShadowBuffer (ForEachShadowBufferCallback proc, void *priv)=0
virtual MCCOMErr MCCOMAPI GetLightParameter (int32 keyword, void *parameter)=0
virtual MCCOMErr MCCOMAPI GetPrimitiveID (int32 &primID)=0
virtual MCCOMErr MCCOMAPI GetNewTrace (int16 &nb, TLightTraceElement *&traceElem)=0
virtual I3DExLightsource *MCCOMAPI GetValidExLightNoAddRef ()=0
virtual boolean MCCOMAPI GetDirection (const TVector3 &position, TVector3 &resultDirection, real &resultDistance)=0
virtual boolean MCCOMAPI GetColor (const TVector3 &position, const TVector3 &direction, const real distance, TMCColorRGB &result, real &shadowIntensity)=0
virtual MCCOMErr MCCOMAPI SetGelComponentByID (int32 kindID)=0
virtual MCCOMErr MCCOMAPI SetGelComponent (I3DShLightsourceGel *gel, ECloneMode cloneMode)=0
virtual void MCCOMAPI GetGelComponent (I3DShLightsourceGel **gel)=0
virtual MCCOMErr MCCOMAPI SetShadowFeatureByID (int32 kindID)=0
virtual MCCOMErr MCCOMAPI SetShadowFeature (I3DShShadowFeature *feature, ECloneMode cloneMode)=0
virtual void MCCOMAPI GetShShadowFeature (I3DShShadowFeature **feature)=0
virtual void MCCOMAPI GetExShadowFeature (I3DExShadowFeature **feature)=0
virtual MCCOMErr MCCOMAPI SetLightComponentByID (int32 kindID)=0
virtual MCCOMErr MCCOMAPI SetLightComponent (IShComponent *component, ECloneMode cloneMode)=0
virtual MCCOMErr MCCOMAPI GetLightComponent (IShComponent **component)=0
virtual IShComponent *MCCOMAPI GetLightComponent ()=0
virtual MCCOMErr MCCOMAPI GetLightInfo (boolean &hasLightCone, boolean &hasLightSphere, real &halfAngle, TTransform3D &transform)=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)=0
virtual int32 MCCOMAPI GetShadowBufferCount ()=0
virtual void MCCOMAPI GetShadowBuffer (int32 bufferIndex, I3DShCamera **camera, TBBox2D &uvBox)=0
virtual boolean MCCOMAPI IsVisibleInPerspective ()=0
virtual I3DShTreeElement *MCCOMAPI GetTreeElement ()=0
virtual boolean MCCOMAPI ShouldLightInstance (I3DShInstance *instance) const =0
virtual const TTreeIdPathList
&MCCOMAPI 
GetRestrictedList (boolean &isExclusion) const =0
virtual void MCCOMAPI SetRestrictedList (const TTreeIdPathList &newList)=0
virtual void MCCOMAPI SetIsExclusion (boolean isExclusion)=0
virtual boolean MCCOMAPI CouldExcludeInstance () const =0
virtual real MCCOMAPI UpdateLightRadius (const real radiusFromShadowFeature)=0
virtual MCCOMErr MCCOMAPI GetPhotometricProfile (I3DExPhotometricProfile **profile)=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:

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 boolean MCCOMAPI I3DShLightsource::CouldExcludeInstance (  )  const [pure virtual]

Return false if ShouldLightInstance will always return true

virtual MCCOMErr MCCOMAPI I3DShLightsource::ForEachShadowBuffer ( ForEachShadowBufferCallback  proc,
void *  priv 
) [pure virtual]
virtual boolean MCCOMAPI I3DShLightsource::GetColor ( const TVector3 position,
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:
position 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.
virtual boolean MCCOMAPI I3DShLightsource::GetDirection ( const TVector3 position,
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 position 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:
position 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
virtual void MCCOMAPI I3DShLightsource::GetExShadowFeature ( I3DExShadowFeature **  feature  )  [pure virtual]

Returns a pointer to the external Shadow feature. This call is equivalent to calling GetShShadowFeature and then QueryInterface(IID_I3DExShadowFeature,...) on the result.

Parameters:
feature A pointer to the shadow feature.
virtual void MCCOMAPI I3DShLightsource::GetGelComponent ( I3DShLightsourceGel **  gel  )  [pure virtual]

Returns the Gel component attached to this light.

Parameters:
gel The gel component.
virtual IShComponent* MCCOMAPI I3DShLightsource::GetLightComponent (  )  [pure virtual]

Returns a pointer to the light component associated with this instance. (Note : no AddRef)

Returns:
A pointer to the light component.
virtual MCCOMErr MCCOMAPI I3DShLightsource::GetLightComponent ( IShComponent **  component  )  [pure virtual]

Returns a pointer to the light component associated with this instance.

Parameters:
component A pointer to the light component.
virtual MCCOMErr MCCOMAPI I3DShLightsource::GetLightGlobalTransform ( TTransform3D transform  )  [pure virtual]

Returns the global transform of the light.

Parameters:
transform The global transform of the light.
virtual MCCOMErr MCCOMAPI I3DShLightsource::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.
virtual MCCOMErr MCCOMAPI I3DShLightsource::GetLightParameter ( int32  keyword,
void *  parameter 
) [pure virtual]

Returns the value of a given parameter of the light.

Parameters:
keyword The identifier of the parameter
parameter A point to a buffer that can store the parameter value.
virtual MCCOMErr MCCOMAPI I3DShLightsource::GetNewTrace ( int16 nb,
TLightTraceElement *&  traceElem 
) [pure virtual]
virtual MCCOMErr MCCOMAPI I3DShLightsource::GetPhotometricProfile ( I3DExPhotometricProfile **  profile  )  [pure virtual]

Get the photometric profile attached to this light

virtual MCCOMErr MCCOMAPI I3DShLightsource::GetPrimitiveID ( int32 &  primID  )  [pure virtual]

Returns the ID of the primitive that is displayed in place of the light.

Parameters:
primID The ID of the primitive that is displayed in place of the light.
virtual void MCCOMAPI I3DShLightsource::GetRandomRay ( int32  regionIndex,
Ray3D ray 
) [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:
regionIndex Index of the region in which the ray should be picked
ray A reference to the ray that should be returned
virtual const TTreeIdPathList& MCCOMAPI I3DShLightsource::GetRestrictedList ( boolean isExclusion  )  const [pure virtual]

Return the list of the only instances that should get light or of the instances that won't

Parameters:
isExclusion true if the instances listed are to be excluded
virtual void MCCOMAPI I3DShLightsource::GetShadowBuffer ( int32  bufferIndex,
I3DShCamera **  camera,
TBBox2D uvBox 
) [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
virtual int32 MCCOMAPI I3DShLightsource::GetShadowBufferCount (  )  [pure virtual]

Returns the number of shadow buffer needed for this light

virtual void MCCOMAPI I3DShLightsource::GetShShadowFeature ( I3DShShadowFeature **  feature  )  [pure virtual]

Returns the Shadow feature attached to this light.

Parameters:
feature A pointer to the shadow feature.
virtual MCCOMErr MCCOMAPI I3DShLightsource::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
virtual I3DShTreeElement* MCCOMAPI I3DShLightsource::GetTreeElement (  )  [pure virtual]

Returns the I3DShTreeElement interface. This call is faster than calling QueryInterface.

virtual I3DExLightsource* MCCOMAPI I3DShLightsource::GetValidExLightNoAddRef (  )  [pure virtual]

Returns a valid external light for the current time (to by pass the app for speed) You should use this call with extreme caution: It assumes nothing will be changed in the scene while you use the external interface. In particular, if the time is changed you should call this function to get a new pointer.

Returns:
A pointer to a valid external light source. Not that it returns null if the light is not active in the current scene.
virtual void MCCOMAPI I3DShLightsource::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)
virtual boolean MCCOMAPI I3DShLightsource::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.

virtual MCCOMErr MCCOMAPI I3DShLightsource::SetGelComponent ( I3DShLightsourceGel gel,
ECloneMode  cloneMode 
) [pure virtual]

Sets the Gel component attached to this light.

Parameters:
gel The gel component
cloneMode The clone mode (see ECloneMode)
virtual MCCOMErr MCCOMAPI I3DShLightsource::SetGelComponentByID ( int32  kindID  )  [pure virtual]

Sets the type of Gel component attached to this light.

Parameters:
kindID The class ID of the Gel attached to this light
virtual void MCCOMAPI I3DShLightsource::SetIsExclusion ( boolean  isExclusion  )  [pure virtual]

Set the mode for the restricted list

Parameters:
isExclusion 
virtual MCCOMErr MCCOMAPI I3DShLightsource::SetLightComponent ( IShComponent component,
ECloneMode  cloneMode 
) [pure virtual]

Sets the light component associated with this instance.

Parameters:
component A pointer to the light component.
cloneMode The clone mode (see ECloneMode).
virtual MCCOMErr MCCOMAPI I3DShLightsource::SetLightComponentByID ( int32  kindID  )  [pure virtual]

Sets the type of the light (Buld, Distance, Spot...).

Parameters:
kindID The Class ID of the light.
virtual void MCCOMAPI I3DShLightsource::SetRestrictedList ( const TTreeIdPathList newList  )  [pure virtual]

Restrict the lightening to these instances if mode is inclusion, or restrict to all instances except these ones if mode is exclusion

Parameters:
newList the list of instances
virtual MCCOMErr MCCOMAPI I3DShLightsource::SetShadowFeature ( I3DShShadowFeature feature,
ECloneMode  cloneMode 
) [pure virtual]

Sets the Shadow feature attached to this light.

Parameters:
feature A pointer to the shadow feature.
cloneMode The clone mode (see ECloneMode)
virtual MCCOMErr MCCOMAPI I3DShLightsource::SetShadowFeatureByID ( int32  kindID  )  [pure virtual]

Sets the type of Shadow feature attached to this light.

Parameters:
kindID The class ID of the Shadow feature attached to this light
virtual boolean MCCOMAPI I3DShLightsource::ShouldLightInstance ( I3DShInstance instance  )  const [pure virtual]

Return true if the light should consider this instance for lighting.

Parameters:
instance the instance that ask for light
virtual real MCCOMAPI I3DShLightsource::UpdateLightRadius ( const real  radiusFromShadowFeature  )  [pure virtual]

Calculates a corrected radius for soft shadows. This is used in particular for distant lights to rescale the parameter

Parameters:
radiusFromShadowFeature radius of the light as specified by the user in the shadow feature

The documentation for this struct was generated from the following file:
Generated on Mon Apr 26 22:47:40 2010 for Carrara SDK Doc by  doxygen 1.6.3