IAudioCaptureClient::GetBuffer 메서드(audioclient.h)

아티클
03/14/2023

캡처 엔드포인트 버퍼에서 사용 가능한 다음 데이터 패킷에 대한 포인터를 검색합니다.

구문

HRESULT GetBuffer(
  [out] BYTE   **ppData,
  [out] UINT32 *pNumFramesToRead,
  [out] DWORD  *pdwFlags,
  [out] UINT64 *pu64DevicePosition,
  [out] UINT64 *pu64QPCPosition
);

매개 변수

[out] ppData

메서드가 클라이언트에서 읽을 수 있는 다음 데이터 패킷의 시작 주소를 쓰는 포인터 변수에 대한 포인터입니다.

[out] pNumFramesToRead

메서드가 프레임 수(데이터 패킷에서 사용할 수 있는 오디오 프레임 수)를 쓰는 UINT32 변수에 대한 포인터입니다. 클라이언트는 전체 데이터 패킷을 읽거나 하나도 읽지 않아야 합니다.

[out] pdwFlags

메서드가 버퍼 상태 플래그를 작성하는 DWORD 변수에 대한 포인터입니다. 메서드는 다음 _AUDCLNT_BUFFERFLAGS 열거형 값 중 하나 이상의 0 또는 비트 OR 조합을 씁니다.

AUDCLNT_BUFFERFLAGS_SILENT

AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY

AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR

참고 AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY 플래그는 Windows Vista에서 지원되지 않습니다.

Windows 7 이상 OS 릴리스에서는 이 플래그를 결함 검색에 사용할 수 있습니다. 캡처 스트림을 시작하려면 클라이언트 애플리케이션이 IAudioClient::Start 를 호출한 다음 루프에서 GetBuffer 를 호출하여 엔드포인트 버퍼에서 사용 가능한 모든 패킷을 읽을 때까지 데이터 패킷을 읽어야 합니다. GetBuffer 는 AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY 플래그를 설정하여 ppData가 가리키는 버퍼의 결함을 나타냅니다.

[out] pu64DevicePosition

메서드가 데이터 패킷에서 첫 번째 오디오 프레임의 디바이스 위치를 쓰는 UINT64 변수에 대한 포인터입니다. 디바이스 위치는 스트림 시작부터 오디오 프레임 수로 표현됩니다. 클라이언트에 디바이스 위치가 필요하지 않은 경우 이 매개 변수는 NULL 일 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[out] pu64QPCPosition

오디오 엔드포인트 디바이스가 데이터 패킷에서 첫 번째 오디오 프레임의 디바이스 위치를 기록할 때 메서드가 성능 카운터의 값을 쓰는 UINT64 변수에 대한 포인터입니다. 메서드는 카운터 값을 *pu64QPCPosition 에 쓰기 전에 100나노초 단위로 변환합니다. 클라이언트에 성능 카운터 값이 필요하지 않은 경우 이 매개 변수는 NULL 일 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

가능한 반환 코드에는 다음 표에 표시된 값이 포함되지만 이에 국한되지는 않습니다.

반환 코드	Description
S_OK	호출이 성공하고 *pNumFramesToRead 가 0이 아니어 패킷을 읽을 준비가 되었음을 나타냅니다.
AUDCLNT_S_BUFFER_EMPTY	호출이 성공하고 *pNumFramesToRead 가 0이므로 읽을 수 있는 캡처 데이터가 없음을 나타냅니다.
AUDCLNT_E_BUFFER_ERROR	Windows 7 이상: GetBuffer 가 데이터 버퍼를 검색하지 못하고 *ppData 가 NULL을 가리킵니다. 자세한 내용은 설명 부분을 참조하세요.
AUDCLNT_E_OUT_OF_ORDER	이전 IAudioCaptureClient::GetBuffer 호출은 여전히 유효합니다.
AUDCLNT_E_DEVICE_INVALIDATED	오디오 엔드포인트 디바이스가 분리되었거나 오디오 하드웨어 또는 관련 하드웨어 리소스가 다시 구성, 비활성화, 제거 또는 사용할 수 없게 되었습니다.
AUDCLNT_E_BUFFER_OPERATION_PENDING	스트림 재설정이 진행 중이므로 버퍼에 액세스할 수 없습니다.
AUDCLNT_E_SERVICE_NOT_RUNNING	Windows 오디오 서비스가 실행되고 있지 않습니다.
E_POINTER	매개 변수 ppData, pNumFramesToRead 또는 pdwFlags는 NULL입니다.

설명

이 메서드는 캡처 엔드포인트 버퍼에서 다음 데이터 패킷을 검색합니다. 특정 시간에 버퍼에는 읽을 준비가 된 0개, 하나 이상의 패킷이 포함될 수 있습니다. 일반적으로 캡처 엔드포인트 버퍼에서 데이터를 읽는 버퍼 처리 스레드는 스레드가 실행 될 때마다 사용 가능한 모든 패킷을 읽습니다.

오디오 캡처 스트림을 처리하는 동안 클라이언트 애플리케이션은 GetBuffer 및 IAudioCaptureClient::ReleaseBuffer 메서드를 번갈아 호출합니다. 클라이언트는 각 GetBuffer 호출을 사용하여 단일 데이터 패킷을 읽을 수 없습니다. 각 GetBuffer 호출 후 클라이언트는 ReleaseBuffer 를 호출하여 패킷을 해제해야 클라이언트가 GetBuffer 를 다시 호출하여 다음 패킷을 가져올 수 있습니다.

