Class GenLight
See Also: Class LightObject, Class NameTab, Class Control, Class Interval, Class Point3, Class ObjLightDesc.
class GenLight : public LightObject
Description:
This class describes a generic light object. It is used as a base class for creating plug-in lights. Methods of this class are used to get and set properties of the light. All methods of this class are implemented by the plug-in.
Methods:
Prototype:
virtual GenLight *NewLight(int type)=0;
Remarks:
Creates a new light object of the specified type.
Parameters:
int type
One of the following values:
OMNI_LIGHT -- Omnidirectional light.
TSPOT_LIGHT -- Targeted spot light.
DIR_LIGHT -- Directional light.
FSPOT_LIGHT -- Free spot light.
TDIR_LIGHT -- Targeted directional light.
Return Value:
A pointer to a new instance of the specified light type.
Prototype:
virtual int Type()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the type of light this is.
Return Value:
One of the following values:
OMNI_LIGHT -- Omnidirectional light.
TSPOT_LIGHT -- Targeted spot light.
DIR_LIGHT -- Directional light.
FSPOT_LIGHT -- Free spot light.
TDIR_LIGHT -- Targeted directional light.
Prototype:
virtual BOOL IsSpot()=0;
Remarks:
Returns TRUE if the light is a spotlight; otherwise FALSE.
Prototype:
virtual BOOL IsDir()=0;
Remarks:
Returns TRUE if the light is directional; otherwise FALSE.
Prototype:
virtual void SetUseLight(int onOff)=0;
Remarks:
Sets the light on or off.
Parameters:
int onOff
Nonzero sets the light on; zero sets it off.
Prototype:
virtual BOOL GetUseLight(void)=0;
Remarks:
Returns TRUE if the light is on; otherwise FALSE.
Prototype:
virtual void SetSpotShape(int s)=0;
Remarks:
Sets the shape used for a spotlight, either rectangular or circular.
Parameters:
int s
One of the following values:
RECT_LIGHT
CIRCLE_LIGHT
Prototype:
virtual int GetSpotShape(void)=0;
Remarks:
Retrieves the shape used for a spotlight.
Return Value:
One of the following values:
RECT_LIGHT
CIRCLE_LIGHT
Prototype:
virtual void SetHotspot(TimeValue time, float f)=0;
Remarks:
Sets the hotspot to the specified angle at the specified time.
Parameters:
TimeValue time
The time to set the value.
float f
The angle in degrees.
Prototype:
virtual float GetHotspot(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the hotspot angle in degrees at the specified time and updates the interval to reflect the validity of the hotspot controller.
Parameters:
TimeValue t
The time to get the angle.
Interval& valid = Interval(0,0)
The interval which is updated.
Prototype:
virtual void SetFallsize(TimeValue time, float f)=0;
Remarks:
Sets the falloff angle at the specified time.
Parameters:
TimeValue time
The time to set the angle.
float f
The angle to set in degrees.
Prototype:
virtual float GetFallsize(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the falloff angle in degrees at the specified time and updates the interval passed to reflect the validity of the falloff controller.
Parameters:
TimeValue t
The time to return the value.
Interval& valid = Interval(0,0)
The interval which is updated.
Prototype:
virtual void SetAtten(TimeValue time, int which, float f)=0;
Remarks:
Sets the specified attenuation range distance at the time passed.
Parameters:
TimeValue time
The time to set the attenuation distance.
int which
Indicates which distance to set. One of the following values:
ATTEN1_START
The near start range.
ATTEN1_END
The near end range.
ATTEN_START
The far start range.
ATTEN_END
The far end range.
float f
The distance to set.
Prototype:
virtual float GetAtten(TimeValue t, int which, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the specified attenuation distance at the time passed and updates the interval to reflect the validity of the attenuation controller.
Parameters:
TimeValue t
The time to get the attenuation distance.
int which
Indicates which distance to get. One of the following values:
ATTEN1_START
The near start range.
ATTEN1_END
The near end range.
ATTEN_START
The far start range.
ATTEN_END
The far end range.
Interval& valid = Interval(0,0)
The interval which is updated.
Prototype:
virtual void SetTDist(TimeValue time, float f)=0;
Remarks:
Sets the light's target distance.
Parameters:
TimeValue time
The time to set the distance.
float f
The distance to set.
Prototype:
virtual float GetTDist(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the light's target distance at the specified time and updates the interval passed to reflect the validity of the target distance.
Parameters:
TimeValue t
The time to retrieve the distance.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual ObjLightDesc *CreateLightDesc(INode *n,BOOL forceShadowBuffer=false)=0;
Remarks:
When the renderer goes to render the scene it asks all of the lights to create an ObjLighDesc object. This is the method that is called to return a pointer to this object.
Parameters:
INode *n
The node pointer of the light.
BOOL forceShadowBuffer
Forces the creation of a shadow buffer.
Prototype:
virtual void SetRGBColor(TimeValue t, Point3& rgb)=0;
Remarks:
Sets the color of the light at the specified time.
Parameters:
TimeValue t
The time to set the color.
Point3& rgb
The color to set.
Prototype:
virtual Point3 GetRGBColor(TimeValue t, Interval &valid = Interval(0,0))=0;
Remarks:
Returns the color of the light at the specified time and updates the validity interval to reflect this parameters validity interval.
Parameters:
TimeValue t
The time to get the color.
Interval &valid = Interval(0,0)
The interval which is updated.
Prototype:
virtual void SetHSVColor(TimeValue t, Point3& hsv)=0;
Remarks:
Sets the HSV color of the light at the specified time.
Parameters:
TimeValue t
The time to set the color.
Point3& hsv
The color.
Sample Code:
The following sample shows how the RGB value can be converted to HSV.
{
int h, s, v;
Point3 rgbf = GetRGBColor(t, valid);
DWORD rgb = RGB((int)(rgbf[0]*255.0f),
(int)(rgbf[1]*255.0f), (int)(rgbf[2]*255.0f));
RGBtoHSV (rgb, &h, &s, &v);
return Point3(h/255.0f, s/255.0f, v/255.0f);
}
Prototype:
virtual Point3 GetHSVColor(TimeValue t, Interval &valid = Interval(0,0))=0;
Remarks:
Retrieves the HSV color of the light at the specified time and updates the validity interval to reflect the color parameter.
Parameters:
TimeValue t
The time to retrieve the color.
Interval &valid = Interval(0,0)
The interval to update.
Return Value:
The color of the light (as a Point3).
Prototype:
virtual void SetIntensity(TimeValue time, float f)=0;
Remarks:
Sets the intensity (multiplier value) of the light at the specified time.
Parameters:
TimeValue time
The time to set the intensity.
float f
The value to set.
Prototype:
virtual float GetIntensity(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the intensity (multiplier value) of the light at the specified time and updates the interval passed to reflect the validity of the controller.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval is updated.
Prototype:
virtual void SetContrast(TimeValue time, float f)=0;
Remarks:
This method is available in release 2.0 and later only.
Sets the light's contrast setting.
Parameters:
TimeValue time
The time to set the contrast value.
float f
The new contrast value in the range of 0.0 to 100.0.
Prototype:
virtual float GetContrast(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the light's contrast setting in the range 0.0 to 100.0.
Parameters:
TimeValue t
The time to get the light's contrast setting.
Interval& valid = Interval(0,0)
This interval is updated to reflect the interval of the light's contrast setting.
Prototype:
virtual void SetAspect(TimeValue t, float f)=0;
Remarks:
Set the aspect property to the specified value.
Parameters:
TimeValue t
The time at which to set the aspect ratio.
float f
Specifies the aspect ratio setting.
Prototype:
virtual float GetAspect(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the aspect property (for rectangular lights) at the specified time and updates the interval passed to reflect the validity of the aspect controller.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual void SetConeDisplay(int s, int notify=TRUE)=0;
Remarks:
Sets the spotlight cone display to on or off. This controls if the cone is depicted graphically in the viewports.
Parameters:
int s
Indicates if the cone display should be on or off. Nonzero indicates the cone should be displayed; otherwise it will be turned off.
int notify=TRUE
If notify is TRUE the plug-in should call NotifyDependents() to notify its dependents.
Prototype:
virtual BOOL GetConeDisplay()=0;
Remarks:
Returns the cone display property. TRUE if the spotlight cone is on; FALSE if off.
Prototype:
virtual void SetUseAtten(int s)=0;
Remarks:
Sets the far attenuation state to on or off.
Parameters:
int s
Nonzero for on; zero for off.
Prototype:
virtual BOOL GetUseAtten()=0;
Remarks:
Returns nonzero if far attenuation is on; zero if off.
Prototype:
virtual void SetAttenDisplay(int s)=0;
Remarks:
Establishes if the light far attenuation range is displayed in the viewports.
Parameters:
int s
Nonzero for on; zero for off.
Prototype:
virtual BOOL GetAttenDisplay()=0;
Remarks:
Returns TRUE if the far attenuation range is displayed; otherwise FALSE.
Prototype:
virtual void SetUseAttenNear(int s)=0;
Remarks:
This method is available in release 2.0 and later only.
Sets if the light uses near attenuation.
Parameters:
int s
Nonzero to use near attenuation; otherwise zero.
Prototype:
virtual BOOL GetUseAttenNear(void)=0;
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the light has near attenuation on; otherwise FALSE.
Prototype:
virtual BOOL GetAttenNearDisplay(void)=0;
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the light near attenuation range is displayed in the viewports; otherwise FALSE.
Prototype:
virtual void SetAttenNearDisplay(int s)=0;
Remarks:
This method is available in release 2.0 and later only.
Establishes if the light near attenuation range is displayed in the viewports.
Parameters:
int s
TRUE to turn on the display; otherwise FALSE.
Prototype:
virtual void Enable(int enab)=0;
Remarks:
Sets the light to enabled or disables (on or off).
Parameters:
int enab
Nonzero for on; zero for off.
Prototype:
virtual void SetMapBias(TimeValue t, float f)=0;
Remarks:
Sets the map bias value at the time passed.
Parameters:
TimeValue t
The time to set the value.
float f
The value to set.
Prototype:
virtual float GetMapBias(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the map bias setting at the specified time and updates the interval passed to reflect the validity of the map bias.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual void SetMapRange(TimeValue t, float f)=0;
Remarks:
Sets the map range value at the time passed.
Parameters:
TimeValue t
The time to set the value.
float f
The value to set.
Prototype:
virtual float GetMapRange(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the map range setting at the specified time and updates the interval passed to reflect the validity of the map range.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual void SetMapSize(TimeValue t, int f)=0;
Remarks:
Sets the map size value at the time passed.
Parameters:
TimeValue t
The time to set the value.
int f
The value to set.
Prototype:
virtual int GetMapSize(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the map size setting at the specified time and updates the interval passed to reflect the validity of the map size.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual void SetRayBias(TimeValue t, float f)=0;
Remarks:
Sets the map raytrace bias value at the time passed.
Parameters:
TimeValue t
The time to set the value.
float f
The value to set.
Prototype:
virtual float GetRayBias(TimeValue t, Interval& valid = Interval(0,0))=0;
Remarks:
Returns the raytrace bias setting at the specified time and updates the interval passed to reflect the validity of the bias.
Parameters:
TimeValue t
The time to get the value.
Interval& valid = Interval(0,0)
The interval to update.
Prototype:
virtual int GetUseGlobal()=0;
Remarks:
Returns TRUE if the use global setting is on; otherwise FALSE.
Prototype:
virtual void SetUseGlobal(int a)=0;
Remarks:
Set the use global setting to on or off.
Parameters:
int a
TRUE for on; FALSE for off.
Prototype:
virtual int GetShadow();
Remarks:
This method is available in release 3.0 and later only.
Returns the lights Cast Shadows flag. Nonzero indicates the light casts shadows; otherwise 0.
Default Implementation:
{return 0;}
Prototype:
virtual void SetShadow(int a);
Remarks:
This method is available in release 3.0 and later only.
Sets the lights Cast Shadows flag.
Parameters:
int a
Nonzero indicates the light casts shadows; zero indicates the light does not cast shadows.
Default Implementation:
{}
Prototype:
virtual int GetShadowType();
Remarks:
This method is available in release 3.0 and later only.
Retrieves the type of shadows used by the light - mapped or raytraced.
Return Value:
One of the following values:
-1: if the Shadow Generator is NULL. (R3 only).
0: if the light uses Shadow Maps.
1: if the light uses Raytraced Shadows.
0xffff: for any other Shadow Generators. (R3 only).
Default Implementation:
{return 0;}
Prototype:
virtual void SetShadowType(int a);
Remarks:
This method is available in release 3.0 and later only.
Sets the type of shadows used by the light - mapped or raytraced.
Parameters:
int a
The shadow type. One of the following values:
0: This value plugs in a Shadow Map Generator.
1: This value plugs in a Raytraced Shadow Generator.
Any other value is a NO-OP.
Default Implementation:
{}
Prototype:
virtual void SetShadowGenerator(ShadowType *s);
Remarks:
This method is available in release 3.0 and later only.
Sets the shadow generator used by the light.
Parameters:
ShadowType *s
The shadow plug-in to use. See Class ShadowType.
Default Implementation:
{}
Prototype:
virtual ShadowType *GetShadowGenerator();
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the shadow generator plug-in in use by the light. See Class ShadowType.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetAtmosShadows(TimeValue t, int onOff);
Remarks:
This method is available in release 3.0 and later only.
Sets the atmospheric shadow flag to on or off at the specified time.
Parameters:
TimeValue t
The time at which to set the value.
int onOff
TRUE for on; FALSE for off.
Default Implementation:
{}
Prototype:
virtual int GetAtmosShadows(TimeValue t);
Remarks:
This method is available in release 3.0 and later only.
Returns the atmospheric shadow setting at the specified time.
Parameters:
TimeValue t
Default Implementation:
{ return 0; }
Prototype:
virtual void SetAtmosOpacity(TimeValue t, float f);
Remarks:
This method is available in release 3.0 and later only.
Sets the atmospheric opacity value at the time passed.
Parameters:
TimeValue t
The time to set the value.
float f
The value to set.
Default Implementation:
{}
Prototype:
virtual float GetAtmosOpacity(TimeValue t, Interval& valid=FOREVER);
Remarks:
This method is available in release 3.0 and later only.
Returns the atmospheric opacity value at the specified time and updates the validity interval to reflect the validity of the opacity controller.
Parameters:
TimeValue t
The time to get the value.
Interval& valid=FOREVER
The interval to update.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual void SetAtmosColAmt(TimeValue t, float f);
Remarks:
This method is available in release 3.0 and later only.
Sets the atmospheric shadow color amount at the specified time.
Parameters:
TimeValue t
The time to set the value.
float f
The value to set.
Default Implementation:
{}
Prototype:
virtual float GetAtmosColAmt(TimeValue t, Interval& valid=FOREVER);
Remarks:
This method is available in release 3.0 and later only.
Returns the atmospheric shadow color amount at the specified time and updates the interval passed to reflect the validity of the amount.
Parameters:
TimeValue t
The time to get.
Interval& valid=FOREVER
The interval to update.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual int GetOvershoot()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns the overshoot setting. Nonzero is on; zero is off.
Prototype:
virtual void SetOvershoot(int a)=0;
Remarks:
This method is available in release 2.0 and later only.
Sets the overshoot setting.
Parameters:
int a
Nonzero for on; zero for off.
Prototype:
virtual ExclList& GetExclusionList()=0;
Remarks:
Returns the exclusion list for the light.
Prototype:
virtual void SetExclusionList(ExclList &list)=0;
Remarks:
Sets the exclusion list for the light.
Parameters:
ExclList &list
The exclusion list.
Prototype:
virtual BOOL SetHotSpotControl(Control *c)=0;
Remarks:
Sets the controller for the hot spot parameter.
Parameters:
Control *c
The controller to set.
Return Value:
TRUE if the controller was set; otherwise FALSE.
Prototype:
virtual BOOL SetFalloffControl(Control *c)=0;
Remarks:
Sets the controller for the falloff parameter.
Parameters:
Control *c
The controller to set.
Return Value:
TRUE if the controller was set; otherwise FALSE.
Prototype:
virtual BOOL SetColorControl(Control *c)=0;
Remarks:
Sets the controller for the color parameter.
Parameters:
Control *c
The controller to set.
Return Value:
TRUE if the controller was set; otherwise FALSE.
Prototype:
virtual Control* GetHotSpotControl()=0;
Remarks:
Returns the controller for the hot spot parameter.
Prototype:
virtual Control* GetFalloffControl()=0;
Remarks:
Returns the controller for the falloff parameter.
Prototype:
virtual Control* GetColorControl()=0;
Remarks:
Returns the controller for the color parameter.
Prototype:
virtual void SetAffectDiffuse(BOOL onOff)=0;
Remarks:
This method is available in release 2.0 and later only.
Establishes if the light affects the diffuse color of objects.
Parameters:
BOOL onOff
TRUE to have the light affect the diffuse color; otherwise FALSE.
Prototype:
virtual BOOL GetAffectDiffuse()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the light affects the diffuse color of objects; otherwise FALSE.
Prototype:
virtual void SetAffectSpecular(BOOL onOff)=0;
Remarks:
This method is available in release 2.0 and later only.
Establishes if the light affects the specular color of objects.
Parameters:
BOOL onOff
TRUE to have the light affect the specular color; otherwise FALSE.
Prototype:
virtual BOOL GetAffectSpecular()=0;
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the light affects the specular color of objects; otherwise FALSE.
Prototype:
virtual void SetDecayType(BOOL onOff);
Remarks:
This method is available in release 2.0 and later only.
Sets the decay state of the light.
Parameters:
BOOL onOff
This boolean works as an integer where 0 is None, 1 is Inverse and 2 is Inverse Square.
Default Implementation:
{}
Prototype:
virtual BOOL GetDecayType();
Remarks:
This method is available in release 2.0 and later only.
Returns the decay state of the light.
Return Value:
This boolean works as an integer where 0 is None, 1 is Inverse and 2 is Inverse Square.
Default Implementation:
{return 0;}
Prototype:
virtual void SetDecayRadius(TimeValue time, float f);
Remarks:
This method is available in release 3.0 and later only.
Sets the decay radius (i.e. falloff) of the light.
Parameters:
TimeValue time
The time at which to set the radius.
float f
The radius to set.
Default Implementation:
{}
Prototype:
virtual float GetDecayRadius(TimeValue t, Interval& valid = Interval(0,0));
Remarks:
This method is available in release 3.0 and later only.
Returns the decay radius of the light and updates the validity interval to reflect the validity of the radius controller.
Parameters:
TimeValue t
The time at which to return the radius.
Interval& valid = Interval(0,0)
The validity interval which is updated.
Default Implementation:
{ return 0.0f;}
Prototype:
virtual void SetDiffuseSoft(TimeValue time, float f);
Remarks:
This method is available in release 2.0 and later only.
Sets the state of the 'Soften Diffuse Edge' parameter.
Parameters:
TimeValue time
The time at which to set the value.
float f
The value to set in the range of 0.0 to 100.0.
Default Implementation:
{}
Prototype:
virtual float GetDiffuseSoft(TimeValue t, Interval& valid = Interval(0,0));
Remarks:
This method is available in release 2.0 and later only.
Returns the state of the 'Soften Diffuse Edge' parameter.
Parameters:
TimeValue t
The time at which to return the value.
Interval& valid = Interval(0,0)
The validity interval that is updated to reflect the state of this parameter.
Default Implementation:
{ return 0.0f; }
Prototype:
virtual void SetShadColor(TimeValue t, Point3& rgb);
Remarks:
This method is available in release 3.0 and later only.
Sets the shadow color to the specified value at the time passed.
Parameters:
TimeValue t
The time at which to set the shadow color.
Point3& rgb
The color to set.
Default Implementation:
{}
Prototype:
virtual Point3 GetShadColor(TimeValue t, Interval &valid = Interval(0,0));
Remarks:
This method is available in release 3.0 and later only.
Returns the shadow color at the time passed and updates the validity interval passed to reflect the validity of the shadow color controller.
Parameters:
TimeValue t
The time at which to return the shadow color.
Interval &valid = Interval(0,0)
The validity interval which is updated.
Default Implementation:
{ return Point3(0,0,0); }
Prototype:
virtual BOOL GetLightAffectsShadow();
Remarks:
This method is available in release 3.0 and later only.
Returns TRUE if the Light Affects Shadow Color flag is set; otherwise FALSE.
Default Implementation:
{ return 0; }
Prototype:
virtual void SetLightAffectsShadow(BOOL b);
Remarks:
This method is available in release 3.0 and later only.
Sets the state of the Light Affects Shadow Color flag to the value passed.
Parameters:
BOOL b
TRUE for set; FALSE for off.
Default Implementation:
{}
Prototype:
virtual void SetShadMult(TimeValue t, float m);
Remarks:
This method is available in release 3.0 and later only.
Sets the shadow color multiplier (density) to the value passed at the specified time.
Parameters:
TimeValue t
The time at which to set the value.
float m
The value to set.
Default Implementation:
{}
Prototype:
virtual float GetShadMult(TimeValue t, Interval &valid = Interval(0,0));
Remarks:
This method is available in release 3.0 and later only.
Returns the shadow color multiplier (density) at the specified time and updates the interval passed to reflect the validity of the multiplier controller.
Parameters:
TimeValue t
The time at which to return the value.
Interval &valid = Interval(0,0)
The interval which is updated.
Default Implementation:
{ return 1.0f; }
Prototype:
virtual Texmap* GetProjMap();
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the texmap used as the projector image or NULL if not set.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetProjMap(Texmap* pmap);
Remarks:
This method is available in release 3.0 and later only.
Sets the texmap to use as the light's projector image.
Parameters:
Texmap* pmap
Points to the texmap to set or NULL to clear it.
Default Implementation:
{}
Prototype:
virtual Texmap* GetShadowProjMap();
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the texmap used as the shadow projector or NULL if not set.
Default Implementation:
{ return NULL; }
Prototype:
virtual void SetShadowProjMap(Texmap* pmap);
Remarks:
This method is available in release 3.0 and later only.
Sets the texmap to use as the light's shadow projector.
Parameters:
Texmap* pmap
Points to the texmap to set or NULL to clear it.
Default Implementation:
{}
Prototype:
virtual void SetAmbientOnly(BOOL onOff);
Remarks:
This method is available in release 3.0 and later only.
Sets the ambient only flag to on or off.
Parameters:
BOOL onOff
TRUE for on; FALSE for off.
Default Implementation:
{}
Prototype:
virtual BOOL GetAmbientOnly();
Remarks:
This method is available in release 3.0 and later only.
Returns the state of the ambient only flag. TRUE is on; FALSE is off.
Default Implementation:
{ return FALSE; }