Condividi tramite

Implementazione di oggetti di elaborazione audio

  • Articolo

Questo argomento descrive come implementare un oggetto di elaborazione audio (APO). Per informazioni generali sulle API, vedere Architettura degli oggetti di elaborazione audio.

Implementazione di API personalizzate

Le API personalizzate vengono implementate come oggetti COM in-process, quindi vengono eseguite in modalità utente e vengono incluse in un pacchetto in una libreria a collegamento dinamico (DLL). Esistono tre tipi di APO, in base alla posizione in cui vengono inseriti nel grafico di elaborazione dei segnali.

  • Effetti di flusso (SFX)
  • Effetti modalità (MFX)
  • Effetti endpoint (EFX)

Ogni dispositivo logico può essere associato a un'apo di ogni tipo. Per altre informazioni sulle modalità ed effetti, vedi Modalità di elaborazione del segnale audio.

È possibile implementare un oggetto APO basando la classe personalizzata sulla classe di base CBaseAudioProcessingObject, dichiarata nel file Baseaudioprocessingobject.h. Questo approccio prevede l'aggiunta di nuove funzionalità nella classe di base CBaseAudioProcessingObject per creare un apo personalizzato. La classe di base CBaseAudioProcessingObject implementa gran parte delle funzionalità richieste da un oggetto APO. Fornisce implementazioni predefinite per la maggior parte dei metodi nelle tre interfacce necessarie. L'eccezione principale è il metodo IAudioProcessingObjectRT::APOProcess .

Per implementare le API personalizzate, seguire questa procedura.

  1. Creare oggetti APO com personalizzati per fornire l'elaborazione audio desiderata.
  2. Facoltativamente, creare un'interfaccia utente per configurare le API personalizzate usando un oggetto .
  3. Creare un file INF per installare e registrare le API e l'interfaccia utente personalizzata.

Considerazioni sulla progettazione per lo sviluppo di APO personalizzati

Tutte le API personalizzate devono avere le caratteristiche generali seguenti:

  • L'APO deve avere un input e una connessione di output. Queste connessioni sono buffer audio e possono avere più canali.

  • Un oggetto APO può modificare solo i dati audio passati tramite la routine IAudioProcessingObjectRT::APOProcess . L'APO non può modificare le impostazioni del dispositivo logico sottostante, inclusa la topologia KS.

  • Oltre a IUnknown, le API devono esporre le interfacce seguenti:

  • Tutte le API devono avere la compatibilità del sistema in tempo reale. Ciò significa che:

    • Tutti i metodi membri delle interfacce in tempo reale devono essere implementati come membri non bloccanti. Non devono bloccare, usare memoria di paging o chiamare routine di sistema bloccanti.

    • Tutti i buffer elaborati dall'APO devono essere non visualizzabili. Tutti i dati e il codice nel percorso del processo devono essere non visualizzabili.

    • Le API non devono introdurre una latenza significativa nella catena di elaborazione audio.

  • Le API personalizzate non devono esporre l'interfaccia IAudioProcessingObjectVBR.

Nota

Per informazioni dettagliate sulle interfacce necessarie, vedere i file Audioenginebaseapo.h e Audioenginebaseapo.idl nella cartella Windows Kits\<build number>\Include\um.

Uso del codice di esempio per accelerare il processo di sviluppo

L'uso dell'esempio di codice APO di scambio SYSVAD come modello può accelerare il processo di sviluppo apo personalizzato. L'esempio swap è l'esempio sviluppato per illustrare alcune caratteristiche degli oggetti di elaborazione audio. L'esempio swap APO scambia il canale sinistro con il canale destro e implementa gli effetti SFX e MFX. È possibile abilitare e disabilitare gli effetti audio di scambio del canale usando la finestra di dialogo delle proprietà.

L'esempio audio SYSVAD è disponibile in GitHub degli esempi di driver di Windows.

È possibile esplorare l'esempio audio Sysvad qui:

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

Scaricare ed estrarre l'esempio audio Sysvad da GitHub

Seguire questa procedura per scaricare e aprire l'esempio SYSVAD.

a. È possibile usare gli strumenti GitHub per lavorare con gli esempi. È anche possibile scaricare gli esempi di driver universali in un unico file ZIP.

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

b. Scaricare il file master.zip nel disco rigido locale.

