10-4 キャプチャと表示の実装例
実践的な開発フェーズへようこそ！コードを 1 行書き始める前に、まずは本章の最終的な成果を見てみましょう。
図に示すように、今日の目標は非常に明確です。Qt のグラフィカル・ユーザー・インターフェース (GUI) に「キャンバス」を構築し、NexVDO SDK を呼び出すことで、外部キャプチャカード（SC710 キャプチャカードなど）から受信した映像を、リアルタイムかつスムーズにこのウィンドウ上にレンダリングします。
複雑に聞こえますか？ご心配なく。NexVDO SDK は、極めて複雑な基盤となる映像処理を完璧にカプセル化しています。上記の結果を達成するために、私たちは 4 つのコア API を学ぶだけで十分です！
© Blender Foundation | Big Buck Bunny | CC BY 3.0
コア API の理解 - デバイスのライフサイクル
正式にコードを書き始める前に、まず NexVDO SDK のライフサイクルを理解する必要があります。この SDK の操作は実は車の運転と同じで、API の呼び出し順序を厳密に守らなければなりません。今日の目標は、これらの API を通じてデバイスを作成し、UI インターフェース上に映像を正常に表示させることです。
1. QCAP_CREATE：映像キャプチャデバイスの「作成（Create）」と初期化を担当します。
2. QCAP_RUN：デバイスの「起動（Run）」を担当し、キャプチャカードを動作させて映像を画面にレンダリングします。
3. QCAP_STOP：デバイスの動作の「停止（Stop）」を担当します。
4. QCAP_DESTROY：デバイスリソースの「解放 / 破棄（Destroy）」を担当します。
⚠️これは非常に重要です：プロジェクトを閉じる前に、メモリリークを防ぐため、ユーザーは必ずこの API を呼び出してデバイスリソースを解放する必要があります！
後続の 3 つの API ( QCAP_RUN, QCAP_STOP, QCAP_DESTROY ) は、 QCAP_CREATE 時に取得したデバイス制御ハンドル ( pDevice ) を渡すだけで済みます。
ライフサイクルを理解したところで、各 API のパラメータを詳しく分解していきましょう。
QCAP_CREATE
これは最も複雑ですが、最も重要な API であり、ソフトウェアのウィンドウを基盤となるハードウェアにバインドする役割を担っています。
⚠️開発前の重要な準備：キャプチャカードのドライバのインストールをお忘れなく！ プログラムが QCAP_CREATE, を介してキャプチャカード (SC710 など) を正常に見つけてバインドできるようにするには、まずオペレーティングシステムがそれを「認識」している必要があります！PC または開発ボードに、対応する キャプチャカードのドライバ が正しくインストールされていることを必ず確認してください。
➤ ドライバはどこで見つけられますか？ 公式のテクニカルサポートに直接お問い合わせいただくことをお勧めします。ハードウェアの基盤を整えて初めて、プログラミングの魔法をかけることができるのです！
ドライバの準備が整ったら、この API に含まれる重要なパラメータを見てみましょう：
QCAP_RUN、QCAP_STOP、QCAP_DESTROY
QCAP_CREATEを介してデバイスの作成に成功すると、その後の起動、停止、解放（破棄）のアクションは非常にシンプルになります。これら 3 つの API の構造はまったく同じで、渡す必要があるパラメータは 1 つだけです：
前章で構築したテンプレートプロジェクトをそのまま開き、私たちと一緒に UI 上にキャンバスを配置（ドラッグ）し、4 つのキャプチャ API を呼び出して、現実世界の映像を UI 上にスムーズに表示させましょう！
コアコードの記述
いよいよコードを書く時間です！ mainwindow.h と mainwindow.cpp を開いて、最後のパズルを完成させましょう：
ヘッダーファイルのインクルードと変数の宣言 ( mainwindow.h )
必須ヘッダーファイルの紹介 #include "qcap.h" と #include "qcap.common.h"そして、デバイス制御コードを格納するための変数をパブリックセクションで宣言します。PVOID m_pDevice = NULL; 。
必須のヘッダーファイルである #include "qcap.h" と #include "qcap.common.h", をインクルードし、 public セクションにデバイス制御ハンドルを格納するための変数を宣言します： PVOID m_pDevice = NULL;。
キャプチャの初期化と起動 ( mainwindow.cpp )
MainWindow のコンストラクタに、以下の 4 つの API を追加します：
• QCAP_CREATE を使用してデバイスを開き、先ほど作成した PreviewWindow にバインドします。
➤ パフォーマンス最適化の秘訣： QCAP_SET_VIDEO_DEFAULT_OUTPUT_FORMAT を使用して、出力カラースペースを NV12 に指定します。基盤となるハードウェアプラットフォームが NVIDIA であるため、NV12 フォーマットを使用することで、NVIDIA プラットフォームの映像処理パフォーマンスを最大限に引き出すことができます！
• QCAP_SET_VIDEO_INPUT を使用して、入力信号の自動検出 ( QCAP_INPUT_TYPE_AUTO )を設定します。
• 最後に QCAP_RUN(m_pDevice); を呼び出してデバイスを起動します。
デバイスの安全なシャットダウン ( mainwindow.cpp )
デストラクタ ~MainWindow() には、必ず条件判定を追加してください：デバイスが空（null）でない場合、順に QCAP_STOP と QCAP_DESTROY を呼び出し、変数を NULL に設定します。
上記の手順を完了した後、「Build and RUN」をクリックすると、ウィンドウ内にスムーズなキャプチャ映像が表示されるはずです！初めての NexVDO SDK プロジェクトの完了、おめでとうございます！
© Blender Foundation | Big Buck Bunny | CC BY 3.0
実践トラブルシューティングガイド
映像アプリケーションの開発において、画面（映像）が出ないことは最もフラストレーションを感じやすい問題です。もし前のステップで映像が表示されなかった場合は、以下の手順に従ってデバイスが正常に動作しているか確認してください：
ハードウェア認識の確認 ( lspci )
ハードウェアデバイスが正しく接続されているか確認します。問題が最も低いレベル（ハードウェア層）にあることもあるため、システムがキャプチャカードを正しく認識しているかをまず確認する必要があります：
1. システムのデスクトップで右クリックし、「端末を開く (Open in Terminal)」を選択します。
2. ターミナルに lspci コマンドを入力します。このコマンドは、システム上のすべての PCI デバイスをリストアップします。
3. 出力されたリストを注意深く確認してください。ユーザーはリスト内に「0710」を含むデバイス情報（ Multimedia controller: YUAN High-Tech Development Co., Ltd. Device 0710 として表示されます）を見つけることができるはずです。これは、ハードウェアがシステムに正常に認識されたことを意味します。
信号ソースの確認 (v4l2-ctl)
ハードウェアの存在を確認した後、次は「デバイスに信号が接続されているか」を確認します：
1. 同じくターミナルで、コマンド v4l2-ctl -DVI --get-parm を入力して信号のステータスを確認します。
➤ v4l2 関連ツールのインストールについては、次をご参照ください： Chapter 2-3 Installing Jetson Component Environment
2. このコマンドは、詳細な信号情報を返します。現在の Resolution ( Width/Height ) とフレームレート Framerate ( Frames per second ) が正しいかどうかに特に注意して確認してください。例えば、1080p60 の信号ソースが接続されている場合、Width/Height は 1920/1080 と表示され、Frames per second は 60.000 と表示されます。
プログラムクラッシュの解決 (fcCacheChains[i] == NULL failed)
プログラムの実行中に「Assertion fcCacheChains[i] == NULL' failed」というエラーメッセージに遭遇してプログラムがクラッシュした場合でも、心配はいりません！Qt Creator の左側メニューから「Projects ➔ Run ➔ Environment」に進み、Add をクリックして環境変数 QCAP_FONT_DEFERRED_LOAD=0 を設定すれば、無事に解決できます！
