Sdílet prostřednictvím

Implementace objektů pro zpracování zvuku

Toto téma popisuje, jak implementovat objekt pro zpracování zvuku (APO). Obecné informace o objektech APO naleznete v tématu Architektura objektů zpracování zvuku.

Implementace vlastních rozhraní API

Vlastní objekty APO se implementují jako objekty modelu COM v procesu, takže se spouštějí v uživatelském režimu a jsou zabalené v dynamické knihovně (DLL). Existují tři typy APO na základě toho, kam se vkládají do grafu zpracování signálu.

  • Efekty streamu (SFX)
  • Efekty režimu (MFX)
  • Účinky koncového bodu (EFX)

Každé logické zařízení může být přidružené k jednomu APO každého typu. Další informace o režimech a efektech naleznete v tématu Režimy zpracování zvukového signálu.

APO můžete implementovat tak, že založíte vlastní třídu na základní třídě CBaseAudioProcessingObject, která je deklarována v souboru Baseaudioprocessingobject.h. Tento přístup zahrnuje přidání nových funkcí do základní třídy CBaseAudioProcessingObject k vytvoření přizpůsobeného objektu APO. Základní třída CBaseAudioProcessingObject implementuje většinu funkcí, které APO vyžaduje. Poskytuje výchozí implementace pro většinu metod ve třech požadovaných rozhraních. Primární výjimkou je metoda IAudioProcessingObjectRT::APOProcess .

Pokud chcete implementovat vlastní apOs, proveďte následující kroky.

  1. Vytvořte vlastní objekty APO com, které zajistí požadované zpracování zvuku.
  2. Volitelně můžete vytvořit uživatelské rozhraní pro konfiguraci vlastních objektů api pomocí objektu APO.
  3. Vytvořte soubor INF pro instalaci a registraci APO a vlastního uživatelského rozhraní.

Aspekty návrhu pro vývoj vlastních APO

Všechna vlastní APOs musí mít následující obecné charakteristiky:

  • APO musí mít jeden vstup a jedno výstupní připojení. Tato připojení jsou zvukové vyrovnávací paměti a můžou mít více kanálů.

  • Objekt APO může upravit pouze zvuková data, která jsou předána prostřednictvím své rutiny IAudioProcessingObjectRT::APOProcess . Objekt APO nemůže změnit nastavení základního logického zařízení, včetně jeho topologie KS.

  • Kromě IUnknown musí apOs vystavit následující rozhraní:

  • Všechny APO musí mít systémovou kompatibilitu v reálném čase. To znamená, že:

    • Všechny metody, které jsou součástí rozhraní pracujících v reálném čase, musí být implementovány jako neblokující součásti. Nesmí blokovat, používat stránkovanou paměť ani volat žádné blokující systémové rutiny.

    • Všechny vyrovnávací paměti, které zpracovává APO, musí být nestránkové. Veškerý kód a data v cestě procesu musí být nestránkovatelný.

    • V řetězu zpracování zvuku by apO neměly zavádět významnou latenci.

  • Vlastní apOs nesmí vystavit rozhraní IAudioProcessingObjectVBR.

Poznámka:

Podrobné informace o požadovaných rozhraních naleznete v souborech Audioenginebaseapo.h a Audioenginebaseapo.idl ve složce Windows Kits\<build number>\Include\um.

Zrychlení procesu vývoje pomocí ukázkového kódu

Použití vzorového kódu SYSVAD Swap APO jako šablony může urychlit proces vývoje vlastního APO. Ukázka Swap je příklad, který byl vyvinut k předvedení některých funkcí objektů pro zpracování zvuku. Ukázkový příklad prohození APO prohodí levý kanál s pravým kanálem a provede efekty SFX i MFX. Zvukové efekty pro výměnu zvukových kanálů můžete povolit a zakázat v dialogovém okně vlastností.

Ukázka zvuku SYSVAD je k dispozici na GitHubu s ukázkami ovladačů windows.

Ukázku zvuku Sysvad můžete procházet tady:

https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad

Stažení a extrahování ukázky zvuku Sysvad z GitHubu

Pokud chcete stáhnout a otevřít ukázku SYSVAD, postupujte podle těchto kroků.

a. K práci s ukázkami můžete použít nástroje GitHubu. Ukázky univerzálních ovladačů si můžete stáhnout také v jednom souboru ZIP.

https://github.com/Microsoft/Windows-driver-samples/archive/master.zip

b) Stáhněte si soubor master.zip na místní pevný disk.

c. Vyberte a podržte (nebo klikněte pravým tlačítkem) Windows-driver-samples-master.zipa zvolte Extrahovat vše. Zadejte novou složku nebo přejděte k existující složce, do které se budou ukládat extrahované soubory. Můžete například zadat C:\DriverSamples\ jako novou složku, do které se soubory extrahují.

d. Po extrahování souborů přejděte do následující podsložky: C:\DriverSamples\Audio\Sysvad

Otevřete řešení ovladače v sadě Visual Studio

V aplikaci Microsoft Visual Studio vyberte Soubor>Otevřít>Projekt/Řešení... a přejděte na složku, která obsahuje extrahované soubory (například C:\DriverSamples\Audio\Sysvad). Poklikáním otevřete soubor řešení Sysvad .

V sadě Visual Studio vyhledejte Průzkumníka řešení. (Pokud tento příkaz ještě není otevřený, v nabídce Zobrazení zvolte Průzkumníka řešení.) V Průzkumníku řešení uvidíte jedno řešení, které má šest projektů.

Příklad kódu SwapAPO

V ukázce SYSVAD je pět projektů, z nichž jeden je primárním zájmem vývojáře APO.

Projekt popis
SwapAPO Ukázkový kód ukázkového objektu APO

Další projekty v ukázce Sysvad jsou shrnuté níže.

Projekt popis
TabletAudioSample Vzorový kód alternativního zvukového ovladače
KeywordDetectorAdapter Ukázkový kód adaptéru detektoru klíčových slov
EndpointsCommon Ukázkový kód pro běžné koncové body

Primární soubory hlaviček pro ukázku SwapAPO jsou swapapo.h. Další primární prvky kódu jsou shrnuty níže.

soubor popis
Swap.cpp Kód C++, který obsahuje implementaci swapového objektu APO.
SwapAPOMFX.cpp Implementace CSwapAPOMFX
SwapAPOSFX.cpp Implementace CSwapAPOSFX
SwapAPODll.cpp Implementace DLL exportů.
SwapAPODll.idl Definice rozhraní MODELU COM a coclass pro knihovnu DLL.
SwapAPOInterface.idl Definice rozhraní a typů pro funkci Swap APO.
swapapodll.def Definice exportu modelu COM

Implementace kódu pro zpracování zvuku objektu COM

Objekt APO zadaný systémem můžete zabalit tak, že založíte vlastní třídu na základní třídě CBaseAudioProcessingObject , která je deklarována v souboru Baseaudioprocessingobject.h. Tento přístup zahrnuje zavedení nových funkcí do základní třídy CBaseAudioProcessingObject k vytvoření přizpůsobeného objektu APO. Základní třída CBaseAudioProcessingObject implementuje většinu funkcí, které APO vyžaduje. Poskytuje výchozí implementace pro většinu metod ve třech požadovaných rozhraních. Primární výjimkou je metoda IAudioProcessingObjectRT::APOProcess .

Pomocí CBaseAudioProcessingObject můžete snadněji implementovat objekt APO. Pokud objekt APO nemá žádné zvláštní požadavky na formát a pracuje s požadovaným formátem float32, výchozí implementace metod rozhraní, které jsou součástí CBaseAudioProcessingObject , by měly být dostatečné. Vzhledem k výchozím implementacím musí být implementovány pouze tři hlavní metody: IAudioProcessingObject::IsInputFormatSupported, IAudioProcessingObjectRT::APOProcess a ValidateAndCacheConnectionInfo.