c. Selezionare e tenere premuto (o fare clic con il pulsante destro del mouse) Windows-driver-samples-master.zip e scegliere Estrai tutto. Specificare una nuova cartella o passare a una cartella esistente che archivierà i file estratti. Ad esempio, è possibile specificare C:\DriverSamples\ come nuova cartella in cui verranno estratti i file.

d. Dopo aver estratto i file, passare alla sottocartella seguente: C:\DriverSamples\Audio\Sysvad

Aprire la soluzione driver in Visual Studio

In Microsoft Visual Studio selezionare File>Apri>progetto/soluzione e passare alla cartella contenente i file estratti, ad esempio C:\DriverSamples\Audio\Sysvad. Fare doppio clic sul file di soluzione Sysvad per aprirlo.

In Visual Studio individuare il Esplora soluzioni. Se non è già aperto, scegliere Esplora soluzioni dal menu Visualizza. In Esplora soluzioni è possibile visualizzare una soluzione con sei progetti.

Codice di esempio swapAPO

Nell'esempio SYSVAD sono presenti cinque progetti, uno dei quali è di interesse principale per lo sviluppatore di APO.

Progetto Descrizione
SwapAPO Codice di esempio per un esempio di APO

Gli altri progetti nell'esempio Sysvad sono riepilogati di seguito.

Progetto Descrizione
TabletAudioSample Codice di esempio per un driver audio alternativo.
KeywordDetectorAdapter Codice di esempio per un adattatore di rilevamento parole chiave
EndpointsCommon Codice di esempio per gli endpoint comuni.

I file di intestazione primari per l'esempio SwapAPO sono swapapo.h. Di seguito sono riepilogati gli altri elementi di codice primari.

file Descrizione
Swap.cpp Codice C++ che contiene l'implementazione dell'APO di scambio.
SwapAPOMFX.cpp Implementazione di CSwapAPOMFX
SwapAPOSFX.cpp Implementazione di CSwapAPOSFX
SwapAPODll.cpp Implementazione delle esportazioni DLL.
SwapAPODll.idl Definizione di interfacce COM e coclassi per la DLL.
SwapAPOInterface.idl L'interfaccia e le definizioni dei tipi per la funzionalità Swap APO.
swapapodll.def Definizioni delle esportazioni COM

Implementazione del codice di elaborazione audio dell'oggetto COM

È possibile eseguire il wrapping di un apo fornito dal sistema basando la classe personalizzata sulla classe di base CBaseAudioProcessingObject , dichiarata nel file Baseaudioprocessingobject.h. Questo approccio prevede l'introduzione di nuove funzionalità nella classe di base CBaseAudioProcessingObject per creare un apo personalizzato. La classe di base CBaseAudioProcessingObject implementa gran parte delle funzionalità richieste da un oggetto APO. Fornisce implementazioni predefinite per la maggior parte dei metodi nelle tre interfacce necessarie. L'eccezione principale è il metodo IAudioProcessingObjectRT::APOProcess .

Usando CBaseAudioProcessingObject, è possibile implementare più facilmente un apo. Se un oggetto APO non ha requisiti di formato speciali e opera nel formato float32 richiesto, le implementazioni predefinite dei metodi di interfaccia inclusi in CBaseAudioProcessingObject devono essere sufficienti. Data l'implementazione predefinita, è necessario implementare solo tre metodi principali: IAudioProcessingObject::IsInputFormatSupported, IAudioProcessingObjectRT::APOProcess e ValidateAndCache Connessione ionInfo.

Per sviluppare le API basate sulla classe CBaseAudioProcessingObject , seguire questa procedura:

  1. Creare una classe che eredita da CBaseAudioProcessingObject.

    Nell'esempio di codice C++ seguente viene illustrata la creazione di una classe che eredita da CBaseAudioProcessingObject. Per un'implementazione effettiva di questo concetto, seguire le istruzioni nella sezione Audio Processing Objects Driver Sample (Esempio di driver di elaborazione degli oggetti di elaborazione audio) per passare all'esempio swap e quindi fare riferimento al file Swapapo.h .

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

    Nota Poiché l'elaborazione del segnale eseguita da un apo SFX è diversa dall'elaborazione del segnale eseguita da un MFX o da un apo EFX, è necessario creare classi separate per ognuna.

  2. Implementare i tre metodi seguenti:

    • IAudioProcessingObject::IsInputFormatSupported. Questo metodo gestisce la negoziazione del formato con il motore audio.

    • IAudioProcessingObjectRT::APOProcess. Questo metodo usa l'algoritmo personalizzato per eseguire l'elaborazione dei segnali.

    • ValidateAndCache Connessione ionInfo. Questo metodo alloca la memoria per archiviare i dettagli del formato, ad esempio il numero di canali, la frequenza di campionamento, la profondità del campione e la maschera del canale.

