KSPROPSETID_Synth

O KSPROPSETID_Synth conjunto de propriedades contém propriedades que são globais à configuração de um nó de sintetizador (KSNODETYPE_SYNTHESIZER).

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

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_CAPS é usada pelo sistema para determinar os recursos de um sintetizador.

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

O valor da propriedade (dados de operação) é uma estrutura do tipo SYNTHCAPS e especifica os recursos do sintetizador. Esses recursos incluem:

• Quantidade de memória de exemplo disponível

• Número máximo de grupos de canais

• Número máximo de vozes

• Número máximo de canais de áudio

• Efeitos de renderização

Para obter mais informações, consulte SYNTHCAPS.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_CAPS retorna STATUS_SUCCESS para indicar que foi concluída com êxito. Caso contrário, a solicitação retornará um erro apropriado status código.

Para obter mais informações sobre as funcionalidades do sintetizador, consulte o método IDirectMusicPort::GetCaps e a estrutura DMUS_PORTCAPS na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_CHANNELGROUPS é usada pelo sistema para definir ou obter o número de grupos de canais ativos na instância de pino. Os grupos de canais são numerados, começando com zero, em cada instância de pino.

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

O valor da propriedade (dados de operação) é do tipo ULONG e especifica quantos grupos de canais o pino dá suporte. Se um pin der suporte a n grupos de canais, os grupos de canais no pino serão numerados de 0 a n-1.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_CAPS 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 falha 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.

Para obter mais informações sobre grupos de canais, consulte as descrições dos métodos IDirectMusicPort::GetNumChannelGroups e IDirectMusicPort::SetNumChannelGroups na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_LATENCYCLOCK é usada para consultar o driver de miniporto para a hora atual do relógio de latência do fluxo, que é sempre maior que a hora do relógio master.

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

O valor da propriedade (dados de operação) é do tipo ULONGLONG e representa o tempo de latência atual do sintetizador. Essa hora é especificada em relação ao relógio master e expressa em unidades de 100 nanossegundos.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_LATENCYCLOCK 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 falha 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_INVALID_DEVICE_REQUEST	A operação é inválida para este dispositivo.

Os relógios de latência normalmente são usados para sincronizar fluxos de saída de áudio entre vários dispositivos.

Uma solicitação get-property KSPROPERTY_SYNTH_LATENCYCLOCK deve retornar uma hora de relógio de latência igual à hora atual do relógio master, além da latência mínima garantida do filtro de áudio pelo qual o fluxo passa. Um programa de aplicativo que agenda os dados de áudio a serem reproduzidos antes do horário atual do relógio de latência corre o risco de ter os dados reproduzidos com atraso.

Para obter mais informações sobre relógios de latência, consulte o seguinte:

• A discussão da propriedade KSPROPERTY_SYNTH_LATENCYCLOCK em Relógios de Latência.

• As descrições dos métodos IDirectMusicPort::GetLatencyClock e IReferenceClock::GetTime na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_PORTPARAMETERS é usada para obter os parâmetros de configuração de uma porta DirectMusic, que é um termo DirectMusic para um dispositivo que envia ou recebe dados de música. (Na terminologia do KS, a porta DirectMusic não corresponde a um driver de porta DMus. Corresponde a um pino de renderização ou captura em um filtro DirectMusic.)

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

O descritor de propriedade (dados de instância) consiste em uma estrutura KSNODEPROPERTY que é seguida imediatamente por uma estrutura SYNTH_PORTPARAMS. Antes de enviar a solicitação de propriedade, o cliente especifica seus valores de parâmetro solicitados gravando-os na estrutura SYNTH_PORTPARAMS.

O valor da propriedade (dados de operação) também é do tipo SYNTH_PORTPARAMS. O driver de miniporta carrega essa estrutura com os valores de parâmetro que ele realmente usa para configurar a porta.

Valor retornado

Se o driver de miniporto tiver êxito na configuração da porta DirectMusic exatamente conforme especificado pelo chamador, ele retornará o código STATUS_SUCCESS. Caso contrário, ele retornará um código de erro apropriado. A tabela a seguir indica alguns dos possíveis códigos de status de erro.

Código de status	Significado
STATUS_NOT_ALL_ASSIGNED	A operação foi bem-sucedida, mas o driver de miniporto teve que modificar um ou mais dos valores de parâmetro marcados pelo chamador como válidos no valor da propriedade.
STATUS_UNSUCCESSFUL	A operação não foi concluída com êxito.

