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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.