L'esempio di codice C++ seguente illustra un'implementazione del metodo APOProcess per la classe di esempio creata nel passaggio 1. Per un'implementazione effettiva di questo concetto, seguire le istruzioni nella sezione Audio Processing Objects Driver Sample (Esempio di driver di elaborazione degli oggetti di elaborazione audio) per passare all'esempio swap e quindi fare riferimento al file 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.
...
}

Nell'esempio di codice seguente viene illustrata un'implementazione del metodo ValidateAndCache Connessione ionInfo. Per un'implementazione effettiva di questo metodo, seguire le istruzioni nella sezione Esempio di driver per l'elaborazione di oggetti audio per passare all'esempio swap e quindi fare riferimento al file 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.
...
}

Nota Le interfacce e i metodi rimanenti ereditati dalla classe da CBaseAudioProcessingObject sono descritti in dettaglio nel file Audioenginebaseapo.idl.

Sostituzione delle API fornite dal sistema

Quando si implementano le interfacce APO, esistono due approcci: è possibile scrivere la propria implementazione oppure chiamare le API posta in arrivo.

Questo pseudocodice illustra il wrapping di un sistema APO.

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

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

Questo pseudocodice illustra la creazione di apo personalizzati.

CMyFromScratchAPO::IsInputFormatSupported {
    my custom logic
}

Quando si sviluppano le API per sostituire quelle fornite dal sistema, è necessario usare gli stessi nomi nell'elenco seguente, per le interfacce e i metodi. Alcune interfacce hanno più metodi oltre ai metodi richiesti elencati. Vedere le pagine di riferimento per tali interfacce per determinare se si desidera implementare tutti i metodi o solo quelli necessari.

Il resto dei passaggi di implementazione è identico a quello di un apo personalizzato.

Implementare le interfacce e i metodi seguenti per il componente COM:

Uso di Visual Studio e API

Quando si lavora con le API in Visual Studio, eseguire queste attività per ogni progetto APO.

I driver destinati a Windows 10 devono collegarsi dinamicamente a CRT universale.

Se è necessario supportare Windows 8,1, abilitare il collegamento statico impostando le proprietà del progetto in C/C++, Generazione di codice. Impostare "Libreria di runtime" su /MT per le build di versione o /MTd per le compilazioni di debug. Questa modifica viene apportata perché per un driver è difficile ridistribuire il file binario MSVCRT<n>.dll. La soluzione consiste nel collegare in modo statico libcmt.dll. Per altre informazioni, vedere /MD, /MT, /LD (Usare la libreria di runtime).

Disabilitare l'uso di un manifesto incorporato

Disabilitare l'uso di un manifesto incorporato impostando le proprietà del progetto per il progetto APO. Selezionare Strumento manifesto, Input e Output. Modificare quindi "Incorpora manifesto" dal valore predefinito Sì a No. Se si dispone di un manifesto incorporato, viene attivato l'uso di determinate API non consentite all'interno di un ambiente protetto. Ciò significa che l'APO verrà eseguito con DisableProtectedAudioDG=1, ma quando questa chiave di test viene rimossa, l'APO non verrà caricato, anche se è firmato con WHQL.

Creazione di pacchetti apo con un driver

Quando si sviluppa un driver audio personalizzato e si esegue il wrapping o si sostituiscono le API fornite dal sistema, è necessario fornire un pacchetto driver per l'installazione del driver e delle API. Per Windows 10, vedi Driver di Windows universali per audio. I pacchetti driver relativi all'audio devono seguire i criteri e il modello di creazione di pacchetti in modo dettagliato.

