ACX オブジェクトの概要

  • [アーティクル]

このトピックでは、ACX オーディオ ドライバーのベースを形成するオーディオクラス拡張機能 (ACX) オブジェクトの概要について説明します。 ACX の一般的な概要については、「ACX オーディオ クラス拡張機能の概要」を参照してください。

ACX オブジェクトは、Windows Driver Framework (WDF) オブジェクト (WDFOBJECT) です。 WDF について詳しくは、「フレームワーク オブジェクトの概要」を参照してください。 WDF オブジェクトの概要については、「フレームワーク オブジェクトの概要」を参照してください。

Note

ACX ヘッダーとライブラリは、WDK 10.0.22621.2428 (2023 年 10 月 24 日リリース) には含まれていませんが、以前のバージョンと WDK の最新 (25000 シリーズ ビルド) Insider Preview で使用できます。 WDK のプレビュー バージョンの詳細については、「Windows Driver Kit (WDK) のプレビュー バージョンのインストール」を参照してください。

ACX オブジェクト階層

ACX (WDF と同様) では、ドライバー オブジェクトはルート オブジェクトであり、他のすべてのオブジェクトはその子/子孫です。 すべての ACX オブジェクトは、他の ACX または WDF オブジェクトを介して直接的または間接的なドライバー オブジェクトの子です。 ACX ドライバーは、作成時に ACX オブジェクトの親を指定できます。 親が指定されていない場合、ACX はこれらのセクションで説明されているように既定の親を使用します。

Diagram illustrating the hierarchy of ACX objects, with WDFDEVICE at the top and major ACX objects like circuit and stream below.

ACX 回線

AcxCircuit は、ユーザーが認識するオーディオ デバイス (スピーカー、マイクなど) への部分的または完全なオーディオ パスを表します。 AcxCircuit には、少なくとも 1 つの入力ピンと 1 つの出力ピン (ACXPIN) があり、1 つ以上の AcxElements のようなオブジェクトを集約できます。 既定では、AcxElements はアセンブリの同じ順序で '接続' されます。

オーディオ回線は、ACX の主要な構成要素です。 新しい ACX フレームワークでは、オーディオ ドライバーは、部分的または完全なオーディオ データ/制御パスを表す 1 つ以上の ACX 回線オブジェクトを作成します。 ACX はこれらの ACX 回線オブジェクトを組み立てて、オーディオ エンドポイントを表す完全なオーディオ パスを作成します。 ACX は、ACX 回線とその依存関係の管理を担当します。 これらの回路の組み立て順序は、初期化時に静的に定義することも、実行時に動的に定義することもできます。

ACX フレームワークのオーディオ エンドポイントは、1 つ以上の ACX 回線のコレクションです。 マルチ回線オーディオ パス内の各 ACX 回線は、異なる PnP デバイス スタックに属している必要があります。 ACX ドライバーは、初期化時に 1 つ以上の回線を作成したり、新しいオーディオ コンポーネントを検出した後などの外部イベントの副作用として回線を作成したり、特定の回線の種類のファクトリとして ACX に登録したりして、ACX フレームワークがその種類の新しい回線を作成するようにファクトリ コンポーネントに要求する場合があります (このトピックで後述する ACX 回線マネージャー/ファクトリを参照)。

ACX 回線の DDI については、acxcircuit.h ヘッダーで説明しています。

ACX ピン

WDM Portcls オーディオ ドライバーと同様に、AcxPin オブジェクトは、データ ストリームがシステム通信バスからアダプターに入るか、アダプターからシステム通信バスに入る論理接続 (物理接続ではない) を表します。

ピンの DDI については、acxpin.h ヘッダーで説明しています。

ACX Stream

AcxStream は、特定の回線のハードウェア上のオーディオ ストリームを表します。 AcxStream は、1 つ以上の AcxElements のようなオブジェクトを集計できます。 既定では、AcxElements はアセンブリの同じ順序で '接続' されます。 AcxStream は、1 つの ACX 回線にのみ関連付けられます。

  • AcxStream には専用の WDF キューがあります。 WDF キューの詳細については、「フレームワーク キュー オブジェクト」を参照してください。
  • AcxStream では、さまざまな状態がサポートされます。 これらの状態は、オーディオが流れている (RUN 状態) か、流れていない (PAUSE または STOP 状態) を示します。
  • 現在、ACX は、非ストリーミング回線で使用される基本的な ACX ストリーム オブジェクトと、ストリーミング回線で使用される ACX RT ストリーム オブジェクトの 2 種類のストリームをサポートしています。

