KSPROPSETID_Synth_Dls

El KSPROPSETID_Synth_Dls conjunto de propiedades contiene propiedades que se usan para descargar muestras e instrumentos DLS en un sintetizador MIDI. Estas son las propiedades de un nodo sintáctil (KSNODETYPE_SYNTHESIZER) en un pin de DirectMusic de un filtro DirectMusic (consulta Midi y DirectMusic Filters).

En esta sección se describe el comportamiento de estas propiedades con respecto a cómo descargan y descargan "fragmentos" de memoria que contienen datos DLS. El formato real del instrumento descargado y los fragmentos de datos de onda se especifica en la discusión de DLS de bajo nivel en la documentación de Microsoft Windows SDK.

Las descargas y descargas de DLS pueden producirse en cualquier momento durante la existencia del pin. A diferencia de los eventos de DirectMusic, no tienen marca de tiempo y deben procesarse lo antes posible.

En esta sección, el término recurso DLS, o simplemente recurso, hace referencia a un fragmento de instrumento DLS o a un fragmento de onda DLS. El sistema mantiene correctamente recuentos de referencia en todos los recursos dls:

• Cuando un cliente descarga el último instrumento que hace referencia a una onda, el sistema genera automáticamente una llamada para descargar la onda.

• Por el contrario, el sistema aplaza la llamada para descargar una onda hasta que el cliente descargue el último instrumento que hace referencia a la onda.

Los elementos de propiedad de este conjunto se especifican mediante KSPROPERTY_SYNTH_DLS valores de enumeración, tal como se define en el archivo de encabezado Dmusprop.h.

Tabla de resumen de uso

La propiedad KSPROPERTY_SYNTH_DLS_APPEND especifica la cantidad de espacio de almacenamiento reservado que el cliente anexa a los datos DLS de cada búfer que descarga en el sintetizador.

Obtener	Set	Destino	Tipo de descriptor de propiedad	Tipo de valor de propiedad
Sí	No	Anclar	KSNODEPROPERTY	ULONG

El valor de propiedad (datos de operación) es de tipo ULONG y especifica el número de bytes que el controlador de miniporte necesita reservar para su propio uso al final de cada búfer de datos DLS descargado. A continuación, el cliente asigna cada búfer de descarga para que sea lo suficientemente grande como para contener el número solicitado de bytes después del final de los datos descargados.

Valor devuelto

Una solicitud de propiedad KSPROPERTY_SYNTH_DLS_APPEND devuelve STATUS_SUCCESS para indicar que se ha completado correctamente. De lo contrario, la solicitud devuelve un código de estado de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código de estado	Significado
STATUS_UNSUCCESSFUL	La operación no se completó correctamente.

Estos bytes adicionales están diseñados para controladores que necesitan relleno adicional para los requisitos de alineación o para replicar el inicio de un ejemplo con el fin de simplificar la interpolación de muestras.

Tabla de resumen de uso

La propiedad KSPROPERTY_SYNTH_DLS_COMPACT es una solicitud del sintetizador para que esté disponible el mayor fragmento posible de memoria de muestra libre.

Obtener	Set	Destino	Tipo de descriptor de propiedad	Tipo de valor de propiedad
No	Sí	Anclar	KSNODEPROPERTY	None

No hay ningún valor de propiedad (datos de operación) asociado a esta propiedad.

Valor devuelto

Una solicitud de propiedad KSPROPERTY_SYNTH_DLS_COMPACT devuelve STATUS_SUCCESS para indicar que se ha completado correctamente. De lo contrario, la solicitud devuelve un código de estado de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código de estado	Significado
STATUS_UNSUCCESSFUL	La operación no se completó correctamente.

La implementación del controlador para esta propiedad no debe interrumpir la reproducción.

Para obtener más información, vea la descripción del método IDirectMusicPort::Compact en la documentación de Microsoft Windows SDK.

Tabla de resumen de uso

La propiedad KSPROPERTY_SYNTH_DLS_DOWNLOAD se usa para descargar datos DLS en el sintetizador.

Obtener	Set	Destino	Tipo de descriptor de propiedad	Tipo de valor de propiedad
Sí	No	Anclar	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

El descriptor de propiedad (datos de instancia) consta de una estructura KSNODEPROPERTY seguida inmediatamente de una estructura de SYNTH_BUFFER, que especifica la ubicación y el tamaño del búfer de datos DLS que se está descargando.

El valor de propiedad (datos de operación) es una estructura SYNTHDOWNLOAD. El controlador de minipuerto devuelve la siguiente información en esta estructura:

• Identificador que genera el controlador de miniporte para identificar de forma única los datos de DLS descargados. Este cliente debe guardar este identificador y usarlo más adelante para descargar los datos (consulte KSPROPERTY_SYNTH_DLS_UNLOAD).

• Valor booleano que indica si el cliente puede liberar el búfer que contiene los datos DLS una vez completada la solicitud de propiedad. Si el controlador de minipuerto ha realizado su propia copia de los datos DLS, el cliente puede liberar el búfer. De lo contrario, si el controlador de minipuerto sigue usando el búfer de datos DLS original del cliente, el cliente no debe liberar el búfer hasta que el controlador de miniporte descargue los datos DLS.