L'API personalizzata viene inserita in un pacchetto come DLL e qualsiasi interfaccia utente di configurazione viene inserita in un pacchetto come un'app UWP o Desktop Bridge separata. Il dispositivo APO INF copia le DLL nelle cartelle di sistema indicate nella direttiva INF CopyFile associata. La DLL che contiene le API deve registrarsi autonomamente includendo una sezione AddReg nel file INF.

I paragrafi e i frammenti di file INF seguenti mostrano le modifiche necessarie per usare il file INF standard per copiare e registrare le API.

I file inf inclusi nell'esempio Sysvad illustrano come vengono registrate le API SwapApo.dll.

Registrazione di API per modalità di elaborazione ed effetti nel file INF

È possibile registrare LE API per modalità specifiche usando determinate combinazioni consentite di chiavi del Registro di sistema. Per altre informazioni sugli effetti disponibili e generali sulle API, vedere Architettura degli oggetti di elaborazione audio.

Per informazioni su ognuna delle impostazioni del file APO INF, vedere questi argomenti di riferimento.

PKEY_FX_StreamEffectClsid

PKEY_FX_ModeEffectClsid

PKEY_FX_EndpointEffectClsid

PKEY_SFX_ProcessingModes_Supported_For_Streaming

PKEY_MFX_ProcessingModes_Supported_For_Streaming

PKEY_EFX_ProcessingModes_Supported_For_Streaming

Gli esempi di file INF seguenti illustrano come registrare gli oggetti di elaborazione audio (APO) per modalità specifiche. Illustrano le possibili combinazioni disponibili in questo elenco.

  • PKEY_FX_StreamEffectClsid con PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid con PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_ModeEffectClsid senza PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_EndpointEffectClsid senza PKEY_EFX_ProcessingModes_Supported_For_Streaming

Esiste una combinazione valida aggiuntiva che non è illustrata in questi esempi.

  • PKEY_FX_EndpointEffectClsid con PKEY_EFX_ProcessingModes_Supported_For_Streaming

Esempio APO INF dell'effetto streaming multi-mode SYSVAD Tablet

Questo esempio mostra un effetto di streaming in più modalità registrato usando le voci AddReg nel file SYSVAD Tablet INF.

Questo codice di esempio proviene dall'esempio audio SYSVAD ed è disponibile in GitHub: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Questo esempio illustra questa combinazione di effetti di sistema:

  • PKEY_FX_StreamEffectClsid con PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid con 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%

Si noti che nel file INF di esempio la proprietà EFX_Streaming viene impostata come commento perché l'elaborazione audio è passata alla modalità kernel sopra tale livello, in modo che la proprietà di streaming non sia necessaria e non venga usata. Sarebbe valido specificare un PKEY_FX_EndpointEffectClsid a scopo di individuazione, ma sarebbe un errore specificare PKEY_EFX_ProcessingModes_Supported_For_Streaming. Ciò è dovuto al fatto che la combinazione di modalità/tee si verifica più in basso nello stack, in cui non è possibile inserire un endpoint APO.

Installazione di APO componenti

A partire da Windows 10, versione 1809, la registrazione apo con il motore audio usa il modello di driver audio con componenti. L'uso della componente audio crea un'esperienza di installazione più fluida e affidabile e supporta meglio la manutenzione dei componenti. Per altre informazioni, vedere Creazione di un'installazione di driver audio componenti.

Il codice di esempio seguente viene estratto dal public ComponentizedAudioSampleExtension.inf e ComponentizedApoSample.inf. Fare riferimento all'esempio audio SYSVAD disponibile in GitHub qui: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

La registrazione dell'APO con il motore audio viene eseguita usando un dispositivo APO appena creato. Affinché il motore audio usi il nuovo dispositivo APO, deve essere un figlio PNP del dispositivo audio, di pari livello degli endpoint audio. La nuova progettazione APO componentizzata non consente la registrazione globale di un apo e l'uso di più driver diversi. Ogni driver deve registrare il proprio APO.

L'installazione dell'APO viene eseguita in due parti. Prima di tutto, l'estensione del driver INF aggiungerà un componente APO al sistema:

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

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

Questo componente APO attiva la seconda parte, l'installazione di APO INF, nell'esempio SYSVAD questa operazione viene eseguita in ComponentizedApoSample.inf. Questo file INF è dedicato al componente APO. Specifica la classe componente come AudioProcessingObject e aggiunge tutte le proprietà APO per la registrazione CLSID e la registrazione con il motore audio.

