IAMCameraControl Interface

The IAMCameraControl interface provides local or remote control over a camera.

This interface should be implemented in Microsoft® DirectShow® for filters that control camera devices that offer some form of device control such as zoom, pan, aperture adjustment, or shutter speed. Note that WDM capture drivers automatically expose this interface from KsProxy.ax if they support the associated kernel streaming property sets.

Applications should use this interface to control device settings such as zoom, pan, aperture adjustment, or shutter speed.

Methods in Vtable Order

IUnknown methods Description

QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMCameraControl methods Description
GetRange Retrieves values associated with the range of a specified camera property.
Set Sets a camera property.
Get Retrieves the value of a specific camera control property.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMCameraControl methods	Description
GetRange	Retrieves values associated with the range of a specified camera property.
Set	Sets a camera property.
Get	Retrieves the value of a specific camera control property.

IAMCameraControl::Get

IAMCameraControl Interface

Retrieves the value of a specific camera control property.

Syntax

HRESULT Get (
	 long Property,
	 long *lValue,
	 long *Flags
	);

Parameters

Property
[in] Value that specifies which property from the CameraControlProperty enumerated type to query.

lValue
[out] Pointer to the retrieved value of the specified property. For a description of the possible ranges and values, see Remarks.

Flags
[out] Pointer to a value from the CameraControlFlags enumerated type that indicates whether the camera property is automatic or manual.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

Each property represented from the CameraControlProperty enumerated type can have an automatic or manual setting. If the Flags parameter is set to CameraControl_Flags_Auto from the CameraControlFlags enumerated type, then the lValue parameter is ignored. The lValue range and meaning depends on the property being queried. The following table describes possible values.

Property lValue range and meaning

Pan Value that specifies the pan setting in degrees. Values range from –180 to +180, with the default set to zero. Positive values are clockwise from the origin (the camera rotates clockwise when viewed from above), and negative values are counterclockwise from the origin. Note that a particular device might implement only a subset of this range.

Tilt Value that specifies the tilt setting in degrees. Values range from –180 to +180, with the default set to zero. Positive values point the imaging plane up, and negative values point the imaging plane down. Note that a particular device might implement only a subset of this range.

Roll Value that specifies the roll setting in degrees. Values range from –180 to +180, with the default being set to zero. Positive values cause a clockwise rotation of the camera along the image viewing axis, and negative values cause a counterclockwise rotation of the camera. Note that a particular device may only implement a subset of this range.

Zoom Value that specifies the zoom setting in millimeter units. Values range from 10 to 600, and the default is device specific.

Exposure Value that specifies the exposure setting in seconds, by using the following formula. For values less than zero, the exposure time is 1/2ⁿ seconds. For positive values and zero, the exposure time is 2ⁿ seconds. Note that a particular device might implement only a subset of this range. For example, a device advertises a range of –7 to 1, with stepping set to 1. The corresponding exposure times are:
Value -7 -6 -5 -4 -3 -2 -1 0 1
Seconds 1/128 1/64 1/32 1/16 1/8 1/4 1/2 1 2

Iris Value that specifies the iris setting expressed as f_stop * 10.

Focus Value that specifies the focus setting as the distance to the optimally focused target, in millimeters. The range and default values are device specific. Note that a particular device might implement only a subset of this range.

IAMCameraControl::GetRange

IAMCameraControl Interface

Retrieves values associated with the range of a specified camera property.

Syntax

HRESULT GetRange ( long property, long *pMin, long *pMax, long *pSteppingDelta, long *pDefault, long *pCapsFlags );

Parameters

property

[in] Value that specifies which property from the CameraControlProperty enumerated type to query.

pMin

[out] Pointer to the minimum range for the specified property.

pMax

[out] Pointer to the maximum range for the specified property.

pSteppingDelta

[out] Pointer to the step size for the specified property.

pDefault

[out] Pointer to the default value of the specified property.

pCapsFlags

[out] Pointer to a value from the CameraControlFlags enumerated type indicating whether the camera property is automatic or manual.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

IAMCameraControl::Set

IAMCameraControl Interface

Sets the value of a specific camera control property.

Syntax

HRESULT Set (
	 long Property,
	 long lValue,
	 long Flags
	);

Parameters

Property

[in] Value that specifies which property from the CameraControlProperty enumerated type to change.

lValue
[in] New value of the specified property.

Flags
[in] Value from the CameraControlFlags enumerated type specifying whether the camera property is automatic or manual.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

Each property represented from the CameraControlProperty enumerated type can have an automatic or manual setting. If the Flags parameter is set to CameraControl_Flags_Auto from the CameraControlFlags enumerated type, then the lValue parameter is ignored. The lValue range and meaning depends on the property being queried. The following table describes possible values.

Property lValue range and meaning

Pan Value that specifies the pan setting in degrees. Values range from –180 to +180, with the default set to zero. Positive values are clockwise from the origin (the camera rotates clockwise when viewed from above), and negative values are counterclockwise from the origin. Note that a particular device might implement only a subset of this range.

Tilt Value that specifies the tilt setting in degrees. Values range from –180 to +180, with the default set to zero. Positive values point the imaging plane up, and negative values point the imaging plane down. Note that a particular device might implement only a subset of this range.

Roll Value that specifies the roll setting in degrees. Values range from –180 to +180, with the default being set to zero. Positive values cause a clockwise rotation of the camera along the image viewing axis, and negative values cause a counterclockwise rotation of the camera. Note that a particular device may only implement a subset of this range.

Zoom Value that specifies the zoom setting in millimeter units. Values range from 10 to 600, and the default is device specific.

Exposure Value that specifies the exposure setting in seconds, by using the following formula. For values less than zero, the exposure time is 1/2ⁿ seconds. For positive values and zero, the exposure time is 2ⁿ seconds. Note that a particular device might implement only a subset of this range. For example, a device advertises a range of –7 to 1, with stepping set to 1. The corresponding exposure times are:
Value -7 -6 -5 -4 -3 -2 -1 0 1
Seconds 1/128 1/64 1/32 1/16 1/8 1/4 1/2 1 2

Iris Value that specifies the iris setting expressed as f_stop * 10.

Focus Value that specifies the focus setting as the distance to the optimally focused target, in millimeters. The range and default values are device specific. Note that a particular device might implement only a subset of this range.

E_FAIL	Failure.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_POINTER	Null pointer argument.
S_OK	Success.