Función SDL_OpenAudioDevice
Sintaxis
SDL_AudioDeviceID SDL_OpenAudioDevice(
const char *device,
int iscapture,
const SDL_AudioSpec *desired,
SDL_AudioSpec *obtained,
int allowed_changes);
Descripción
Abre un dispositivo de audio específico.
Parámetros
- device
- Una cadena UTF-8 devuelta por SDL_GetAudioDeviceName() o un nombre específico del controlador según corresponda. NULL solicita el dispositivo por defecto más razonable.
- iscapture
- Distinto de cero para especificar que un dispositivo debe abrirse para grabación, no para reproducción.
- desired
- Una estructura SDL_AudioSpec que representa el formato de salida deseado; véase SDL_OpenAudio() para más información
- obtained
- Una estructura SDL_AudioSpec rellenada con el formato de salida real; véase SDL_OpenAudio() para más información.
- allowed_changes
- 0, o uno o más banderas combinadas con OR.
Valor de retorno
Devuelve un ID de dispositivo válido que es > 0 en caso de éxito o 0 en caso de fallo; llame a SDL_GetErrorpara más información.
Por compatibilidad con SDL 1.2, esto nunca devolverá 1, ya que SDL reserva ese ID para la función heredada SDL_OpenAudio().
Observaciones
SDL_OpenAudio(), a diferencia de esta función, siempre actúa sobre el ID de dispositivo 1. Como tal, esta función nunca devolverá un 1 para no entrar en conflicto con la función heredada.
Por favor, tenga en cuenta que SDL 2.0 antes de 2.0.5 no soportaba grabación; como tal, esta función fallaría si iscapture no era cero. A partir de SDL 2.0.5, la grabación está implementada y este valor puede ser distinto de cero.
Pasar un nombre de dispositivo NULL solicita el valor por defecto más razonable (y es equivalente a lo que hace SDL_OpenAudio() para elegir un dispositivo). El nombre del dispositivo es una cadena UTF-8 reportada por SDL_GetAudioDeviceName(), pero algunos controladores permiten cadenas arbitrarias y específicas del controlador, como un nombre de host/dirección IP para un servidor de audio remoto, o un nombre de archivo en el controlador diskaudio.
Un dispositivo de audio abierto comienza en pausa, y debe ser habilitado para la reproducción llamando a SDL_PauseAudioDevice(devid, 0) cuando esté listo para que su función de callback de audio sea llamada. Dado que el controlador de audio puede modificar el tamaño solicitado del búfer de audio, se debe asignar cualquier búfer de mezcla local después de abrir el dispositivo de audio.
La retrollamada de audio se ejecuta en un hilo separado en la mayoría de los casos; puede prevenir race conditions entre la retrollamada y otros hilos sin pausar completamente la reproducción con SDL_LockAudioDevice(). Para más información sobre el callback, ver SDL_AudioSpec.
Gestionar la especificación de audio a través de desired y obtained.
Cuando se rellena la estructura de la especificación de audio deseada:
desired->freq debe ser la frecuencia en muestras-cuadros-por-segundo (Hz).
desired->format debe ser el formato de audio (AUDIO_S16SYS, etc).
desired->samples es el tamaño deseado del búfer de audio, en marcos de muestra (con salida estéreo, dos muestras -izquierda y derecha- formarían un único marco de muestra). Este número debe ser una potencia de dos, y puede ser ajustado por el controlador de audio a un valor más adecuado para el hardware. Los buenos valores parecen oscilar entre 512 y 8096 inclusive, dependiendo de la aplicación y la velocidad de la CPU. Valores más pequeños reducen la latencia, pero pueden llevar a un desbordamiento si la aplicación está haciendo un procesamiento pesado y no puede llenar el buffer de audio a tiempo. Tenga en cuenta que el número de fotogramas de muestra está directamente relacionado con el tiempo mediante la siguiente fórmula: ms = (sampleframes*1000)/freq.
desired->size es el tamaño en bytes del buffer de audio, y es calculado por SDL_OpenAudioDevice(). Esto no se inicializa.
desired->silence es el valor usado para poner el buffer en silencio, y es calculado por SDL_OpenAudioDevice(). No se inicializa.
desired->callback debe establecerse a una función que será llamada cuando el dispositivo de audio esté listo para más datos. Se le pasa un puntero al buffer de audio, y la longitud en bytes del buffer de audio. Esta función normalmente se ejecuta en un hilo separado, por lo que se debe proteger las estructuras de datos a las que accede llamando a SDL_LockAudioDevice() y SDL_UnlockAudioDevice() en el código. Alternativamente, se puede pasar un puntero NULL aquí, y llamar a SDL_QueueAudio() con cierta frecuencia, para poner en cola más muestras de audio para ser reproducidas (o para dispositivos de captura, llamar a SDL_DequeueAudio() con cierta frecuencia, para obtener muestras de audio).
desired->userdata se pasa como primer parámetro a la función de retrollamada. Si se pasa un callback NULL, este valor es ignorado.
allowed_changes puede tener los siguientes indicadores combinados con OR:
- SDL_AUDIO_ALLOW_FREQUENCY_CHANGE
- SDL_AUDIO_ALLOW_FORMAT_CHANGE
- SDL_AUDIO_ALLOW_CHANNELS_CHANGE
- SDL_AUDIO_ALLOW_SAMPLES_CHANGE
- SDL_AUDIO_ALLOW_ANY_CHANGE
Estas banderas especifican cómo debe comportarse SDL cuando un dispositivo no puede ofrecer una característica específica. Si la aplicación solicita una característica que el hardware no ofrece, SDL siempre intentará obtener el equivalente más cercano.
Por ejemplo, si se solicita un formato de audio float32, pero la tarjeta de sonido sólo soporta int16, SDL ajustará el hardware a int16. Si había establecido SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL cambiará el formato en la estructura obtenida. Si esa bandera no fue establecida, SDL se preparará para convertir el audio float32 de la retrollamada a int16 antes de alimentarlo al hardware y mantendrá el formato originalmente solicitado en la estructura obtenida.
Las especificaciones de audio resultantes, que varían dependiendo del hardware y de los cambios permitidos, se escribirán de nuevo en obtained.
Si su aplicación sólo puede manejar un formato de datos específico, pasar un cero para allowed_changes y dejar que SDL maneje de forma transparente cualquier diferencia.