Open CASCADE Technology 7.8.2.dev
Graphic3d_CLight Class Reference

Generic light source definition. This class defines arbitrary light source - see Graphic3d_TypeOfLightSource enumeration. Some parameters are applicable only to particular light type; calling methods unrelated to current type will throw an exception. More...

#include <Graphic3d_CLight.hxx>

Inheritance diagram for Graphic3d_CLight:

Public Member Functions

 Graphic3d_CLight (Graphic3d_TypeOfLightSource theType)
 Empty constructor, which should be followed by light source properties configuration.
 
void CopyFrom (const Handle< Graphic3d_CLight > &theLight)
 Copy parameters from another light source excluding source type.
 
Graphic3d_TypeOfLightSource Type () const
 Returns the Type of the Light, cannot be changed after object construction.
 
const TCollection_AsciiStringName () const
 Returns light source name; empty string by default.
 
void SetName (const TCollection_AsciiString &theName)
 Sets light source name.
 
const Quantity_ColorColor () const
 Returns the color of the light source; WHITE by default.
 
void SetColor (const Quantity_Color &theColor)
 Defines the color of a light source by giving the basic color.
 
Standard_Boolean IsEnabled () const
 Check that the light source is turned on; TRUE by default. This flag affects all occurrences of light sources, where it was registered and activated; so that it is possible defining an active light in View which is actually in disabled state.
 
void SetEnabled (Standard_Boolean theIsOn)
 Change enabled state of the light state. This call does not remove or deactivate light source in Views/Viewers; instead it turns it OFF so that it just have no effect.
 
Standard_Boolean ToCastShadows () const
 Return TRUE if shadow casting is enabled; FALSE by default. Has no effect in Ray-Tracing rendering mode.
 
void SetCastShadows (Standard_Boolean theToCast)
 Enable/disable shadow casting.
 
Standard_Boolean IsHeadlight () const
 Returns true if the light is a headlight; FALSE by default. Headlight flag means that light position/direction are defined not in a World coordinate system, but relative to the camera orientation.
 
Standard_Boolean Headlight () const
 Alias for IsHeadlight().
 
void SetHeadlight (Standard_Boolean theValue)
 Setup headlight flag.
 
positional/spot light properties
const gp_PntPosition () const
 Returns location of positional/spot light; (0, 0, 0) by default.
 
void SetPosition (const gp_Pnt &thePosition)
 Setup location of positional/spot light.
 
void Position (Standard_Real &theX, Standard_Real &theY, Standard_Real &theZ) const
 Returns location of positional/spot light.
 
void SetPosition (Standard_Real theX, Standard_Real theY, Standard_Real theZ)
 Setup location of positional/spot light.
 
Standard_ShortReal ConstAttenuation () const
 Returns constant attenuation factor of positional/spot light source; 1.0f by default. Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:
 
Standard_ShortReal LinearAttenuation () const
 Returns linear attenuation factor of positional/spot light source; 0.0 by default. Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:
 
void Attenuation (Standard_Real &theConstAttenuation, Standard_Real &theLinearAttenuation) const
 Returns the attenuation factors.
 
void SetAttenuation (Standard_ShortReal theConstAttenuation, Standard_ShortReal theLinearAttenuation)
 Defines the coefficients of attenuation; values should be >= 0.0 and their summ should not be equal to 0.
 
directional/spot light additional properties
gp_Dir Direction () const
 Returns direction of directional/spot light.
 
void SetDirection (const gp_Dir &theDir)
 Sets direction of directional/spot light.
 
void Direction (Standard_Real &theVx, Standard_Real &theVy, Standard_Real &theVz) const
 Returns the theVx, theVy, theVz direction of the light source.
 
void SetDirection (Standard_Real theVx, Standard_Real theVy, Standard_Real theVz)
 Sets direction of directional/spot light.
 
const gp_PntDisplayPosition () const
 Returns location of positional/spot/directional light, which is the same as returned by Position().
 
void SetDisplayPosition (const gp_Pnt &thePosition)
 Setup location of positional/spot/directional light, which is the same as SetPosition() but allows directional light source (technically having no position, but this point can be used for displaying light source presentation).
 
spotlight additional definition parameters
Standard_ShortReal Angle () const
 Returns an angle in radians of the cone created by the spot; 30 degrees by default.
 