Chcete-li vyvíjet apOs na základě CBaseAudioProcessingObject třídy, proveďte následující kroky:

  1. Vytvořte třídu, která dědí z CBaseAudioProcessingObject.

    Následující příklad kódu C++ ukazuje vytvoření třídy, která dědí z CBaseAudioProcessingObject. Pokud chcete provést skutečnou implementaci tohoto konceptu, postupujte podle pokynů v části Ukázkový ovladač zpracování zvukových objektů a přejděte na ukázku Swap, a potom se podívejte do souboru Swapapo.h.

    // Custom APO class - SFX
Class MyCustomAPOSFX: public CBaseAudioProcessingObject
{
 public:
//Code for custom class goes here
...
};

    Poznámka Vzhledem k tomu, že zpracování signálu, které provádí SFX APO, se liší od zpracování signálu prováděného MFX nebo EFX APO, musíte pro každý vytvořit samostatné třídy.

  2. Implementujte následující tři metody:

    • IAudioProcessingObject::IsInputFormatSupported. Tato metoda zpracovává vyjednávání formátu se zvukovým enginem.

    • IAudioProcessingObjectRT::APOProcess. Tato metoda používá vlastní algoritmus k provádění zpracování signálu.

    • ValidateAndCacheConnectionInfo. Tato metoda přiděluje paměť k ukládání podrobností o formátu, například počtu kanálů, vzorkovací frekvence, hloubky vzorku a masky kanálu.

Následující příklad kódu C++ ukazuje implementaci metody APOProcess pro ukázkovou třídu, kterou jste vytvořili v kroku 1. Pokud chcete provést skutečnou implementaci tohoto konceptu, postupujte podle pokynů v části Ukázka ovladače zpracování zvuku, přejděte k ukázce Swap a poté se podívejte do souboru Swapapolfx.cpp.

// Custom implementation of APOProcess method
STDMETHODIMP_ (Void) MyCustomAPOSFX::APOProcess (...)
{
// Code for method goes here. This code is the algorithm that actually
// processes the digital audio signal.
...
}

Následující příklad kódu ukazuje implementaci ValidateAndCacheConnectionInfo metoda. Pokud chcete provést skutečnou implementaci této metody, postupujte podle pokynů v části Audio Processing Objects Driver Sample, přejděte na ukázku Swap a pak se podívejte do souboru Swapapogfx.cpp.

// Custom implementation of the ValidateAndCacheConnectionInfo method.
HRESULT CSwapAPOGFX::ValidateAndCacheConnectionInfo( ... )
{
// Code for method goes here.
// The code should validate the input/output format pair.
...
}

Poznámka Zbývající rozhraní a metody, které vaše třída dědí z CBaseAudioProcessingObject jsou podrobně popsány v audioenginebaseapo.idl souboru.

Nahrazení systémově zadaných rozhraní API

Při implementaci rozhraní APO existují dva přístupy: můžete napsat vlastní implementaci, nebo můžete využít předdefinované APO.

Tento pseudokód znázorňuje zabalování systémového APO.

CMyWrapperAPO::CMyWrapperAPO {
    CoCreateInstance(CLSID_InboxAPO, m_inbox);
}

CMyWrapperAPO::IsInputFormatSupported {
    Return m_inbox->IsInputFormatSupported(…);
}

Tento pseudokód znázorňuje, jak vytvořit vlastní APO.

CMyFromScratchAPO::IsInputFormatSupported {
    my custom logic
}

Při vývoji objektů APO k nahrazení těmi dodávanými systémem je nutné použít stejné názvy v následujícím seznamu pro rozhraní a metody. Některá rozhraní mají kromě uvedených požadovaných metod více metod. Pokud chcete určit, jestli chcete implementovat všechny metody nebo jenom požadované metody, podívejte se na referenční stránky těchto rozhraní.

Zbytek kroků implementace je stejný jako u vlastního APO.

Implementujte pro komponentu COM následující rozhraní a metody:

