Método IAudioCaptureClient::GetBuffer (audioclient.h)
Recupera un puntero al siguiente paquete disponible de datos en el búfer del punto de conexión de captura.
Sintaxis
HRESULT GetBuffer(
[out] BYTE **ppData,
[out] UINT32 *pNumFramesToRead,
[out] DWORD *pdwFlags,
[out] UINT64 *pu64DevicePosition,
[out] UINT64 *pu64QPCPosition
);
Parámetros
[out] ppData
Puntero a una variable de puntero en la que el método escribe la dirección inicial del siguiente paquete de datos que está disponible para que el cliente lea.
[out] pNumFramesToRead
Puntero a una variable UINT32 en la que el método escribe el recuento de fotogramas (el número de fotogramas de audio disponibles en el paquete de datos). El cliente debe leer todo el paquete de datos o ninguno de ellos.
[out] pdwFlags
Puntero a una variable DWORD en la que el método escribe las marcas de estado del búfer. El método escribe 0 o la combinación or bit a bit de uno o varios de los siguientes valores de enumeración _AUDCLNT_BUFFERFLAGS :
AUDCLNT_BUFFERFLAGS_SILENT
AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY
AUDCLNT_BUFFERFLAGS_TIMESTAMP_ERROR
En windows 7 y versiones posteriores del sistema operativo, esta marca se puede usar para la detección de errores. Para iniciar la secuencia de captura, la aplicación cliente debe llamar a IAudioClient::Start seguida de llamadas a GetBuffer en un bucle para leer paquetes de datos hasta que se hayan leído todos los paquetes disponibles en el búfer del punto de conexión. GetBuffer establece la marca AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY para indicar un error en el búfer señalado por ppData.
[out] pu64DevicePosition
Puntero a una variable UINT64 en la que el método escribe la posición del dispositivo del primer fotograma de audio del paquete de datos. La posición del dispositivo se expresa como el número de fotogramas de audio desde el inicio de la secuencia. Este parámetro puede ser NULL si el cliente no requiere la posición del dispositivo. Para obtener más información, vea la sección Comentarios.
[out] pu64QPCPosition
Puntero a una variable UINT64 en la que el método escribe el valor del contador de rendimiento en el momento en que el dispositivo de punto de conexión de audio grabó la posición del dispositivo del primer fotograma de audio en el paquete de datos. El método convierte el valor del contador en unidades de 100 nanosegundos antes de escribirlo en *pu64QPCPosition. Este parámetro puede ser NULL si el cliente no requiere el valor del contador de rendimiento. Para obtener más información, vea la sección Comentarios.
Valor devuelto
Entre los posibles códigos de retorno se incluyen, entre otros, los valores que se muestran en la tabla siguiente.
| Código devuelto | Descripción |
|---|---|
|
La llamada se realizó correctamente y *pNumFramesToRead es distinto de cero, lo que indica que un paquete está listo para leerse. |
|
La llamada se realizó correctamente y *pNumFramesToRead es 0, lo que indica que no hay datos de captura disponibles para leerse. |
|
Windows 7 y versiones posteriores: 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. |
|
Una llamada A IAudioCaptureClient::GetBuffer anterior sigue en vigor. |
|
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. |
|
No se puede tener acceso al búfer porque hay un restablecimiento de secuencia en curso. |
|
El servicio de audio de Windows no se está ejecutando. |
|
El parámetro ppData, pNumFramesToRead o pdwFlags es NULL. |
Comentarios
Este método recupera el siguiente paquete de datos del búfer del punto de conexión de captura. En un momento determinado, el búfer puede contener cero, uno o más paquetes que están listos para leerse. Normalmente, un subproceso de procesamiento de búfer que lee datos de un búfer de punto de conexión de captura lee todos los paquetes disponibles cada vez que se ejecuta el subproceso.
Durante el procesamiento de una secuencia de captura de audio, la aplicación cliente llama alternativamente a GetBuffer y al método IAudioCaptureClient::ReleaseBuffer . El cliente no puede leer más de un solo paquete de datos con cada llamada GetBuffer . Después de cada llamada a GetBuffer , el cliente debe llamar a ReleaseBuffer para liberar el paquete antes de que el cliente pueda llamar a GetBuffer de nuevo para obtener el siguiente paquete.
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.
Durante cada llamada a GetBuffer , el autor de la llamada debe obtener el paquete completo o ninguno de él. Antes de leer el paquete, el autor de la llamada puede comprobar el tamaño del paquete (disponible a través del parámetro pNumFramesToRead ) para asegurarse de que tiene suficiente espacio para almacenar todo el paquete.
Durante cada llamada a ReleaseBuffer , el autor de la llamada notifica el número de fotogramas de audio que leyó del búfer. Este número debe ser el tamaño de paquete (distinto de cero) o 0. Si el número es 0, la siguiente llamada a GetBuffer presentará al autor de la llamada con el mismo paquete que en la llamada getBuffer anterior.
Después de cada llamada a GetBuffer , los datos del paquete permanecen válidos hasta que la siguiente llamada ReleaseBuffer libera el búfer.
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.
El método genera el contador de rendimiento y la posición del dispositivo a través de los parámetros de salida pu64DevicePosition y pu64QPCPosition . Estos valores proporcionan una marca de tiempo para la primera trama de audio del paquete de datos. Mediante el parámetro de salida pdwFlags , el método indica si la posición del dispositivo notificada es válida.
La posición del dispositivo que el método escribe en *pu64DevicePosition es la posición relativa a la secuencia del fotograma de audio que se está reproduciendo actualmente a través de los altavoces (para una secuencia de representación) o que se graba a través del micrófono (para una secuencia de captura). La posición se expresa como el número de fotogramas desde el principio de la secuencia. El tamaño de un fotograma en una secuencia de audio se especifica mediante el miembro nBlockAlign de la estructura WAVEFORMATEX (o WAVEFORMATEXTENSIBLE) que especifica el formato de secuencia. 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 la muestra por canal. Por ejemplo, para una secuencia estéreo (2 canales) con muestras de 16 bits, el tamaño del fotograma es de cuatro bytes.
El valor del contador de rendimiento que GetBuffer escribe en *pu64QPCPosition no es el valor de contador sin formato obtenido de la función QueryPerformanceCounter . Si t es el valor del contador sin formato y si f es la frecuencia obtenida de la función QueryPerformanceFrequency , GetBuffer calcula el valor del contador de rendimiento de la siguiente manera:
*pu64QPCPosition = 10 000 000.T/F
El resultado se expresa en unidades de 100 nanosegundos. Para obtener más información sobre QueryPerformanceCounter y QueryPerformanceFrequency, consulte la documentación de Windows SDK.
Si no hay ningún paquete nuevo disponible actualmente, el método establece *pNumFramesToRead = 0 y devuelve el código de estado AUDCLNT_S_BUFFER_EMPTY. En este caso, el método no escribe en las variables a las que apuntan los parámetros ppData, pu64DevicePosition y pu64QPCPosition .
Los clientes deben evitar retrasos excesivos entre la llamada GetBuffer que adquiere un paquete y la llamada ReleaseBuffer que libera el paquete. 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. Los clientes que retrasan la liberación de un paquete durante más de un período de riesgo pierden datos de ejemplo.
En Windows 7 y versiones posteriores, 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 un ejemplo de código que llama al método GetBuffer, vea Capturar 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 |
Consulte también
IAudioCaptureClient (interfaz)