void SetAngle (Standard_ShortReal theAngle)
 Angle in radians of the cone created by the spot, should be within range (0.0, M_PI).
 
Standard_ShortReal Concentration () const
 Returns intensity distribution of the spot light, within [0.0, 1.0] range; 1.0 by default. This coefficient should be converted into spotlight exponent within [0.0, 128.0] range:
 
void SetConcentration (Standard_ShortReal theConcentration)
 Defines the coefficient of concentration; value should be within range [0.0, 1.0].
 
Ray-Tracing / Path-Tracing light properties
Standard_ShortReal Intensity () const
 Returns the intensity of light source; 1.0 by default.
 
void SetIntensity (Standard_ShortReal theValue)
 Modifies the intensity of light source, which should be > 0.0.
 
Standard_ShortReal Smoothness () const
 Returns the smoothness of light source (either smoothing angle for directional light or smoothing radius in case of positional light); 0.0 by default.
 
void SetSmoothRadius (Standard_ShortReal theValue)
 Modifies the smoothing radius of positional/spot light; should be >= 0.0.
 
void SetSmoothAngle (Standard_ShortReal theValue)
 Modifies the smoothing angle (in radians) of directional light source; should be within range [0.0, M_PI/2].
 
bool HasRange () const
 Returns TRUE if maximum distance of point light source is defined.
 
Standard_ShortReal Range () const
 Returns maximum distance on which point light source affects to objects and is considered during illumination calculations. 0.0 means disabling range considering at all without any distance limits. Has sense only for point light sources (positional and spot).

 
void SetRange (Standard_ShortReal theValue)
 Modifies maximum distance on which point light source affects to objects and is considered during illumination calculations. Positional and spot lights are only point light sources. 0.0 means disabling range considering at all without any distance limits.
 
- Public Member Functions inherited from Standard_Transient
 Standard_Transient ()
 Empty constructor.
 
 Standard_Transient (const Standard_Transient &)
 Copy constructor – does nothing.
 
Standard_Transientoperator= (const Standard_Transient &)
 Assignment operator, needed to avoid copying reference counter.
 
virtual ~Standard_Transient ()
 Destructor must be virtual.
 
virtual const opencascade::handle< Standard_Type > & DynamicType () const
 Returns a type descriptor about this object.
 
Standard_Boolean IsInstance (const opencascade::handle< Standard_Type > &theType) const
 Returns a true value if this is an instance of Type.
 
Standard_Boolean IsInstance (const Standard_CString theTypeName) const
 Returns a true value if this is an instance of TypeName.
 
Standard_Boolean IsKind (const opencascade::handle< Standard_Type > &theType) const
 Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
 
Standard_Boolean IsKind (const Standard_CString theTypeName) const
 Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism.
 
Standard_TransientThis () const
 Returns non-const pointer to this object (like const_cast). For protection against creating handle to objects allocated in stack or call from constructor, it will raise exception Standard_ProgramError if reference counter is zero.
 
Standard_Integer GetRefCount () const noexcept
 Get the reference counter of this object.
 
void IncrementRefCounter () noexcept
 Increments the reference counter of this object.
 
Standard_Integer DecrementRefCounter () noexcept
 Decrements the reference counter of this object; returns the decremented value.
 
virtual void Delete () const
 Memory deallocator for transient classes.
 

low-level access methods

TCollection_AsciiString myId
 resource id
 
TCollection_AsciiString myName
 user given name
 
gp_Pnt myPosition
 light position
 
Quantity_ColorRGBA myColor
 light color
 
Graphic3d_Vec4 myDirection
 direction of directional/spot light
 
Graphic3d_Vec4 myParams
 packed light parameters
 
Standard_ShortReal mySmoothness
 radius for point light or cone angle for directional light
 
Standard_ShortReal myIntensity
 intensity multiplier for light
 
const Graphic3d_TypeOfLightSource myType
 Graphic3d_TypeOfLightSource enumeration.
 
Standard_Size myRevision
 modification counter
 
Standard_Boolean myIsHeadlight
 flag to mark head light
 
Standard_Boolean myIsEnabled
 enabled state
 
Standard_Boolean myToCastShadows
 casting shadows is requested
 
const TCollection_AsciiStringGetId () const
 