Práce se sadou Visual Studio a rozhraními API

Při práci s APO ve Visual Studiu provádějte tyto úkony pro každý projekt APO.

Ovladače, které cílí na Windows 10, by se měly dynamicky propojit s univerzálním CRT.

Pokud potřebujete podporovat Windows 8,1, povolte statické propojení nastavením vlastností projektu v C/C++, generování kódu. Nastavte "knihovnu runtime" na /MT pro vydání verze nebo na /MTd pro sestavení ladění. Tato změna se provádí, protože pro softwarový ovladač je obtížné opětovně distribuovat binární soubor MSVCRT<n>.dll. Řešením je staticky propojit libcmt.dll. Další informace naleznete v tématu /MD, /MT, /LD (použití knihovny Run-Time) .

Zakázání použití vloženého manifestu

Zakažte použití vloženého manifestu nastavením vlastností projektu pro projekt APO. Vyberte nástroj manifestu, vstup a výstup. Pak změňte "Vložit manifest" z výchozí hodnoty Ano na Ne. Pokud máte vložený manifest, aktivuje se použití určitých rozhraní API, která jsou zakázaná v rámci chráněného prostředí. To znamená, že pokud máte nastaveno DisableProtectedAudioDG=1, váš APO se spustí. Jakmile je však tento testovací klíč odstraněn, váš APO se nenačte, a to ani pokud je podepsán certifikátem WHQL.

Balení vašeho APO s ovladačem

Při vývoji vlastního zvukového ovladače a zahrnutí nebo nahrazení systémových APOs, musíte poskytnout balíček pro instalaci ovladače a APOs. V případě Windows 10 se podívejte na univerzální ovladače systému Windows pro zvuk. Balíčky ovladačů souvisejících se zvukem by měly dodržovat zásady a model balení ovladačů, jak je uvedeno tam.

Vlastní APO se zabalí jako knihovna DLL a jakékoli konfigurační uživatelské rozhraní se zabalí jako samostatná aplikace UWP nebo Desktop Bridge. Zařízení APO INF zkopíruje knihovny DLL do systémových složek, které jsou uvedeny v související direktivě INF CopyFile. Knihovna DLL, která obsahuje objekty APO, se musí zaregistrovat sama tím, že zahrne oddíl AddReg v souboru INF.

Následující odstavce a fragmenty souborů INF ukazují změny, které jsou nezbytné k použití standardního souboru INF ke kopírování a registraci objektů API.

Inf soubory, které jsou součástí ukázky Sysvad, ukazují, jak jsou zaregistrované SwapApo.dll APOs.

Registrace apO pro režimy zpracování a efekty v souboru INF

ApOs můžete zaregistrovat pro konkrétní režimy pomocí určitých povolených kombinací klíčů registru. Další informace o tom, které efekty jsou k dispozici a obecné informace o apO, naleznete v tématu Architektura objektu zpracování zvuku.

Informace o každém nastavení souboru INF APO najdete v těchto referenčních tématech.

PKEY_FX_StreamEffectClsid

PKEY_FX_ModeEffectClsid

PKEY_FX_EndpointEffectClsid

PKEY_SFX_ProcessingModes_Supported_For_Streaming

PKEY_MFX_ProcessingModes_Supported_For_Streaming

PKEY_EFX_Zpracováváné_Režimy_Podpora_Pro_Streamování

Následující ukázky souborů INF ukazují, jak zaregistrovat objekty pro zpracování zvuku (APO) pro konkrétní režimy. Znázorňují možné kombinace dostupné v tomto seznamu.

  • PKEY_FX_StreamEffectClsid s PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid s PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_ModeEffectClsid bez PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_EndpointEffectClsid bez PKEY_EFX_ProcessingModes_Supported_For_Streaming

Existuje jedna další platná kombinace, která se v těchto ukázkách nezobrazuje.

  • PKEY_FX_EndpointEffectClsid s PKEY_EFX_ProcessingModes_Supported_For_Streaming

