Метод IAudioClock::GetPosition (audioclient.h)

Статья
03/14/2023

Метод GetPosition получает текущую позицию устройства.

Синтаксис

HRESULT GetPosition(
  [out] UINT64 *pu64Position,
  [out] UINT64 *pu64QPCPosition
);

Параметры

[out] pu64Position

Указатель на переменную UINT64 , в которую метод записывает положение устройства. Позиция устройства — это смещение от начала потока до текущей позиции в потоке. Однако единицы измерения, в которых выражается это смещение, неопределенны— значение положения устройства имеет значение только по отношению к частоте, сообщаемой методом IAudioClock::GetFrequency . Дополнительные сведения см. в подразделе "Примечания".

[out] pu64QPCPosition

Указатель на переменную UINT64 , в которую метод записывает значение счетчика производительности в момент, когда звуковое конечное устройство считывает положение устройства (*pu64Position) в ответ на вызов GetPosition . Метод преобразует значение счетчика в 100-наносекундные единицы времени, прежде чем записывать его в *pu64QPCPosition. Этот параметр может иметь значение NULL , если клиенту не требуется значение счетчика производительности.

Возвращаемое значение

Если метод завершается успешно и получает точное считывание позиции, он возвращает S_OK. Если метод завершается успешно, но длительность вызова достаточно длинна, чтобы отвлечься от точности чтения позиции, метод возвращает S_FALSE. В случае сбоя возможные коды возврата включают, но не ограничиваются ими, значения, показанные в следующей таблице.

Код возврата	Описание
E_POINTER	Параметр pu64Position имеет значение NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Устройство конечной точки звука было отключено, или звуковое оборудование или связанные аппаратные ресурсы были перенастроены, отключены, удалены или иным образом стали недоступными для использования.
AUDCLNT_E_SERVICE_NOT_RUNNING	Аудиослужба Windows не запущена.

Клиенты отрисовки или записи, которым необходимо предоставить часы на основе текущего воспроизведения или положения записи потока, могут использовать этот метод для получения этих часов.

Этот метод извлекает два коррелированных значения потоковой позиции:

Положение устройства. Клиент получает положение устройства с помощью выходного параметра pu64Position. Это положение в потоке образца, который в настоящее время воспроизводимся через динамики (для потока отрисовки) или записывается через микрофон (для потока захвата).
Счетчик производительности. Клиент получает счетчик производительности с помощью выходного параметра pu64QPCPosition. Это значение счетчика, полученное методом путем вызова функции QueryPerformanceCounter во время записи аудиоконечного устройства позиции потока (*pu64Position). Обратите внимание, что GetPosition преобразует значение счетчика в 100-наносекундные единицы времени.

Положение устройства не имеет смысла, если оно не сочетается с частотой устройства, сообщаемой методом IAudioClock::GetFrequency . Причина заключается в том, что единицы измерения, в которых выражается положение устройства для разных потоков, могут отличаться в зависимости от таких факторов, как открытие потока в общем или монопольном режиме. Однако частота f , полученная из GetFrequency , всегда выражается в единицах, совместимых с единицами положения устройства p. Таким образом, относительное смещение потока в секундах всегда можно вычислить как p/f.

Положение устройства является относительным по потоку смещением. То есть он указывается как смещение от начала потока. Положение устройства может рассматриваться как смещение в идеализированном буфере, который содержит весь поток и является непрерывным от начала до конца.

Учитывая положение устройства и счетчик производительности во время вызова GetPosition , клиент может обеспечить более своевременную оценку положения устройства чуть позже, вызвав QueryPerformanceCounter , чтобы получить текущий счетчик производительности, и экстраполируя позицию устройства в зависимости от того, насколько далеко счетчик продвинулся с момента записи исходного положения устройства. Клиент может вызвать функцию QueryPerformanceFrequency , чтобы определить частоту часов, которые увеличивают счетчик. Перед сравнением необработанного значения счетчика, полученного из QueryPerformanceCounter , со значением, записанным в *pu64QPCPositionметодом GetPosition, преобразуйте необработанное значение счетчика в 100-наносекундные единицы времени следующим образом:

Умножьте необработанное значение счетчика на 10 000 000.
Разделите результат на частоту счетчика, полученную из QueryPerformanceFrequency.

Дополнительные сведения о QueryPerformanceCounter и QueryPerformanceFrequency см. в документации по Windows SDK.

Сразу после создания нового потока положение устройства равно 0. После вызова метода IAudioClient::Start положение устройства увеличивается с одинаковой скоростью. Метод IAudioClient::Stop замораживает положение устройства, а последующий вызов Start приводит к возобновлению приращения позиции устройства от его значения во время вызова Stop . Вызов IAudioClient::Reset, который должен выполняться только во время остановки потока, сбрасывает положение устройства до 0.

При первоначальном запуске нового потока отрисовки или потока отрисовки сброса его положение устройства может оставаться 0 в течение нескольких миллисекундах, пока звуковые данные не успеют распространиться из буфера конечной точки на устройство конечной точки отрисовки. Положение устройства изменяется с 0 до ненулевого значения, когда данные начинают воспроизводиться на устройстве.

Последовательные показания устройств монотонно увеличиваются. Хотя положение устройства может не меняться между двумя последовательными показаниями, положение устройства никогда не уменьшается от одного чтения к другому.

Параметр pu64Position должен быть допустимым указателем, не имеющим значения NULL , иначе метод завершится ошибкой и вернет код ошибки E_POINTER.

Измерения положения иногда могут задерживаться периодическими событиями с высоким приоритетом. Эти события могут быть не связаны со звуком. В случае потока в монопольном режиме метод может возвращать S_FALSE, а не S_OK, если метод завершается успешно, но длительность вызова достаточно длинна, чтобы отвлечься от точности сообщаемой позиции. В этом случае вызывающий объект может снова вызвать метод , чтобы попытаться получить более точную позицию (на что указывает возвращаемое значение S_OK). Однако вызывающий объект не должен выполнять этот тест в бесконечном цикле в случае, если метод последовательно возвращает S_FALSE.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	audioclient.h