Eksponowanie węzłów wielokanałowych

W wersjach systemu Microsoft Windows wcześniejszych niż Windows XP sterowniki audio WDM nie mają usprawnionego sposobu uwidaczniania węzłów wielokanałowych następujących typów:

#B0 #A1 KSNODETYPE_VOLUME #A2 #C3

#B0 #A1 KSNODETYPE_MUTE #A2 #C3

KSNODETYPE_TONE

W szczególności nie istnieje żaden mechanizm jawnego wysyłania zapytań do węzła dla liczby kanałów, które obsługuje. Chociaż istnieją obejścia tego problemu, mają one wady. Na przykład klient może użyć właściwości KSPROPERTY_AUDIO_VOLUMELEVEL do iteracyjnego wykonywania zapytań dotyczących węzła woluminu (KSNODETYPE_VOLUME) dla poziomu woluminu każdego kanału --0, 1 itd., dopóki żądanie nie zwróci błędu wskazującego, że nie ma więcej kanałów. Jednak ta technika wymaga wielu zapytań i jest zbyt nieefektywna do obsługi nowszych urządzeń audio multichannel. W systemach operacyjnych Windows XP i nowszych ograniczenie to jest rozwiązywane przez zdefiniowanie dwóch dodatkowych bitów flag w elemencie Flags struktury KSPROPERTY_MEMBERSHEADER, które program obsługi właściwości zwraca w odpowiedzi na zapytanie o podstawową obsługę.

• KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL

  Podczas żądania właściwości podstawowej obsługi w węźle program obsługi ustawia ten bit flagi, aby wskazać, że członek MembersCount KSPROPERTY_MEMBERSHEADER zawiera liczbę kanałów, które obsługuje węzeł. W systemach operacyjnych Windows Vista i nowszych systemach operacyjnych Windows ta flaga musi być ustawiona dla każdej właściwości kanału.

• KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM

  Procedura obsługi wykonuje bitową wartość OR między tym bitem flagi a bitem flagi KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL, aby wskazać, że pojedyncza wartość właściwości jest stosowana równomiernie we wszystkich kanałach w węźle. Jeśli na przykład sprzęt oferuje tylko jedną kontrolę poziomu głośności dla wszystkich kanałów, menedżer obsługi podstawowej dla węzła głośności ustawia flagę KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM, aby wskazać to ograniczenie. Jeśli ta flaga nie jest ustawiona, poziom głośności dla każdego kanału może być kontrolowany niezależnie od poziomów głośności dla innych kanałów.

  Uwaga Flaga KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM nie jest używana przez system operacyjny Windows Vista.

W sterownikach miniportów dla systemu Windows XP i nowszych, procedura obsługi właściwości dla węzła wielokanałowej regulacji głośności powinna ustawić bit KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL w odpowiedzi na zapytanie dotyczące obsługi podstawowej KSPROPERTY_AUDIO_VOLUMELEVEL. Procedura obsługi zwraca tablicę struktur KSPROPERTY_STEPPING_LONG, po jednym dla każdego kanału ujawnionego przez węzeł, i ustawia element MembersSize na sizeof(KSPROPERTY_STEPPING_LONG). Każdy element tablicy opisuje minimalne i maksymalne poziomy głośności kanału oraz różnicę między kolejnymi wartościami w tym zakresie. Dla każdego kanału można określić inny zakres, aby kanały z niejednolitymi zakresami mogły być prawidłowo odzwierciedlone. Na przykład, kanał subwoofera może mieć zakres, który różni się od innych kanałów.

W poniższym przykładzie kodu pokazano, jak obsługiwać zapytanie związane z podstawowym wsparciem dla właściwości audio z niejednolitymi wartościami właściwości. Zmienna pDescription w pierwszym wierszu kodu poniżej wskazuje strukturę KSPROPERTY_DESCRIPTION na początku buforu danych, w którym program obsługi zapisuje podstawowe informacje o obsłudze:

  //
  // Fill in the members header.
  //
  PKSPROPERTY_MEMBERSHEADER pMembers = PKSPROPERTY_MEMBERSHEADER(pDescription + 1);

  pMembers->MembersFlags = KSPROPERTY_MEMBER_STEPPEDRANGES;
  pMembers->MembersSize = sizeof(KSPROPERTY_STEPPING_LONG);
  pMembers->MembersCount = ulNumChannels;
  pMembers->Flags = KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL;

  //
  // Fill in the stepped range with the driver default.
  //
  PKSPROPERTY_STEPPING_LONG pRange = PKSPROPERTY_STEPPING_LONG(pMembers + 1);
  pRange->Reserved = 0;

  for (ULONG i=0; i<ulNumChannels; i++)
  {
      pRange[i].Bounds.SignedMinimum = ulChannelMin[i];
      pRange[i].Bounds.SignedMaximum = ulChannelMax[i];
      pRange[i].SteppingDelta = ChannelStepping[i];
  }

  pPropertyRequest->ValueSize = sizeof(KSPROPERTY_DESCRIPTION) +
                                sizeof(KSPROPERTY_MEMBERSHEADER) + 
                                ulNumChannels * sizeof(KSPROPERTY_STEPPING_LONG);