Nota

Gli esempi di file INF mostrati supportano l'isolamento del pacchetto driver usando la chiave del Registro di sistema HKR. Prima di Windows 11, versione 22000, gli esempi usavano HKCR per archiviare i valori persistenti per le registrazioni CLSID, anziché HKR. La registrazione apo è stata supportata con HKR a partire da Windows 10, versione 1809. Per altre informazioni, vedere Uso di un file INF universale.

[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%
...

Quando questo INF installa l'APO componentizzato, in un sistema desktop "Audio Processing Objects" verrà visualizzato in Windows Gestione dispositivi.

Aggiornamenti ai CLSID quando viene rilasciata una nuova versione apo

Quando viene rilasciata una nuova versione apo, è consigliabile e in genere è consigliabile aggiornare il CLSID della classe COM. Usare strumenti come GUIDGEN per creare nuovi GUID.

Requisito di aggiornamento dei CLSID durante il passaggio da HKCR a HKR

È un requisito quando si effettua il passaggio dalle registrazioni COM globali (HKCR) al dispositivo relative alle registrazioni COM HKR per modificare il GUID della classe COM COM. Questo approccio riduce la possibilità che i nuovi oggetti COM non vengano registrati correttamente e non vengano caricati.

Esempio APO INF di esempio audio Bluetooth

Questo esempio illustra questa combinazione di effetti di sistema:

  • PKEY_FX_StreamEffectClsid con PKEY_SFX_ProcessingModes_Supported_For_Streaming

  • PKEY_FX_ModeEffectClsid con PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

Questo codice di esempio supporta dispositivi Bluetooth senza mani e stereo.

; 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}"

Esempio di audio APO INF

Questo file INF di esempio illustra la combinazione di effetti di sistema seguenti:

  • PKEY_FX_StreamEffectClsid con PKEY_SFX_ProcessingModes_Supported_For_Streaming

  • PKEY_FX_ModeEffectClsid con PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

  • PKEY_FX_EndpointEffectClsid senza 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%

Definire un esempio APO e APO INF CLSID personalizzato

Questo esempio illustra come definire un CLSID personalizzato per un'apo personalizzata. Questo esempio usa msApoFxProxy CLSID {889C03C8-ABAD-4004-BF0A-BC7BB825E166}. La creazione di questo GUID crea un'istanza di una classe in MsApoFxProxy.dll che implementa le interfacce IAudioProcessingObject ed esegue una query sul driver sottostante tramite il set di proprietà KSPROP edizione Standard TID_AudioEffectsDiscovery.

Questo esempio di file INF mostra la sezione [BthHfAud] che esegue il pull in [MsApoFxProxy.Registration] da wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], che quindi registra PKEY_FX_EndpointEffectClsid come CLSID noto per MsApoFxProxy.dll.

Questo esempio di file INF illustra anche l'uso di questa combinazione di effetti di sistema:

  • PKEY_FX_EndpointEffectClsid senza 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

Registrazione dell'effetto APO di esempio

Questo esempio mostra la sezione [Apo_AddReg] di Sysvad ComponentizedApoSample.inx. Questa sezione registra il GUID del flusso di scambio con COM e registra l'effetto APO di Swap Stream. La sezione [Apo_CopyFiles] ha un Valore DestinationDirs pari a 13, che copia swapapo.dll nel Drivertore. Per altre informazioni, vedere "Esegui da drivertore" in Isolamento pacchetto driver.

Per informazioni generali sui file INF, vedere Panoramica dei file 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}"

...

Registrazione APO

La registrazione APO viene usata per supportare un processo che corrisponde dinamicamente agli effetti agli endpoint usando un calcolo ponderato. Il calcolo ponderato utilizza gli archivi di proprietà seguenti. Ogni interfaccia audio ha zero o più archivi di proprietà endpoint e gli archivi delle proprietà degli effetti registrati tramite .inf o in fase di esecuzione. L'archivio delle proprietà dell'endpoint più specifico e l'archivio delle proprietà degli effetti più specifici hanno i pesi più alti e vengono usati. Tutti gli altri archivi di proprietà vengono ignorati.

La specificità viene calcolata nel modo seguente:

La proprietà endpoint archivia il peso

  1. FX con KSNODETYPE specifico
  2. FX con KSNODETYPE_ANY
  3. MSFX con KSNODETYPE specifico
  4. MSFX con KSNODETYPE_ANY

La proprietà Effects archivia il peso

  1. EP con KSNODETYPE specifico
  2. EP con KSNODETYPE_ANY
  3. M edizione Standard P con KSNODETYPE specifico
  4. M edizione Standard P con KSNODETYPE_ANY

I numeri devono iniziare da 0 e aumentare in sequenza: M edizione Standard P\0, M edizione Standard P\1, ..., M edizione Standard P\n Se (ad esempio) EP\3 è mancante, Windows smetterà di cercare EP\n e non visualizzerà EP\4, anche se esiste.

Il valore di PKEY_FX_Association (per gli archivi proprietà degli effetti) o PKEY_EP_Association (per gli archivi delle proprietà dell'endpoint) viene confrontato con KSPINDESCRIPTOR. Valore della categoria per la factory di pin alla fine hardware del percorso del segnale, come esposto da Kernel Streaming.

Solo i driver di classe Posta in arrivo Microsoft (che possono essere inclusi incapsulati da uno sviluppatore di terze parti) devono usare M edizione Standard P e MSFX. Tutti i driver di terze parti devono usare EP e FX.

Compatibilità dei tipi di nodo APO

L'esempio di file INF seguente illustra l'impostazione della chiave PKEY_FX_Association su un GUID associato all'APO.

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

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

Poiché un adattatore audio è in grado di supportare più input e output, è necessario indicare in modo esplicito il tipo di nodo di streaming del kernel (KS) compatibile con l'APO personalizzato. Nel frammento di file INF precedente, l'APO viene visualizzato come associato a un tipo di nodo KS di %KSNODETYPE_ANY%. Più avanti in questo file INF, KSNODETYPE_ANY viene definito come segue:

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

Un valore NULL per KSNODETYPE_ANY indica che l'APO è compatibile con qualsiasi tipo di nodo KS. Per indicare, ad esempio, che l'APO è compatibile solo con un tipo di nodo KS di KSNODETYPE_SPEAKER, il file INF mostrerà il tipo di nodo KS e l'associazione APO come indicato di seguito:

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

Per altre informazioni sui valori GUID per i diversi tipi di nodo KS, vedere il file di intestazione Ksmedia.h.

Risoluzione degli errori di caricamento apo

Vengono fornite le informazioni seguenti per comprendere come viene monitorato l'errore per le API. È possibile usare queste informazioni per risolvere i problemi relativi alle API che non riescono a essere incorporate nel grafico audio.

Il sistema audio monitora i codici restituiti APO per determinare se le API vengono incorporate correttamente nel grafico. Monitora i codici restituiti monitorando i valori HRESULT restituiti da uno dei metodi designati. Il sistema mantiene un valore di conteggio degli errori separato per ogni SFX, MFX e EFX APO che viene incorporato nel grafico.

Il sistema audio monitora i valori HRESULT restituiti dai quattro metodi seguenti.

  • Cocreateinstance

  • IsInputFormatSupported

  • IsOutputFormatSupported

  • LockForProcess

Il valore del conteggio degli errori viene incrementato per un apo ogni volta che uno di questi metodi restituisce un codice di errore. Il numero di errori viene reimpostato su zero quando un apo restituisce un codice che indica che è stato incorporato correttamente nel grafico audio. Una chiamata riuscita al metodo LockForProcess indica che l'APO è stata incorporata correttamente.

Per CoCreateInstance in particolare, esistono diversi motivi per cui il codice HRESULT restituito potrebbe indicare un errore. I tre motivi principali sono i seguenti:

  • Il grafico esegue contenuto protetto e l'APO non è firmato correttamente.

  • L'APO non è registrato.

  • L'APO è stato rinominato o manomesso.

Inoltre, se il valore del numero di errori per un SFX, MFX o EFX APO raggiunge un limite specificato dal sistema, le API SFX, MFX e EFX vengono disabilitate impostando la chiave del Registro di sistema PKEY_Endpoint_Disable_SysFx su '1'. Il limite specificato dal sistema è attualmente un valore pari a 10.

Oggetti di elaborazione audio di Windows

Creazione di un'installazione di driver audio componenti

Isolamento del pacchetto driver