Valor devuelto

Una solicitud de propiedad KSPROPERTY_SYNTH_DLS_DOWNLOAD devuelve STATUS_SUCCESS para indicar que se ha completado correctamente. De lo contrario, la solicitud devuelve un código de estado de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código de estado	Significado
STATUS_BUFFER_TOO_SMALL	El búfer era demasiado pequeño para completar la operación.
STATUS_UNSUCCESSFUL	La operación no se completó correctamente.
STATUS_NO_MEMORY	No hay memoria disponible para completar esta solicitud.

Para obtener más información, vea la explicación del método IDirectMusicPort::D ownloadInstrument en la documentación de Microsoft Windows SDK.

Ejemplo

La solicitud de propiedad KSPROPERTY_SYNTH_DLS_DOWNLOAD especifica la ubicación de los datos de descarga de DLS con una dirección de memoria del usuario. El controlador de minipuerto debe sondear y bloquear la memoria del usuario que contiene los datos DLS antes de intentar acceder a ellos. En el código de ejemplo siguiente se muestra cómo hacerlo:

  NTSTATUS Status = STATUS_UNSUCCESSFUL;
  PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
  PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
                            FALSE, FALSE, NULL);
  if (pMdl)
  {
      __try
      {
          MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
          PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
 
         // do something with the data here
      }
      __except (EXCEPTION_EXECUTE_HANDLER)
      {
          Status = GetExceptionCode();
      }
 
      MmUnlockPages(pMdl);
      IoFreeMdl(pMdl);
  }
  else
  {
      Status = STATUS_NO_MEMORY;
  }

Tabla de resumen de uso

La propiedad KSPROPERTY_SYNTH_DLS_UNLOAD descarga un recurso de datos DLS que se descargó anteriormente.

Obtener	Set	Destino	Tipo de descriptor de propiedad	Tipo de valor de propiedad
No	Sí	Anclar	KSNODEPROPERTY	HANDLE

El valor de propiedad (datos de operación) es de tipo HANDLE y contiene el identificador del recurso de datos DLS descargado que se va a liberar. Este es el identificador que generó el controlador de minipuerto para identificar los datos DLS en una solicitud de KSPROPERTY_SYNTH_DLS_DOWNLOADget-property anterior.

Valor devuelto

Una solicitud de propiedad KSPROPERTY_SYNTH_DLS_UNLOAD devuelve STATUS_SUCCESS para indicar que se ha completado correctamente. De lo contrario, la solicitud devuelve un código de estado de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código de estado	Significado
STATUS_BUFFER_TOO_SMALL	El búfer era demasiado pequeño para completar la operación.
STATUS_UNSUCCESSFUL	La operación no se completó correctamente.
STATUS_PENDING	La operación se completará más adelante.

El controlador de minipuerto debe descargar los datos dls tan pronto como no haya notas que usen los datos DLS. Si el sintetizador no puede liberar la memoria asociada al recurso de datos DLS en el momento de la solicitud de propiedad set-property de KSPROPERTY_SYNTH_DLS_UNLOAD, puede usar la finalización de propiedades asincrónicas para finalizar la solicitud más adelante.

Si, después de descargar el recurso de datos DLS, el sintetizador recibe un evento de nota que usa el recurso, el controlador de miniporte debe omitir el evento a menos que se haya descargado un nuevo recurso de datos DLS mientras tanto.

Para obtener más información, vea la explicación del método IDirectMusicPort::UnloadInstrument en la documentación de Microsoft Windows SDK.

Tabla de resumen de uso

La propiedad KSPROPERTY_SYNTH_DLS_WAVEFORMAT se usa para consultar el sintetizador para su formato de onda de salida.

Obtener	Set	Destino	Tipo de descriptor de propiedad	Tipo de valor de propiedad
Sí	No	Anclar	KSNODEPROPERTY	WAVEFORMATEX

El valor de propiedad (datos de operación) es de tipo WAVEFORMATEX y especifica el formato de onda del flujo de salida del sintetizador.

Valor devuelto

Una solicitud de propiedad KSPROPERTY_SYNTH_DLS_WAVEFORMAT devuelve STATUS_SUCCESS para indicar que se ha completado correctamente. De lo contrario, la solicitud devuelve un código de estado de error adecuado. En la tabla siguiente se muestran algunos de los posibles códigos de error.

Código de estado	Significado
STATUS_BUFFER_TOO_SMALL	El búfer era demasiado pequeño para completar la operación.

Es posible que un búfer de valor de propiedad de bytes sizeof(WAVEFORMATEX) no sea lo suficientemente grande para todos los formatos de onda. Por ejemplo, un formato multicanal requiere un búfer de bytes sizeof(WAVEFORMATEXTENSIBLE). Si la solicitud de propiedad devuelve un código de estado de STATUS_BUFFER_TOO_SMALL, el cliente puede comprobar el tamaño del valor de propiedad que genera el controlador de miniporte, asignar un búfer mayor y, a continuación, enviar una segunda solicitud.

Para obtener más información, vea la descripción del método IDirectMusicPort::GetFormat en la documentación de Microsoft Windows SDK.