Edit

IAudioClient3::GetSharedModeEnginePeriod method (audioclient.h)

  • Article

Returns the range of periodicities supported by the engine for the specified stream format. The periodicity of the engine is the rate at which the engine wakes an event-driven audio client to transfer audio data to or from the engine. The values returned depend on the characteristics of the audio client as specified through a previous call to IAudioClient2::SetClientProperties.

Syntax

HRESULT GetSharedModeEnginePeriod(
  [in]  const WAVEFORMATEX *pFormat,
  [out] UINT32             *pDefaultPeriodInFrames,
  [out] UINT32             *pFundamentalPeriodInFrames,
  [out] UINT32             *pMinPeriodInFrames,
  [out] UINT32             *pMaxPeriodInFrames
);

Parameters

[in] pFormat

Type: const WAVEFORMATEX*

The stream format for which the supported periodicities are queried.

[out] pDefaultPeriodInFrames

Type: UINT32*

The default period with which the engine will wake the client for transferring audio samples

[out] pFundamentalPeriodInFrames

Type: UINT32*

The fundamental period with which the engine will wake the client for transferring audio samples. When setting the audio engine periodicity, you must use an integral multiple of this value.

[out] pMinPeriodInFrames

Type: UINT32*

The shortest period, in audio frames, with which the audio engine will wake the client for transferring audio samples.

[out] pMaxPeriodInFrames

Type: UINT32*

The longest period, in audio frames, with which the audio engine will wake the client for transferring audio samples.

Return value

Type: HRESULT

This method returns S_OK to indicate that it has completed successfully. Otherwise it returns an appropriate error code.

Remarks

Audio clients request a specific periodicity from the audio engine with the PeriodInFrames parameter to IAudioClient3::InitializeSharedAudioStream. The value of PeriodInFrames must be an integral multiple of the value returned in the pFundamentalPeriodInFrames parameter. PeriodInFrames must also be greater than or equal to the value returned in pMinPeriodInFrames and less than or equal to the value of pMaxPeriodInFrames.

For example, for a 44100 kHz format, GetSharedModeEnginePeriod might return:

  • pDefaultPeriodInFrames = 448 frames (about 10.16 milliseconds)

  • pFundamentalPeriodInFrames = 4 frames (about 0.09 milliseconds)

  • pMinPeriodInFrames = 48 frames (about 1.09 milliseconds)

  • pMaxPeriodInFrames = 448 frames (same as the default)

Allowed values for the PeriodInFrames parameter to InitializeSharedAudioStream would include 48 and 448. They would also include things like 96 and 128.

They would NOT include 4 (which is smaller than the minimum allowed value) or 98 (which is not a multiple of the fundamental) or 1000 (which is larger than the maximum allowed value).

Requirements

Requirement Value
Minimum supported client Windows 10 [desktop apps only]
Minimum supported server Windows Server 2016 [desktop apps only]
Target Platform Windows
Header audioclient.h

See also

IAudioClient3