const Graphic3d_Vec4PackedParams () const
 Packed light parameters.
 
const Graphic3d_Vec4PackedColor () const
 Returns the color of the light source with dummy Alpha component, which should be ignored.
 
const Graphic3d_Vec4PackedDirectionRange () const
 Returns direction of directional/spot light and range for positional/spot light in alpha channel.
 
Graphic3d_Vec3 PackedDirection () const
 Returns direction of directional/spot light.
 
Standard_Size Revision () const
 
void DumpJson (Standard_OStream &theOStream, Standard_Integer theDepth=-1) const
 Dumps the content of me into the stream.
 

Additional Inherited Members

- Public Types inherited from Standard_Transient
typedef void base_type
 Returns a type descriptor about this object.
 
- Static Public Member Functions inherited from Standard_Transient
static constexpr const char * get_type_name ()
 Returns a type descriptor about this object.
 
static const opencascade::handle< Standard_Type > & get_type_descriptor ()
 Returns type descriptor of Standard_Transient class.
 

Detailed Description

Generic light source definition. This class defines arbitrary light source - see Graphic3d_TypeOfLightSource enumeration. Some parameters are applicable only to particular light type; calling methods unrelated to current type will throw an exception.

Constructor & Destructor Documentation

◆ Graphic3d_CLight()

Graphic3d_CLight::Graphic3d_CLight ( Graphic3d_TypeOfLightSource theType)

Empty constructor, which should be followed by light source properties configuration.

Member Function Documentation

◆ Angle()

Standard_ShortReal Graphic3d_CLight::Angle ( ) const
inline

Returns an angle in radians of the cone created by the spot; 30 degrees by default.

◆ Attenuation()

void Graphic3d_CLight::Attenuation ( Standard_Real & theConstAttenuation,
Standard_Real & theLinearAttenuation ) const
inline

Returns the attenuation factors.

◆ Color()

const Quantity_Color & Graphic3d_CLight::Color ( ) const
inline

Returns the color of the light source; WHITE by default.

◆ Concentration()

Standard_ShortReal Graphic3d_CLight::Concentration ( ) const
inline

Returns intensity distribution of the spot light, within [0.0, 1.0] range; 1.0 by default. This coefficient should be converted into spotlight exponent within [0.0, 128.0] range:

float aSpotExponent = Concentration() * 128.0;
anAttenuation *= pow (aCosA, aSpotExponent);"
Handle< Units_Dimensions > pow(const Handle< Units_Dimensions > &, const Standard_Real)
Standard_ShortReal Concentration() const
Returns intensity distribution of the spot light, within [0.0, 1.0] range; 1.0 by default....
Definition Graphic3d_CLight.hxx:175

The concentration factor determines the dispersion of the light on the surface, the default value (1.0) corresponds to a minimum of dispersion.

◆ ConstAttenuation()

Standard_ShortReal Graphic3d_CLight::ConstAttenuation ( ) const
inline

Returns constant attenuation factor of positional/spot light source; 1.0f by default. Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:

float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance);
Standard_ShortReal LinearAttenuation() const
Returns linear attenuation factor of positional/spot light source; 0.0 by default....
Definition Graphic3d_CLight.hxx:115
Standard_ShortReal ConstAttenuation() const
Returns constant attenuation factor of positional/spot light source; 1.0f by default....
Definition Graphic3d_CLight.hxx:108

◆ CopyFrom()

void Graphic3d_CLight::CopyFrom ( const Handle< Graphic3d_CLight > & theLight)

Copy parameters from another light source excluding source type.

◆ Direction() [1/2]

gp_Dir Graphic3d_CLight::Direction ( ) const
inline

Returns direction of directional/spot light.

◆ Direction() [2/2]

void Graphic3d_CLight::Direction ( Standard_Real & theVx,
Standard_Real & theVy,
Standard_Real & theVz ) const
inline

Returns the theVx, theVy, theVz direction of the light source.

◆ DisplayPosition()

const gp_Pnt & Graphic3d_CLight::DisplayPosition ( ) const
inline

Returns location of positional/spot/directional light, which is the same as returned by Position().

◆ DumpJson()

void Graphic3d_CLight::DumpJson ( Standard_OStream & theOStream,
Standard_Integer theDepth = -1 ) const

