§1 はじめに |
このドキュメントは、『PSX Multi Converter(以下、PsxMCと言います)』が使用するPSRプラグインの仕様について説明します。
さて、このプラグイン仕様から、とうとう「案」という文字が消えました。 前回までの仕様案では、ASPIを介したCDの読み取りに対応できないということが判明したために、今回大幅な仕様変更を行いました。
PSRプラグインは、PsxMCに様々な形式のムービーまたはオーディオデータを扱えるようにするプラグインです。 基本的にはストリームの読み取りを行うためのプラグインという位置づけになりますが、様々な形式のデータを様々な形式のユーザインターフェースに使用できるように考慮しました。
なお、本ドキュメントの転載・配付はご自由に行って下さい。
§2 前提条件 |
先に述べたように、PSRプラグインの目的は、ストリームの読み取りを行うことにありますが、ストリームデータの形式については実に様々な形式があります。
プラグインのインターフェース設計を行う上で、次のような形式のストリームデータを扱えるよう考慮しました。
なお、CD-ROMを読み込むための機能をCDACCESSというライブラリにまとめましたので、CD-ROMを読み込むためのプラグインは、このライブラリを使用するようにして下さい。(PSRプラグイン仕様は、このライブラリを使用することを前提に設計してあります。)
§3 ファイル名の規定 |
PSRプラグインは、それがプラグインであることを識別するために、'psr'という拡張子のファイルで作成します。 また、拡張子を含めて16byte以下の名前にして下さい。
§4 ファンクション一覧 |
プラグインに必要なファンクションは全部で17となりました。 すべてのプラグインが全部のファンクションをサポートするのではなく、各プラグインが必要なファンクションのみを用意するものとします。 また、ファイルを読み込むためのプラグインとCD-ROMを読み込むためのプラグインによりサポートするファンクションが異なります。詳しくは、以下のファンクション一覧を参照して下さい。
関数名 | 機能名 | 区分 | サポート |
PsrQueryPlugin | プラグイン情報の取得 | 共通 | 必須 |
PsrIsSupportFile | ストリームファイルのサポート判定 | FILE | 必須 |
PsrIsSupportCDBegin | CDサポート判定 開始処理 | CD-ROM | 必須 |
PsrIsSupportCDEnd | CDサポート判定 終了処理 | CD-ROM | 必須 |
PsrIsSupportCDSector | CDサポート判定 セクタ通知 | CD-ROM | 必須 |
PsrIsSupportCDResult | CDサポート判定 結果取得 | CD-ROM | 必須 |
PsrGetStrFileInfo | ストリームファイル情報の取得 | FILE | 必須 |
PsrGetStrDataInfo | ストリームデータ情報の取得 | CD-ROM | 必須 |
PsrOpenFile | ストリームファイルのオープン | FILE | 必須 |
PsrOpenCD | CDストリームのオープン | CD-ROM | 必須 |
PsrClose | ストリームデータのクローズ | 共通 | 必須 |
PsrRead | ストリームデータの読み取り | 共通 | 必須 |
PsrSeek | 読み取り位置の設定 | 共通 | 必須 |
PsrDecodeFrame | 動画データのデコード | 共通 | - |
PsrDecodeBs | BSデコード | 共通 | - |
PsrDecodeAudio | 音声データのデコード | 共通 | - |
PsrSetEntrionment | 環境設定パネルの呼び出し | 共通 | - |
§5 ファンクション詳細 |
次に各ファンクションの機能詳細を示します。
変数名などについてはWindowsっぽいものになるようにしたつもりでが、色々な部分に趣味が入っているかも知れません。
なお、このプラグインに特化するような定数値や形式については、別途インクルードファイルを用意します。
プラグインを識別する名前などプラグイン固有の文字情報を返します。
このファンクションは、インストールされているプラグインをリスト表示するような場合に使用されます。
VOID PsrQueryPlugin( LPPSRPLUGIN lpPlugin); // プラグイン情報取得バッファ
lpPluginプラグイン情報を取得するバッファのアドレスを指定します。 このパラメータの形式については、PSRPLUGIN形式を参照して下さい。
リターン値はありません。
指定ファイルのデータが当該プラグインでサポートできる形式のデータであるかを判定します。
このファンクションは、PsxMCが使用すべきプラグインを自動認識する際に使用されます。
BOOL PioIsSupportFile( LPCTSTR lpFileName); // ファイル名
lpFileNameサポート判定するストリームファイルの名称を指定します。
当該プラグインがlpFileNameにより指定されたファイルの読み取りをサポートしているかが次の値で返ります。
値 意味 TRUE サポートできる形式 FALSE 非サポート形式 扱うデータの種類によっては、サポート判定に長時間を要する場合があるかも知れません。 このようなプラグインの場合、適当にサポート判定を行ってTRUEを返して下さい。 最終的なサポート判定は、PsrGetStrFileInfo関数によりストリームデータ情報が取得できるかどうかで判定されます。
CDが当該プラグインでサポートできる形式のストリームデータを含んでいるかを判定するための開始処理を行います。
このファンクションは、PsxMCがCD解析処理を行う場合、最初に呼び出されます。 このファンクションの後に、PsrIsSupportCDSector関数が複数回呼び出され、CD中のセクタが順番に通知されます。そして、最後にPsrIsSupportCDResult関数で解析結果を取得した後に、PsrIsSupportCDEnd関数が呼び出されます。
HANDLE PsrIsSupportCDBegin( INT iNumToc, // TOCの数 LPTOCENTRY lptoc); // TOC
iNumToc解析するCDのTOCの数を指定します。lptoc解析するCDの全TOCを指定します。 このパラメータの形式については、CDACCESSライブラリのTOCENTRY形式を参照して下さい。
ファンクションの処理が成功した場合CDサポート判定ハンドルが返り、何らかのエラーが発生した場合NULLが返ります。
CDが当該プラグインでサポートできる形式のストリームデータを含んでいるかを判定するための終了処理を行います。
VOID PsrIsSupportCDEnd( HANDLE hIsCD); // CDサポート判定ハンドル
hIsCDPsrIsSupportCDBegin関数で取得したCDサポート判定ハンドルを指定します。
リターン値はありません。
CDが当該プラグインでサポートできる形式のストリームデータを含んでいるかを判定します。 このファンクションには、解析CDの全セクタが順番に通知されます。
BOOL PsrIsSupportCDSector( HANDLE hIsCD, // CDサポート判定ハンドル TOCENTRY toc, // TOC DWORD nSector, // セクタ番号 PVOID pvSector); // セクタ
hIsCDPsrIsSupportCDBegin関数で取得したCDサポート判定ハンドルを指定します。toc通知セクタを含むトラックのTOCを指定します。 このパラメータの形式については、CDACCESSライブラリのTOCENTRY形式を参照して下さい。nSector通知したセクタ(pvSector)のセクタ番号を指定します。 先頭のセクタ番号は0です。pvSector通知したセクタの内容が格納されているバッファのアドレスを指定します。 ここで指定されたセクタの内容は、他のプラグインも使用するので絶対に書き換えてはいけません。
このトラックのCDサポート判定を続けたい場合にはTRUEが返り、中断したい場合にはFALSEが返ります。
CDが当該プラグインでサポートできる形式のストリームデータを含んでいるかを判定した結果を返します。
INT PsrIsSupportCDResult( HANDLE hIsCD, // CDサポート判定ハンドル INT iIndex, // ストリームインデックス値 LPPSRSTREAMINFO lpStreamInfo); // ストリームデータ情報
hIsCDPsrIsSupportCDBegin関数で取得したCDサポート判定ハンドルを指定します。iIndex取得したいストリームデータ情報のインデックス値を指定します。 iIndexの有効値は、0~ストリーム数-1の範囲です。 ストリーム数は、PsrIsSupportCDResult関数のlpStreamInfoにNULLを指定することで取得できます。lpStreamInfoストリームデータ情報を取得するバッファのアドレスを指定します。 lpStreamInfoにNULLを指定した場合、ストリームデータ情報を取得せずに、発見されたストリームの数だけを取得することができます。 このパラメータの形式については、PSRSTREAMINFO形式を参照してください。
hIsCDに不正なハンドルが指定された場合、または、lpStreamInfoにNULL以外の値が指定され、iIndexが有効値でない場合-1が返ります。 それ以外の場合、発見されたストリームの数が返ります。
指定ファイルのストリームデータに関する情報を返します。
このファンクションは、PsxMCがこれから処理するストリームデータの情報を予め知っておきたい場合や、サポートの最終判定に使用されます。
BOOL PsrGetStrFileInfo( LPCTSTR lpStreamFile, // ストリームファイル名 LPPSRSTREAMINFO lpStreamInfo); // ストリームデータ情報
lpStreamFile情報を取得するストリームデータが格納されているファイルの名称を指定します。lpStreamInfoストリームデータ情報を取得するバッファのアドレスを指定します。 このパラメータの形式については、PSRSTREAMINFO形式を参照してください。
ファンクションの処理が成功した場合TRUEが返り、何らかのエラーが発生した場合FALSEが返ります。
CD-ROM中の指定ストリームデータに関する情報を返します。
このファンクションは、PsxMCがこれから処理するストリームデータの情報を予め知っておきたい場合に使用されます。
BOOL PsrGetStrDataInfo( INT iDriveNo, // ドライブ番号 DWORD dwBegin, // 開始セクタ番号 DWORD dwNumSector, // セクタ数 LPPSRSTREAMINFO lpStreamInfo); // ストリームデータ情報
iDriveNoCDACCESSライブラリで使用するCD-ROMドライブ番号を指定します。dwBeginストリームデータ情報を取得するストリームが格納されているCD-ROM中のセクタ番号を指定します。dwNumSectorストリームデータ情報を取得するストリームのセクタ数を指定します。lpStreamInfoストリームデータ情報を取得するバッファのアドレスを指定します。 このパラメータの形式については、PSRSTREAMINFO形式を参照してください。
ファンクションの処理が成功した場合TRUEが返り、何らかのエラーが発生した場合FALSEが返ります。
HANDLE PsrOpenFile( LPCTSTR lpStreamFile, // ストリームファイル名 LPPSRSTREAMINFO lpStreamInfo); // ストリームデータ情報
lpStreamFileオープンするストリームデータが格納されているファイルの名称を指定します。lpStreamInfoオープンするストリームデータの情報を指定します。 このパラメータの形式については、PSRSTREAMINFO形式を参照してください。
ストリームデータのオープンに成功すると、ストリームデータのハンドルが返ります。 失敗するとNULLが返ります。
HANDLE PsrOpenCD( INT iDriveNo, // ドライブ番号 LPPSRSTREAMINFO lpStreamInfo); // ストリームデータ情報
iDriveNoCDACCESSライブラリで使用するCD-ROMドライブ番号を指定します。lpStreamInfoオープンするストリームデータの情報を指定します。 このパラメータの形式については、PSRSTREAMINFO形式を参照してください。
ストリームデータのオープンに成功すると、ストリームデータのハンドルが返ります。 失敗するとNULLが返ります。
BOOL PsrClose( HANDLE hStream); // ストリームハンドル
hStreamPsrOpenFile関数または、PsrOpenCD関数により取得したストリームデータのハンドルを指定します。
ファンクションの処理が成功した場合TRUEが返り、何らかのエラーが発生した場合FALSEが返ります。
BOOL PsrRead( HANDLE hStream, // ストリームハンドル LPPSRREADBUFF lpBuffer); // 読み取りバッファ
hStreamPsrOpenFile関数または、PsrOpenCD関数により取得したストリームデータのハンドルを指定します。lpBuffer動画データまたは音声データを読み取るバッファのアドレスを指定します。 このパラメータの形式については、PSRREADBUFF形式を参照してください。
ファンクションの処理が成功した場合TRUEが返り、何らかのエラーが発生した場合FALSEが返ります。 (EOFの場合にもFALSEが返ります。)
BOOL PsrSeek( HANDLE hStream, // ストリームハンドル DWORD dwPosition); // 読み取り位置 1/1000秒
hStreamPsrOpenFile関数または、PsrOpenCD関数により取得したストリームデータのハンドルを指定します。dwPosition設定する読み取り位置をミリ秒単位で指定します。
ファンクションの処理が成功した場合TRUEが返り、何らかのエラーが発生した場合FALSEが返ります。
通常のSTRファイルとは異なる動画データをデコードします。
このファンクションとPsrDecodeBs関数Mが省略された場合、そのプラグインのPsrRead関数が読み取った動画データが通常のSTRファイルの形式であると認識します。
LPBITMAPINFO PsrDecodeFrame( LPPSRREADBUFF lpFrame, // フレームデータ LPBITMAPINFO lpbmi); // DIBビットマップ
lpFramePsrRead関数により読み取った動画データを指定します。 このパラメータの形式については、PSRREADBUFF形式を参照してください。lpbmiDIBビットマップデータを取得するバッファのアドレスを指定します。
ファンクションの処理が成功した場合、DIBビットマップのアドレスが返ります。 何らかのエラーが発生した場合は、PSR_DECODE_ERRORが返ります。 デコードをPsxMC本体または、PsrDecodeBs関数に任せたい場合は、PSR_DECODE_NORMALが返ります。
通常のSTRファイルとは異なる動画データをデコードします。 ただし、このファンクションはBSデコードのみを行い、MDECは本体に任せます。
このファンクションとPsrDecodeFrame関数Mが省略された場合、そのプラグインのPsrRead関数が読み取った動画データが通常のSTRファイルの形式であると認識します。
PUSHORT PsrDecodeBs( LPPSRREADBUFF lpFrame); // フレームデータ
lpFramePsrRead関数により読み取った動画データを指定します。 このパラメータの形式については、PSRREADBUFF形式を参照してください。
ファンクションの処理が成功した場合、BSデコード結果を格納したバッファのアドレスが返ります。 呼び出し元は、返されたバッファの内容を更新しません。また、このバッファの解放はプラグイン側で行います。 何らかのエラーが発生した場合は、PSR_DECODE_ERRORが返ります。 デコードをPsxMC本体に任せたい場合は、PSR_DECODE_NORMALが返ります。
通常のSTRファイルとは異なる音声データをデコードします。
このファンクションが省略された場合、そのプラグインのPsrRead関数が読み取った音声データが通常のSTRファイルの形式であると認識されます。
DWORD PsrDecodeAudio( LPPSRREADBUFF lpAudio, // 音声データ PVOID pvBuffer, // デコード後の音声データ DWORD nLength); // lpBufferのバイト数
lpAudioPsrRead関数により読み取った音声データを指定します。 このパラメータの形式については、PSRREADBUFF形式を参照してください。pvBufferデコード後の音声データを格納するバッファのアドレスを指定します。 pvBufferにNULLが指定された場合には、リターン値にpvBufferに必要なバイト数を返します。nLengthpvBufferにより指定したバッファのバイト数を指定します。 もし、pvBuffer≠NULLで、返却すべき音声データがnLengthで指定されたバイト数より長い場合にはエラーとなります。
ファンクションの処理が成功した場合、デコード後の音声データのバイト数が返ります。 何らかのエラーが発生した場合は、0(zero)が返ります。
当該プラグインに必要な環境設定を行うパネルを表示します。
このファンクションが省略された場合、そのプラグインに環境設定の必要がないと認識されます。
VOID PsrSetEnvironment( HWND hWndParent); // 親ウインドウ
hWndParent環境設定パネルの親となるウインドウのハンドルを指定します。
§6 プラグインで使用する形式 |
次にプラグインで使用する形式とその説明を示します。
typedef struct { CHAR aName[PSR_MAX_PLUGINNAME+1]; CHAR aCopyright[PSR_MAX_COPYRIGHT+1]; USHORT usVersion; USHORT usIsSupportVersion; USHORT usSystemVersion; CHAR aSiteName[PSR_MAX_SITENAME+1]; CHAR aSiteUrl[PSR_MAX_SITEURL+1]; } PSRPLUGIN, *LPPSRPLUGIN;
aNameプラグインを識別するための名称aCopyrightプラグインの著作権情報usVersionプラグインの版番号。usIsSupportVersion
1.10の場合、110を設定します。CDサポート判定結果を保証するプラグインの版番号。usSystemVersion
ファイル用のプラグインの場合、この値は無視されます。
1.00の場合、100を設定します。0を指定すると、すべてのバージョンの CDサポート判定結果を保証することを示します。対応するPsxMCシステムのバージョン。aSiteName
PSR_SYSTEMVERSION固定当該プラグインを公開しているサイトの名前を設定します。aSiteUrl
aSiteNameの設定は省略が可能です。 PsxMC 2.30T以降で、aSiteUrlを設定すると、 ユーザに対してプラグインの入手先リンクにサイト名を表示させることができます。 aSiteNameとaSiteUrlの設定を省略した場合、プラグインの入手先リンクが表示されません。 aSiteNameのみを省略した場合、入手先リンクにaSiteUrlが表示されます。当該プラグインを公開しているサイトのURLを設定します。
aSiteUrlの設定は省略が可能です。 PsxMC 2.30T以降で、aSiteUrlを設定すると、 ユーザに対してプラグインの入手先リンクにサイト名を表示させることができます。 aSiteUrlの設定を省略した場合、プラグインの入手先リンクが表示されません。
typedef struct { WORD wTypeFlags; // データ種別フラグ WORD wReserved; // 予備 DWORD nBeginSector; // 開始セクタ番号 DWORD nNumSector; // セクタ数 DWORD nPlayTime; // 再生時間 DWORD nNumFrame; // フレーム数 SIZE szFrame; // フレームサイズ WORD wFrameRate; // フレームレート WORD wFormatTag; // 音声データのフォーマット WORD wChannels; // モノラル/ステレオの別 WORD wBitsPerSample; // サンプル当たりのビット数 DWORD nSamplesPerSec; // サンプリングレート DWORD nDataSize; // データサイズ } PSRSTREAMINFO, *LPPSRSTREAMINFO;
wTypeFlags当該ストリームデータの種別を表すフラグ値wReserved
値 意味 PSR_STRTYPE_MOVIE 動画ストリームを含む PSR_STRTYPE_AUDIO 音声ストリームを含む PSR_STRTYPE_ALL 動画ストリームと音声ストリームを含む PSR_STRTYPE_VFRATE 可変フレームレートの動画ストリーム 予備nBeginSector当該ストリームが開始されるセクタの番号nNumSector
ストリームファイルの場合は0(zero)当該ストリームのセクタ数nPlayTime
ストリームファイルの場合は0(zero)全データを再生する所要時間nNumFrame
1/1000秒単位ストリームデータ中のフレームの数szFrame
音声データのみ場合は0(zero)先頭フレームのXとYのピクセル数wFrameRate
音声データのみ場合は0(zero)1秒当たりに再生されるフレームの数×10wFormatTag
音声データのみ場合は0(zero)デコード後の音声データのフォーマットwChannels
通常は、WAVE_FORMAT_PCM1:モノラル 2:ステレオ 0:音声データなしwBitsPreSampleサンプル当たりのビット数nSamplesPerSec
映像データのみ場合は0(zero)サンプリングレート (Hz)nDataSize
映像データのみ場合は0(zero)当該ストリームデータのサイズをバイト単位で設定します。
nDataSizeは、変換や再生に使用される数値ではなく、単にデータサイズの目安として表示するものです。 よって、nDataSizeは正確な数値を要求するものではありません。設定の省略も可能です。 nDataSizeの設定を省略した場合、ユーザに対して表示するデータサイズに「不明」と表示されます。
typedef struct { DWORD nFrameNo; // フレーム番号 SIZE szFrame; // フレームサイズ WORD wFrameRate; // フレームレート WORD wReserved; // 予備 DWORD nLength; // データ長 BYTE abData[PIO_FRAMEBUFFER]; // データ } PIOREADBUFF, *LPPIOREADBUFF;
nFrameNoフレーム番号。 ただし格納データが音声データの場合は0(zero)が設定されます。szFrameフレームのXとYのピクセル数。ただし格納データが音声データの場合は何も設定されません。wFrameRate可変フレームレートのデータの場合、当該フレームのフレームレートが設定されます。 固定フレームレートの場合は 0(zero)が設定されます。wReserved0が設定されます。nLengthabDataに格納されているデータのバイト数abData動画データまたは、音声データ
§7 変更履歴 |
2000/01/28 | PIOWM_XX_BEGINのnAllLengthは、特に長い処理でない場合には0(zero)が通知されるようにした。 |
2000/01/28 | PioQueryPlugin()の取得バッファのアドレスはpszBufferに変更 |
2000/01/28 | ストリームを指定する部分は、開始位置だけでなく長さも指定するよに変更。 |
2000/01/28 | PioDecodeFrame()とPioDecodeAudio()にストリームハンドルを追加 |
2000/01/28 | PioOpenでオープンフラグを指定するようにした。 |
2000/01/28 | 定数PIO_MAX_PLUGIN_DATAを追加 |
2000/01/28 | PioQueryStreamInfo()は、コールバックを必要としないファンクションに変更! |
2000/01/28 | PioQueryStreamInfo()の取得項目を指定するフラグは不要なので削除! |
2000/01/28 | PioSeek()は必須にしました。 |
2000/01/28 | PioSeek()に指定する単位は、フレーム番号ではなく1/1000秒にする。 |
2000/01/28 | 構造体PIOSTREAMINFOにメンバー追加 |
2000/02/02 | PioIsSupport()のリターン値を変更 |
2000/02/02 | PIOFIND構造体にachPluginを追加 |
2000/02/05 | PioOpen()のオープンフラグを削除(すいません、必要なくなってしまったのです…) |
2000/02/14 | PIOSTREAMINFO構造体に、nPlayTimeを追加 |
2000/02/14 | プラグインのファイル名規則を明記 |
2000/06/21 | 全面修正 |
2000/06/30 | PsrIsSupportCDSector()の引数にtocを追加 |
2000/06/30 | PsrIsSupportCDSector()がFALSEを返した場合は、そのトラックのみをスキップするようにした。 |
2000/06/30 | PSRSTREAMINFO構造体のwSectPerFrameを削除して、wReservedとした。 |
2000/07/18 | PSRPLUGIN構造体を変更した。 |
2000/07/21 | データ種別フラグにPSR_STRTYPE_VFRATEを追加 |
2000/07/21 | PSRREADBUFF構造体にwFrameRateとwReservedを追加 |
2000/08/08 | PsrDecodeBs関数を追加 |
2000/08/08 | PsrDecodeFrame関数とPsrDecodeAudio関数のリターン値の説明を変更 |
2000/08/08 | PsrDecodeFrame関数とPsrDecodeAudio関数の引数(hStream)を削除 |
2000/09/16 | 「§6 プラグインで使用するウインドウメッセージ」を削除 |
2000/09/16 | PsrGetOutputStreamInfo関数とPsrOutputStreamFile関数を削除 |
2000/10/31 | PSRPLUGIN構造体にaSiteNameとaSizeUrlを追加 |
2000/10/31 | PSRSTREAMINFO構造体にnDataSizeを追加 |