INuiAudioBeam::GetPosition Method

Article
09/12/2013

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Provides an estimate of the sound source location, which is determined by the KinectAudio DMO's sound source localizer.

Syntax

public:
HRESULT GetPosition(
         double *angle,
         double *confidence
)

Parameters

angle
Type: double
Contains the estimated horizontal angle (in radians) to the sound source in camera coordinates, where the x- and z-axes define the horizontal plane. The angle is relative to the z-axis, which is perpendicular to the Kinect sensor.
confidence
Type: double
Receives the confidence value of the estimate. The value is in the range [0.0 - 1.0], with 1.0 indicating the highest confidence.

Return Value

Type: HRESULT
Returns S_OK if successful; otherwise, returns a failure code.

Remarks

Important

You must call IMediaObject::ProcessOutput before calling GetPosition. The preliminary execution of this method is important because it drives the processing of audio samples. This is required for determining the direction of the sound source. For more information, see Capturing Audio Data in C#.

GetPosition drives the processing of audio samples, which is required for determining the audio source direction.

GetPosition will be successful only if IMediaObject::ProcessOutput has returned S_OK. Do not simply check for success, because IMediaObject::ProcessOutput can also return S_FALSE if it lacks sufficient data to proceed.

If IMediaObject::ProcessOutput returns S_FALSE, continue calling the method until it returns S_OK, and then call GetPosition.

GetPosition is based on a measurement queue. If the queue empties, the function returns zero for both parameters.

Note

The Kinect Audio DirectX Media Object supports 11 beams. They have fixed directions ranging from -0.875 radians to +0.875 radians in .0175 radian increments, which corresponds to approximately -50 degrees to +50 degrees, in ten degree increments.

For a general conceptual discussion about sound beams, see Beamforming.

For a detailed discussion of microphone arrays and microphone array support in Windows, see the white papers Microphone Array Support in Windows Vista and How to Build and Use Microphone Arrays for Windows Vista

For more information about the beam direction generated by the DirectX Media Object, see KinectAudio DMO.

Requirements

Header: Declared in NuiSensor.h.

Share via