Mengekspos Topologi Filter
Driver miniport menjelaskan topologi internal filter KS dalam hal pin, simpul, dan koneksi. Topologi ini menentukan jalur aliran data melalui filter dan juga menentukan target logis--pin dan simpul--untuk permintaan properti. Topologi intra-filter adalah representasi logis dari struktur internal perangkat keras yang mendasar filter. Driver miniport menjelaskan topologi ini dengan array statis pin, node, dan deskriptor koneksi.
Pin ditentukan dalam array statis struktur PCPIN_DESCRIPTOR . Setiap pin memiliki ID yang merupakan ordinalnya dalam array.
Simpul ditentukan dalam array statis struktur PCNODE_DESCRIPTOR . Setiap simpul memiliki ID yang merupakan ordinalnya dalam array.
Koneksi (pin-to-pin, pin-to-node, atau node-to-node) ditentukan dalam array statis struktur PCCONNECTION_DESCRIPTOR .
Driver miniport mengekspos ketiga array ini dalam struktur PCFILTER_DESCRIPTOR yang dihasilkannya dari metode IMiniport::GetDescription .
Contoh
Contoh kode berikut menentukan topologi internal filter KS sederhana yang memiliki satu pin input dan satu pin output. Filter berisi satu simpul, yang merupakan kontrol tingkat volume.
#define KSPIN_WAVEOUT_SRC 0
#define KSPIN_SPEAKERS_DST 1
PCPIN_DESCRIPTOR
MiniportPins[] =
{
{ // Pin 0 -- KSPIN_WAVEOUT_SRC
0,0,0, // InstanceCount
NULL, // AutomationTable
{ // KsPinDescriptor
0, // InterfacesCount
NULL, // Interfaces
0, // MediumsCount
NULL, // Mediums
SIZEOF_ARRAY(PinDataRangePointersBridge), // DataRangesCount
PinDataRangePointersBridge, // DataRanges
KSPIN_DATAFLOW_IN, // DataFlow
KSPIN_COMMUNICATION_NONE, // Communication
&KSNODETYPE_LEGACY_AUDIO_CONNECTOR, // Category
NULL, // Name
0 // Reserved
}
},
{ // Pin 1 -- KSPIN_SPEAKERS_DST
0,0,0, // InstanceCount
NULL, // AutomationTable
{ // KsPinDescriptor
0, // InterfacesCount
NULL, // Interfaces
0, // MediumsCount
NULL, // Mediums
SIZEOF_ARRAY(PinDataRangePointersBridge), // DataRangesCount
PinDataRangePointersBridge, // DataRanges
KSPIN_DATAFLOW_OUT, // DataFlow
KSPIN_COMMUNICATION_NONE, // Communication
&KSNODETYPE_SPEAKER, // Category
&KSAUDFNAME_VOLUME_CONTROL, // Name (This name shows up as the
// playback panel name in SndVol32)
0 // Reserved
}
}
};
#define KSNODE_WAVEOUT_VOLUME 0
PCNODE_DESCRIPTOR TopologyNodes[] =
{
{ // KSNODE_WAVEOUT_VOLUME
0, // Flags
&AutomationVolume, // AutomationTable
&KSNODETYPE_VOLUME, // Type
&KSAUDFNAME_WAVE_VOLUME // Name
}
};
PCCONNECTION_DESCRIPTOR MiniportConnections[] =
{ //FromNode---------------FromPin------------ToNode-----------------ToPin
{ PCFILTER_NODE, KSPIN_WAVEOUT_SRC, KSNODE_WAVEOUT_VOLUME, 1 },
{ KSNODE_WAVEOUT_VOLUME, 0, PCFILTER_NODE, KSPIN_SPEAKERS_DST }
};
Gambar berikut menunjukkan topologi filter yang dijelaskan oleh kode sampel sebelumnya.
Filter ini adalah contoh sederhana dari filter topologi, yang dibentuk driver adaptor dengan mengikat objek IMiniportTopology ke objek IPortTopology yang dibuat driver sistem PortCls. Pin input (sink) dan output (sumber) filter diberi nama KSPIN_WAVEOUT_SRC dan KSPIN_SPEAKERS_DST. Kedua pin membawa sinyal analog. API mixer mengekspos koneksi ke pin ini sebagai garis mixer sumber dan tujuan (masing-masing MIXERLINE_COMPONENTTYPE_SRC_WAVEOUT dan MIXERLINE_COMPONENTTYPE_DST_SPEAKERS).
Tabel berikut mengilustrasikan sumber potensi kebingungan saat membahas pemetaan pin KS ke garis mixer.
| Menyematkan nama | Terminologi MIXER API | Terminologi filter KS |
|---|---|---|
KSPIN_WAVEOUT_SRC |
Garis mixer sumber |
Pin sink |
KSPIN_SPEAKERS_DST |
Garis mixer tujuan |
Pin sumber |
Perhatikan bahwa KSPIN_WAVEOUT_SRC adalah garis mixer sumber, dan KSPIN_SPEAKERS_DST adalah pin sumber. Untuk informasi selengkapnya, lihat diskusi terminologi KS dan mixer-line dalam Topologi Streaming Kernel ke Terjemahan AUDIO Mixer API.
Perhatikan juga bahwa nama "KSPIN_WAVEOUT_SRC" berisi "WAVEOUT" bukan karena pin membawa data digital berformat gelombang, tetapi karena membawa sinyal analog yang dihasilkan oleh filter gelombang, yang merupakan filter jenis WaveCyclic atau WavePci. Filter gelombang mewakili bagian perangkat keras adaptor audio yang mengonversi aliran gelombang menjadi sinyal analog. Sematkan KSPIN_SPEAKERS_DST menghasilkan sinyal analog yang mendorong satu set speaker.
Filter berisi satu simpul, KSNODE_WAVEOUT_VOLUME, yang diwakili API mixer sebagai kontrol volume (MIXERCONTROL_CONTROLTYPE_VOLUME). Jenis node KS untuk kontrol volume KSNODETYPE_VOLUME. Semua simpul jenis ini mendukung properti KSPROPERTY_AUDIO_VOLUMELEVEL , yang digunakan klien filter untuk mengontrol tingkat volume.
Simpul volume memiliki dua pin "logis", yang bernomor 0 dan 1. Dua koneksi yang ditentukan oleh array MiniportConnections diwakili dalam gambar dengan panah putus-putus yang menunjuk ke arah aliran data. Setiap koneksi dijelaskan oleh salah satu dari dua elemen dalam array.
Pin KSPIN_WAVEOUT_SRC dan KSPIN_SPEAKERS_DST keduanya adalah pin penghubung, yang berarti bahwa pin tersebut mewakili koneksi hardwired dalam adaptor. Dalam kode sampel sebelumnya, dua deskriptor pin dalam array MiniportPins menentukan arah aliran IRP mereka sebagai KSPIN_COMMUNICATION_NONE, yang sesuai karena pin penghubung tidak mengirim atau menerima RUN. Kedua deskriptor pin juga merujuk ke array PinDataRangePointersBridge, yang didefinisikan sebagai berikut:
static KSDATARANGE PinDataRangesBridge[] =
{
{
sizeof(KSDATARANGE),
0, 0, 0,
STATICGUIDOF(KSDATAFORMAT_TYPE_AUDIO),
STATICGUIDOF(KSDATAFORMAT_SUBTYPE_ANALOG),
STATICGUIDOF(KSDATAFORMAT_SPECIFIER_NONE)
}
};
static PKSDATARANGE PinDataRangePointersBridge[] =
{
&PinDataRangesBridge[0]
};
Array PinDataRangePointersBridge menentukan rentang data untuk pin jembatan yang membawa sinyal audio analog. Untuk informasi selengkapnya, lihat diskusi pin jembatan di Grafik Filter Audio.
Untuk contoh topologi yang lebih kompleks, lihat Filter Topologi.