KSPROPSETID_Synth_Dls

O KSPROPSETID_Synth_Dls conjunto de propriedades contém propriedades que são usadas para baixar amostras e instrumentos DLS para um sintetizador MIDI. Estas são as propriedades de um nó de sintetizador (KSNODETYPE_SYNTHESIZER) em um pino DirectMusic de um filtro DirectMusic (consulte Filtros MIDI e DirectMusic).

Esta seção descreve o comportamento dessas propriedades em relação a como elas baixam e descarregam "partes" de memória que contêm dados DLS. O formato real das partes de dados de onda e instrumento baixados é especificado na discussão de DLS de baixo nível na documentação do SDK do Microsoft Windows.

Os downloads e descarregamentos de DLS podem ocorrer a qualquer momento durante a existência do pino. Ao contrário dos eventos DirectMusic, eles não têm carimbo de data/hora e devem ser processados o mais rápido possível.

Nesta seção, o termo recurso DLS ou apenas recurso refere-se a uma parte do instrumento DLS ou a uma parte de onda DLS. O sistema mantém corretamente as contagens de referência em todos os recursos DLS:

• Quando um cliente descarrega o último instrumento referenciando uma onda, o sistema gera automaticamente uma chamada para descarregar a onda.

• Por outro lado, o sistema adia a chamada para descarregar uma onda até que o cliente descarregue o último instrumento referenciando a onda.

Os itens de propriedade nesse conjunto são especificados por KSPROPERTY_SYNTH_DLS valores de enumeração, conforme definido no arquivo de cabeçalho Dmusprop.h.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_DLS_APPEND especifica a quantidade de espaço de armazenamento reservado que o cliente acrescenta aos dados DLS em cada buffer baixado para o sintetizador.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Não	Pin	KSNODEPROPERTY	ULONG

O valor da propriedade (dados de operação) é do tipo ULONG e especifica o número de bytes que o driver de miniporta precisa reservar para seu próprio uso no final de cada buffer de dados DLS baixado. Em seguida, o cliente aloca cada buffer de download para ser grande o suficiente para conter o número solicitado de bytes após o final dos dados baixados.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_DLS_APPEND retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de status	Significado
STATUS_UNSUCCESSFUL	A operação não foi concluída com êxito.

Esses bytes adicionais destinam-se a drivers que precisam de preenchimento extra para requisitos de alinhamento ou para replicar o início de um exemplo para simplificar a interpolação de exemplo.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_DLS_COMPACT é uma solicitação para que o sintetizador disponibilize a maior parte possível da memória de exemplo livre.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Não	Sim	Pin	KSNODEPROPERTY	Nenhum

Nenhum valor de propriedade (dados de operação) está associado a essa propriedade.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_DLS_COMPACT retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de status	Significado
STATUS_UNSUCCESSFUL	A operação não foi concluída com êxito.

A implementação do manipulador para essa propriedade não deve interromper a reprodução.

Para obter mais informações, consulte a descrição do método IDirectMusicPort::Compact na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_DLS_DOWNLOAD é usada para baixar dados DLS para o sintetizador.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Não	Pin	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

O descritor de propriedade (dados de instância) consiste em uma estrutura KSNODEPROPERTY que é imediatamente seguida por uma estrutura SYNTH_BUFFER, que especifica o local e o tamanho do buffer de dados DLS que está sendo baixado.

O valor da propriedade (dados de operação) é uma estrutura SYNTHDOWNLOAD. O driver de miniporta retorna as seguintes informações nesta estrutura:

• Um identificador que o driver de miniporto gera para identificar exclusivamente os dados DLS baixados. Esse cliente deve salvar esse identificador e usá-lo posteriormente para descarregar os dados (consulte KSPROPERTY_SYNTH_DLS_UNLOAD).

• Um valor booliano que indica se o cliente pode liberar o buffer que contém os dados DLS após a conclusão da solicitação de propriedade. Se o driver de miniporto tiver feito sua própria cópia dos dados DLS, o cliente poderá liberar o buffer. Caso contrário, se o driver de miniporto continuar a usar o buffer de dados DLS original do cliente, o cliente não deverá liberar o buffer até que o driver de miniporto descarregue os dados DLS.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_DLS_DOWNLOAD retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de status	Significado
STATUS_BUFFER_TOO_SMALL	O buffer era muito pequeno para concluir a operação.
STATUS_UNSUCCESSFUL	A operação não foi concluída com êxito.
STATUS_NO_MEMORY	Não há memória disponível para concluir esta solicitação.

Para obter mais informações, consulte a discussão do método IDirectMusicPort::D ownloadInstrument na documentação do SDK do Microsoft Windows.

Exemplo

A solicitação de propriedade KSPROPERTY_SYNTH_DLS_DOWNLOAD especifica o local dos dados de download do DLS com um endereço de memória do usuário. O driver de miniporta deve investigar e bloquear a memória do usuário que contém os dados DLS antes de tentar acessá-los. O código de exemplo a seguir mostra como fazer isso:

  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;
  }

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_DLS_UNLOAD descarrega um recurso de dados DLS que foi baixado anteriormente.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Não	Sim	Pin	KSNODEPROPERTY	HANDLE

O valor da propriedade (dados de operação) é do tipo HANDLE e contém o identificador do recurso de dados DLS baixado que deve ser liberado. Esse é o identificador gerado pelo driver de miniporto para identificar os dados DLS em uma solicitação de propriedadeget KSPROPERTY_SYNTH_DLS_DOWNLOAD anterior.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_DLS_UNLOAD retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de status	Significado
STATUS_BUFFER_TOO_SMALL	O buffer era muito pequeno para concluir a operação.
STATUS_UNSUCCESSFUL	A operação não foi concluída com êxito.
STATUS_PENDING	A operação será concluída posteriormente.

O driver de miniporto deve descarregar os dados DLS assim que não houver nenhuma observação reproduzida que use os dados DLS. Se o sintetizador não conseguir liberar a memória associada ao recurso de dados DLS no momento da solicitação KSPROPERTY_SYNTH_DLS_UNLOAD set-property, ele poderá usar a conclusão da propriedade assíncrona para concluir a solicitação posteriormente.

Se, depois de descarregar o recurso de dados DLS, o sintetizador receber um evento de anotação que usa o recurso, o driver de miniporte deverá ignorar o evento, a menos que um novo recurso de dados DLS tenha sido baixado nesse ínterim.

Para obter mais informações, consulte a discussão do método IDirectMusicPort::UnloadInstrument na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_DLS_WAVEFORMAT é usada para consultar o sintetizador para seu formato de onda de saída.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Não	Pin	KSNODEPROPERTY	WAVEFORMATEX

O valor da propriedade (dados de operação) é do tipo WAVEFORMATEX e especifica o formato de onda do fluxo de saída do sintetizador.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_DLS_WAVEFORMAT retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código. A tabela a seguir mostra alguns dos códigos de erro possíveis.

Código de status	Significado
STATUS_BUFFER_TOO_SMALL	O buffer era muito pequeno para concluir a operação.

Um buffer de valor de propriedade de bytes sizeof(WAVEFORMATEX) pode não ser grande o suficiente para todos os formatos de onda. Por exemplo, um formato multicanal requer um buffer de bytes (WAVEFORMATEXTENSIBLE). Se a solicitação de propriedade retornar um código status de STATUS_BUFFER_TOO_SMALL, o cliente poderá marcar o tamanho do valor da propriedade que o driver de miniporto gera, alocar um buffer maior e enviar uma segunda solicitação.

Para obter mais informações, consulte a descrição do método IDirectMusicPort::GetFormat na documentação do SDK do Microsoft Windows.