IAudioClient::GetCurrentPadding 메서드(audioclient.h)

아티클
03/14/2023

GetCurrentPadding 메서드는 엔드포인트 버퍼의 패딩 프레임 수를 검색합니다.

구문

HRESULT GetCurrentPadding(
  [out] UINT32 *pNumPaddingFrames
);

매개 변수

[out] pNumPaddingFrames

메서드가 프레임 수(버퍼의 안쪽 여백 오디오 프레임 수)를 쓰는 UINT32 변수에 대한 포인터입니다.

반환 값

메서드가 성공하면 S_OK가 반환되고, 실패할 경우 가능한 반환 코드는 다음 표에 표시된 값을 포함하지만 이에 국한되지 않습니다.

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

설명

이 메서드를 사용하려면 IAudioClient 인터페이스를 미리 초기화해야 합니다. 이 메서드에 대한 모든 호출은 클라이언트가 IAudioClient::Initialize 메서드를 성공적으로 호출하여 오디오 스트림을 초기화할 때까지 오류 AUDCLNT_E_NOT_INITIALIZED 실패합니다.

이 메서드는 엔드포인트 버퍼에 현재 포함된 유효한 읽지 않은 데이터의 양을 나타내는 패딩 값을 검색합니다. 렌더링 애플리케이션은 패딩 값을 사용하여 오디오 엔진이 버퍼에서 아직 읽지 않은 이전에 작성된 데이터를 덮어쓰지 않고 엔드포인트 버퍼에 안전하게 쓸 수 있는 새 데이터의 양을 결정할 수 있습니다. 캡처 애플리케이션은 패딩 값을 사용하여 오디오 엔진이 아직 유효한 데이터를 작성하지 않은 버퍼 영역에서 잘못된 데이터를 읽지 않고 엔드포인트 버퍼에서 안전하게 읽을 수 있는 새 데이터의 양을 결정할 수 있습니다.

안쪽 여백 값은 여러 오디오 프레임으로 표현됩니다. 오디오 프레임의 크기는 클라이언트가 IAudioClient::Initialize 메서드에 전달한 WAVEFORMATEX(또는 WAVEFORMATEXTENSIBLE) 구조체의 nBlockAlign 멤버에 의해 지정됩니다. 오디오 프레임의 크기(바이트)는 스트림의 채널 수와 채널당 샘플 크기를 곱한 값입니다. 예를 들어 프레임 크기는 16비트 샘플이 있는 스테레오(2 채널) 스트림의 경우 4바이트입니다.

공유 모드 렌더링 스트림의 경우 GetCurrentPadding 에서 보고한 패딩 값은 엔드포인트 버퍼에서 재생하기 위해 대기 중인 오디오 프레임 수를 지정합니다. 엔드포인트 버퍼에 쓰기 전에 클라이언트는 버퍼 길이에서 패딩 값을 빼서 버퍼에서 사용 가능한 공간의 양을 계산할 수 있습니다. IAudioRenderClient::GetBuffer 메서드에 대한 후속 호출이 성공하도록 하려면 클라이언트가 버퍼에서 사용 가능한 공간을 초과하지 않는 패킷 길이를 요청해야 합니다. 버퍼 길이를 가져오려면 IAudioClient::GetBufferSize 메서드를 호출합니다.

공유 모드 캡처 스트림의 경우 GetCurrentPadding 에서 보고한 패딩 값은 엔드포인트 버퍼의 다음 패킷에서 사용할 수 있는 캡처 데이터의 프레임 수를 지정합니다. 특정 순간에 클라이언트가 버퍼에서 읽을 수 있도록 캡처 데이터의 0개, 1개 이상의 패킷이 준비될 수 있습니다. 현재 사용할 수 있는 패킷이 없는 경우 메서드는 패딩 값 0을 보고합니다. GetCurrentPadding 호출에 따라 IAudioCaptureClient::GetBuffer 메서드 호출은 GetCurrentPadding에서 보고한 패딩 값과 길이가 정확히 같은 패킷을 검색합니다. GetBuffer에 대한 각 호출은 전체 패킷을 검색합니다. 패킷에는 항상 정수의 오디오 프레임이 포함됩니다.

공유 모드 캡처 스트림의 경우 GetCurrentPadding을 호출하는 것은 IAudioCaptureClient::GetNextPacketSize 메서드를 호출하는 것과 같습니다. 즉, GetCurrentPadding 에서 보고하는 패딩 값은 GetNextPacketSize에서 보고한 패킷 길이와 같습니다.

AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그로 초기화된 단독 모드 렌더링 또는 캡처 스트림의 경우 클라이언트는 일반적으로 GetCurrentPadding에서 보고한 패딩 값을 사용하지 않습니다. 대신 클라이언트는 각 처리 단계 동안 전체 버퍼에 액세스합니다. 버퍼를 처리할 수 있게 될 때마다 오디오 엔진은 클라이언트의 이벤트 핸들에 신호를 전송하여 클라이언트에 알릴 수 있습니다. 이 플래그에 대한 자세한 내용은 IAudioClient::Initialize를 참조하세요.

AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그로 초기화되지 않은 단독 모드 렌더링 또는 캡처 스트림의 경우 클라이언트는 공유 모드 스트림에 대해 이전에 설명한 것과 유사한 방식으로 GetCurrentPadding 에서 가져온 패딩 값을 사용할 수 있습니다. 세부 정보는 다음과 같습니다.

먼저 단독 모드 렌더링 스트림의 경우 패딩 값은 엔드포인트 버퍼에서 재생하기 위해 대기 중인 오디오 프레임 수를 지정합니다. 이전과 마찬가지로 클라이언트는 버퍼 길이에서 패딩 값을 빼서 버퍼에서 사용 가능한 공간의 양을 계산할 수 있습니다.

둘째, 단독 모드 캡처 스트림의 경우 GetCurrentPadding 에서 보고한 패딩 값은 다음 패킷의 현재 길이를 지정합니다. 그러나 이 패딩 값은 패킷 길이의 스냅샷 클라이언트가 IAudioCaptureClient::GetBuffer 메서드를 호출하기 전에 증가할 수 있습니다. 따라서 GetBuffer에서 검색한 패킷의 길이는 적어도 GetBuffer 호출 이전의 GetCurrentPadding 호출에서 보고한 패딩 값보다 클 수 있습니다. 반면 공유 모드 캡처 스트림의 경우 GetBuffer 에서 가져온 패킷의 길이는 항상 이전 GetCurrentPadding 호출에서 보고한 패딩 값과 같습니다.

GetCurrentPadding 메서드를 호출하는 코드 예제는 Stream 렌더링을 참조하세요.

요구 사항

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