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

아티클
03/14/2023

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나노초 시간 단위로 변환합니다.

원시 카운터 값을 10,000,000으로 곱합니다.
결과를 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