ACX オーディオ データ形式とデータ形式リスト
このトピックでは、ドライバーで ACX 形式の種類をどのように使用すれば、信号データ形式を追跡、管理、比較できるかについて説明します。 ACX の一般的な概要と一般的な ACX 用語のリストについては、「ACX オーディオ クラス拡張機能の概要」を参照してください。 オーディオ エンコード形式の一般的な情報については、「オーディオ データ形式」を参照してください。
ACXDATAFORMAT オブジェクトと ACXDATAFORMATLIST オブジェクト
データ形式の操作には、2 つの ACX オブジェクトが使用されます。
- オーディオ デバイスでサポートされるデータ形式を表す ACXDATAFORMAT。
- 使用できるオーディオ データ形式のリストである ACXDATAFORMATLIST。
ACX オブジェクトの操作の詳細については、「ACX オブジェクトの概要」を参照してください。
ACX は、データ形式を指定するために KSDATAFORMAT 構造体を参照する ACX_DATAFORMAT_TYPE 列挙体を使用します。
ACXDATAFORMAT
ACXDATAFORMAT は、データ形式オブジェクトへのハンドルを提供します。 ドライバーでは、AcxDataFormatCreate 関数を使用してこれらのオブジェクトが作成され、AcxDataFormatIsEqual を使用してそれらを比較することができます。
ACXDATAFORMATLIST
ACXDATAFORMATLIST は、データ形式オブジェクトのコンテナーです。 ドライバーで ACXPIN が作成されると、ACX は生の信号処理モード用に空のデータ形式リストを自動的に作成します。 ドライバーは、AcxPinGetRawDataFormatList を使用してリストにアクセスできます。 指定された ACXPIN の ACXDATAFORMATLIST を返します。
ドライバーは、AcxDataFormatListAddDataFormat を使用して、特定のリストに形式を追加できます。
// The raw processing mode list is associated with each single circuit
// by ACX. A driver uses AcxPinGetRawDataFormatList to retrieve the built-in raw
// data-format list.
//
RETURN_NTSTATUS_IF_TRUE(CodecCaptureHostPin >= CodecCapturePinCount, STATUS_INVALID_PARAMETER);
formatList = AcxPinGetRawDataFormatList(Pin[CodecCaptureHostPin]);
RETURN_NTSTATUS_IF_TRUE(formatList == nullptr, STATUS_INSUFFICIENT_RESOURCES);
//
// The driver uses AcxDataFormatListAddDataFormat to add data formats to the raw
// processing mode list associated with the current circuit.
//
RETURN_NTSTATUS_IF_FAILED(AcxDataFormatListAddDataFormat(formatList, formatPcm44100c1));
RETURN_NTSTATUS_IF_FAILED(AcxDataFormatListAddDataFormat(formatList, formatPcm48000c1));
ドライバーでは、ACXPIN など特定の WDFDEVICE の AcxDataFormatListCreate を使用して、追加のデータ形式リストを作成し、特定の信号処理モードにそうしたリストを関連付けることができます。
NTSTATUS AcxDataFormatListCreate(device, attributes, <format cfg>, &ACXDATAFORMATLIST)
ドライバーは、AcxPinRetrieveModeDataFormatList を使用して、特定のピンに関連付けられている形式リストを取得できます。
ドライバーでは、AcxDataFormatListRemoveDataFormat を使用して、特定のリストから形式を削除できます。 この形式が既定の形式でもある場合、ACX はリストで使用可能な最初の形式 (存在している場合) を既定として選択する点にご注意ください。
ドライバーは、AcxDataFormatListAssignDefaultDataFormat を使用して、リスト内の既定の形式を指定できます。 既定の形式はリストに存在している必要があります。ない場合は追加されます。
ドライバーでは、AcxDataFormatListRetrieveDefaultDataFormat を使用して、リスト内の既定の形式を取得できます。
ドライバーは、次の DDI を使用して形式リストを反復処理し、グループとして変更を加えることができます。
変更が適用されるのは、ドライバーが反復処理を終了した後のみであることにご注意ください。
VOID AcxDataFormatListBeginIteration(ACXDATAFORMATLIST, PACX_DATAFORMAT_LIST_ITERATOR)
NTSTATUS AcxDataFormatListRetrieveNextDataFormat(ACXDATAFORMATLIST, PACX_DATAFORMAT_LIST_ITERATOR, &ACXFORMAT);
VOID AcxDataFormatListEndIteration(ACXDATAFORMATLIST, PACX_DATAFORMAT_LIST_ITERATOR)
上記の DDI により、ドライバーで次のコールバックを実装する必要がなくなります。
PFN_ACX_PIN_GET_SIGNALPROCESSING_MODES EvtAcxPinGetSignalProcessingModes;
PFN_ACX_PIN_GET_DATAFORMATS EvtAcxPinGetDataFormats;
PFN_ACX_PIN_GET_DEFAULT_DATAFORMAT EvtAcxPinGetDefaultDataFormat;
PFN_ACX_PIN_PROPOSE_DATAFORMAT EvtAcxPinProposeDataFormat;
上記の DDI により、ドライバーで次のイベントを実装する必要もありません (ACX は、リストが変更された後、このイベントを自動的にトリガーします)。
// Clients enable this event to receive format change notifications. Drivers fire this even when it detects a dynamic format change on the specified pin (h/w pin).
//
KSEVENT_PINCAPS_FORMATCHANGE(pin)
上記の DDI により、ドライバーでモードと形式のストレージを独自に管理する必要もなくなります。
入力/出力形式が同じでない場合(DSP 回線) でも、ドライバーでは次の DDI がサポートされている必要があります。 この DDI はストリームに依存せず、回路ピンに固有であり、s/w ストリーミング ピン以外でのみサポートされます。
PFN_ACX_PIN_SET_DATAFORMAT EvtAcxPinSetDataFormat;