ストリームの DDI については、acxstreams.h ヘッダーで定義しています。

ACX ターゲット

WdfIoTarget は、2 つの異なるスタック間の通信を容易にする WDF 抽象化です。 WDF IO ターゲットの詳細については、「I/O ターゲットの概要」を参照してください。

  • ドライバーは、AcxTargetCircuit を使用して、異なるスタックによって公開されたリモート回線と通信します。 AcxTargetCircuit は、WdfIoTarget を使用して実装されます。
  • ドライバーは、AcxTargetPin を使用して、異なるスタックによって公開されたリモート回線のピンと通信します。 AcxTargetPin は、リモート ピン エンティティにメッセージを送信する WdfIoTarget を使用して実装されます。
  • ドライバーは、AcxTargetElement を使用して、異なるスタックによって公開されたリモート回線の要素と通信します。 AcxTargetElement は、リモート要素エンティティにメッセージを送信するために WdfIoTarget を使用して実装されます。
  • ドライバーは、AcxTargetStream を使用して、異なるスタックによって公開されたリモート回線のストリームと通信します。 AcxTargetStream は、リモート ストリームを作成し、リモート ストリームの状態を変更するために WdfIoTarget を使用して実装されています。
  • ドライバーは、AcxTargetFactoryCircuit を使用して、リモート回線ファクトリ インスタンスと通信します。 AcxTargetFactoryCircuit は、リモート回線ファクトリにメッセージを送信するために WdfTarget を使用して実装されます。

上記の ACX 型はそれぞれ、リモート回線と相互作用するためのプロパティ、メソッド、およびイベントをサポートしています。 これらの型はすべて、WdfIoTarget オブジェクトの上に構築されます。

ターゲットの DDI は、acxtargets.h ヘッダーで定義されます。

ACX ストリーム ブリッジ

AcxStreamBridge オブジェクトは、回線セグメント間でストリームの作成、ストリームの状態遷移、DRM 設定を伝達するために回線によって使用されます。 このオブジェクトは、マルチ回線 (オーディオ複合) シナリオでのみ使用されます。 ドライバーは、1 つ以上の ACXSTREAMBBRIDGE オブジェクトをブリッジ ピンに関連付けることができます。 ブリッジ ピンは、他の回路の対応する ACXPIN に論理的に接続する ACXPIN です。

ストリームの DDI については、acxstreams.h ヘッダーで説明しています。

ACX オーディオ エンジン ノードの回線レイアウトの例

次の図は、ACX 回線を示しています。 ホスト ピンとオフロード ピンは、エコー キャンセルに使用できるループバック ピンを持つ回線への入力です。 出力には、スピーカーにルーティングするブリッジ ピンを指定できます。

Diagram illustrating an ACX circuit with host, offload, and loopback pins on the left, and a bridge pin on the right, routed through an audio engine node.

回路/要素が回線に追加されたのと同じ順序で接続されている場合、ドライバーは明示的に接続する手順を実行する必要はありません。

既定では、ACX は、回路の ACX 要求シンク ピンから始まり、レンダリング デバイスとキャプチャ デバイスの両方の回線のデバイス ブリッジ ピンで終わる要素を接続します。

ACX Manager

ACX マネージャーは、複合オーディオ エンドポイントのサポートなどのシステム タスクに使用されます。 これらの種類のエンドポイントは、同じベンダーまたは異なるベンダーの 1 つ以上のドライバー スタックによって管理されます。 クライアントは、ACPI でこの構成を事前に構成することも、ACX マネージャーの DDI を直接使用することもできます。 ACX マネージャーの DDI については、acxmanager.h ヘッダーで説明しています。

ACX オブジェクト バッグ

ACX オブジェクト バッグは、さまざまなデータ型の格納に使用します。 ACXOBJECTBAG は、さまざまな DDI で引数として渡すことができます。 オブジェクト バッグの DDI については、acxmisc.h ヘッダーで説明します。

ACX オブジェクトの概要

次の表に、すべての ACX オブジェクトの一覧と、各オブジェクトに関する基本情報を示します。

