PV1 SDK 技術資料 (バージョン 1.0.3)
このページには、SDK を使用してアプリケーションソフトウェアを開発する際に
必要となる技術資料を掲載しています。
PCB クラス
[概要]
このクラスは、SDK のメインクラスです。機能ごとのクラスのインスタンスを返します。
[構造体]
// コンストラクタ引数
struct arg {
Kernel *kernel; // カーネル抽象化クラスのインスタンス
uint32 index; // ボード番号 (0基底)
};
[関数]
(1) ~PCB();
デストラクタ
(2) bool IsValid() const;
初期化が成功したかどうかを返します。インスタンス生成後に確認をしてください。
(3) PCB_Audio *Audio () const;
(4) PCB_Encoder *Encoder() const;
(5) PCB_Decoder *Decoder() const;
(6) PCB_Overlay *Overlay() const;
(7) PCB_Codec *Codec () const;
(8) PCB_Memory *Memory () const;
各インタンスを返します。
PCB_Audio クラス
[概要]
このクラスでは、オーディオに関する処理を行います。オーディオクロックの設定、
オーディオ信号経路の設定、オーディオ単独のキャプチャ・プレイバックを行います。
[定数]
// サンプリング周波数
enum {
CLOCK_48, // 48 kHz [初期状態]
CLOCK_441, // 44.1 kHz
CLOCK_32 // 32 kHz
};
// 同期方式
enum sync {
SYNC_LOCK, // アナログビデオ入力の信号に合わせてオーディオクロックを生成します [初期状態]
SYNC_UNLOCK // 他と同期を取らずにオーディオクロックを生成します
};
// インターフェース番号
enum interfacfe {
INTERFACE_1,
INTERFACE_2
};
// 入力元
enum input {
INPUT_AUDIO, // オーディオ A/D コンバータ
INPUT_CODEC, // DV コーデック
INPUT_MEMORY // メインメモリ
};
// 出力先
enum output {
OUTPUT_AUDIO, // オーディオ D/A コンバータ
OUTPUT_CODEC // DV コーデック
};
// チャンネル配置 (現在は CHANNEL_NORMAL のみサポートしています)
enum channel {
CHANNEL_NORMAL, // L / R
CHANNEL_L, // L / L
CHANNEL_R, // R / R
CHANNEL_RESERSE // R / L
};
// 操作内容 (キャプチャかプレイバックか)
enum operation {
OPERATION_CAPTURE,
OPERATION_PLAYBACK
};
// ブロックサイズ (データを読み書きするブロックのサイズ単位)
enum block {
BLOCK_64,
BLOCK_128,
/* 中略 */
BLOCK_512K,
BLOCK_1M
};
// 状態
enum state {
STATE_IDLE, // 非アクティブ
STATE_BUSY // DMA 転送実行中
};
[構造体]
// 信号経路
struct path {
enum input input; // 入力元
enum output output; // 出力先
enum channel channel; // チャンネル配置
};
[関数]
( 1) ES::status SetClock(clock);
サンプリング周波数を設定します。ボード上のオーディオクロックの周波数が変わります。
ビデオキャプチャ中はコールできません。
( 2) clock Clock() const;
サンプリング周波数を取得します。
( 3) ES::status SetSync(sync);
ボード上のオーディオクロックの同期方式を設定します。SYNC_LOCK を設定すると、
アナログビデオ入力の信号に合わせてオーディオクロックを生成します(ロックオーディオ)。
通常は SYNC_LOCK 状態にします。オーディオキャプチャ・オーディオプレイバック・
ビデオプレイバック開始前に SYNC_UNLOCK に設定し、それらの終了後に SYNC_LOCK に
戻すことをお薦めします。
なお、ビデオキャプチャ中はコールできません。
( 4) sync Sync() const;
オーディオクロックの同期方式を返します。
( 5) ES::status SetPath(interface, input, output, channel);
( 6) ES::status SetPath(interface, const path *);
( 7) ES::status SetPath(const path *path1, const path *path2);
信号経路を設定します。(7) の関数で引数に NULL を渡すことにより、
そのインターフェースを非アクティブにすることができます。
( 8) ES::status GetPath(path *path1, path *path2);
信号経路を取得します。
( 9) ES::status SetBlock(interface, operation, block);
インターフェースと操作内容ごとのブロックサイズを指定します。
このサイズを単位に PCB_Stream クラスのデータ入出力を行います。
(10) ES::status GetBlock(interface, operation, block *) const;
インターフェースと操作ごとのブロックサイズを取得します。
(11) ES::status StartCapture(interface, PCB_Stream *);
キャプチャを開始します。ストリームは、PCB_Stream から派生させたクラスを定義し、
そのクラスのインスタンスを指定します。
(12) ES::status StopCapture(intercace);
キャプチャを停止します。
(13) ES::status StartPlayback(intercace, PCB_Stream *);
プレイバックを開始します。ストリームは、StartCapture() と同様に指定します。
(14) ES::status StopPlayback(interface);
プレイバックを停止します。
(15) ES::status GetState(interface, operation, state *) const;
インターフェースと操作内容ごとの現在の状態を取得します。
PCB_Encoder クラス
[概要]
このクラスでは、ディジタルビデオをアナログに変換するビデオエンコーダの設定を行います。
[定数]
// サブキャリア周波数設定用
enum {
SUB_CARRIER_FREQUENCY_1 = 39375000, // サブキャリア周波数の分子
SUB_CARRIER_FREQUENCY_2 = 11, // サブキャリア周波数の分母
VIDEO_CLOCK_FREQUENCY = (27)*1000*1000 // ボード上のビデオクロックの標準周波数 27MHz
};
// フォーマット
enum format {
FORMAT_YUV, // YUV [初期状態]
FORMAT_RGB // RGB (同期信号 G)
};
[関数]
(1) ES::status SetSubcarrier(uint32 value);
サブキャリア周波数を設定します。value は下記の式で得られた値を渡します。
value = (2^32 - 1) * fsc / f656;
ここで、fsc はサブキャリア周波数、f656 はビデオクロックの周波数です。
fsc は規格で定められている下記の式
秒間フレーム数 fv = 30 * (1000/1001)
秒間ライン数 fh = fv * 525
サブキャリア周波数 fsc = fh * (455/2)
より、SUB_CARRIER_FREQUENCY_1 / SUB_CARRIER_FREQUENCY_2 になります。
一方、f656 は規格で 27MHz と定められています。
PV1 のボード上のビデオクロック周波数は、ビデオプレイバックのために
後述の PCB_Decoder::SetSync() に SYNC_UNLOCK を指定すると、
27MHz から若干偏差を生じます。偏差は約 +150ppm で、これをキャンセル
するために本関数が公開されています。
キャンセルを行わないと、ビデオプレイバック時に接続したモニタが
カラーバースト信号のデコードに失敗したり、信号そのものが無効と判断され、
白黒表示になることがあります。
なお、ビデオキャプチャ中はこの関数を呼び出すことはできません。
(2) ES::status SetFormat(format);
3信号系のフォーマットを設定します。ビデオキャプチャ中はコールできません。
(3) foramt Format() const;
3信号系のフォーマットを取得します。
PCB_Decoder クラス
[概要]
このクラスでは、アナログビデオをディジタルに変換するビデオデコーダの設定を行います。
[定数]
// ビデオ映像形式
enum format {
FORMAT_CVBS, // コンポジット
FORMAT_YC // Sビデオ
};
// 同期方式 (ボード上のビデオクロックの生成方法)
enum sync {
SYNC_LOCK, // アナログビデオ入力信号に合わせてビデオクロックを生成します [初期状態]
SYNC_UNLOCK // ビデオプレイバック用のビデオクロックを生成します
};
[関数]
(1) ES::status SetInput(foramt, uint32 index);
アナログビデオ信号の入力源を指定します。PV1 の場合は、index は 0 か 1 を指定します。
初期状態では format = FORMAT_YC, index = 0 が入力源になっています。
ビデオキャプチャ中はコールできません。
(2) ES::status GetInput(format *, uint32 *index) const;
アナログビデオ信号の入力源を取得します。
(3) ES::status SetSync(sync);
ビデオクロックの同期方法を指定します。
通常は SYNC_LOCK の状態にします。ビデオプレイバック開始前に SYNC_UNLOCK に設定し、
ビデオプレイバックが終了したら SYNC_LOCK に戻すことをお薦めします。
なお、ビデオキャプチャ中はコールできません。
(4) sync Sync() const;
ビデオクロックの同期方法を取得します。
PCB_Overlay クラス
[概要]
このクラスでは、ビデオピクセルデータの DMA 転送や画面比を取り扱います。
[定数]
// 画面比
enum ratio {
RATIO_4_3, // 4:3 正方形ピクセルでのサイズ例 ... 640x480
RATIO_16_9 // 16:9 正方形ピクセルでのサイズ例 ... 853x480
};
// バイトスワップ (DMA 転送時にハードウェアにてバイトオーダーを変更します)
enum swap {
SWAP_NONE, // 0123 → 0123
SWAP_2, // 0123 → 1032
SWAP_4 // 0123 → 3210
};
// ピクセルフォーマット
enum format {
FORMAT_RGB15,
FORMAT_RGB16,
FORMAT_RGB32,
FORMAT_YCbCr422
};
// 反転表示
enum flip {
FLIP_NONE, // ノーマル
FLIP_LEFT_RIGHT, // 左右反転
FLIP_TOP_BOTTOM, // 上下反転
FLIP_UPSIDE_DOWN // 左右反転+上下反転
};
// ウェイト
enum {
WAIT_NONE, // 待ちません
WAIT_FIELD, // フィールドのアクティブ領域の終わりまで待ちます
WAIT_FRAME // フレーム のアクティブ領域の終わりまで待ちます
};
[構造体]
// 矩形
struct rect {
sint32 left;
sint32 top;
sint32 right;
sint32 bottom;
};
// 領域
struct region {
uint32 count; // rects で指定する矩形リストの数
const rect *rects; // 矩形リスト (重なりがあってはなりません)
};
// バッファ情報
struct buffer {
ES::physical address; // バッファ先頭の物理アドレス
enum format format; // ピクセル形式
enum swap swap; // バイトスワップ
uint32 bytes_per_row; // 1ラインあたりのバイト数
const rect *frame; // フレーム矩形 (address 位置を原点として計算します)
const region *clip; // クリッピング領域 (frame 左上を原点として計算します)
enum flip flip; // 反転表示
};
[型]
// 画面比変更通知用
typedef void (*func)(ratio, void *arg);
[関数]
(1) ES::status GetSrcSize(uint32 *width, uint32 *height) const;
ハードウェア上で扱われているビデオのサイズを取得します。
PV1 では width=720, height=480 です。
(2) ES::status GetDstSize(
uint32 *min_width , uint32 *max_width ,
uint32 *min_height, uint32 *max_height,
bool left_right_flip = false) const;
拡大・縮小できる範囲を取得します。左右反転を行うかどうかによって、
max_width が変わります。
(3) ES::status SetCallback(func, void *arg = NULL);
画面比サイズの変更を通知するコールバック関数を指定します。
コールバックを停止するには func に NULL を指定します。
(4) ES::status Start(const buffer *);
DMA 転送を開始します。
(5) ES::status Modify(const buffer *);
DMA 転送を変更します。Stop()→Start() では画面が乱れますので、
この関数を使用してください。
(6) ES::status Stop(wait);
指定された項目を待って、DMA 転送を停止します。
PCB_Codec クラス
[概要]
このクラスでは、ビデオのキャプチャやプレイバックを行います。
[定数]
// オーディオ・ビット数
enum bit {
BIT_16, // 16 ビット
BIT_12 // 12 ビット (32kHz 時のみ有効)
};
// オーディオ・チャンネル
enum channel {
CHANNEL_AB, // チャンネルA,B (通常はこのチャンネルを指定してください)
CHANNEL_CD // チャンネルC,D (32kHz 12bit 時のみ有効)
};
// フレームサイズ
enum {
FRAME_SIZE = (120)*1000 // DV 形式の 1 フレームのサイズは (120)*1000 バイト
};
// 動作状態
enum state {
STATE_IDLE, // 非アクティブ [初期状態]
STATE_CAPTURE, // キャプチャ動作中
STATE_PLAYBACK // プレイバック動作中
};
[関数]
(1) ES::status StartCapture(PCB_Stream *, bit = BIT_16, channel = CHANNEL_AB);
キャプチャを開始します。ストリームは、PCB_Stream から派生させたクラスを定義し、
そのクラスのインスタンスを指定します。
(2) ES::status StopCapture();
キャプチャを停止します。
(3) ES::status StartPlayback(PCB_Stream *, channel = CHANNEL_AB);
プレイバックを開始します。ストリームは、StartCapture() と同様に指定します。
(4) ES::status StopPlayback();
プレイバックを停止します。
(5) state State() const;
動作状態を返します。
[備考]
(A) キャプチャ・プレイバック共に連続動作可能時間は 8時間 に制限されます。
(B) StartCapture() と StartPlayback() の初回コール時には、ドライバ内部で大量のコードが
実行され、この処理に約1秒 (Celeron 300MHz にて計測) の時間が掛かります。
次のメジャーバージョンアップではアルゴリズムを抜本的に見直し高速化を図ります。
PCB_Memory クラス
[概要]
このクラスでは、論理アドレスから物理アドレスを取得したり、
オーディオ・ビデオ用の DMA バッファの確保を行います。
[定数]
// バッファのタイプ
enum type {
TYPE_VIDEO, // ビデオ用 キャプチャ・プレイバック兼用 (16MB)
TYPE_AUDIO_CAPTURE_1, // オーディオインターフェース1 キャプチャ用 ( 1MB)
TYPE_AUDIO_PLAYBACK_1, // オーディオインターフェース1 プレイバック用 ( 1MB)
TYPE_AUDIO_CAPTURE_2, // オーディオインターフェース2 キャプチャ用 ( 1MB)
TYPE_AUDIO_PLAYBACK_2 // オーディオインターフェース2 プレイバック用 ( 1MB)
};
// バッファの状態
enum state {
STATE_FREE, // メモリが確保されていない状態 [初期状態]
STATE_UNLOCK, // メモリは確保されているが物理メモリに固定されていない状態
STATE_LOCK // メモリが確保され物理メモリに固定されている状態
};
[関数]
(1) ES::status ConvertAddress(void *logical, void **physical);
論理アドレスから物理アドレスを取得します。
物理アドレスの計算にあたって、メモリのロック操作は行われません。
つまり、指定する論理アドレスは VGA カードバッファなどの
物理メモリを指している必要があります。
(2) ES::status SetState(type, state);
指定したタイプのバッファの状態を変更します。ハードウェア動作時には、
DMA 転送が行われるため、バッファの状態を STATE_LOCK にする必要があります。
(3) ES::status GetState(type, state *) const;
指定したタイプのバッファの状態を取得します。
PCB_Stream クラス
[概要]
オーディオやビデオデータの入出力を扱います。キャプチャやプレイバックを
開始するときに、このクラスの派生クラスのインスタンスを渡します。
ドライバがデータの入出力を必要とするときに、必要な関数を呼び出します。
[構造体]
// メモリブロック
struct block {
void *ptr; // 先頭アドレス
uint32 size; // サイズ
};
// メモリブロックリスト
struct list {
uint32 count; // メモリブロックのリスト数
struct block *block; // メモリブロックのリスト
};
[関数]
(1) void Open();
データの入出力を開始します。ファイルをオープンする等、必要な処理を行います。
(2) void Data(const list *);
データの入出力を行います。基本的には、メモリブロックリストが指すメモリ領域に
対して、データの読み書き操作を行います。
各処理内容ごとの詳細は[備考]を参照してください。
(3) void Close();
データの入出力を終了します。遅延書き込みのフラッシュ等、必要な処理を行います。
[備考]
各処理ごとの関数呼び出し順序・規則は下記の通りです。
(A) オーディオキャプチャ時
Open() → DMA動作開始
→ Data(ブロックサイズ) → Data(ブロックサイズ) → ... → Close()
(B) オーディオプレイバック時
Open() → Data(1MB)[*1] → DMA動作開始 →
→ Data(ブロックサイズ) → Data(ブロックサイズ) → ... → Close()
必ずしも [*1] の時点で要求されたサイズ全てのデータを用意する必要は
ありません。
(C) ビデオキャプチャ時
Open() → DMA動作開始
→ Data(1フレームのサイズ) → Data(1フレームのサイズ) → ... → Close()
ビデオ入力信号の同期が乱れる・ハードウェア DV コーデックの FIFO エラー
などの原因により、エンコードに失敗したときには、Data() の引数 list の
count メンバが 0 になります。Data() のコールバック終了後に、
ドライバは DV コーデックデバイスをリセットしてキャプチャを再スタートします。
リスタート後はビデオバッファが先頭から使用されます。遅延書き込みを
している場合には、フラッシュを行ってください。
(D) ビデオプレイバック時
Open() → Data(16MB)[*2] → DMA動作開始
→ Data(1フレームのサイズ) → Data(1フレームのサイズ) → ... → Close()
必ずしも [*2] の時点で要求されたサイズ全てのデータを用意する必要は
ありません。
ハードウェア DV コーデックの FIFO エラーなどの原因により、デコードに
失敗したときには、Data() の引数 list の count メンバが 0 になります。
Data() のコールバック終了後に、ドライバは DV コーデックデバイスを
リセットしてプレイバックを再スタートします。