SysVad Tablet Multi-Mode Streaming Effect APO INF ukázka

Tato ukázka ukazuje efekt streamování s více režimy, který se registruje pomocí položek AddReg v souboru INF sysVAD Tablet.

Tento ukázkový kód pochází z ukázky zvuku SYSVAD a je k dispozici na GitHubu: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Tato ukázka znázorňuje tuto kombinaci systémových efektů:

  • PKEY_FX_StreamEffectClsid s PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid s PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
[SWAPAPO.I.Association0.AddReg]
; Instruct audio endpoint builder to set CLSID for property page provider into the
; endpoint property store
HKR,EP\0,%PKEY_AudioEndpoint_ControlPanelPageProvider%,,%AUDIOENDPOINT_EXT_UI_CLSID%

; Instruct audio endpoint builder to set the CLSIDs for stream, mode, and endpoint APOs
; into the effects property store
HKR,FX\0,%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,FX\0,%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,FX\0,%PKEY_FX_UserInterfaceClsid%,,%FX_UI_CLSID%

; Driver developer would replace the list of supported processing modes here
; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

;HKR,FX\0,%PKEY_EFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%

Všimněte si, že v ukázkovém souboru INF je vlastnost EFX_Streaming okomentována, protože zpracování zvuku přešlo na režim jádra nad danou vrstvou, takže vlastnost streamování není nutná a nebyla použita. Bylo by platné zadat PKEY_FX_EndpointEffectClsid pro účely detekce, ale zadání PKEY_EFX_ProcessingModes_Supported_For_Streaming by bylo považováno za chybu. Důvodem je, že mix režimů / tee se v zásobníku odehrává níže, kde není možné vložit APO koncového bodu.

Instalace APO po komponentách

S počátkem Windows 10, vydání 1809, používá registrace APO se zvukovým procesorem model komponentového zvukového ovladače. Použití audio componentization vytváří plynulejší a spolehlivější prostředí instalace a lépe podporuje údržbu komponent. Další informace naleznete v tématu Vytvoření komponentizované instalace ovladače zvuku.

Následující příklad kódu je extrahován z veřejného souboru ComponentizedAudioSampleExtension.inf a ComponentizedApoSample.inf. Podívejte se na ukázku zvuku SYSVAD, která je k dispozici na GitHubu zde: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Registrace APO se zvukovým enginem se provádí pomocí nově vytvořeného APO zařízení. Aby zvukový subsystém používal nové zařízení APO, musí být podřízeným členem PNP zvukového zařízení, rovnocenným koncovým bodům zvuku. Návrh nového komponentovaného objektu APO neumožňuje registraci objektu APO globálně a jeho použití několika různými ovladači. Každý řidič musí zaregistrovat vlastní APO.

Instalace APO se provádí ve dvou částech. Za prvé, rozšíření ovladače INF přidá do systému komponentu APO:

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

[Apo_AddComponent]
ComponentIDs = VEN_SMPL&CID_APO
Description = "Audio Proxy APO Sample"

Tato komponenta APO aktivuje druhou část instalace APO INF v ukázce SYSVAD, která se provádí v ComponentizedApoSample.inf. Tento soubor INF je vyhrazený pro komponentu APO. Určuje komponentní třídu jako AudioProcessingObject a přidává všechny vlastnosti APO potřebné k registraci CLSID a připojení ke zvukovému jádru.

Poznámka:

Ukázky souborů INF ukazují podporu izolace balíčků ovladačů pomocí klíče registru HKR. Před Windows 11 verze 22000 ukázky používaly HKCR k ukládání trvalých hodnot pro registrace CLSID místo HKR. Registrace APO byla podporována pomocí HKR od Windows 10 verze 1809. Další informace najdete v tématu Použití univerzálního souboru INF.

[Version]
...
Class       = AudioProcessingObject
ClassGuid   = {5989fce8-9cd0-467d-8a6a-5419e31529d4}
...

[ApoComponents.NT$ARCH$]
%Apo.ComponentDesc% = ApoComponent_Install,APO\VEN_SMPL&CID_APO