Dumps the content of me into the stream.

◆ GetId()

const TCollection_AsciiString & Graphic3d_CLight::GetId ( ) const
inline
Returns
light resource identifier string

◆ HasRange()

bool Graphic3d_CLight::HasRange ( ) const
inline

Returns TRUE if maximum distance of point light source is defined.

◆ Headlight()

Standard_Boolean Graphic3d_CLight::Headlight ( ) const
inline

Alias for IsHeadlight().

◆ Intensity()

Standard_ShortReal Graphic3d_CLight::Intensity ( ) const
inline

Returns the intensity of light source; 1.0 by default.

◆ IsEnabled()

Standard_Boolean Graphic3d_CLight::IsEnabled ( ) const
inline

Check that the light source is turned on; TRUE by default. This flag affects all occurrences of light sources, where it was registered and activated; so that it is possible defining an active light in View which is actually in disabled state.

◆ IsHeadlight()

Standard_Boolean Graphic3d_CLight::IsHeadlight ( ) const
inline

Returns true if the light is a headlight; FALSE by default. Headlight flag means that light position/direction are defined not in a World coordinate system, but relative to the camera orientation.

◆ LinearAttenuation()

Standard_ShortReal Graphic3d_CLight::LinearAttenuation ( ) const
inline

Returns linear attenuation factor of positional/spot light source; 0.0 by default. Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:

float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance);

◆ Name()

const TCollection_AsciiString & Graphic3d_CLight::Name ( ) const
inline

Returns light source name; empty string by default.

◆ PackedColor()

const Graphic3d_Vec4 & Graphic3d_CLight::PackedColor ( ) const
inline

Returns the color of the light source with dummy Alpha component, which should be ignored.

◆ PackedDirection()

Graphic3d_Vec3 Graphic3d_CLight::PackedDirection ( ) const
inline

Returns direction of directional/spot light.

◆ PackedDirectionRange()

const Graphic3d_Vec4 & Graphic3d_CLight::PackedDirectionRange ( ) const
inline

Returns direction of directional/spot light and range for positional/spot light in alpha channel.

◆ PackedParams()

const Graphic3d_Vec4 & Graphic3d_CLight::PackedParams ( ) const
inline

Packed light parameters.

◆ Position() [1/2]

const gp_Pnt & Graphic3d_CLight::Position ( ) const
inline

Returns location of positional/spot light; (0, 0, 0) by default.

◆ Position() [2/2]

void Graphic3d_CLight::Position ( Standard_Real & theX,
Standard_Real & theY,
Standard_Real & theZ ) const
inline

Returns location of positional/spot light.

◆ Range()

Standard_ShortReal Graphic3d_CLight::Range ( ) const
inline

Returns maximum distance on which point light source affects to objects and is considered during illumination calculations. 0.0 means disabling range considering at all without any distance limits. Has sense only for point light sources (positional and spot).

◆ Revision()

Standard_Size Graphic3d_CLight::Revision ( ) const
inline
Returns
modification counter

◆ SetAngle()

void Graphic3d_CLight::SetAngle ( Standard_ShortReal theAngle)

Angle in radians of the cone created by the spot, should be within range (0.0, M_PI).

◆ SetAttenuation()

void Graphic3d_CLight::SetAttenuation ( Standard_ShortReal theConstAttenuation,
Standard_ShortReal theLinearAttenuation )

Defines the coefficients of attenuation; values should be >= 0.0 and their summ should not be equal to 0.

◆ SetCastShadows()

void Graphic3d_CLight::SetCastShadows ( Standard_Boolean theToCast)

Enable/disable shadow casting.

◆ SetColor()

void Graphic3d_CLight::SetColor ( const Quantity_Color & theColor)

Defines the color of a light source by giving the basic color.

◆ SetConcentration()

void Graphic3d_CLight::SetConcentration ( Standard_ShortReal theConcentration)

Defines the coefficient of concentration; value should be within range [0.0, 1.0].

◆ SetDirection() [1/2]

void Graphic3d_CLight::SetDirection ( const gp_Dir & theDir)

Sets direction of directional/spot light.

◆ SetDirection() [2/2]

void Graphic3d_CLight::SetDirection ( Standard_Real theVx,
Standard_Real theVy,
Standard_Real theVz )
inline