Este é o mais complicado dos itens de propriedade DirectMusic a serem manipulados. Embora essa propriedade dê suporte apenas à solicitação get, a solicitação get também define os parâmetros de porta. A porta passa uma estrutura SYNTH_PORTPARAMS como descritor de propriedade para a solicitação de propriedade. Um buffer de valor de propriedade acompanha a solicitação de propriedade, mas como essa é uma solicitação get, o buffer só é usado para recuperar informações do driver de miniporto.

O driver de miniporte deve primeiro copiar a estrutura SYNTH_PORTPARAMS do descritor de propriedade para o buffer property-value. Em seguida, ele deve marcar para ver se ele é capaz de dar suporte a todos os valores de parâmetro que o chamador solicitou (marcados como válidos). Se o driver de miniporta não puder dar suporte a um ou mais dos valores de parâmetro solicitados, ele deverá substituir (na estrutura SYNTH_PORTPARAMS no buffer de valor da propriedade) os valores solicitados para esses parâmetros específicos com os valores aos quais ele pode dar suporte.

Se o driver de miniporto não fizer alterações no SYNTH_PORTPARAMS do chamador, o chamador deverá obter de volta um valor de propriedade que corresponda exatamente aos parâmetros no descritor de propriedade que o chamador enviou originalmente para o driver de miniport.

Por convenção, o driver também preenche valores para parâmetros que não têm bits correspondentes definidos no membro dwValidParams de SYNTH_PORTPARAMS. Isso permite que o chamador veja quais valores padrão o driver de miniporto usado para esses parâmetros. O driver de miniporta gera os valores de parâmetro reais que ele usou para criar o dispositivo de interface de onda.

O manipulador de KSPROPERTY_SYNTH_PORTPARAMETERS do driver de miniporte deve estar preparado para lidar corretamente com solicitações de alterações de taxa de amostragem.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_RUNNINGSTATS é usada para consultar o driver de miniporto quanto às estatísticas de desempenho do sintetizador.

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

O valor da propriedade (dados de operação) é uma estrutura do tipo SYNTH_STATS. O manipulador de propriedades do driver de miniporta grava as seguintes estatísticas nessa estrutura:

• O número médio de vozes reproduzindo

• Uso da CPU

• Número de anotações perdidas

• Quantidade de memória livre

• Nível de volume de pico

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_RUNNINGSTATS 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_INVALID_DEVICE_REQUEST	A operação é inválida para este dispositivo.

As estatísticas de desempenho do sintetizador são atualizadas continuamente enquanto o dispositivo permanece no estado KSSTATE_RUN. Cada vez que o dispositivo entra nesse estado, ele redefine as estatísticas, que zeram valores cumulativos, como o volume de pico e o número de anotações perdidas.

Para obter informações adicionais, consulte a descrição do método IDirectMusicPort::GetRunningStats e a estrutura DMUS_SYNTHSTATS na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_VOICEPRIORITY especifica qual prioridade uma voz específica em um sintetizador MIDI deve ter quando o driver de miniporto precisa bater vozes de seu cache de voz.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Sim	Pin	KSNODEPROPERTY + SYNTHVOICEPRIORITY_INSTANCE	DWORD

O descritor de propriedade (dados de instância) consiste em uma estrutura KSNODEPROPERTY que é seguida imediatamente por uma estrutura de SYNTHVOICEPRIORITY_INSTANCE, que especifica o grupo de canais da voz (conjunto de 16 canais MIDI) e o número do canal (dentro do grupo).

O valor da propriedade (dados de operação) é um DWORD que especifica a prioridade. O cliente usa um KSPROPERTY_SYNTH_VOICEPRIORITY solicitação set-property para enviar a nova prioridade da voz para o driver de miniporto e usa uma solicitação get-property KSPROPERTY_SYNTH_VOICEPRIORITY para recuperar a prioridade atual da voz do driver de miniporto.

Prioridades de voz

As seguintes prioridades de grupo de canais são definidas no arquivo de cabeçalho Dmusprop.h:

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

A lista anterior é ordenada com a prioridade mais alta na parte superior da lista e a mais baixa na parte inferior. Essas prioridades são ORed com os deslocamentos de prioridade de canal para chegar à prioridade de voz para cada canal dentro de um grupo de canais. As prioridades resultantes são passadas nas solicitações get- e set-property.