[Apo_AddReg]
; CLSID registration
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%%SystemRoot%%\System32\swapapo.dll
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"
...
;Audio engine registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
...

Když tento INF soubor nainstaluje komponentní APO, na stolním počítači se ve Správci zařízení systému Windows zobrazí "Zvukové zpracovatelské objekty".

Aktualizace identifikátorů CLSID při vydání nové verze APO

Při vydání nové verze APO je vhodné a obecně se doporučuje aktualizovat CSLID třídy COM. K vytvoření nových identifikátorů GUID použijte nástroje, jako je GUIDGEN.

Požadavek na aktualizaci identifikátorů CLSI při přechodu z HKCR na HKR

Je požadováno, aby při přechodu z globálních registrací COM (HKCR) na registrace COM vázané na zařízení (HKR), byl změněn identifikátor GUID třídy COM. Tento přístup snižuje možnost, že nové objekty COM nebudou správně registrovány a nenačtou se.

Ukázka APO INF s ukázkou zvuku Bluetooth

Tato ukázka znázorňuje tuto kombinaci systémových efektů:

  • PKEY_FX_StreamEffectClsid s PKEY_SFX_ProcessingModes_Supported_For_Streaming

  • PKEY_FX_ModeEffectClsid s PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

Tento ukázkový kód podporuje hands-free a stereo zařízení Bluetooth.

; wdma_bt.inf – example usage
...
[BthA2DP]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration,WDMAUDIO.Registration,BtaMPM.CopyFilesOnly,mssysfx.CopyFilesAndRegister
...
[BTAudio.SysFx.Render]
HKR,"FX\\0",%PKEY_ItemNameDisplay%,,%FX_FriendlyName%
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_UiClsid%,,%FX_UI_CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
...
[Strings]
FX_UI_CLSID      = "{5860E1C5-F95C-4a7a-8EC8-8AEF24F379A1}"
FX_STREAM_CLSID  = "{62dc1a93-ae24-464c-a43e-452f824c4250}"
PKEY_FX_StreamEffectClsid   = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},5"
PKEY_FX_ModeEffectClsid     = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},6"
PKEY_SFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},5"
PKEY_MFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},6"
AUDIO_SIGNALPROCESSINGMODE_DEFAULT = "{C18E2F7E-933D-4965-B7D1-1EEF228D2AF3}"

Ukázka zvuku APO INF

Tento ukázkový soubor INF ukazuje následující kombinaci systémových efektů:

  • PKEY_FX_StreamEffectClsid s PKEY_SFX_ProcessingModes_Supported_For_Streaming

  • PKEY_FX_ModeEffectClsid s PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

  • PKEY_FX_EndpointEffectClsid bez PKEY_EFX_ProcessingModes_Supported_For_Streaming

[MyDevice.Interfaces]
AddInterface=%KSCATEGORY_AUDIO%,%MyFilterName%,MyAudioInterface

[MyAudioInterface]
AddReg=MyAudioInterface.AddReg

[MyAudioInterface.AddReg]
;To register an APO for discovery, use the following property keys in the .inf (or at runtime when registering the KSCATEGORY_AUDIO device interface):
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_MODE_CLSID%

;To register an APO for streaming and discovery, add the following property keys as well (to the same section):
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

;To register an APO for streaming in multiple modes, use a REG_MULTI_SZ property and include all the modes:
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

Definujte vlastní APO a CLSID APO INF Sample

Tato ukázka ukazuje, jak definovat vlastní CLSID pro vlastní objekt APO. Tato ukázka používá MSApoFxProxy CLSID {889C03C03C8-ABAD-4004-BF0A-BC7BB825E166}. Použití CoCreate tohoto identifikátoru GUID vytvoří instanci třídy v MsApoFxProxy.dll, která implementuje rozhraní IAudioProcessingObject a dotazuje základní ovladač prostřednictvím sady vlastností KSPROPSETID_AudioEffectsDiscovery.

