다음을 통해 공유

IAudioClock::GetPosition 메서드(audioclient.h)

  • 아티클

GetPosition 메서드는 현재 디바이스 위치를 가져옵니다.

구문

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

매개 변수

[out] pu64Position

메서드가 디바이스 위치를 쓰는 UINT64 변수에 대한 포인터입니다. 디바이스 위치는 스트림 시작부터 스트림의 현재 위치까지의 오프셋입니다. 그러나 이 오프셋이 표현되는 단위는 정의되지 않습니다. 디바이스 위치 값은 IAudioClock::GetFrequency 메서드에서 보고한 빈도와 관련하여만 의미가 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[out] pu64QPCPosition

GetPosition 호출에 대한 응답으로 오디오 엔드포인트 디바이스가 디바이스 위치(*pu64Position)를 읽을 때 메서드가 성능 카운터의 값을 쓰는 UINT64 변수에 대한 포인터입니다. 메서드는 카운터 값을 *pu64QPCPosition에 쓰기 전에 100나노초 시간 단위로 변환합니다. 클라이언트에 성능 카운터 값이 필요하지 않은 경우 이 매개 변수는 NULL 일 수 있습니다.

반환 값

메서드가 성공하고 위치를 정확하게 읽으면 S_OK 반환합니다. 메서드가 성공하지만 호출 기간이 위치 읽기의 정확도를 떨어뜨릴 만큼 충분히 길면 메서드는 S_FALSE 반환합니다. 실패할 경우 가능한 반환 코드에는 다음 표에 표시된 값이 포함되지만 이에 국한되지는 않습니다.

반환 코드 설명
E_POINTER
 pu64Position 매개 변수는 NULL입니다.
AUDCLNT_E_DEVICE_INVALIDATED
 오디오 엔드포인트 디바이스가 분리되었거나 오디오 하드웨어 또는 관련 하드웨어 리소스가 다시 구성, 비활성화, 제거 또는 사용할 수 없게 되었습니다.
AUDCLNT_E_SERVICE_NOT_RUNNING
 Windows 오디오 서비스가 실행되고 있지 않습니다.

설명

스트림의 현재 재생 또는 레코드 위치에 따라 클록을 노출해야 하는 클라이언트를 렌더링하거나 캡처하면 이 메서드를 사용하여 해당 클록을 파생시킬 수 있습니다.

이 메서드는 상관 관계가 있는 두 개의 스트림 위치 값을 검색합니다.

  • 디바이스 위치입니다. 클라이언트는 출력 매개 변수 pu64Position을 통해 디바이스 위치를 가져옵니다. 현재 스피커를 통해 재생 중이거나(렌더링 스트림의 경우) 마이크를 통해 기록되는 샘플의 스트림 위치입니다(캡처 스트림용).
  • 성능 카운터. 클라이언트는 출력 매개 변수 pu64QPCPosition을 통해 성능 카운터를 가져옵니다. 이는 오디오 엔드포인트 디바이스가 스트림 위치(*pu64Position)를 기록할 때 QueryPerformanceCounter 함수를 호출하여 메서드가 가져온 카운터 값입니다. GetPosition은 카운터 값을 100나노초 시간 단위로 변환합니다.
디바이스 위치는 IAudioClock::GetFrequency 메서드에서 보고하는 디바이스 빈도와 결합되지 않는 한 의미가 없습니다. 그 이유는 서로 다른 스트림에 대한 디바이스 위치가 표현되는 단위는 스트림이 공유 모드에서 열렸는지 또는 단독 모드로 열렸는지와 같은 요인에 따라 달라질 수 있기 때문입니다. 그러나 GetFrequency에서 얻은 frequency f는 항상 디바이스 위치 p와 호환되는 단위로 표현됩니다. 따라서 스트림 상대 오프셋(초)은 항상 p/f로 계산될 수 있습니다.

디바이스 위치는 스트림 상대 오프셋입니다. 즉, 스트림의 시작부터 오프셋으로 지정됩니다. 디바이스 위치는 전체 스트림을 포함하고 처음부터 끝까지 연속되는 이상적인 버퍼에 대한 오프셋으로 간주될 수 있습니다.

GetPosition 호출 시 디바이스 위치 및 성능 카운터를 감안할 때 클라이언트는 QueryPerformanceCounter를 호출하여 현재 성능 카운터를 가져오고 원래 디바이스 위치가 기록된 이후 카운터가 얼마나 발전했는지에 따라 디바이스 위치를 추정하여 약간 나중에 디바이스 위치를 보다 적시에 예측할 수 있습니다. 클라이언트는 QueryPerformanceFrequency 함수를 호출하여 카운터를 증가시키는 클록의 빈도를 확인할 수 있습니다. QueryPerformanceCounter에서 가져온 원시 카운터 값을 GetPosition으로 *pu64QPCPosition에 기록된 값과 비교하기 전에 다음과 같이 원시 카운터 값을 100나노초 시간 단위로 변환합니다.

  1. 원시 카운터 값을 10,000,000으로 곱합니다.
  2. 결과를 QueryPerformanceFrequency에서 얻은 카운터 빈도로 나눕니다.
QueryPerformanceCounter 및 QueryPerformanceFrequency에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

새 스트림을 만든 직후 디바이스 위치는 0입니다. IAudioClient::Start 메서드를 호출한 후 디바이스 위치가 균일한 속도로 증가합니다. IAudioClient::Stop 메서드는 디바이스 위치를 중지하고 후속 시작 호출을 수행하면 중지 호출 시 디바이스 위치가 해당 값에서 증가하여 다시 시작됩니다. 스트림이 중지되는 동안에만 발생해야 하는 IAudioClient::Reset에 대한 호출은 디바이스 위치를 0으로 다시 설정합니다.

새 또는 다시 설정 렌더링 스트림이 처음 실행되기 시작하면 오디오 데이터가 엔드포인트 버퍼에서 렌더링 엔드포인트 디바이스로 전파할 시간이 있을 때까지 디바이스 위치가 몇 밀리초 동안 0으로 유지될 수 있습니다. 디바이스를 통해 데이터가 재생되기 시작하면 디바이스 위치가 0에서 0이 아닌 값으로 변경됩니다.

연속적인 디바이스 판독값은 단조롭게 증가하고 있습니다. 두 개의 연속 판독값 간에 디바이스 위치가 변경되지 않을 수 있지만 디바이스 위치는 한 읽기에서 다음 판독값으로 결코 감소하지 않습니다.

pu64Position 매개 변수는 NULL이 아닌 유효한 포인터여야 합니다. 그렇지 않으면 메서드가 실패하고 오류 코드 E_POINTER 반환합니다.

위치 측정은 간헐적인 우선 순위가 높은 이벤트에 의해 때때로 지연될 수 있습니다. 이러한 이벤트는 오디오와 관련이 없을 수 있습니다. 배타적 모드 스트림의 경우 메서드가 성공하는 경우 메서드는 S_OK 대신 S_FALSE 반환할 수 있지만 호출 기간은 보고된 위치의 정확도를 떨어트리기에 충분합니다. 이 경우 호출자는 메서드를 다시 호출하여 반환 값 S_OK 표시된 대로 보다 정확한 위치를 검색하려고 시도할 수 있습니다. 그러나 호출자는 메서드가 S_FALSE 일관되게 반환하는 경우 무한 루프에서 이 테스트를 수행하지 않아야 합니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows Vista [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2008 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 audioclient.h

추가 정보

IAudioClient::Reset

IAudioClient::Start

IAudioClient::Stop

IAudioClock 인터페이스

IAudioClock::GetFrequency