Edit

Share via

Light sensor thresholds

  • Article

This topic provides information about the light sensor thresholds.

The following table shows the driver's default thresholds for the light sensor. The default interval for the light sensor is 10 Hz. For more information about the types shown in the type column, see the PROPVARIANT structure.

Property key Type Required/Optional Default value Description
PKEY_SensorData_LightLevel_Lux VT_R4 Required 0.25f Minimum amount of change of illuminance required to reach the threshold, measured in percentages of lux. A value of 0.25f means 25% change in illuminance.
PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference VT_R4 Optional 1.0f Minimum amount of change of illuminance required to reach the threshold, measured in lux. A value of 1.0f means 1 lux change in illuminance.
Note: Implementing this threshold is highly recommended on portable devices as it helps reduce battery power consumption in low ambient light environments.
PKEY_SensorData_LightChromaticityX VT_R4 Required if color is supported. Optional otherwise 0.01f Minimum amount of change of the CIE 1931 x color coordinate required to reach the threshold, expressed as an absolute difference.
PKEY_SensorData_LightChromaticityY VT_R4 Required if color is supported. Optional otherwise 0.01f Minimum amount of change of the CIE 1931 y color coordinate required to reach the threshold, expressed as an absolute difference.
PKEY_SensorData_LightTemperature_Kelvins VT_R4 Required if color is supported. Optional otherwise 50.0f Minimum amount of change of the light temperature required to reach the threshold, measured in Kelvins.

The light sensor must report new data samples only if the LUX value changes. This recommended reporting model ensures that the light sensor does not report new data samples repeatedly, when it is in a completely dark, zero (0) LUX environment.

If PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference is not provided, ambient light sensor drivers must report a sample reading to the sensors class extension by calling SensorsCxSensorDataReady when PKEY_SensorData_LightLevel_Lux threshold is met. The PKEY_SensorData_LightLevel_Lux threshold is expressed as a percentage of difference in lux. For example, if this threshold value is set to 0.25f and the last sample reported to the sensor class extension was of 40 lux, the next sample to be reported should either be lower than 30 lux or greater than 50 lux (+/-25% of 40). If PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference is provided in addition to PKEY_SensorData_LightLevel_Lux, ambient light sensors must report a sample reading to the sensors class extension if both thresholds are met. For example, if PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference is set to 4.0 lux and PKEY_SensorData_LightLevel_Lux is set to 0.25 (i.e. 25%) and if the value of the last sample reading reported to the sensors class extension is 4 lux, the most restrictive threshold is PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference. Therefore, the next sample reading to be reported should be 0 lux or 8 lux. Comparatively, if PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference is set to 4.0 lux and PKEY_SensorData_LightLevel_Lux is set to 0.25 (i.e. 25%) but the value of the last sample reading reported to the sensors class extension is 40 lux, the most restrictive threshold is PKEY_SensorData_LightLevel_Lux. In this case, the next sample reading to be reported should be 30 lux or 50 lux. PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference is never set without PKEY_SensorData_LightLevel_Lux.

When the sensor driver reports Chromaticity x and Chromaticity y color components, ambient light sensor drivers must also support PKEY_SensorData_LightChromaticityX, PKEY_SensorData_LightChromaticityY, and PKEY_SensorData_LightTemperature_Kelvins thresholds. The ambient light sensor driver reports a sample reading to the sensors class extension when either the PKEY_SensorData_LightChromaticityX, the PKEY_SensorData_LightChromaticityY, or the PKEY_SensorData_LightTemperature_Kelvins threshold is met.

Ambient light sensor drivers must always report one sample reading immediately after the sensors class extension calls the EvtSensorStart callback irrespective of the threshold values. This sample is known as the initial sample reading.

Note

The ambient light sensor driver must also report a sample reading to the sensor class extension when IsValid data field changes, irrespective of the thresholds being set.

When PKEY_SensorData_LightLevel_Lux_Threshold_AbsoluteDifference and PKEY_SensorData_LightLevel_Lux are set to 0.0f, the driver must report sample readings to the sensors class extension at every interval. When PKEY_SensorData_LightChromaticityX or PKEY_SensorData_LightChromaticityY or PKEY_SensorData_LightTemperature_Kelvins is set to 0.0f, the driver must report sample readings to the sensors class extension at every interval. Reporting a sensor sample at every interval is known as sensor sample streaming.

Note

In thresholding mode, do not report consecutive samples that have PKEY_SensorData_IsValid set to FALSE. In other words, in thresholding mode, only send the first sample in which PKEY_SensorData_IsValid was switched to FALSE.