ハンドル 名前 パーパス
ACXMANAGER ACX マネージャー 他のオブジェクトの管理と制御に使用される ACX Manager オブジェクト。
ACXOBJECTBAG オブジェクト バッグ オブジェクトで使用するデータを格納するために使用されます。
ACXEVENT ACX イベント KS (カーネル ストリーミング) イベント用。
ACXEVENTDATA イベント データ イベントと関連付けられたデータ。
ACXPNPEVENT Pnp イベント プラグ アンド プレイ イベント用。
ACXCIRCUIT 回線 このトピックで前述した ACX 回線。
ACXPIN ピン留めする ACX ピン オブジェクトは論理接続を表し、このトピックで前述されています。
ACXELEMENT 要素 AcxCircuit または AcxStream に追加できる要素 (AcxVolume など) を表すために使用されます。
ACXAUDIOENGINE オーディオ エンジン DSP を表すためにレンダリング回線で使用される ACX オーディオ エンジン。
ACXSTREAMAUDIOENGINE ストリーム オーディオ エンジン DSP を表すためにレンダー ストリームで使用されます。
ACXKEYWORDSPOTTER キーワード スポッター オーディオ ストリームのキーワード検出のためにキャプチャ回線で使用されるキーワード スポッター。
ACXVOLUME 体積 ボリューム、ゲイン、ブーストを表すために使用されます。
ACXMUTE Mute ミュート要素を表すために使用されます。
ACXJACK Jack オーディオ ジャックまたはその他の物理コネクタを表すために使用されます。
ACXMICARRAYGEOMETRY Mic Array Geometry マイク配列のジオメトリ (マイクの位置など) を表すために使用されます。
ACXPEAKMETER ピーク メーター ハードウェアがピークメーター機能をサポートする場合に使用されます。
ACXSTREAM ストリーム このトピックで前述した回線によって作成されたオーディオ ストリームを表すために使用されます。
ACXDATAFORMAT データ形式 データ形式は、オーディオ デバイスでサポートされているデータ形式を表します。
ACXDATAFORMATLIST データ形式の一覧 使用できるオーディオ データ形式の一覧。
ACXTARGETCIRCUIT ターゲット回線 別のスタックによって公開されているリモート回線と通信するために使用されます。
ACXTARGETPIN ターゲット ピン 別のスタックによって公開されているリモート回線のピンと通信するために使用されます。
ACXTARGETELEMENT Target 要素 AcxCircuit または AcxStream に追加できるターゲット要素 (AcxVolume など) を表すために使用されます。
ACXTARGETSTREAM ターゲット ストリーム 別のスタックによって公開されているリモート回線のストリームと通信するために使用されます。
ACXTARGETFACTORYCIRCUIT ターゲット回線ファクトリ リモート回線のファクトリとの通信に使用されます。
ACXSTREAMBRIDGE ストリーム ブリッジ 回線がストリームの作成、状態遷移、および回線セグメント間の DRM を伝達するために使用されます。
ACXCOMPOSITE 複合 マルチ回線/マルチスタック/複数ベンダーのストリーム アーキテクチャを表すために使用されます。
ACXCOMPOSITEFACTORY 複合ファクトリ 複合オーディオ回線を作成するファクトリ。
ACXFACTORYCIRCUIT ファクトリ回線 特定のテンプレートを使用して回線を作成するファクトリ。
ACXCIRCUITMANAGER 回線マネージャー 動的な回線の作成に使用される回線プロバイダー。
ACXCOMPOSITETEMPLATE 複合テンプレート 複合テンプレートは、部分的または完全なオーディオ バインディングを表します。 複合テンプレートには、1 つ以上の回線テンプレートを含めることができます。
ACXCIRCUITTEMPLATE 回線テンプレート 回線テンプレートは、部分的なオーディオ パスを表します。
ACXAUDIOMODULE オーディオ モジュール カスタムサード パーティのアドオン機能の場合。

次の ACX オブジェクトは、回線、ストリーム、および回線ファクトリ情報を格納するために使用されます。

ハンドル パーパス
ACXCIRCUIT_INIT ACX 回線の初期化データを格納します
ACXSTREAM_INIT ACX ストリーム初期化データを格納します
ACXFACTORYCIRCUIT_INIT ACX 回線ファクトリで使用される初期化データを格納します

関連項目

ACX オーディオ クラス拡張機能の概要

ACX リファレンス ドキュメント