Tento soubor INF ukazuje část [BthHfAud], která načítá [MsApoFxProxy.Registration] z wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], která pak zaregistruje PKEY_FX_EndpointEffectClsid jako známý CLSID pro MsApoFxProxy.dll.

Tento ukázkový soubor INF ukazuje také použití této kombinace systémových efektů:

  • PKEY_FX_EndpointEffectClsid bez PKEY_EFX_ProcessingModes_Supported_For_Streaming
;wdma_bt.inf
[BthHfAud]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration, WDMAUDIO.Registration, BtaMPM.CopyFilesOnly, MsApoFxProxy.Registration
CopyFiles=BthHfAud.CopyList
AddReg=BthHfAud.AddReg

; Called by needs entry in oem inf
[BthHfAudOEM.CopyFiles]
CopyFiles=BthHfAud.CopyList

[BthHfAud.AnlgACapture.AddReg.Wave]
HKR,,CLSID,,%KSProxy.CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_DISCOVER_EFFECTS_APO_CLSID%
#endif

Registrace efektu APO - ukázka

Tato ukázka ukazuje část [Apo_AddReg] ze složky Sysvad ComponentizedApoSample.inx. Tato část zaregistruje GUID swap streamu u modelu COM a zaregistruje efekt Swap Stream APO. Oddíl [Apo_CopyFiles] má nastavené DestinationDirs na 13, což kopíruje swapapo.dll do úložiště ovladačů. Další informace naleznete v tématu "Spustit ze složky ovladačů" v Izolace balíčku ovladačů.

Obecné informace o souborech INF naleznete v tématu Přehled souborů INF.

; ComponentizedApoSample.inx

...

[ApoComponent_Install]
CopyFiles = Apo_CopyFiles
AddReg    = Apo_AddReg

[Apo_CopyFiles]
swapapo.dll

...

[Apo_AddReg]
; Swap Stream effect APO COM registration
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%13%\swapapo.dll
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"

