Función Mix_RegisterEffect

Sintaxis

int Mix_RegisterEffect(int chan, Mix_EffectFunc_t f, Mix_EffectDone_t d, void *arg);

Descripción

Registra una función de efecto especial.

Parámetros

chan

El canal al que registrar un efecto, o MIX_CHANNEL_POST.

f

Retrollamada de efecto a ejecutar cuando más de este canal va a ser mezclado.

d

Efecto hecho callback

arg

Argumento

Valor de retorno

Devuelve cero si hay error (no existe tal canal), distinto de cero si se ha añadido. Los mensajes de error se pueden recuperar desde Mix_GetError().

Observaciones

En el momento de la mezcla, los datos del canal se copian en un búfer y se pasan a través de cada función de efecto registrada. Después de pasar por todas las funciones, se mezclan en el flujo de salida final. La copia al buffer se realiza una vez, luego cada función de efecto actúa sobre la salida del efecto anterior. Se comprende que esta copia extra a un buffer no se realiza si no hay efectos registrados para un chunk dado, lo que ahorra ciclos de CPU, y cualquier efecto dado será ciclos extra, también, por lo que es crucial que el código corra rápido. También hay que tener en cuenta que los datos que se le dan a su función están en el formato del dispositivo de sonido, y no en el formato que le dio a Mix_OpenAudio(), aunque en realidad pueden ser los mismos. Este es un problema de velocidad desafortunado pero necesario. Usar Mix_QuerySpec() para determinar si se pueden manejar los datos antes de registrar su efecto, y tomar las acciones apropiadas.

También se puede especificar una retrollamada (Mix_EffectDone_t) que es llamado cuando el canal termina de reproducirse. Esto da un control más fino que Mix_ChannelFinished(), en caso de que se necesite liberar recursos específicos del efecto, etc. Si no se necesita, se puede especificar NULL.

Se pueden establecer las retrollamadas antes o después de llamar a Mix_PlayChannel().

Cosas como Mix_SetPanning() son solo funciones internas de efectos especiales, así que si se está usando eso, ya se ha incurrido en la sobrecarga de una copia a un buffer separado, y que estos efectos estarán en la cola con cualquier función que se haya registrado. La lista de efectos registrados para un canal se reinicia cuando un chunk termina de reproducirse, por lo que se necesita establecerlos explícitamente con cada llamada a Mix_PlayChannel*().

También se puede registrar una función de efecto especial que se ejecutará después de la mezcla final. Las reglas para estas retrollamadas son idénticas a las de Mix_RegisterEffect, pero se ejecutan después de que todos los canales y la música se hayan mezclado en un único flujo, mientras que los efectos específicos de canal se ejecutan en un canal determinado antes de que se produzca cualquier otra mezcla. Estas retrollamadas de efectos globales se denominan "postefectos". Los postefectos solo tienen su función Mix_EffectDone_t llamada cuando son desregistrados (ya que el flujo de salida principal nunca está "hecho" en el mismo sentido que un canal). Se deben desregistrar manualmente cuando se haya tenido suficiente. Su retrollamada será indicada que el canal que se está mezclando es MIX_CHANNEL_POST si el procesamiento se considera un postefecto.

Después de que todos estos efectos hayan terminado de procesarse, el callback registrado a través de Mix_SetPostMix() se ejecuta, y entonces el stream va al dispositivo de audio.

¡NO LLAMAR NUNCA a SDL_LockAudio() desde la función callback! Ya se está ejecutando en el hilo de audio y el bloqueo ya está guardado.

Hay que tener en cuenta que a diferencia de la mayoría de las funciones SDL y SDL_mixer, esta función devuelve cero si hay un error, no en caso de éxito. Pedimos disculpas por la incoherencia en el diseño de la API en este caso.