Estrutura WAVEFORMATEXTENSIBLE (ksmedia.h)
A estrutura WAVEFORMATEXTENSIBLE especifica o formato de um fluxo de onda de áudio.
Sintaxe
typedef struct {
WAVEFORMATEX Format;
union {
WORD wValidBitsPerSample;
WORD wSamplesPerBlock;
WORD wReserved;
} Samples;
DWORD dwChannelMask;
GUID SubFormat;
} WAVEFORMATEXTENSIBLE, *PWAVEFORMATEXTENSIBLE;
Membros
Format
Especifica o formato de dados de onda do fluxo. Esse membro é uma estrutura do tipo WAVEFORMATEX. O membro wFormat de WAVEFORMATEX deve ser definido como WAVE_FORMAT_EXTENSIBLE. O membro wBitsPerSample de WAVEFORMATEX é definido de forma inequívoca como o tamanho do contêiner para cada exemplo. Contêineres de exemplo são sempre alinhados a bytes e wBitsPerSample deve ser um múltiplo de oito.
Samples
Samples.wValidBitsPerSample
Especifica a precisão do exemplo em bits. O valor desse membro deve ser menor ou igual ao tamanho do contêiner especificado no Formato. membro wBitsPerSample . Para obter mais informações, consulte a seção Comentários a seguir.
Samples.wSamplesPerBlock
Especifica o número de amostras contidas em um bloco compactado. Esse valor é útil para estimar os requisitos de buffer para formatos compactados que têm um número fixo de amostras em cada bloco. Defina esse membro como zero se cada bloco de dados de áudio compactados contiver um número variável de exemplos. Nesse caso, as informações de estimativa de buffer e posição de buffer devem ser obtidas de outras maneiras.
Samples.wReserved
Reservado para uso interno pelo sistema operacional. Inicialize para zero.
dwChannelMask
Especifica a atribuição de canais no fluxo multicanal para posições de alto-falante. A codificação é a mesma usada para o membro ActiveSpeakerPositions da estrutura KSAUDIO_CHANNEL_CONFIG . Para obter mais informações, consulte a seção Comentários.
SubFormat
Especifica o subformulário. Para obter mais informações, consulte a seção Comentários.
Comentários
WAVEFORMATEXTENSIBLE é uma forma estendida da estrutura WAVEFORMATEX . WAVEFORMATEX pode descrever sem ambiguidade apenas um subconjunto dos formatos que podem ser descritos por WAVEFORMATEXTENSIBLE. WAVEFORMATEXTENSIBLE não está sujeito às limitações de WAVEFORMATEX, que não pode especificar formatos sem ambiguidade com mais de dois canais ou para os quais o número de bits válidos por exemplo não é igual ao tamanho do contêiner de exemplo. Para obter mais informações, consulte Formatos de dados de áudio e intervalos de dados.
Frequentemente, o membro wValidBitsPerSample , que especifica a precisão de exemplo, contém o mesmo valor que o Formato. membro wBitsPerSample , que especifica o tamanho do contêiner de exemplo. No entanto, esses valores podem ser diferentes. Por exemplo, se os dados de onda se originaram de um conversor A/D de 20 bits, wValidBitsPerSample deverá ser 20, mas Formatar. wBitsPerSample pode ser 24 ou 32. Se wValidBitsPerSample for menor que Format. wBitsPerSample, os bits válidos (os dados reais do PCM) são alinhados à esquerda dentro do contêiner. Os bits não utilizados na parte menos significativa do contêiner devem ser definidos como zero.
Os contêineres de exemplo começam e terminam em limites de bytes e o valor de Formato. wBitsPerSample deve ser sempre um múltiplo de oito. Além disso, o valor de wValidBitsPerSample nunca deve exceder o de Format. wBitsPerSample. Os drivers devem rejeitar formatos de onda que violem essas regras.
O membro dwChannelMask da estrutura WAVEFORMATEXTENSIBLE contém uma máscara que indica quais canais estão presentes no fluxo multicanal. O bit menos significativo representa o alto-falante frontal à esquerda, o próximo bit corresponde ao alto-falante frontal direito e assim por diante. Os bits de sinalizador a seguir são definidos no arquivo de cabeçalho Ksmedia.h.
| Posição do locutor | Bit de sinalizador |
|---|---|
| SPEAKER_FRONT_LEFT | 0x1 |
| SPEAKER_FRONT_RIGHT | 0x2 |
| SPEAKER_FRONT_CENTER | 0x4 |
| SPEAKER_LOW_FREQUENCY | 0x8 |
| SPEAKER_BACK_LEFT | 0x10 |
| SPEAKER_BACK_RIGHT | 0x20 |
| SPEAKER_FRONT_LEFT_OF_CENTER | 0x40 |
| SPEAKER_FRONT_RIGHT_OF_CENTER | 0x80 |
| SPEAKER_BACK_CENTER | 0x100 |
| SPEAKER_SIDE_LEFT | 0x200 |
| SPEAKER_SIDE_RIGHT | 0x400 |
| SPEAKER_TOP_CENTER | 0x800 |
| SPEAKER_TOP_FRONT_LEFT | 0x1000 |
| SPEAKER_TOP_FRONT_CENTER | 0x2000 |
| SPEAKER_TOP_FRONT_RIGHT | 0x4000 |
| SPEAKER_TOP_BACK_LEFT | 0x8000 |
| SPEAKER_TOP_BACK_CENTER | 0x10000 |
| SPEAKER_TOP_BACK_RIGHT | 0x20000 |
Os canais especificados em dwChannelMask devem estar presentes na ordem mostrada na tabela anterior, começando na parte superior.
Por exemplo, se somente front-left e front-center forem especificados, front-left e front-center deverão estar nos canais 0 e 1, respectivamente, do fluxo intercalado.
Como segundo exemplo, se nChannels (no membro Format ; consulte WAVEFORMATEX) estiver definido como 4 e dwChannelMask estiver definido como 0x00000033, os canais de áudio serão destinados à reprodução para os alto-falantes front-left, front-right, back-left e back-right. Os dados do canal devem ser intercalados nessa ordem dentro de cada bloco.
Locais de canal além dos predefinidos são considerados reservados.
Como alternativa, a máscara de canal pode ser especificada como uma das seguintes constantes, que são definidas em Ksmedia.h e são combinações ORed bit a bit dos sinalizadores anteriores que representam as configurações de alto-falante padrão:
KSAUDIO_SPEAKER_MONO
KSAUDIO_SPEAKER_STEREO
KSAUDIO_SPEAKER_QUAD
KSAUDIO_SPEAKER_SURROUND
KSAUDIO_SPEAKER_5POINT1
KSAUDIO_SPEAKER_7POINT1
KSAUDIO_SPEAKER_DIRECTOUT
Um dispositivo de hardware pode ser definido como uma dessas configurações de alto-falante por uma solicitação KSPROPERTY_AUDIO_CHANNEL_CONFIG set-property. Para obter mais informações sobre como definir configurações de alto-falante, consulte KSAUDIO_CHANNEL_CONFIG.
Normalmente, a contagem em nChannels é igual ao número de bits definido em dwChannelMask, mas isso não é necessariamente assim. Se nChannels for menor que o número de bits definido em dwChannelMask, os bits extras (mais significativos) em dwChannelMask serão ignorados. Se nChannels exceder o número de bits definidos em dwChannelMask, os canais que não têm bits de máscara correspondentes não serão atribuídos a nenhuma posição física do locutor. Em qualquer configuração de alto-falante diferente de KSAUDIO_SPEAKER_DIRECTOUT, um coletor de áudio como KMixer (consulte KMixer System Driver) simplesmente ignora esses canais em excesso e mistura apenas os canais que têm bits de máscara correspondentes.
KSAUDIO_SPEAKER_DIRECTOUT representa uma configuração sem alto-falantes e é definida em Ksmedia.h como zero. Nessa configuração, o dispositivo de áudio renderiza o primeiro canal para a primeira porta no dispositivo, o segundo canal para a segunda porta no dispositivo e assim por diante. Isso permite que um aplicativo de criação de áudio gere dados multicanal diretamente e sem modificação em um dispositivo, como um mixer digital ou um dispositivo de armazenamento de áudio digital (disco rígido ou ADAT). Por exemplo, canais de 0 a 30 podem conter, respectivamente, bateria, guitarra, baixo, voz e assim por diante. Para esse tipo de dados de áudio brutos, as posições do alto-falante não têm sentido e atribuir posições de alto-falante aos fluxos de entrada ou saída pode fazer com que um componente como KMixer interfira inadequadamente executando uma conversão de formato indesejado. Se um dispositivo não puder processar os fluxos de áudio brutos, ele deverá rejeitar uma solicitação para alterar a configuração do alto-falante para KSAUDIO_SPEAKER_DIRECTOUT. Para obter mais informações, consulte DSSPEAKER_DIRECTOUT Configuração do Locutor.
Para obter mais informações sobre configurações multicanal, consulte o white paper intitulado Multiple Channel Audio Data and WAVE Files no site de tecnologia de áudio .
O membro SubFormat contém um GUID que especifica o formato de dados geral para um fluxo de ondas. Por exemplo, esse GUID pode especificar que o fluxo contém dados inteiros do PCM. Os outros membros fornecem informações adicionais, como o tamanho da amostra e o número de canais. O significado do GUID subformatação é semelhante ao da marca de formato de 16 bits no membro wFormatTag da estrutura WAVEFORMATEX.
Antes de WAVEFORMATEXTENSIBLE ser introduzido no Windows 98 Second Edition, WAVEFORMATEX era a estrutura preferencial para especificar formatos de onda. Nesse momento, os fornecedores precisavam registrar cada novo formato de onda com a Microsoft para que uma marca de formato oficial pudesse ser atribuída ao formato. Uma lista de marcas de formato registradas aparece no arquivo de cabeçalho público Mmreg.h.
Com WAVEFORMATEXTENSIBLE, o registro de formatos não é mais necessário. Os fornecedores podem atribuir guids subformatação independentemente aos novos formatos, conforme necessário. No entanto, a Microsoft lista alguns dos GUIDs subformatação mais populares no arquivo de cabeçalho público Ksmedia.h. Antes de definir um novo GUID de SubFormatação, os fornecedores devem marcar a lista de constantes KSDATAFORMAT_SUBTYPE_Xxx em Ksmedia.h para ver se um GUID apropriado já foi definido para um formato específico.
Para compatibilidade com versões anteriores, qualquer formato de onda que possa ser especificado por uma estrutura WAVEFORMATEX autônoma também pode ser definido por uma estrutura WAVEFORMATEXTENSIBLE. Portanto, cada marca de formato em Mmreg.h tem um GUID subformatação correspondente. A tabela a seguir mostra algumas marcas de formato típicas e seus GUIDs subformatação correspondentes.
| Marca de formato | GUID de SubFormatação |
|---|---|
| WAVE_FORMAT_PCM | KSDATAFORMAT_SUBTYPE_PCM |
| WAVE_FORMAT_IEEE_FLOAT | KSDATAFORMAT_SUBTYPE_IEEE_FLOAT |
| WAVE_FORMAT_DRM | KSDATAFORMAT_SUBTYPE_DRM |
| WAVE_FORMAT_ALAW | KSDATAFORMAT_SUBTYPE_ALAW |
| WAVE_FORMAT_MULAW | KSDATAFORMAT_SUBTYPE_MULAW |
| WAVE_FORMAT_ADPCM | KSDATAFORMAT_SUBTYPE_ADPCM |
Para obter mais informações, consulte Converter entre marcas de formato e GUIDs de subformulário.
Como WAVEFORMATEXTENSIBLE é uma versão estendida de WAVEFORMATEX, ele pode descrever formatos adicionais que não podem ser descritos apenas por WAVEFORMATEX. Os fornecedores são livres para definir seus próprios GUIDs de SubFormatação para identificar formatos proprietários para os quais não existem marcas de formato de onda.
Requisitos
| Requisito | Valor |
|---|---|
| Cabeçalho | ksmedia.h (inclua Mmreg.h, Ksmedia.h, Mmreg.h) |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de