'''
; Swap Stream effect APO registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Copyright",,%Copyright%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MajorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Flags",0x00010001,%APO_FLAG_DEFAULT%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInstances",0x00010001,0xffffffff
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"NumAPOInterfaces",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"APOInterface0",,"{FD7F2B29-24D0-4B5C-B177-592C39F9CA10}"
...

[Strings]
; Driver developers would replace these CLSIDs with those of their own APOs
SWAP_FX_STREAM_CLSID   = "{B48DEA3F-D962-425a-8D9A-9A5BB37A9904}"

...

Registrace APO

Registrace objektu APO se používá k podpoře procesu, který dynamicky odpovídá účinkům koncových bodů pomocí váženého výpočtu. Vážený výpočet používá následující úložiště vlastností. Každé zvukové rozhraní má nulové nebo více úložišť vlastností koncového bodu a úložišť vlastností efektů registrovaných buď prostřednictvím souboru .inf, nebo za běhu. Nejkonkrétnější datové úložiště vlastností koncového bodu a nejkonkrétnější efekty vlastnostního úložiště mají nejvyšší váhy, a proto se používají. Všechna ostatní úložiště vlastností se ignorují.

Specificita se vypočítá takto:

Vlastnost koncového bodu ukládá vážení.

  1. FX s konkrétním typem KSNODETYPE
  2. FX s KSNODETYPE_ANY
  3. MSFX s konkrétním typem KSNODETYPE
  4. MSFX s KSNODETYPE_ANY

Vlastnosti Efekty ukládají váhy

  1. EP s konkrétním typem KSNODETYPE
  2. EP s KSNODETYPE_ANY
  3. MSEP s konkrétním typem uzlu KSNODETYPE
  4. MSEP s KSNODETYPE_ANY

Čísla musí začínat na 0 a postupně se zvětšovat: MSEP\0, MSEP\1, ..., MSEP\n Pokud (například) EP\3 chybí, Systém Windows přestane hledat EP\n a neuvidí EP\4, i když existuje.

Hodnota PKEY_FX_Association (pro úložiště vlastností efektů) nebo PKEY_EP_Association (pro úložiště vlastností koncového bodu) se porovnává s hodnotou KSPINDESCRIPTOR.Category pro pinovou továrnu na hardwarovém konci cesty signálu, jak je vystavuje streamování jádra.

MsEP a MSFX by měly používat pouze ovladače třídy doručené pošty Microsoftu, které může zabalit vývojář třetí strany; všechny ovladače třetích stran by měly používat EP a FX.

Kompatibilita typu uzlu APO

Následující ukázka souboru INF ilustruje nastavení klíče PKEY_FX_Association na GUID přidružený k APO.

;; Property Keys
PKEY_FX_Association = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},0"
"

;; Key value pairs
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%

Protože je zvukový adaptér schopný podporovat více vstupů a výstupů, musíte explicitně určit typ uzlu streamování jádra (KS), se kterým je váš vlastní objekt APO kompatibilní. V předchozím fragmentu souboru INF je zobrazeno přidružení APO k typu uzlu KS %KSNODETYPE_ANY%. Dále v tomto souboru INF je KSNODETYPE_ANY definován takto:

[Strings]
;; Define the strings used in MyINF.inf
...
KSNODETYPE_ANY      = "{00000000-0000-0000-0000-000000000000}"
KSNODETYPE_SPEAKER  = "{DFF21CE1-F70F-11D0-B917-00A0C9223196}"
...

Hodnota NULL pro KSNODETYPE_ANY znamená, že tento APO je kompatibilní s jakýmkoli typem uzlu KS. Chcete-li například označit, že váš APO je kompatibilní pouze s typem uzlu KS KSNODETYPE_SPEAKER, soubor INF zobrazí typ uzlu KS a přidružení APO následujícím způsobem:

;; Key value pairs
...
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_SPEAKER%
...

Další informace o hodnotách GUID pro různé typy uzlů KS naleznete v souboru hlaviček Ksmedia.h.

Řešení problémů při selhání načítání APO

Jsou poskytovány následující informace, které vám pomohou pochopit, jak se monitoruje selhání u APO. Tyto informace můžete použít k řešení potíží s rozhraními API, které se nepodaří začlenit do zvukového grafu.

Zvukový systém monitoruje návratové kódy APO a zjišťuje, zda jsou APO úspěšně začleněny do grafu. Sleduje návratové kódy sledováním hodnot HRESULT vrácených některou z určených metod. Systém udržuje samostatnou hodnotu počtu selhání pro každý SFX, MFX a EFX APO, které jsou začleněny do grafu.

Zvukový systém monitoruje vrácené hodnoty HRESULT z následujících čtyř metod.

  • CoCreateInstance

  • JeInputFormatPodporován

  • JePodporovánVýstupníFormát

  • LockForProcess

Hodnota počtu selhání se pro objekt APO zvýší pokaždé, když jedna z těchto metod vrátí kód selhání. Počet selhání se resetuje na nulu, když APO vrátí kód, který označuje, že byl úspěšně začleněn do zvukového grafu. Úspěšné volání LockForProcess metody je dobrou indikací, že APO byl úspěšně začleněn.

Pro CoCreateInstance zejména existuje několik důvodů, proč vrácený kód HRESULT může značit selhání. Tři hlavní důvody jsou následující:

  • Graf spouští chráněný obsah a APO není správně podepsaný.

  • APO není zaregistrované.

  • Objekt APO byl přejmenován nebo manipulován.

Pokud hodnota počtu selhání pro SFX, MFX nebo EFX APO dosáhne systémem stanoveného limitu, jsou tyto APO zakázány nastavením klíče registru PKEY_Endpoint_Disable_SysFx na hodnotu 1. Systémový limit je aktuálně hodnota 10.

Objekty pro zpracování zvuku systému Windows Audio Processing Objects

Vytvoření instalace audio ovladače s modulární strukturou

Izolace balíčku ovladače

  • Last updated on