Na poniższej ilustracji przedstawiono układ buforu danych dla tego przykładu. Wskaźniki pDescription, pMembers i pRange są pokazane jako wskazujące na odpowiednie przesunięcia w buforze.

W tym przykładzie program obsługi ustawia MembersCount na ulNumChannels, liczbę kanałów. Rozmiar w bajtach tablicy zakresów to

* Wielkość członkówLiczba członków

Należy pamiętać, że gdyby w tym przykładzie ustawiono flagę KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM, program obsługi ustawiłby wszystkie struktury KSPROPERTY_STEPPING_LONG w tablicy w tym samym zakresie.

Podstawowa obsługa dla właściwości węzła tonu KSPROPERTY_AUDIO_BASS, KSPROPERTY_AUDIO_TREBLE lub KSPROPERTY_AUDIO_MID działa w podobny sposób.

Jeśli węzeł wielokanałowy ma właściwość z wartością właściwości dla kanału typu BOOL, program obsługi podstawowej musi wypełnić wartości dla tablicy zakresu krokowego. W tym przypadku obsługa ustawia elementy członkowskie na wartości pokazane w poniższym przykładzie kodu. Dwa przykłady tego typu właściwości to właściwość KSPROPERTY_AUDIO_MUTE węzła wyciszenia i właściwość KSPROPERTY_AUDIO_BASS_BOOST węzła tonu.

Poniższy przykład kodu pokazuje, jak obsługiwać żądanie podstawowego wsparcia dla węzła wielokanałowego, w przypadku, gdy właściwość ma wartość typu BOOL przypisaną do kanału.

  //
  // Fill in the members header.
  //
  PKSPROPERTY_MEMBERSHEADER pMembers = PKSPROPERTY_MEMBERSHEADER(pDescription + 1);

  pMembers->MembersFlags = KSPROPERTY_MEMBER_STEPPEDRANGES;
  pMembers->MembersSize = sizeof (KSPROPERTY_STEPPING_LONG);
  pMembers->MembersCount = ulNumChannels;
  pMembers->Flags = KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL;

  pPropertyRequest->ValueSize = sizeof(KSPROPERTY_DESCRIPTION) +
                                sizeof(KSPROPERTY_MEMBERSHEADER) + 
                                ulNumChannels * sizeof(KSPROPERTY_STEPPING_LONG);

  //
  // Fill in the stepped range with values in FOR loop.
  //
  PKSPROPERTY_STEPPING_LONG pRange = PKSPROPERTY_STEPPING_LONG(pMembers + 1);
  pRange->Reserved = 0;

  for (ULONG i=0; i<ulNumChannels; i++)
  {
      pRange[i].Bounds.SignedMinimum = 0;
      pRange[i].Bounds.SignedMaximum = 1;
      pRange[i].SteppingDelta = 1;
  }

Zwróć uwagę, że w poprzednim przykładzie kodu pętla FOR używa zera (0) i jednego (1) w celu ustawienia minimalnych i maksymalnych wartości dla zakresów kanałów. Dzieje się tak, ponieważ konfigurujemy węzeł wielokanałowy z właściwością dla każdego kanału typu BOOL.

Jeśli właściwość kanału jest jednolita, można wykonać bitową operację OR pomiędzy flagą KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM a flagą KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL, a następnie przypisać wynik do członka pMembers->Flags. Ta wartość służy do wskazania, że sprzęt stosuje tę samą wartość właściwości jednolicie we wszystkich kanałach w węźle.

