kmGenerateFogTable
Generates the fog table automatically.
Description:
This function generates the fog table automatically.
When a value is given to the depth of the front and back borders of the range where fog is valid, a fog table with smooth fog and fog coefficient are generated in the range.
At the fog table, the initial entry is created indicating the fog density of the value of the back border (fBackBorder) of the range (see the figure below). At the same time, when the generated fog coefficient (*fHWFogDensity) is set to the hardware by the kmConvertFogDensity and kmSetFogDensity functions, the leading entry of the generated fog table can now be referenced by the value of the back border (fBackBorder) of the range.
In this case, the last part of the fog table (front border) indicates the fog density at the position where depth = 248 X fBackBorder. In other words, the valid range of the fog table created by this function is from depth = fBackBorder (back border) to 248 ~ fBackBorder (front border) (hardware specification).
Note that depending on the value of fBackBorder, not all of the range specified by fFrontBorder can be covered.
The fog table to create can be selected from one of the following four types (each with different density):
KM_FOGTYPE_NONE
Specifies to use no fog. All entries of the fog table will be set to zero.B
KM_FOGTYPE_LINEAR
Specifies to use linear fog.
The fog table is generated with changing line shape for depth value between fFrontBorder and fBackBorder.
When fFogDensity is 1.0, the fog density is 1.0 (maximum density) at the fBackBorder position and 0.0 (no fog) at the fFrontBorder position (the red curve line in the figure below).
By changing the value of fFogDensity between 1.0f and 0.0f, the steepness of fog density can be changed as well.
KM_FOGTYPE_EXPONENTIAL
Specifies to use exponential fog. The fog density of a depth (Z value) is determined by the following formula:
Fog density = e ^ - (fFogDensity x Z)
(e is the base of the natural log, and ^ indicates the exponent.)
This is equivalent to the exponential fog mode of Direct3D.
If fFogDensity is 1.0, when y value is 1.0 the exponential graph changes to have fog density being 0.367879... (the red curve in the figure below).
Also, in the interval where the Z value is smaller than fBackBorder (depth), the value for the position of fBackBorder is maintained. On the contrary, in the interval where the Z value is greater than fFrontBorder (the forward area), the fog density becomes zero.
As long as fFogDensity is greater than zero, any value can be specified. If fFogDensity is zero, the steepness of the fog density becomes flat (always maximum density). The bigger fFogDensity is, the steeper the fog density becomes.
KM_FOGTYPE_EXPONENTIAL2
Specifies to use exponential fog. The steepness of the fog density is bigger than that of KM_FOGTYPE_EXPONENTIAL. The fog density of a depth (Z value) is determined by the following formula:
Fog density = (e ^ - (fFogDensity x Z)) ^ 2
(e is the base of the natural log, and ^ indicates the exponent.)
This is equivalent to the exponential squared fog mode of Direct3D.
If fFogDensity is 1.0, when y value is 1.0 the exponential graph changes to have fog density being 0.135335... (the red curve in the figure below). Also, in the interval where the Z value is smaller than fBackBorder (depth), the value for the position of fBackBorder is maintained. On the contrary, in the interval where the Z value is greater than fFrontBorder (the forward area), the fog density becomes zero.
As long as fFogDensity is greater than zero, any value can be specified. If fFogDensity is zero, the steepness of the fog density becomes flat (always maximum density). The bigger fFogDensity is, the steeper the fog density becomes.
To generate fog table automatically, use the following Kamui APIs.
1) kmGenerateFogTable | (Generates fog table.) |
2) kmConvertFogDensity | (Converts fog coefficient.) |
3) kmSetFogDensity | (Sets fog coefficient.) |
4) kmSetFogTableColor | (Sets fog color.) |
5) kmSetFogTable | (Sets fog table.) |
Parameters:
pFogTable(output)
This parameter is the pointer to the one-dimensional array in the MKFLOAT format of 128 entries, for storing the generated fog table. Each element has clipping performed in the range from 0.0f to 1.0f. If this function returns an error, a fog table is also generated but it is different from the one specifically planned by the user and so the effect may be different.
When NULL is specified for pFogTable, the fog table that was generated and fHWFogDensity are set immediately in the hardware.
fFrontBorder(input)
This parameter specifies the depth of the front border of the area where the fog is valid. The value must be greater than 0.0f or fBackBorder.
fBackBorder(input)
This parameter specifies the depth of the back border of the area where the fog is valid. The value must be greater than 0.0f or less than fFrontBorder.
fFogDensity(input)
This parameter specifies the fog density. The value must be floating point and greater than 0.0f. The value has the following meanings according to the type of fog.
If dwFogType == KM_FOGTYPE_NONE
This value carries no meaning.
If dwFogType == KM_FOGTYPE_LINEAR
Each of the elements of the generated table will be multiplied by this value. Control of the density of fog is possible. The valid value is between 0.0f and 1.0f.
If dwFogType == KM_FOGTYPE_EXPONENTIAL
The steepness of the density of the fog table can be changed. The bigger this value is, the steeper the density will become. When specifying the value, use floating point and make sure it is greater than 0.0f.
If dwFogType == KM_FOGTYPE_EXPONENTIAL2
The steepness of the density of the fog table can be changed. The bigger this value is, the steeper the density will become. When specifying the value, use floating point and make sure it is greater than 0.0f.
*fHWFogDensity(output)
This parameter returns the fog coefficient, in floating point, set at the PowerVR hardware by the kmSetFogDensity function. Be sure to use the kmConvertFogDensity function to convert it to WORD value and use the kmSetFogDensity function to set to the hardware.
dwFogType(input)
This parameter specifies the type of fog table. Depending on the fog type selected, the density steepness of the generated fog table will be different. One of the following can be selected.
Type Code | Description |
---|---|
KM_FOGTYPE_NONE | Specifies to use no fog. All entries in the fog table become zero. |
KM_FOGTYPE_LINEAR | Sets linear fog. A fog table is generated with the line shape changing in the interval of depth value from fFrontBorder to fBackBorder. |
KM_FOGTYPE_EXPONENTIAL | Sets exponential fog. This is equivalent to the exponential fog mode of Direct3D. |
KM_FOGTYPE_EXPONENTIAL2 | Sets exponential fog. This is equivalent to the exponential squared fog mode of Direct3D. |
Return values:
Value | Explanation |
---|---|
KMSTATUS_SUCCESS | Success |
KMSTATUS_OUT_OF_RANGE | fBackBorder is less than 0.0f, or fBackBorder is greater than fFrontBorder, or fFogDensity is less than 0.0f. |
kmGenerateFogTable