Método IAudioClient::GetCurrentPadding (audioclient.h)

Artículo
08/22/2023

El método GetCurrentPadding recupera el número de fotogramas de relleno en el búfer del punto de conexión.

Sintaxis

HRESULT GetCurrentPadding(
  [out] UINT32 *pNumPaddingFrames
);

Parámetros

[out] pNumPaddingFrames

Puntero a una variable UINT32 en la que el método escribe el recuento de fotogramas (el número de fotogramas de audio de relleno en el búfer).

Valor devuelto

Si el método se realiza correctamente, devuelve S_OK. Si se produce un error, los posibles códigos de retorno incluyen, pero no están limitados a, los valores que se muestran en la tabla siguiente.

Código devuelto	Descripción
AUDCLNT_E_NOT_INITIALIZED	La secuencia de audio no se ha inicializado correctamente.
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 no están disponibles para su uso.
AUDCLNT_E_SERVICE_NOT_RUNNING	El servicio de audio de Windows no se está ejecutando.
E_POINTER	El parámetro pNumPaddingFrames es NULL.

Comentarios

Este método requiere una inicialización previa de la interfaz IAudioClient . Todas las llamadas a este método producirán un error AUDCLNT_E_NOT_INITIALIZED hasta que el cliente inicialice la secuencia de audio llamando correctamente al método IAudioClient::Initialize .

Este método recupera un valor de relleno que indica la cantidad de datos válidos y no leídos que contiene actualmente el búfer del punto de conexión. Una aplicación de representación puede usar el valor de relleno para determinar la cantidad de datos nuevos que puede escribir de forma segura en el búfer del punto de conexión sin sobrescribir los datos escritos previamente que el motor de audio aún no ha leído del búfer. Una aplicación de captura puede usar el valor de relleno para determinar la cantidad de datos nuevos que puede leer de forma segura desde el búfer del punto de conexión sin leer datos no válidos de una región del búfer en la que el motor de audio aún no ha escrito datos válidos.

El valor de relleno se expresa como una serie de fotogramas de audio. El tamaño de una trama de audio se especifica mediante el miembro nBlockAlign de la estructura WAVEFORMATEX (o WAVEFORMATEXTENSIBLE) que el cliente pasó al método IAudioClient::Initialize . El tamaño en bytes de un fotograma de audio es igual al número de canales de la secuencia multiplicado por el tamaño de muestra por canal. Por ejemplo, el tamaño del marco es de cuatro bytes para una secuencia estéreo (2 canales) con muestras de 16 bits.

Para una secuencia de representación en modo compartido, el valor de relleno notificado por GetCurrentPadding especifica el número de fotogramas de audio que se ponen en cola para reproducir en el búfer del punto de conexión. Antes de escribir en el búfer del punto de conexión, el cliente puede calcular la cantidad de espacio disponible en el búfer restando el valor de relleno de la longitud del búfer. Para asegurarse de que una llamada posterior al método IAudioRenderClient::GetBuffer se realiza correctamente, el cliente debe solicitar una longitud de paquete que no supere el espacio disponible en el búfer. Para obtener la longitud del búfer, llame al método IAudioClient::GetBufferSize .

Para una secuencia de captura en modo compartido, el valor de relleno notificado por GetCurrentPadding especifica el número de fotogramas de los datos de captura que están disponibles en el siguiente paquete del búfer del punto de conexión. En un momento determinado, es posible que cero, uno o más paquetes de datos de captura estén listos para que el cliente lea desde el búfer. Si no hay paquetes disponibles actualmente, el método notifica un valor de relleno de 0. Después de la llamada a GetCurrentPadding , una llamada al método IAudioCaptureClient::GetBuffer recuperará un paquete cuya longitud es exactamente igual al valor de relleno notificado por GetCurrentPadding. Cada llamada a GetBuffer recupera un paquete completo. Un paquete siempre contiene un número entero de fotogramas de audio.

Para una secuencia de captura en modo compartido, llamar a GetCurrentPadding equivale a llamar al método IAudioCaptureClient::GetNextPacketSize . Es decir, el valor de relleno notificado por GetCurrentPadding es igual a la longitud del paquete notificada por GetNextPacketSize.

En el caso de una secuencia de captura o representación en modo exclusivo que se inicializó con la marca de AUDCLNT_STREAMFLAGS_EVENTCALLBACK, el cliente normalmente no tiene ningún uso para el valor de relleno notificado por GetCurrentPadding. En su lugar, el cliente accede a un búfer completo durante cada paso de procesamiento. Cada vez que un búfer está disponible para su procesamiento, el motor de audio notifica al cliente mediante la señalización del identificador de eventos del cliente. Para obtener más información sobre esta marca, vea IAudioClient::Initialize.

En el caso de una secuencia de captura o representación en modo exclusivo que no se inicializó con la marca de AUDCLNT_STREAMFLAGS_EVENTCALLBACK, el cliente puede usar el valor de relleno obtenido de GetCurrentPadding de una manera similar a la descrita anteriormente para una secuencia en modo compartido. Los detalles son los siguientes.

En primer lugar, para una secuencia de representación en modo exclusivo, el valor de relleno especifica el número de fotogramas de audio que se ponen en cola para reproducir en el búfer del punto de conexión. Como antes, el cliente puede calcular la cantidad de espacio disponible en el búfer restando el valor de relleno de la longitud del búfer.

En segundo lugar, para una secuencia de captura en modo exclusivo, el valor de relleno notificado por GetCurrentPadding especifica la longitud actual del siguiente paquete. Sin embargo, este valor de relleno es una instantánea de la longitud del paquete, que podría aumentar antes de que el cliente llame al método IAudioCaptureClient::GetBuffer . Por lo tanto, la longitud del paquete recuperado por GetBuffer es al menos tan grande como, pero puede ser mayor que, el valor de relleno notificado por la llamada GetCurrentPadding que precede a la llamada GetBuffer . En cambio, para una secuencia de captura en modo compartido, la longitud del paquete obtenido de GetBuffer siempre es igual al valor de relleno notificado por la llamada a GetCurrentPadding anterior.

Para obtener un ejemplo de código que llama al método GetCurrentPadding, consulte Representación de un Stream.

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