Użycie KSPROPERTY_MEMBER_FLAG_UNIFORM i flagi KSPROPERTY_MEMBER_FLAG_MULTICHANNEL eliminuje konieczność grupowania kanałów w pary i uwidaczniania oddzielnego węzła głośności stereo dla każdej pary kanałów, podobnie jak w przykładowym sterowniku Ac97 w zestawie sterowników systemu Windows (WDK). Ponieważ wersje systemu Windows starsze niż Windows XP nie obsługują tych flag, podstawowa obsługa sterownika musi używać interfejsu IPortClsVersion do wykonywania zapytań o wersję Portcls.sys w celu określenia, czy używać tych flag.

Analizator topologii (w sterowniku systemu WDMAud w trybie jądra, Wdmaud.sys) uzyskuje topologię urządzenia audio ze sterownika audio WDM. Parser eksponuje to urządzenie jako tradycyjny mikser audio za pośrednictwem starszego interfejsu API miksera Windows Multimedia. W systemie Windows XP i nowszych WDMAud używa flagi KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_MULTICHANNEL do określenia liczby kanałów do raportowania w elemencie cChannels struktury MIXERLINE. Ponadto, jeśli podstawowy program obsługi węzła określa flagę KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM, komponent WDMAud ustawia flagę MIXERCONTROL_CONTROLF_UNIFORM w odpowiedniej strukturze MIXERCONTROL. Za pomocą tej flagi aplikacje mogą określić, czy mogą dostosować każdy kanał indywidualnie, czy wszystkie kanały równomiernie za pomocą kontrolki głównej. Aby uzyskać więcej informacji na temat MIXERCONTROL, MIXERLINE i interfejsu API miks, zobacz dokumentację Microsoft Windows SDK.

W systemie Windows XP i nowszych program sterowania woluminami SndVol32 (zobacz SysTray i SndVol32) wyświetla kontrolki dla urządzeń wielokanałowych, jak pokazano na poniższej ilustracji.

Jeśli funkcja SndVol32 wykryje linię, która ma więcej niż dwa kanały, zastępuje normalną kontrolkę przesuwania przyciskiem z etykietą Głośność głośnika, która pojawia się powyżej głównego suwaka głośności na poprzedniej ilustracji. Kliknięcie przycisku Głośność głośnika spowoduje wyświetlenie okna dialogowego z kontrolkami dla wszystkich kanałów dla określonego wiersza, jak pokazano na poniższym rysunku.

Ponieważ interfejs API miksera uwidacznia kanały według liczby, wywnioskuje nazwy kanałów z konfiguracji głośnika, która jest obecnie wybrana w oknie dialogowym Zaawansowane właściwości dźwięku w panelu sterowania multimediami systemu Windows (Mmsys.cpl).

Jeśli na przykład urządzenie uwidacznia cztery kanały na linii, a użytkownik wybrał pozycję "głośniki kwadrofoniczne", nazwy kanałów będą "Left" (kanał 0), "Right" (kanał 1), "Back Left" (kanał 2) i "Back Right" (kanał 3), jak pokazano na poprzedniej ilustracji. Zmiana konfiguracji głośnika na "Surround sound speakers" spowoduje mapowanie kanału "Left" (kanał 0), "Right" (kanał 1), "Front Center" (kanał 2) i "Back Center" (kanał 3).

Na poziomie sterowników, właściwość KSPROPERTY_AUDIO_CHANNEL_CONFIG używa wartości maski KSAUDIO_SPEAKER_QUAD lub KSAUDIO_SPEAKER_SURROUND do odpowiedniego reprezentowania konfiguracji kwadrofonicznej lub dźwięku przestrzennego. Plik nagłówka Ksmedia.h definiuje następujące wartości:

  #define KSAUDIO_SPEAKER_QUAD      (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
                                     SPEAKER_BACK_LEFT | SPEAKER_BACK_RIGHT)

  #define KSAUDIO_SPEAKER_SURROUND  (SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT | \
                                     SPEAKER_FRONT_CENTER | SPEAKER_BACK_CENTER)

Każda maska zawiera cztery bity, które określają pozycje głośnika czterech kanałów. W obu przypadkach właściwość KSPROPERTY_AUDIO_VOLUMELEVEL identyfikuje te same cztery kanały, odpowiednio jako kanały 0, 1, 2 i 3.

Jeśli podstawowa obsługa węzła ustawia bit flagi KSPROPERTY_MEMBER_FLAG_BASICSUPPORT_UNIFORM, suwaki wyświetlane w oknie dialogowym Głośność głośnika poruszają się w zgodzie ze zmianami wprowadzonych do dowolnego suwaka.