TVML 外部制御 API 開発マニュアル

TVML 外部制御 API 開発マニュアル
TVML 研究開発チーム
http://www.strl.nhk.or.jp/TVML
2001 年７月
TVML Research and Development Team
- 1 -
目次
1. はじめに
3
2. 使用許諾
4
3. 開発環境・言語
5
4. 開発動作環境
5
5. 供給ファイル
5-1. ヘッダファイル
5-2. ライブラリ
6
6. 供給されるサンプルコード
7
7. サンプルコードのサーバモジュール
7
8. イベントモードについて
8
9. C オプション API
9-1. 関数戻り値
9-2. シェアードメモリへのアクセス
9-3. 各モードの状態取得・設定
9-4. ウィンドウ制御関数
9-5. マウス情報取得関数
9-6. TVML 起動オプション指定関数
9-7. 指定ファイル再生関数
9-8. パーサエラー状態関数
9-9. スクリプト追加関数（コントロールモードのみ）
9-10. 時間取得関数
TVML Research and Development Team
9
9
10
11
14
15
15
16
16
17
17
- 2 -
1. はじめに
このマニュアルでは、TVML Player for Windows Version1.2（以下 Player)を用いて外
部制御を行う C オプションの開発を行うための API 解説書である。C オプションの詳細
については、Dkit に付属している 「TVML 外部制御 API 取り扱い資料 (Manual_j.pdf)」
を参照。
TVML Research and Development Team
- 3 -
2. 使用許諾
TVML Player for Windows （以下、本ソフトウェアとする）をインストールし使用する場合、下記の内
容に関しての諸条件を承諾したことになります。本諸条件に同意されない場合は、直ちにインストール
作業を中止し本ソフトウェアによって配布された、すべてのマティリアルを削除してください。
1. 本ソフトウエアの著作権は、TVML 研究開発チームに帰属します。
2. 本ソフトウェアの利用範囲は、個人、または利用者の属する会社、または研究機関に限定されます。
3. 本ソフトウェアの利用によって損害、障害、（修復コスト、データの紛失に障害、使用、利益、好意、
財産の損害、その他を含む）等が生じた場合、ソフトウェアの配布元、またソフトウェアの開発元およ
び開発者に対して、一切責任を問うことはできません。また、本ソフトウェアと同胞される他社製ソフ
トウェアに対してもそれらのソフトウェアの配布元、またソフトウェアの開発元および開発者に対して
一切責任を問うことはできません。
4. 本ソフトウェアを利用して得られたすべてのコンテンツを営利目的に使用することはできません。
5. 本ソフトウェアを使用して得られた研究成果（報告書、出版物、派生ソフトウェアなど）を公開する
場合には、本ソフトウェアを使用した旨を明記し、TVML 研究開発チームまたは配布元に連絡することを
義務付けます。また、本ソフトウェアの利用者は、組織、所属等に変更が生じた場合は、速やかに配布
元である NHK 技研に報告することを義務付けます。
6. 本ソフトウェアに含まれている CG データ、映像データ、イメージデータ、音声データなどのすべて
のマティリアルは、本ソフトウェアからの直接的な使用以外に二次利用することを禁止します。
7. 本ソフトウェアに含まれているバイナリ本体、他社製ソフトウェア、CG データ、映像データ、イ
メージデータ、音声データなどのすべてのマティリアルの再配布することを禁止します。
8. 本ソフトウェアに含まれるバイナリ本体、他社製ソフトウェア、CG データ、映像データ、イメージ
データ、音声データなどのすべてのマティリアルに対して、リバース・エンジニアリング、デコンパイ
ル、ディスアッセンブルを行うことを禁止します。
9. 本誓約書に定めのない事項が生じた場合は、誠意を持って協議し、問題の解決に努めます。
TVML Research and Development Team
- 4 -
3. 開発環境・言語
Microsoft Visual C Version 6.0 （最終確認のサービス・パックは SP5。
）
C オプションの API は、C 言語である。C++ からの参照は、特に制限はない。また、VB は
サポートしていない。
4. 開発動作環境
C オプションの開発を行うための開発環境は、Windows 2000 Professionl SP1 以上とす
る。Windows98 上でも Player は動作するが、C オプションの動作保証は、Windows 2000
Professional に限定する。
TVML Research and Development Team
- 5 -
5. 供給ファイル
5-1. ヘッダファイル
C オプションを使用するために、
1つのヘッダファイルが供給される。ヘッダファイルは、
DKit の”include”フォルダに収録されている。
tvmlcopt.h
5-2. ライブラリ
C オプションを使用するために、２つのライブラリが供給される。以下はスタテック・リ
ンクライブラリで、DKit の”lib”フォルダに収録されている。
libtvmldev.lib
libtvsmem.lib
また、Windows のアプリケーション開発用に、上記２つのライブラリの DLL 形式ファイル
も DKit の”DLL”フォルダに収録されている。DLL ライブラリを使用する際、コンパイラ
側からリンクするライブラリとして、DLLファイルに対する、LIBファイル（すなわち、ス
タテック・リンクライブラリと同一名称のファイル）が収録されている。コンパイルとき
に注意すること。
TVML Research and Development Team
- 6 -
6. 供給されるサンプルコード
“sample”フォルダには、
C オプションを使用したサンプルコードを収録している。
各フォ
ルダには、VC のプロジェクトファイルと、ソースコードを含む。また、
“sample”フォル
ダの中には、各 VC のプロジェクトファイルをバッチ処理する、”Batch Bild.dsw”を収
録している。
このプロジェクトファイルから、
すべてのサンプルコードをバッチビルドす
ることが可能である。
※配布した状態のディレクトリツリーの状態でそのままコンパイル可能となっている。相対パスで”
include”フォルダ、”lib”フォルダを参照している。
Capture
gui_nomenu
play
set_control
stand_fullvga
Cplay
gui_normal
quit
set_normal
stand_svga
Cserver
gui_sample1
safeplay
set_normal2ctrl
stop
execute
lock_win
search_mouse
stand_enormal
timeinfo
getwinpos
pause
server
stand_esmall
unlock_win
winpos
上記のサンプルコードは、
いくつかを組み合わせて使用するように構成されている。
各サ
ンプルコードの詳細は、別紙「TVML外部制御API取り扱い資料 (Manual_j.pdf)」を参照。
※gui_sample1については、MFCを使用したGUIによるPlayerの制御を可能とするアプリケーションとなっ
ている。
7. サンプルコードのサーバモジュール
サンプルコードには、
２つのサーバが用意されている。
どちらも同一の機能として動作す
るが、NORMAL モード、CONTROL モードの初期化の違いである。
（NORMAL モード、CONTROL
モードについては、
「8. イベントモードについての説明」を参照）
サーバは、常に Player 起動前に起動する必要がある。サーバは Player との通信を行う
シェアードメモリの管理を行う。
サーバが動いていれば、
その他のサンプルコードの各バ
イナリを実行することができる。
（サーバは同時２つ動作することはできない。）
TVML Research and Development Team
- 7 -
8. イベントモードについて
TVML の C オプションには、２つの制御モードがある。１つは、NORMAL モードで、通常の
Player 同様に動作し、各種ユーザアクション（再生、停止、ポーズ、キャプチャ、ウィ
ンドウ位置など）を外部から制御することが可能なモードである。もう１つは CONTROL
モードで、従来の C オプション同等な機能として動作する。各イベントモードは、実行中
に切り替えることが可能である。
以下に各イベントモードを切り替えたときの動作状態を
示す。
・NORMAL モード→ CONTROL モード
再生スクリプトの指定が無い状態、または動作停止状態に変更が可能である。また、スク
リプト再生後自動切換え（RUN_NORAML_TO_CTL）が可能であるため、指定スクリプト実行
後、CONTROL モードによるスクリプト実行が可能である。CONTROL モードに切り替えが行
われた直後、APIによるファイル指定がリセットされ、再生スクリプトの指定が無い状態
になる。描画結果は最後の実行された最後のスクリプトの状態となる。
・CONTROL モード→ NORMAL モード
CONTROL モード中、NORMAL モードに切り替えると、再生スクリプトの指定が無い場合、停
止状態になる。CONTROLモード中に再生スクリプトの指定が行われ、NORMALモードに切り
替えられた場合、停止せずに、指定スクリプトを実行する。指定スクリプトはNORMALモー
ドで実行された状態と同一の結果となる。
上記の動作モードは３つの定義変数によって指定することができる。NORMAL モードの場
合、RUN_NORMAL、CONTROL モードの場合、RUN_CONTROL、NORMAL モードから CONTROL モー
ドへの自動切換えを行う場合、RUN_NORMAL_TO_CTL を指定する。
サンプルコード、set_control, set_normal, set_normal2ctrl を参照。
TVML Research and Development Team
- 8 -
9. C オプション API
C オプション API の解説行う。
9-1. 関数戻り値
各関数の戻り値は以下の定義変数で表される。型は int型である。定義は、tvmlcopt.hで
定義されている。
TVSTAT_OK
TVSTAT_ERROR
TVSTAT_UNKNOW
TVSTAT_CANT_ACCESS
TVSTAT_CANT_FILE
TVSTAT_TABLE_FULL
TVSTAT_NAME_NOT_FOUND
正常実行。
エラー発生。
引数の判定ができない。
シェアードメモリにアクセスすることができない。
ファイルが存在しない。
内部テーブルデータが一杯。
指定された名称無し。
TVML Research and Development Team
- 9 -
9-2. シェアードメモリへのアクセス
シェアードメモリの初期化は、init_tvmldev 関数で行う。第一引数は以下を指定するこ
とができる。
CREATE_SHMEM
シェアードメモリの作成（外部アプリケーションで使用。
）
CONNET_SHMEM
シェアードメモリへの接続（Player、その他外部アプリケーションで使用。
）
FORCE_CREATE_SHMEM
強制的にシェアードメモリを作成。
すでにシェアードメモリが作成されていても強制的に
シェアードメモリを作るため使用には注意が必要。
第二引数は、使用する、キャラクタ、小道具、などの最大数を指定する。ディフォルト値
は、定義変数 DEFAULT_MAX_ITEMS。
シェアードメモリの使用終了は、exit_tvmldev 関数で必ず行う。シェアードメモリ管理
アプリケーション（サンプルコード server, Cserver などは、exit_tvmldev を使用して
終了すること。）
シェアードメモリのリセットは、reset_tvmldev関数で行う。シェアードメモリ作成後は
必ず初期化される。
サンプルコード、server, Cserver を参照。
TVML Research and Development Team
- 10 -
9-3. 各モードの状態取得・設定
Player の制御／状態取得は、以下の２つの関数で行う。
int
int
get_tvmlstat(int mode,int *param);
set_tvmlstat(int mode,int param);
第一引数には以下の定義変数を指定することができる。
DATA_MAX
MODE_GUI MODE_MENU
MODE_SCRIPT
MODE_RUNNING
MODE_EVENT
MODE_COMMAND
MODE_MOUSE
MODE_STAND
MODE_START
MODE_PARSER
シェアードメモリの初期化テーブル数取得
GUI 制御
MENU 制御 (Windows 版では、使用不可。
）
スクリプト制御
動作制御
動作モード制御
C オプション制御
マウス制御
Player 起動状態制御
Player 起動オプション制御
Player の Parser 状態取得
DATA_MAX, MODE_PARSER は、get_tvmlstat関数のみで状態取得に使用することができる。
各 MODE 系定義変数は以下の定義変数を指定することができる。
● MODE_GUI
MODE_GUI_ON MODE_GUI_OFF
GUI の ON （ディフォルト）
GUI の OFF
MODE_GUI の指定は、Player 起動前しか有効ではない。
サンプルコード、gui_nomenu, gui_normal を参照。
TVML Research and Development Team
- 11 -
● MODE_MENU
MENU_BAR_ON
MENU_FILE_ENABLE
MENU_EDIT_ENABLE
MENU_CONTROL_ENABLE
MENU_HELP_ENABLE
MENU_QUIT_ENABLE
MENU_REPEAT_ENABLE
MENU_VIDEO_ENABLE
MENU_REPEAT_ON
MENU_VIDEO_ON
MENU_RESET メニューバーの表示※
ファイルメニューの有効
エディットメニューの有効
コントロールメニューの有効
ヘルプメニューの有効
Quit アイテムの有効
リピートアイテムの有効
ビデオアイテムの有効
リピートチェックをいれる
ビデオチェックを入れる
メニューのリセット。ディフォルト状態にする。
（ディフォルト）
※この定義変数は、Player 起動前しか指定することがない。
サンプルコード、gui_nomenu, gui_normal を参照。
● MODE_SCRIPT
スクリプトにエラーがあるときの再生制御を行う。SCRIPT_SAFE_ON の場合、スクリプト
にエラーがあると再生することができない。
SCRIPT_SAFE_OFF
SCRIPT_SAFE_ON
セーフモードオフ（ディフォルト）
セーフモードオン
サンプルコード、safeplay を参照。エラースクリプトとして、”bin”フォルダにある
errorin.tvml を実行することで、safeplay の動作を確認することができる。
TVML Research and Development Team
- 12 -
● MODE_RUNNING
RUN_STOP
RUN_PLAY
RUN_PAUSE_ON
RUN_PAUSE_OFF
RUN_QUIT
RUN_RESET
RUN_NOSCRIPT
RUN_CAPTURE
RUN_READING
RUN_NONE ※
停止
再生
ポーズ・オン
ポーズ・オフ
Player の終了
Player のリセット
再生するスクリプトが存在しない。
（ディフォルト）
スクリーンキャプチャ
スクリプト読みこみ中
再生イベント無し。
※コントロールモードのときのみ
サンプルコード、play, stop, pause, quit, capture を参照。
● MODE_EVENT
RUN_NORMAL
RUN_CONTROL
RUN_NORAML_TO_CTL
える。
ノーマルモード（ディフォルト）※
コントロールモード
ノーマルモードで再生が終わるとコントロールモードに切り替
※ノーマルモードでは、Player の制御のみを行うことができる。
サンプルコード、set_control, set_normal, set_normal2ctrl を参照。
● MODE_COMMAND
ENABLE_MENU
ENABLE_WINDOW
ENABLE_SCRIPT
ENABLE_RUNNING
RESET_COMMAND
MODE_MENU コマンドの有効／無効
ウィンドウ系コマンドの有効／無効
MODE_SCRIPT コマンドの有効／無効
MODE_RUNNING コマンドの有効／無効
RESET_COMMAND コマンドの有効／無効（ディフォルト）
サンプルコード、lock_win, unlock_win を参照。
TVML Research and Development Team
- 13 -
● MODE_MOUSE
MOUSE_OFF
MOUSE_ON
マウス状態監視の終了（ディフォルト）
マウス状態監視の開始
サンプルコード、search_mouse を参照。
● MODE_STAND
STAND_NO
STAND_UP
STAND_OK
STAND_EXIT
STAND_EXEC
Player は起動していない。
（ディフォルト）
Player 起動中
Player 起動
Player 終了
Player を起動させる。※
※set_tvmlstatのみが指定できる。外部アプリケーションからTVML Playerを起動させる場合に使用。起
動対象Playerは、環境変数TVML_PLAYERで指定されたTVML Playerか、バイナリにパスが通っているPlayer
が起動される。
サンプルコード execute, server を参照。
9-4. ウィンドウ制御関数
ウィンドウの位置の取得、ウィンドウの表示位置の指定は以下の関数で行う。
int
int
get_winpos(int *x,int *y);
set_winpos(int x,int y);
サンプルコード winpos, getwinpos を参照。
Player ウィンドウを外部アプリケーションからフォアグラウンドへの移動は、以下の関
数で行う。
void tvml_window_top(void);
TVML Research and Development Team
- 14 -
9-5. マウス情報取得関数
MODE_MOUSE が、MOUSE_ON のとき、以下の関数を使用して、マウスの位置、ボタンの状態
を取得する。
int
int
get_mouse_pos(int *x,int *y);
get_mouse_button(int *stat);
では、以下の定義変数がボタンの状態に合わせて、引数 stat に返される。
MOUSE_BUTTON1
MOUSE_BUTTON2
MOUSE_BUTTON3
サンプルコード search_mouse を参照。
以下の関数にて、ホイルマウスの状態を取得することができる。
int get_mouse_wheel(int *zflag);
int reset_mouse_wheel(void);
ホイルの状態は、get_mouse_wheel関数でzflagの値参照し、参照後、reset_mouse_wheel
を呼び出すことにより、ホイルの回転状態を知ることができる。
9-6. TVML 起動オプション指定関数
int
set_player_option(int opt);
外部アプリケーションからTVML Playerを起動する時、Playerのオプションを以下の定
義変数で指定することができる。
START_DEFALUT
START_SMALL
START_FULLSCR
START_SVGA
（ディフォルト：640x480）
スモールモード（-s 320x240）
VGA フルスクリーンモード
SVGA モード（800x600)
この関数は、Player 起動前に実行する必要がある。サンプルコード、stand_enormal、
stand_esmall、stand_fullvga、stand_svga を参照。
TVML Research and Development Team
- 15 -
9-7. 指定ファイル再生関数
ローカルに存在するスクリプトファイルを再生する場合、
スクリプト名称を以下の関数で
指定することができる。この関数は読み込むスクリプト名を指定するだけで、
実行はされ
ない。
int set_tvml_script(char *filename);
また、最後に指定されたファイル名を以下の関数で取得することができる。
int get_tvml_script(char *filename);
Playerに再生スクリプトファイル名が指定されているか調べるには以下の関数を使用す
る。ファイルそのものの存在は確認しない。
int chk_tvml_script(void);
サンプルコード、play を参照。
9-8. パーサエラー状態関数
パーサのエラー状態を確認することができる。
以下の関数で、
パーサにエラーが発生した
か調べる。
int chk_parser_error(void);
パーサのエラー出力（テキスト）は、以下の関数でそのテキストのポインタを出力するこ
とができる。この取得したポインタ内部の操作は禁止されている。
char *get_parser_error_ptr(void);
パーサのエラーをリセットするには、以下の関数を使用する。
int reset_parsre_error(void);
サンプルコード safeplay を参照。
TVML Research and Development Team
- 16 -
9-9. スクリプト追加関数（コントロールモードのみ）
以下は、コントロールモードとき、メモリー経由でスクリプトの指定を行う関数である。
int
int
int
set_script(char *tvml_str);
add_script(char *tvml_str);
clean_script(char *tvml_str);
set_script 関数は、新規スクリプトを追加する。追加するスクリプトは、テキスト形式
で各 OS に合わせて整形したものに限る。add_script関数は、すでに set_scriptで新規ス
クリプトを追加後、別のスクリプトを追加するときに使用する。
すべてのスクリプトを消去するには、clean_script 関数を使用する。サンプルコード
Cplay を参照。
9-10. 時間取得関数
以下に、C オプションの時間関数郡を列挙する。
int
int
reset_copt_time(void);
get_copt_time(double *current_time);
reset_copt_time 関数はタイマーのリセットを行う。get_copt_time 関数は、リセット後
の経過時間を引数 current_time に取得する。サンプルコードの timerinfo を参照。
TVML Research and Development Team
- 17 -