Sets direction of directional/spot light.

◆ SetDisplayPosition()

void Graphic3d_CLight::SetDisplayPosition ( const gp_Pnt & thePosition)

Setup location of positional/spot/directional light, which is the same as SetPosition() but allows directional light source (technically having no position, but this point can be used for displaying light source presentation).

◆ SetEnabled()

void Graphic3d_CLight::SetEnabled ( Standard_Boolean theIsOn)

Change enabled state of the light state. This call does not remove or deactivate light source in Views/Viewers; instead it turns it OFF so that it just have no effect.

◆ SetHeadlight()

void Graphic3d_CLight::SetHeadlight ( Standard_Boolean theValue)

Setup headlight flag.

◆ SetIntensity()

void Graphic3d_CLight::SetIntensity ( Standard_ShortReal theValue)

Modifies the intensity of light source, which should be > 0.0.

◆ SetName()

void Graphic3d_CLight::SetName ( const TCollection_AsciiString & theName)
inline

Sets light source name.

◆ SetPosition() [1/2]

void Graphic3d_CLight::SetPosition ( const gp_Pnt & thePosition)

Setup location of positional/spot light.

◆ SetPosition() [2/2]

void Graphic3d_CLight::SetPosition ( Standard_Real theX,
Standard_Real theY,
Standard_Real theZ )
inline

Setup location of positional/spot light.

◆ SetRange()

void Graphic3d_CLight::SetRange ( Standard_ShortReal theValue)

Modifies maximum distance on which point light source affects to objects and is considered during illumination calculations. Positional and spot lights are only point light sources. 0.0 means disabling range considering at all without any distance limits.

◆ SetSmoothAngle()

void Graphic3d_CLight::SetSmoothAngle ( Standard_ShortReal theValue)

Modifies the smoothing angle (in radians) of directional light source; should be within range [0.0, M_PI/2].

◆ SetSmoothRadius()

void Graphic3d_CLight::SetSmoothRadius ( Standard_ShortReal theValue)

Modifies the smoothing radius of positional/spot light; should be >= 0.0.

◆ Smoothness()

Standard_ShortReal Graphic3d_CLight::Smoothness ( ) const
inline

Returns the smoothness of light source (either smoothing angle for directional light or smoothing radius in case of positional light); 0.0 by default.

◆ ToCastShadows()

Standard_Boolean Graphic3d_CLight::ToCastShadows ( ) const
inline

Return TRUE if shadow casting is enabled; FALSE by default. Has no effect in Ray-Tracing rendering mode.

◆ Type()

Graphic3d_TypeOfLightSource Graphic3d_CLight::Type ( ) const
inline

Returns the Type of the Light, cannot be changed after object construction.

Field Documentation

◆ myColor

Quantity_ColorRGBA Graphic3d_CLight::myColor
protected

light color

◆ myDirection

Graphic3d_Vec4 Graphic3d_CLight::myDirection
protected

direction of directional/spot light

◆ myId

TCollection_AsciiString Graphic3d_CLight::myId
protected

resource id

◆ myIntensity

Standard_ShortReal Graphic3d_CLight::myIntensity
protected

intensity multiplier for light

◆ myIsEnabled

Standard_Boolean Graphic3d_CLight::myIsEnabled
protected

enabled state

◆ myIsHeadlight

Standard_Boolean Graphic3d_CLight::myIsHeadlight
protected

flag to mark head light

◆ myName

TCollection_AsciiString Graphic3d_CLight::myName
protected

user given name

◆ myParams

Graphic3d_Vec4 Graphic3d_CLight::myParams
protected

packed light parameters

◆ myPosition

gp_Pnt Graphic3d_CLight::myPosition
protected

light position

◆ myRevision

Standard_Size Graphic3d_CLight::myRevision
protected

modification counter

◆ mySmoothness

Standard_ShortReal Graphic3d_CLight::mySmoothness
protected

radius for point light or cone angle for directional light

◆ myToCastShadows

Standard_Boolean Graphic3d_CLight::myToCastShadows
protected

casting shadows is requested

◆ myType

const Graphic3d_TypeOfLightSource Graphic3d_CLight::myType
protected

Graphic3d_TypeOfLightSource enumeration.


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