Método IAudioRenderClient::GetBuffer (audioclient.h)

Artículo
03/14/2023

Recupera un puntero al siguiente espacio disponible en el búfer del punto de conexión de representación en el que el autor de la llamada puede escribir un paquete de datos.

Sintaxis

HRESULT GetBuffer(
  [in]  UINT32 NumFramesRequested,
  [out] BYTE   **ppData
);

Parámetros

[in] NumFramesRequested

Número de fotogramas de audio del paquete de datos que el autor de la llamada planea escribir en el espacio solicitado en el búfer. Si la llamada se realiza correctamente, el tamaño del área de búfer a la que apunta *ppData coincide con el tamaño especificado en NumFramesRequested.

[out] ppData

Puntero a una variable de puntero en la que el método escribe la dirección inicial del área de búfer en la que el autor de la llamada escribirá el paquete de datos.

Valor devuelto

Si el método se realiza correctamente, devuelve S_OK. Si se produce un error, los códigos de retorno posibles incluyen, entre otros, los valores que se muestran en la tabla siguiente.

Código devuelto	Descripción
AUDCLNT_E_BUFFER_ERROR	GetBuffer no pudo recuperar un búfer de datos y *ppData apunta a NULL. Para obtener más información, vea la sección Comentarios.
AUDCLNT_E_BUFFER_TOO_LARGE	El valor NumFramesRequested supera el espacio de búfer disponible (tamaño de búfer menos tamaño de relleno).
AUDCLNT_E_BUFFER_SIZE_ERROR	La secuencia es el modo exclusivo y usa el almacenamiento en búfer controlado por eventos, pero el cliente intentó obtener un paquete que no era el tamaño del búfer.
AUDCLNT_E_OUT_OF_ORDER	Una llamada A IAudioRenderClient::GetBuffer anterior sigue en vigor.
AUDCLNT_E_DEVICE_INVALIDATED	El dispositivo de punto de conexión de audio se ha desconectado o el hardware de audio o los recursos de hardware asociados se han reconfigurado, deshabilitado, quitado o dejado de estar disponible para su uso.
AUDCLNT_E_BUFFER_OPERATION_PENDING	No se puede tener acceso al búfer porque hay un restablecimiento de secuencia en curso.
AUDCLNT_E_SERVICE_NOT_RUNNING	El servicio de audio de Windows no se está ejecutando.
E_POINTER	El parámetro ppData es NULL.

Comentarios

El autor de la llamada puede solicitar un tamaño de paquete menor o igual que la cantidad de espacio disponible en el búfer (excepto en el caso de una secuencia de modo exclusivo que usa el almacenamiento en búfer controlado por eventos; para obtener más información, vea IAudioClient::Initialize). El espacio disponible es simplemente el tamaño del búfer menos la cantidad de datos del búfer que ya está en cola para reproducirse. Si el autor de la llamada especifica un valor NumFramesRequested que supera el espacio disponible en el búfer, se produce un error en la llamada y se devuelve el código de error AUDCLNT_E_BUFFER_TOO_LARGE.

El cliente es responsable de escribir una cantidad suficiente de datos en el búfer para evitar que se produzcan problemas en la secuencia de audio. Para obtener más información sobre los requisitos de almacenamiento en búfer, vea IAudioClient::Initialize.

Después de obtener un paquete de datos llamando a GetBuffer, el cliente rellena el paquete con datos de representación y emite el paquete al motor de audio llamando al método IAudioRenderClient::ReleaseBuffer .

El cliente debe llamar a ReleaseBuffer después de una llamada GetBuffer que obtenga correctamente un paquete de cualquier tamaño distinto de 0. El cliente tiene la opción de llamar o no llamar a ReleaseBuffer para liberar un paquete de tamaño 0.

En el caso de los tamaños de paquete distinto de cero, el cliente debe alternar llamadas a GetBuffer y ReleaseBuffer. Cada llamada a GetBuffer debe ir seguida de una llamada ReleaseBuffer correspondiente. Una vez que el cliente ha llamado a GetBuffer para adquirir un paquete de datos, el cliente no puede adquirir el siguiente paquete de datos hasta que haya llamado a ReleaseBuffer para liberar el paquete anterior. No se permiten dos o más llamadas consecutivas a GetBuffer o a ReleaseBuffer y se producirá un error en el código de error AUDCLNT_E_OUT_OF_ORDER.

Para garantizar el orden correcto de las llamadas, debe producirse una llamada GetBuffer y su llamada ReleaseBuffer correspondiente en el mismo subproceso.

El tamaño de un fotograma de audio se especifica mediante el miembro nBlockAlign de la estructura WAVEFORMATEX que obtiene el cliente llamando al método IAudioClient::GetMixFormat .

Si el llamador establece NumFramesRequested = 0, el método devuelve el código de estado S_OK pero no escribe en la variable a la que apunta el parámetro ppData .

Los clientes deben evitar retrasos excesivos entre la llamada GetBuffer que adquiere un búfer y la llamada ReleaseBuffer que libera el búfer. La implementación del motor de audio supone que la llamada GetBuffer y la llamada ReleaseBuffer correspondiente se producen dentro del mismo período de procesamiento del búfer. Clientes que retrasan la liberación de un búfer durante más de un período, lo que pierde datos de ejemplo.

En Windows 7, GetBuffer puede devolver el código de error AUDCLNT_E_BUFFER_ERROR para un cliente de audio que usa el búfer de punto de conexión en el modo exclusivo. Este error indica que el búfer de datos no se recuperó porque un paquete de datos no estaba disponible (*ppData recibió NULL).

Si GetBuffer devuelve AUDCLNT_E_BUFFER_ERROR, el subproceso que consume las muestras de audio debe esperar al siguiente paso de procesamiento. El cliente puede beneficiarse de mantener un recuento de las llamadas GetBuffer con errores. Si GetBuffer devuelve este error repetidamente, el cliente puede iniciar un nuevo bucle de procesamiento después de apagar el cliente actual llamando a IAudioClient::Stop, IAudioClient::Reset y liberando el cliente de audio.

Ejemplos

Para obtener ejemplos de código que llaman al método GetBuffer , consulte los temas siguientes:

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	audioclient.h