Skip to main content
En este tema, se explica el flujo de código previsto sobre cómo usar la reverberación por convolución de hardware en dispositivos XBOX Series X mediante uno de los ejemplos incluidos con el Microsoft Game Development Kit (GDK).

Conexión con el hardware e inicio

Se debe establecer una conexión con la unidad de aceleración de hardware mediante XDspConnect o XDspConnectWithMaximumStreamLimit. El llamador establece los requisitos de la conexión mediante los parámetros siguientes:
  1. baseBuffer: un puntero a la memoria asignada por el usuario suficiente para contener los búferes de entrada, salida, envolvente o multiplicadores de bloque que se pasarán al hardware. Esta memoria se debe asignar mediante XMemAlloc con estos atributos: XALLOC_MEMTYPE_PHYSICAL_CACHEABLE, XALLOC_PAGESIZE_64KB, XALLOC_ALIGNMENT_64K. Estos atributos se deben establecer mediante MAKE_XALLOC_ATTRIBUTES(), como se muestra en el ejemplo siguiente. Esta memoria no se debe liberar hasta que la llamada a XDspDisconnect se realice correctamente. Este búfer debe tener un tamaño mínimo de 64 KB.
  2. baseBufferLength: la longitud del baseBuffer en bytes. Este búfer debe tener al menos 64 KB y no más de 500 MB.
  3. aggregateImpulseResponseInSeconds: representa la duración total de todas las respuestas al impulso individuales que se activarán simultáneamente mediante XDspActivate con XDspProcessType::Convolution. Si este valor es 0, no se puede activar ninguna secuencia con XDspProcessType::Convolution.
  4. handle: un puntero al XDspClientHandle que contendrá el identificador devuelto por esta llamada.
Si la llamada se realiza correctamente, el llamador puede usar el baseBuffer para pasar los datos de entrada y recuperar los datos de salida de las secuencias mediante los parámetros de XDspCommand. Cualquier búfer que se pase en XDspCommand debe estar alineado a 16 bytes. El siguiente ejemplo de un administrador de búferes sencillo se puede usar para administrar los búferes de entrada y salida.
Los búferes de envolvente de cada secuencia deben formar parte del baseBuffer que se pasa a XDspConnect o XDspConnectWithMaximumStreamLimit, de forma similar a los búferes de entrada y salida. La longitud de cada búfer de envolvente se puede calcular de la siguiente manera.
A continuación se muestra el ejemplo de código del primer paso para asignar memoria y establecer una conexión. Tenga en cuenta que se puede usar XDspConnectWithMaximumStreamLimit en lugar de XDspConnect para reducir el uso de memoria interna si el número de secuencias que pueden estar activas es inferior a 256.
Donde XMemAllocAttributes representa los atributos mencionados anteriormente. El código siguiente establece aggregateImpulseResponse en 32 segundos.

Activación y desactivación de secuencias

