Edit

KSPROPERTY_CAMERACONTROL_EXTENDED_IRTORCHMODE

  • Article

This extended property control is used by the client to control an IR camera's infrared torch's power level and duty cycle. It is sent to the driver along with a standard KSCAMERA_EXTENDEDPROP_HEADER structure followed by a KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure.

Usage Summary Table

Get Set Target Property descriptor type Property value type
Yes Yes Filter KSPROPERTY KSCAMERA_EXTENDEDPROP_HEADER

Remarks

The property request contains a KSCAMERA_EXTENDEDPROP_HEADER structure and a KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure.

The total property data size is sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING). The Size member of KSCAMERA_EXTENDEDPROP_HEADER is set to this total property data size.

The following are flags that can be placed in the KSCAMERA_EXTENDEDPROP_HEADER.Flags and KSCAMERA_EXTENDEDPROP_HEADER.Capability fields. They define the IR torch's operating mode(s).

Torch mode Description
KSCAMERA_EXTENDEDPROP_IRTORCHMODE_OFF Off
KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALWAYS_ON Always on
KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALTERNATING_FRAME_ILLUMINATION On for every other frame

KSCAMERA_EXTENDEDPROP_IRTORCHMODE is always a synchronous control. The control has no defined behavior when the camera is not streaming.

For a GET request, a driver sets the following fields:

  • KSCAMERA_EXTENDEDPROP_HEADER.Capability with a bitmask of the above KSCAMERA_EXTENDEDPROP_IRTORCHMODE_XXX flags representing the operating modes supported by the camera.
  • KSCAMERA_EXTENDEDPROP_HEADER.Flags to one of the above KSCAMERA_EXTENDEDPROP_IRTORCHMODE_XXX flags to indicate the current operating mode.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.Mode to 0.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.Min to the minimum power level available.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.Max to the maximum power level available.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.Step to the minimum increment between power levels.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.VideoProc.ul to the current power level. This value should default to the same power level normally used by the face authentication control.

For a SET request, a driver uses the following fields:

  • KSCAMERA_EXTENDEDPROP_HEADER.Flags to set an operating mode.
  • KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING.VideoProc.ul to set a power level. This value has no effect on KSCAMERA_EXTENDEDPROP_IRTORCHMODE_OFF.

The table below contains the descriptions and requirements for the KSCAMERA_EXTENDEDPROP_HEADER structure fields when using the metadata control.

Member Description

Version

This must be 1.

PinId

KSCAMERA_EXTENDEDPROP_FILTERSCOPE (0xFFFFFFFF).

Size

This must be sizeof(KSCAMERA_EXTENDEDPROP_HEADER)+sizeof([KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING](/windows-hardware/drivers/ddi/ksmedia/ns-ksmedia-tagkscamera_extendedprop_videoprocsetting)),

Result

This value is ignored for synchronous controls.

Capability

May be any combination of KSCAMERA_EXTENDEDPROP_IRTORCHMODE_OFF, KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALWAYS_ON or KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALTERNATIVE_FRAME_ILLUMINATION. This field must report at least one capability. The field must report either KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALWAYS_ON or KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALTERNATIVE_FRAME_ILLUMINATION or both. The value KSCAMERA_EXTENDEDPROP_IRTORCHMODE_OFF is optional.

Flags

Must be one of the flags reported in Capability. The default must value must be either KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALWAYS_ON or KSCAMERA_EXTENDEDPROP_IRTORCHMODE_ALTERNATIVE_FRAME_ILLUMINATION.

The table below contains the descriptions and requirements for the KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure fields when using the IR torch mode control.

Member Description

Mode

Unused. Must be 0.

Min/Max/Step

The Min/Max/Step contains the minimum/maximum/increment of the IR power settings. Driver must return these for GET operations. (Max – Min) must be evenly divisible by Step. Step may not be zero (0).

VideoProc

For SET operations, the VideoProc.Value.ul must specify the power level within the range described by the Min/Max/Step parameter. For GET operations, the driver must return the current power level.

Reserved

Unused. Must be ignored by the driver.

Requirements

Header

 Ksmedia.h