Enables the application of lighting effects.
The lighting effect class applies a diffuse or specular lighting effect to the alpha channel of an input bitmap, which functions as a bump map. The output is an RGBA representation of the light effect. If no light Colour is specified by the client then the output will be in grey scale.
For diffuse lighting, the resulting RGBA image is computed as follows:
Dr = kd * N.L * Lr Dg = kd * N.L * Lg Db = kd * N.L * Lb Da = 1.0
where
kd = Diffuse lighting constant N = Surface normal unit vector, a function of x and y L = Unit vector pointing from surface to light, a function of x and y in the point and spot light cases Lr,Lg,Lb = RGB components of light, a function of x and y in the spot light case
For specular lighting, the resulting RGBA image is computed as follows:
Sr = ks * pow(N.H, specularExponent) * Lr Sg = ks * pow(N.H, specularExponent) * Lg Sb = ks * pow(N.H, specularExponent) * Lb Sa = max(Sr, Sg, Sb)
where
ks = Specular lighting constant N = Surface normal unit vector, a function of x and y H = "Halfway" unit vector between eye unit vector and light unit vector Lr,Lg,Lb = RGB components of light
The definition of H reflects our assumption of the constant eye vector E = (0,0,1):
H = (L + E) / Norm(L + E)
where L is the light unit vector.
The LightingFX class consists of the following fields:
Access | Name | Type | Comment | ||||||
|---|---|---|---|---|---|---|---|---|---|
| Colour | FLOAT [] | Defines the colour of the light source. | |||||||
Set the Colour field to define the colour of the light source. The colour is defined as an array of four 32-bit floating point values between 0 and 1.0. The array elements consist of Red, Green, Blue and Alpha values in that order. If the algorithm supports it, the Alpha component defines the intensity of the light source. The default colour is pure white, | |||||||||
| Constant | DOUBLE | Specifies the ks/kd value in Phong lighting model. | |||||||
In the Phong lighting model, this field specifies the kd value in diffuse mode, or ks value in specular mode. | |||||||||
| Exponent | DOUBLE | Exponent for specular lighting, larger is more "shiny". Ranges from 1.0 to 128.0. | |||||||
This field defines the exponent value for specular lighting, within a range of 1.0 to 128.0. The larger the value, shinier the end result. | |||||||||
| Scale | DOUBLE | The maximum height of the input surface (bump map) when the alpha input is 1.0. | |||||||
| Type | INT | Defines the type of surface light scattering, which can be specular or diffuse. | |||||||
| |||||||||
| UnitX | DOUBLE | The intended distance in current filter units for dx in the surface normal calculation formulas. | |||||||
Indicates the intended distance in current filter units (i.e. as determined by the value of PrimitiveUnits) for dx in the surface normal calculation formulas. By specifying value(s) for UnitX, the kernel becomes defined in a scalable, abstract coordinate system. If UnitX is not specified, the default value is one pixel in the offscreen bitmap, which is a pixel-based coordinate system, and thus potentially not scalable. For some level of consistency across display media and user agents, it is necessary that a value be provided for at least one of ResX and UnitX. | |||||||||
| UnitY | DOUBLE | The intended distance in current filter units for dy in the surface normal calculation formulas. | |||||||
Indicates the intended distance in current filter units (i.e. as determined by the value of PrimitiveUnits) for dy in the surface normal calculation formulas. By specifying value(s) for UnitY, the kernel becomes defined in a scalable, abstract coordinate system. If UnitY is not specified, the default value is one pixel in the offscreen bitmap, which is a pixel-based coordinate system, and thus potentially not scalable. For some level of consistency across display media and user agents, it is necessary that a value be provided for at least one of ResY and UnitY. | |||||||||
| XMLDef | STRING | Returns an SVG compliant XML string that describes the filter. | |||||||
The following actions are currently supported:
| Draw | Render the effect to the target bitmap. | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)
| ||||||||||||
The following methods are currently supported:
| SetDistantLight | Configure lighting with a distant light source. | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ERR lt::SetDistantLight(OBJECTPTR Object, DOUBLE Azimuth, DOUBLE Elevation)
This method applies a distant light configuration to the lighting effect. It will override any previously defined light source setting. A distant light can be thought of as like the light from the sun. An infinite amount of parallel light rays travel in the direction that the distant light points to. Distant lights are handy when you want equal illumination on objects in a scene. | |||||||||||||||||||
| SetPointLight | Configure lighting with a pointed light source. | ||||||||||||||||||
ERR lt::SetPointLight(OBJECTPTR Object, DOUBLE X, DOUBLE Y, DOUBLE Z)
This method applies a pointed light configuration to the lighting effect. It will override any previously defined light source setting. A point light sends light out from the specified (X, Y, Z) location equally in all directions. A light bulb or open flame is a good example of a point light. The intensity of the light can be controlled by altering the alpha component of the light Colour. | |||||||||||||||||||
| SetSpotLight | Configure lighting with a spot light source. | ||||||||||||||||||
ERR lt::SetSpotLight(OBJECTPTR Object, DOUBLE X, DOUBLE Y, DOUBLE Z, DOUBLE PX, DOUBLE PY, DOUBLE PZ, DOUBLE Exponent, DOUBLE ConeAngle)
This method applies a spot light configuration to the lighting effect. It will override any previously defined light source setting. A spot light beams light rays from the defined (X, Y, Z) position to the (PX, PY, PZ) position. The Exponent and ConeAngle work together to constrain the edge of the light projection. | |||||||||||||||||||
Lighting algorithm for the LightingFX class.
| Name | Description |
|---|---|
| LT::DIFFUSE | Select diffuse lighting. |
| LT::SPECULAR | Select specular lighting. |