Una vez establecida la conexión con el dispositivo, el llamador debe enviar un comando de activación de secuencia para iniciar una convolución, FFT o IFFT. El llamador debe especificar el XDspProcessType, el número de tramas por bloque, el número de canales, la longitud de la respuesta al impulso en floats y un puntero a los datos de la respuesta al impulso en el dominio de la frecuencia en XDspActivationParameters. Solo se permiten secuencias mono o estéreo. Para XDspProcessType::ForwardFourierTransform y XDspProcessType::inverseFourierTransform, XDspActivationParameters::impulseResponse debe ser nullptr y XDspActivationParameters::impulseResponseLengthInFloats = 0. XDspActivationOptions se debe establecer adecuadamente. A continuación se muestra el código para activar una secuencia para convolución.
XDspActivate devuelve un búfer XDspStatus como uno de sus parámetros. Este búfer XDspStatus se debe usar para conocer el estado de los comandos procesados por el hardware para esta secuencia. Una vez recibido el resultado de la activación, el llamador puede empezar a enviar datos para la convolución, la FFT o la IFFT. Esto se debe hacer mediante la API XDspSubmitCommand o XDspSubmitCommandWithEnvelope. En cada llamada, el llamador debe hacer lo siguiente:
  1. Rellenar el búfer de entrada con exactamente blockFrameCount de datos.
  2. Rellenar el XDspCommand con los valores adecuados y con búferes de entrada y salida alineados a 16 bytes.
  3. Llamar a XDspSubmitCommand para enviar el comando al hardware. Esta función devuelve un número de secuencia de comando que se puede usar para hacer un seguimiento del número de comandos enviados al hardware.
  4. Para aplicar una envolvente, rellene el búfer de envolvente con valores de ganancia para cada bloque del filtro de respuesta al impulso, llame a XDspSubmitCommandWithEnvelope y continúe realizando esta llamada con el mismo búfer de envolvente hasta que la envolvente ya no sea necesaria o deba cambiarse.
  5. Cuando la envolvente ya no sea necesaria, llame a XDspSubmitCommand o a XDspSubmitCommandWithEnvelope con un nullptr para envelopeBuffer. Tenga en cuenta que XDspSubmitCommandWithEnvelope con un nullptr para envelopeBuffer equivale a XDspSubmitCommand.
  6. Al cambiar la envolvente, el envelopeBuffer actual solo se puede actualizar para la siguiente envolvente si el hardware procesó todos los comandos que usaban esa envolvente y se han recogido los resultados. De lo contrario, use un búfer de envolvente diferente.
El siguiente fragmento de código muestra un ejemplo de cómo rellenar el búfer de envolvente con valores de ganancia para cada bloque del filtro de respuesta al impulso. Aquí se muestra cómo usar solo la primera mitad del filtro de respuesta al impulso, con los valores de ganancia de la primera mitad de los bloques de respuesta al impulso comenzando en 1.0f y disminuyendo linealmente, y la segunda mitad rellenada con un valor de ganancia de 0.0f. Para un filtro de respuesta al impulso estéreo, el filtro completo del canal izquierdo va seguido del filtro del canal derecho; el búfer de envolvente para el filtro de respuesta al impulso estéreo sigue el mismo patrón, con los valores de ganancia de todo el canal izquierdo seguidos de los valores de ganancia de todo el canal derecho. Consulte Información general sobre la envolvente mediante la API XDSP para obtener información sobre cómo calcular el tamaño del búfer de envolvente.
El siguiente fragmento de código muestra cómo aplicar la envolvente mediante una llamada a XDspSubmitCommandWithEnvelope con un envelopeBuffer válido. Es igual que el fragmento que muestra cómo enviar un comando mediante XDspSubmitCommand, salvo que se pasa el parámetro adicional envelopeBuffer. Esto se debe repetir hasta que la envolvente ya no sea necesaria, momento en el que se debe llamar a XDspSubmitCommand o a XDspSubmitCommandWithEnvelope con un nullptr para envelopeBuffer.
A continuación, se puede comprobar XDspStatus para conocer el estado de los comandos enviados al hardware de la siguiente manera:
Cuando se procesan los paquetes de la secuencia o el hardware devuelve un error en el resultado de XDspStatus, se debe llamar a XDspDeactivate.
XDspDeactivate devuelve XDSP_E_PENDING_RESULTS si el hardware no ha terminado de procesar todos los comandos enviados para esta secuencia.

Finalización

Después de que XDspDeactivate se realice correctamente, el llamador debe llamar a XDspDisconnect para desconectarse de la unidad de aceleración de hardware de audio y liberar todos los recursos asignados. Si no se han desactivado todas las secuencias, XDspDisconnect devolverá el error XDSP_E_NOT_ALL_HANDLES_DEACTIVATED.

Documentación de referencia de la API

Consulte también

Información general de XDSP Información general sobre la envolvente mediante la API XDSP
Última modificación el 28 de agosto de 2026