|
|
              
QGLLightParameters ClassThe QGLLightParameters class represents the parameters of a light in a 3D scene. More... #include <QGLLightParameters>Inherits: QObject. QGLLightParameters is instantiated by QML element Light This class was introduced in Qt 4.8. Public Types
Properties
Public Functions
Signals
Additional Inherited Members
Detailed DescriptionThe QGLLightParameters class represents the parameters of a light in a 3D scene. The functions in this class are a convenience wrapper for the OpenGL enumerations which control each light source in a 3D scene. For the general ambient light in a scene, not from a source refer to QGLLightModel. The ambient, diffuse and specular components of the light can be controlled for by colour, and are set by the following functions: Other than changing intensity by using darker color values, see below for how to change the intensity of the light with distance from the lit object. Light sources are of two types, directional and positional, described by the enumeration QGLLightParameters::LightType. By default a light source is directional. A directional light source is infinitely distant, such that its rays are all parallel, to a direction vector. This vector is set by the setDirection() function. If the light source is not directional when setDirection() is called, its type is changed to Directional. Directional light sources model real world light sources like the sun. Such light sources are not located at any particular point and affect the scene evenly. In the OpenGL model-view, a directional light is represented by a 4d vector, with the 4th value, w, set to 0.0f. This means that the spatial data of the light is not changed during certain transformations, for example translation. See 3D Math Basis for a fuller explanation of this. Calling the setPosition() function defines the light source to be located at a given point, a finite distance from the lit object. If the light source is not positional when this function is called its type is changed to Positional. A positional light source models a real world lamp, such as a light-bulb or car headlight. Since it is a finite distance from the lit object the rays diverge and lighting calculations are thus more complex. In OpenGL the light has its spatial data w value set to 1.0f, resulting in the lights position being changed along with other objects in the scene by transformations such as translation. See 3D Math Basis for more. Positional lights are by default point sources, like the light-bulb where light radiates in all directions. Calling the spotAngle() function sets an angle to restrict the light from a positional source to a cone like the car headlight. This makes the light behave like a spotlight, where objects outside of the cone of the light do not receive any light from that source. The spotlight may be further specified by its spotExponent() which dictates the behaviour of the cutoff at the lighting cone; and by the attenuation functions which are the terms in the following equation:
here d is the distance of the light from the lit object, and A is the attenuation factor which is a multiplier of the light source, determining its intensity at the lit object. The terms in the denominator are:
When these terms are large the light contributed by the source becomes much weaker with distance from the object. Member Type Documentation
|
| Constant | Value | Description |
|---|---|---|
| QGLLightParameters::Directional | 0 | The default. Directional lights are infinitely distant from the lit object, and its rays are parallel to a direction vector. Use setDirection() to make a light Directional. |
| QGLLightParameters::Positional | 1 | Positional lights are a finite distance from the lit object. Complex lighting with spot-lights, and attenuation are enabled with Positional lighting. Use setPosition() to make a light Positional. |
Property Documentation
ambientColor : QColor
This property holds the ambient color of this light. The default value is black.
Access functions:
| QColor | ambientColor() const |
| void | setAmbientColor(const QColor & value) |
Notifier signal:
| void | ambientColorChanged() |
See also diffuseColor(), specularColor(), and ambientColorChanged().
constantAttenuation : qreal
This property holds the constant light attenuation factor. The default value is 1.
This parameter has no effect on a Directional light.
Access functions:
| qreal | constantAttenuation() const |
| void | setConstantAttenuation(qreal value) |
Notifier signal:
| void | constantAttenuationChanged() |
See also linearAttenuation(), quadraticAttenuation(), and constantAttenuationChanged().
diffuseColor : QColor
This property holds the diffuse color of this light. The default value is white.
Access functions:
| QColor | diffuseColor() const |
| void | setDiffuseColor(const QColor & value) |
Notifier signal:
| void | diffuseColorChanged() |
See also ambientColor(), specularColor(), and diffuseColorChanged().
direction : QVector3D
This property holds the direction of this light if it is Directional; or a null QVector3D if it is Positional. By default, the light is Directional.
For a Directional light, the return value is the direction vector of an infinitely distant directional light, like the sun.
The default value is (0, 0, 1), for a directional light pointing along the positive z-axis.
OpenGL will ignore other parameters such as attenuation and spot angle when this value is set, since a directional light has no location. In order to set the direction of a spot light, use the setSpotDirection() function.
Setting the direction converts the light from Positional to Directional.
Access functions:
| QVector3D | direction() const |
| void | setDirection(const QVector3D & value) |
Notifier signal:
| void | directionChanged() |
See also position(), type(), and directionChanged().
linearAttenuation : qreal
This property holds the linear light attenuation factor. The default value is 0.
This parameter has no effect on a Directional light.
Access functions:
| qreal | linearAttenuation() const |
| void | setLinearAttenuation(qreal value) |
Notifier signal:
| void | linearAttenuationChanged() |
See also constantAttenuation(), quadraticAttenuation(), and linearAttenuationChanged().
position : QVector3D
This property holds the position of this light if it is Positional; or a null QVector3D if it is Directional. By default, the light is Directional.
For a Positional light, the return value is the location in model space of the light, at some finite distance from the origin. The value is transformed by the model-view transformation when the light parameters are applied.
When the light is Positional OpenGL will obey other parameters relating to the light's position, such as attenuation and spot angle.
Setting the position converts the light from Directional to Positional.
Access functions:
| QVector3D | position() const |
| void | setPosition(const QVector3D & value) |
Notifier signal:
| void | positionChanged() |
See also direction(), type(), and positionChanged().
quadraticAttenuation : qreal
This property holds the quadratic light attenuation factor. The default value is 0.
This parameter has no effect on a Directional light.
Access functions:
| qreal | quadraticAttenuation() const |
| void | setQuadraticAttenuation(qreal value) |
Notifier signal:
| void | quadraticAttenuationChanged() |
See also constantAttenuation(), linearAttenuation(), and quadraticAttenuationChanged().
specularColor : QColor
This property holds the specular color of this light. The default value is white.
Access functions:
| QColor | specularColor() const |
| void | setSpecularColor(const QColor & value) |
Notifier signal:
| void | specularColorChanged() |
See also ambientColor(), diffuseColor(), and specularColorChanged().
spotAngle : qreal
This property holds the angle over which light is spread from this light. It should be between 0 and 90 for spot lights, and 180 for uniform light distribution from a remote light source. The default value is 180.
This parameter has no effect on a Directional light.
Access functions:
| qreal | spotAngle() const |
| void | setSpotAngle(qreal value) |
Notifier signal:
| void | spotAngleChanged() |
See also spotCosAngle() and spotAngleChanged().
spotDirection : QVector3D
This property holds the direction that a spot-light is shining in.
A spotlight is a positional light that has a value other than the default for spot angle. The default value is (0, 0, -1).
This parameter has no effect on a Directional light.
Access functions:
| QVector3D | spotDirection() const |
| void | setSpotDirection(const QVector3D & value) |
Notifier signal:
| void | spotDirectionChanged() |
See also spotExponent() and spotDirectionChanged().
spotExponent : qreal
This property holds the exponent value between 0 and 128 that indicates the intensity distribution of a spot-light. The default value is 0, indicating uniform light distribution.
This parameter has no effect on a Directional light.
Access functions:
| qreal | spotExponent() const |
| void | setSpotExponent(qreal value) |
Notifier signal:
| void | spotExponentChanged() |
See also spotAngle(), setPosition(), and spotExponentChanged().
type : const LightType
This property holds the type of this light; Positional or Directional.
Access functions:
| QGLLightParameters::LightType | type() const |
Member Function Documentation
QGLLightParameters::QGLLightParameters(QObject * parent = 0)
Constructs a new light parameters object with default values and attaches it to parent.
QGLLightParameters::~QGLLightParameters()
Destroys this light parameters object.
QVector4D QGLLightParameters::eyePosition(const QMatrix4x4 & transform) const
Returns the position of this light after transforming it from world co-ordinates to eye co-ordinates using transform.
If the light is Directional, then direction() will be transformed, after setting the w co-ordinate to 0. If the light is Positional, then position() will be transformed after setting the w co-ordinate to 1.
The returned result is suitable to be applied to the GL_POSITION property of glLight(), assuming that the modelview transformation in the GL context is set to the identity.
See also eyeSpotDirection().
QVector3D QGLLightParameters::eyeSpotDirection(const QMatrix4x4 & transform) const
Returns the spotDirection() for this light after transforming it from world co-ordinates to eye co-ordinates using the top-left 3x3 submatrix within transform.
The returned result is suitable to be applied to the GL_SPOT_DIRECTION property of glLight(), assuming that the modelview transformation in the GL context is set to the identity.
See also eyePosition().
void QGLLightParameters::lightChanged() [signal]
This signal is emitted when any of the properties on the light changes.
qreal QGLLightParameters::spotCosAngle() const
Returns the cosine of spotAngle(), or -1 if spotAngle() is 180.
The cosine of spotAngle() is useful in lighting algorithms. This function returns a cached copy of the cosine so that it does not need to be computed every time the lighting parameters are read.
See also spotAngle().