Os valores de prioridade do grupo de canais anteriores são grandes em comparação com os deslocamentos de prioridade do canal. O resultado é que alterar a prioridade do grupo de canais aumenta ou reduz a prioridade de todo o grupo de canais em relação a outros grupos de canais sem alterar as prioridades relativas dos canais dentro do grupo de canais.

Prioridades padrão

Quando um driver de miniporto sintetizador é criado, ele atribui uma prioridade padrão a cada uma de suas vozes. Os padrões são definidos da seguinte maneira:

• Por padrão, as prioridades são iguais entre grupos de canais. Isso significa, por exemplo, que o canal 5 no grupo de canais 1 tem a mesma prioridade que o canal 5 no grupo de canais 2.

• De acordo com as especificações de Nível 1 do DLS, o canal 10 (o canal de percussão MIDI) tem a prioridade mais alta, seguido por 1 a 9 e 11 a 16.

O arquivo de cabeçalho Dmusprop.h define os seguintes deslocamentos de prioridade:

  DAUD_CHAN10_VOICE_PRIORITY_OFFSET
  DAUD_CHAN1_VOICE_PRIORITY_OFFSET
  DAUD_CHAN2_VOICE_PRIORITY_OFFSET
  DAUD_CHAN3_VOICE_PRIORITY_OFFSET
  DAUD_CHAN4_VOICE_PRIORITY_OFFSET
  DAUD_CHAN5_VOICE_PRIORITY_OFFSET
  DAUD_CHAN6_VOICE_PRIORITY_OFFSET
  DAUD_CHAN7_VOICE_PRIORITY_OFFSET
  DAUD_CHAN8_VOICE_PRIORITY_OFFSET
  DAUD_CHAN9_VOICE_PRIORITY_OFFSET
  DAUD_CHAN11_VOICE_PRIORITY_OFFSET
  DAUD_CHAN12_VOICE_PRIORITY_OFFSET
  DAUD_CHAN13_VOICE_PRIORITY_OFFSET
  DAUD_CHAN14_VOICE_PRIORITY_OFFSET
  DAUD_CHAN15_VOICE_PRIORITY_OFFSET
  DAUD_CHAN16_VOICE_PRIORITY_OFFSET

A lista anterior de deslocamentos é ordenada com a prioridade mais alta na parte superior da lista. O arquivo de cabeçalho Dmusprop.h também define as prioridades padrão dos canais em cada grupo de canais por ORing bit a bit cada um desses deslocamentos com DAUD_STANDARD_VOICE_PRIORITY. Por exemplo, a definição a seguir fornece a prioridade padrão para o canal 1 em cada grupo de canais:

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_VOICEPRIORITY 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.

Para obter mais informações sobre prioridades de voz, consulte as descrições dos métodos IDirectMusicPort::GetChannelPriority e IDirectMusicPort::SetChannelPriority na documentação do SDK do Microsoft Windows.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_VOLUME obtém ou define o nível de volume de um dispositivo sintetizador.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Sim	Pin	KSPROPERTY	LONG

O valor da propriedade (dados de operação) é do tipo LONG e especifica o nível de volume do dispositivo sintetizador. A configuração de volume é especificada em unidades de 1/100º de um decibéis. O driver de miniporte deve alterar seu volume ou relatar seu volume, dependendo se a solicitação deve obter ou definir a propriedade.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_VOLUME 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.

Tabela de Resumo de Uso

A propriedade KSPROPERTY_SYNTH_VOLUMEBOOST especifica a quantidade pela qual o volume de um dispositivo sintetizador é aumentado.

Obter	Definir	Destino	Tipo de descritor de propriedade	Tipo de valor da propriedade
Sim	Sim	Pin	KSNODEPROPERTY	LONG

O valor da propriedade (dados de operação) é do tipo LONG e especifica por quanto aumentar o sinal de áudio após o estágio de combinação. Essa é a quantidade de volume a ser adicionada à saída final do sintetizador após a conclusão de toda a articulação e mistura de voz. A quantidade de aumento de volume é especificada em 1/100º de um decibéis. Esse valor pode ser positivo ou negativo.

Valor retornado

Uma solicitação de propriedade KSPROPERTY_SYNTH_VOLUMEBOOST 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.

Nenhum outro impulso deve ser adicionado à saída. O sintetizador deve seguir convenções estritas de Nível 1 do DLS para articulação.

Essa propriedade é usada para equalizar o volume do sintetizador com outra saída de áudio no sistema e, portanto, os valores de aumento devem ser interpretados de maneira consistente em todos os dispositivos.