Método IAudioRenderClient::GetBuffer (audioclient.h)
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 |
|---|---|
|
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. |
|
El valor NumFramesRequested supera el espacio de búfer disponible (tamaño de búfer menos tamaño de relleno). |
|
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. |
|
Una llamada A IAudioRenderClient::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 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 |