INuiAudioBeam::GetBeam Method

Article
09/12/2013

Kinect for Windows 1.5, 1.6, 1.7, 1.8

Gets the beam angle, which is the direction that the sensor is actively listening.

Syntax

public:
HRESULT GetBeam(
         double *angle
)

Parameters

angle
Type: double
Contains the horizontal angle (in radians) of the currently selected beam 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. Kinect audio beamforming functionality supports 11 fixed beams, which range from −50 to +50 degrees in 10 degree increments. Applications can use the DirectX Media Object (DMO) adaptive beamforming option, which automatically selects the optimal beam or specify a particular beam. The DMO also includes a source localization algorithm, which estimates the source direction. For more information, see Capturing Audio Data in C#.

Return Value

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

Remarks

Important

You must call IMediaObject::ProcessOutput before calling GetBeam. 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#.

GetBeam 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 GetBeam.

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.

Note

The confidence value reported is in the range [0.0, 1.0], with 1.0 being the highest confidence.

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