GetBuffer 또는 ReleaseBuffer에 대한 두 개 이상의 연속 호출은 허용되지 않으며 오류 코드 AUDCLNT_E_OUT_OF_ORDER 실패합니다. 호출 순서가 올바른지 확인하려면 GetBuffer 호출과 해당 ReleaseBuffer 호출이 동일한 스레드에서 발생해야 합니다.

각 GetBuffer 호출 중에 호출자는 전체 패킷을 가져오거나 패킷을 가져오지 않아야 합니다. 패킷을 읽기 전에 호출자는 패킷 크기(pNumFramesToRead 매개 변수를 통해 사용 가능)를 검사 전체 패킷을 저장할 충분한 공간이 있는지 확인할 수 있습니다.

각 ReleaseBuffer 호출 중에 호출자는 버퍼에서 읽은 오디오 프레임 수를 보고합니다. 이 숫자는 (0이 아닌) 패킷 크기 또는 0이어야 합니다. 숫자가 0이면 다음 GetBuffer 호출은 이전 GetBuffer 호출과 동일한 패킷을 호출자에게 표시합니다.

각 GetBuffer 호출 후에는 다음 ReleaseBuffer 호출이 버퍼를 해제할 때까지 패킷의 데이터가 유효한 상태로 유지됩니다.

클라이언트는 0 이외의 크기의 패킷을 성공적으로 가져오는 GetBuffer 호출 후 ReleaseBuffer를 호출해야 합니다. 클라이언트에는 ReleaseBuffer 를 호출하거나 호출하지 않고 크기 0 패킷을 해제할 수 있습니다.

메서드는 pu64DevicePosition 및 pu64QPCPosition 출력 매개 변수를 통해 디바이스 위치 및 성능 카운터를 출력합니다. 이러한 값은 데이터 패킷의 첫 번째 오디오 프레임에 대한 타임스탬프를 제공합니다. pdwFlags 출력 매개 변수를 통해 메서드는 보고된 디바이스 위치가 유효한지 여부를 나타냅니다.

메서드가 *pu64DevicePosition 에 쓰는 디바이스 위치는 현재 스피커를 통해 재생되거나(렌더링 스트림의 경우) 마이크를 통해 기록되는 오디오 프레임의 스트림 상대 위치입니다(캡처 스트림의 경우). 위치는 스트림의 시작부터 프레임 수로 표현됩니다. 오디오 스트림의 프레임 크기는 스트림 형식을 지정하는 WAVEFORMATEX(또는 WAVEFORMATEXTENSIBLE) 구조체의 nBlockAlign 멤버에 의해 지정됩니다. 오디오 프레임의 크기(바이트)는 채널당 샘플 크기를 곱한 스트림의 채널 수와 같습니다. 예를 들어 16비트 샘플이 있는 스테레오(2 채널) 스트림의 경우 프레임 크기는 4바이트입니다.

GetBuffer가 *pu64QPCPosition에 쓰는 성능 카운터 값은 QueryPerformanceCounter 함수에서 가져온 원시 카운터 값이 아닙니다. t가 원시 카운터 값이고 f가 QueryPerformanceFrequency 함수에서 얻은 빈도인 경우 GetBuffer는 다음과 같이 성능 카운터 값을 계산합니다.

*pu64QPCPosition = 10,000,000^.T/F

결과는 100나노초 단위로 표현됩니다. QueryPerformanceCounter 및 QueryPerformanceFrequency에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

현재 사용할 수 있는 새 패킷이 없는 경우 메서드는 *pNumFramesToRead = 0을 설정하고 코드 AUDCLNT_S_BUFFER_EMPTY 상태 반환합니다. 이 경우 메서드는 ppData, pu64DevicePosition 및 pu64QPCPosition 매개 변수가 가리키는 변수에 쓰지 않습니다.

클라이언트는 패킷을 획득하는 GetBuffer 호출과 패킷을 해제하는 ReleaseBuffer 호출 간에 과도한 지연을 방지해야 합니다. 오디오 엔진의 구현에서는 GetBuffer 호출 및 해당 ReleaseBuffer 호출이 동일한 버퍼 처리 기간 내에 발생한다고 가정합니다. 한 기간 이상 패킷 해제를 지연하는 클라이언트는 샘플 데이터를 잃을 위험이 있습니다.

Windows 7 이상에서 GetBuffer 는 단독 모드에서 엔드포인트 버퍼를 사용하는 오디오 클라이언트에 대한 AUDCLNT_E_BUFFER_ERROR 오류 코드를 반환할 수 있습니다. 이 오류는 데이터 패킷을 사용할 수 없기 때문에 데이터 버퍼가 검색되지 않았음을 나타냅니다(*ppData 가 NULL을 수신).

GetBuffer가 AUDCLNT_E_BUFFER_ERROR 반환하는 경우 오디오 샘플을 사용하는 스레드는 다음 처리 단계를 기다려야 합니다. 클라이언트는 실패한 GetBuffer 호출 수를 유지하는 것이 도움이 될 수 있습니다. GetBuffer가 이 오류를 반복적으로 반환하는 경우 클라이언트는 IAudioClient::Stop, IAudioClient::Reset을 호출하고 오디오 클라이언트를 해제하여 현재 클라이언트를 종료한 후 새 처리 루프를 시작할 수 있습니다.

예제

GetBuffer 메서드를 호출하는 코드 예제는 Stream 캡처를 참조하세요.

요구 사항

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