HSP ver2 (Hot Soup Processor) DLL Development Manual

HSP : Hot Soup Processor ver2.61 / onion software 1997-2004(c)

HSPからのDLL呼び出し方法リファレンスマニュアル

はじめに

HSP拡張プラグインの規定

HSPから呼び出して使用するためのDLLプログラムを、「HSP拡張プラグイン」と呼びHSPを拡張する方法として提供することができます。

「HSP拡張プラグイン」を作る上での制約は特にありません。あなたが、個人的な用途で作る場合も、配布や販売を目的とした場合であっても HSPの作者(ONION software)に無断で運用してかまいません。
ただし、「HSP拡張プラグイン」を使用して起こった不具合やトラブルなどの責任はHSP作者(ONION software)は負いかねます。

「HSP拡張プラグイン」を配布する場合は、HSPに対応した拡張プラグインである旨をドキュメント等に明記して、なるべくHSP本体の入手先(

「Hot Soup Processor Page」

「ONION software HOMEPAGE」

以前のバージョンからの変更点

サンプルプログラムについて

HSPSDK/SAMPLE ディレクトリ

HSPがサポートするファイルシステムや、各種グラフィック設定の補助となる関数をまとめた、HSPサポートルーチンズ(HSPSDK)が収められています。 Cによるソースと、Visual C++プロジェクトファイル、サンプルスクリプトが含まれています。これにより、HSPとの連携がより便利になります。詳しくは、ソースリスト(hspsdk.cpp) の中にコメントの形で解説されているので参考にしてみてください。
HSPSDK/LIB ディレクトリ

HSP拡張ランタイムを作成するためのlibファイルが収録されています。 HSP拡張ランタイムについての詳細は、「hsp2lib.htm」をお読みください。

DLL呼び出しの概要

命令の詳細


	#uselib "filename"			外部DLLの指定

	#func 新規名称  関数名  タイプ		外部DLL呼び出し命令登録

	新規命令 p1,p2,p3,p4

	(p1～p3までのパラメータ)

	  タイプ0 : 新規命令 p1,p2,p3,p4
	    ( p1=int, p2=int, p3=int )

	  タイプ1 : 新規命令 p1,p2,p3,p4
	    ( p1=変数バッファへのポインタ, p2=int, p3=int )

	  タイプ2 : 新規命令 p2,p3,p4
	    ( p1=BMSCR構造体へのポインタ, p2=int, p3=int )

	  タイプ3 : 新規命令 p1,p2,p3,p4
	    ( p1=変数情報PVAL構造体へのポインタ, p2=int, p3=int )

	  タイプ4 : 新規命令 p2,p3,p4
	    ( p1=int, p2=str, p3=int )

	  タイプ5 : 新規命令 p1,p2,p3,p4
	    ( p1=変数バッファへのポインタ, p2=str, p3=int )

	  タイプ6 : 新規命令 p2,p3,p4
	    ( p1=BMSCR構造体へのポインタ, p2=str, p3=int )

	  タイプ7 : 新規命令 p1,p2,p3,p4
	    ( p1=変数情報PVAL構造体へのポインタ, p2=str, p3=int )

	  タイプ$83 : 新規命令 p1,p2,p3,p4
	    ( p1=変数情報PVAL2構造体へのポインタ, p2=int, p3=int )

	  タイプ$87 : 新規命令 p1,p2,p3,p4
	    ( p1=変数情報PVAL構造体へのポインタ, p2=str, p3=int )


	(p4のパラメータ)

	  各タイプ+$00 : p4=int
	  各タイプ+$10 : p4=システム変数refstrへのポインタ
	  各タイプ+$20 : p4=ファイルハンドルdpminfoへのポインタ
	  各タイプ+$30 : p4=パレットデータrgbptrへのポインタ


	(その他)

	  $202 : HSPEXINFOタイプ関数 (Ver2.6以降専用)
	    ( p1=HSPEXINFO構造体へのポインタ )

	  各タイプ+$100 : HSP終了時に自動的に呼び出される関数
	                  (クリーンアップ関数)の指定

DLLの作成 ( Microsoft Visual C++ 6.0以降の場合 )

１．Visual C++で 新規作成 -> Win32 Dynamic-Link Library を選択、
    新しいプロジェクトを作成します。
２．CまたはC++のソースファイルを作成して、プロジェクトに追加します。
３．HSPのDLLを作るためのヘッダファイル「hspdll.h」をインクルードして
    ください。
４．タイプに応じた関数を作成して、その関数をEXPORTマクロでエクスポート
    関数に指定します。
５．コンパイルしてDLLを作成します。
６．HSPで呼び出すための、#uselibと#funcを記述したテスト用のスクリプト
    を作成して、呼び出せるかどうか確認してみる。
７．うまくいったら、あとはデバッグして完成。

DLLの作成 ( Borland C++ Builder 1.0の場合 )

１．新規作成でDLL(ダイナミックリンクライブラリ)を選択、
    新しいプロジェクトを作成します。
２．CまたはC++のソースファイルを作成して、プロジェクトに追加します。
３．HSPのDLLを作るためのヘッダファイル「hspdll.h」をインクルードして
    ください。
４. DLL関数のエクスポート名を定義するための定義ファイル(DEFファイル)を
    作成してください。
５．定義ファイル(DEFファイル)をプロジェクトに追加します。
６．タイプに応じた関数を作成して、その関数をEXPORTマクロでエクスポート
    関数に指定します。(VC++での作成方法と同じです)
７．コンパイルしてDLLを作成します。
８．HSPで呼び出すための、#uselibと#funcを記述したテスト用のスクリプト
    を作成して、呼び出せるかどうか確認してみる。
９．うまくいったら、あとはデバッグして完成。

EXPORTS
_testfunc@16=testfunc

１．VCLを使わない時は、makファイル内のALLLIB行にあるvcl.lib を削除、
    そしてcp32mt.lib を cw32mt.libに変更する。
    さらに、最初にインクルード指定されている「#include 」
    を削除し、かわりに「#include 」を記述する。
２．C++ Builder 3.0の場合は２．のmakファイルがbprファイルになっている
    ので注意が必要です。また、bprファイル内のALLOBJ行にある、
    「sysinit.obj も削除してください。
３．マルチスレッドを使用しない場合は、リンクするライブラリをcw32mt.lib
    ではなくcw32.libにすることで、さらに少しサイズの節約ができます。
４．最終コンパイル時は、プロジェクトオプションのスピードを「リリース」
    のモードにしておく。

各タイプに応じた関数の作成

	EXPORT BOOL WINAPI test ( int p1, int p2, int p3, int p4 )
	{
	//  start
	//   :
	//  end
	return 0;
	}

タイプ0 : 新規命令 p1,p2,p3,p4
    ( p1=int, p2=int, p3=int, p4=int )
    [ test( int p1, int p2, int p3, int p4 ); ]

タイプ1 : 新規命令 p1,p2,p3,p4
    ( p1=変数バッファへのポインタ, p2=int, p3=int, p4=int )
    [ test( void *p1, int p2, int p3, int p4 ); ]

タイプ2 : 新規命令 p2,p3,p4
    ( p1=BMSCR構造体へのポインタ, p2=int, p3=int, p4=int )
    [ test( BMSCR *p1, int p2, int p3, int p4 ); ]

タイプ3 : 新規命令 p1,p2,p3,p4
    ( p1=変数のPVAL構造体へのポインタ, p2=int, p3=int, p4=int )
    [ test( PVAL *p1, int p2, int p3, int p4 ); ]

タイプ$83 : 新規命令 p1,p2,p3,p4
    ( p1=変数情報PVAL2構造体へのポインタ, p2=int, p3=int )
    [ test( PVAL2 *p1, int p2, int p3, int p4 ); ]

タイプ4 : 新規命令 p1,p2,p3,p4
    ( p1=int, p2=str, p3=int, p4=int )
    [ test( int p1, char *p2, int p3, int p4 ); ]

タイプ5 : 新規命令 p1,p2,p3,p4
    ( p1=変数バッファへのポインタ, p2=str, p3=int, p4=int )
    [ test( void *p1, char *p2, int p3, int p4 ); ]

タイプ6 : 新規命令 p2,p3,p4
    ( p1=BMSCR構造体へのポインタ, p2=str, p3=int, p4=int )
    [ test( BMSCR *p1, char *p2, int p3, int p4 ); ]

タイプ7 : 新規命令 p1,p2,p3,p4
    ( p1=変数のPVAL構造体へのポインタ, p2=str, p3=int, p4=int )
    [ test( PVAL *p1, char *p2, int p3, int p4 ); ]

タイプ$87 : 新規命令 p1,p2,p3,p4
    ( p1=変数情報PVAL2構造体へのポインタ, p2=str, p3=int )
    [ test( PVAL2 *p1, char *p2, int p3, int p4 ); ]

タイプ+$10
    ( p1=??, p2=??, p3=??, p4=refstr )
    [ test( … , char *p4 ); ]

タイプ+$20
    ( p1=??, p2=??, p3=??, p4=dpminfo )
    [ test( … , char *p4 ); ]

タイプ+$30
    ( p1=??, p2=??, p3=??, p4=rgbptr )
    [ test( … , char *p4 ); ]

タイプ+$100

タイプ$202

typedef struct HSPEXINFO
{
	//		HSP internal info data (2.6)
	//
	short ver;		// Version Code
	short min;		// Minor Version
	//
	int *er;		// Parameter Error Flag
	char *pstr;		// String Buffer (master)
	char *stmp;		// String Buffer (sub)
	PVAL2 **pval;	// Master PVAL ptr.
	//
	int *actscr;	// Active Window ID
	int *nptype;	// Next Parameter Type
	int *npval;		// Next Parameter Value
	int *strsize;	// StrSize Buffer
	char *refstr;	// RefStr Buffer
	//
	int (*HspFunc_prm_getv)( void );
	int (*HspFunc_prm_geti)( void );
	int (*HspFunc_prm_getdi)( int defval );
	char *(*HspFunc_prm_gets)( void );
	char *(*HspFunc_prm_getds)( char *defstr );
	int (*HspFunc_val_realloc)( PVAL2 *pv, int size, int mode );
	int (*HspFunc_fread)( char *fname, void *readmem, int rlen, int seekofs );
	int (*HspFunc_fsize)( char *fname );
	void *(*HspFunc_getbmscr)( int wid );
	int (*HspFunc_getobj)( int wid, int id, HSPOBJINFO *inf );
	int (*HspFunc_setobj)( int wid, int id, HSPOBJINFO *inf );
	//
} HSPEXINFO;

EXPORT BOOL WINAPI test( HSPEXINFO *hei, int p1, int p2, int p3 )
{
	//	DLL test (type$202)
	int ep1,ep2,ep3;
	ep2 = hei->HspFunc_prm_getdi(0);		// パラメータ1:数値
	ep3 = hei->HspFunc_prm_getdi(0);		// パラメータ2:数値
	ep4 = hei->HspFunc_prm_getdi(0);		// パラメータ3:数値
	if ( *hei->er ) return *hei->er;		// エラーチェック
	return 0;
}

EXPORT BOOL WINAPI test( HSPEXINFO *hei, int p1, int p2, int p3 )
{
	//	DLL test (type$202)
	PVAL2 *pval;
	char *ep1;
	char *ep2;
	ep1 = (char *)hei->HspFunc_prm_getv();	// パラメータ1:変数
	pval = *hei->pval;			// 変数のPVAL2ポインタを取得
	ep2 = hei->HspFunc_prm_gets();		// パラメータ2:文字列
	if ( *hei->er ) return *hei->er;	// エラーチェック
	return 0;
}

	short ver;		// Version Code

	short min;		// Minor Version

	int *er;		// Parameter Error Flag

	char *pstr;		// String Buffer (master)

	char *stmp;		// String Buffer (sub)

	PVAL2 **pval;	// Master PVAL ptr.

	int *actscr;	// Active Window ID

	int *nptype;	// Next Parameter Type

	int *npval;		// Next Parameter Value

	int *strsize;	// StrSize Buffer

	char *refstr;	// RefStr Buffer

	int (*HspFunc_prm_getv)( void );

	int (*HspFunc_prm_geti)( void );

	int (*HspFunc_prm_getdi)( int defval );

	char *(*HspFunc_prm_gets)( void );

	char *(*HspFunc_prm_getds)( char *defstr );

	int (*HspFunc_val_realloc)( PVAL2 *pv, int size, int mode );

	int (*HspFunc_fread)( char *fname, void *readmem, int rlen, int seekofs );

	int (*HspFunc_fsize)( char *fname );

	void *(*HspFunc_getbmscr)( int wid );

	int (*HspFunc_getobj)( int wid, int id, HSPOBJINFO *inf );

	int (*HspFunc_setobj)( int wid, int id, HSPOBJINFO *inf );

戻り値の設定について

戻り値	行なわれる処理
0	正常終了
-1以下	システム変数statに戻り値を代入して終了
1～255	エラーを表示して停止
0x10000～0x1ffff	終了後awaitを実行
0x20000～0x3ffff	終了後waitを実行

戻り値に、1～255の値を返すとその値をエラーコードとしてエラーが出力されます。

戻り値に、-1以下の負の値を返すとその値はシステム変数statの値として取り出され、正常終了されます。

関数を作成する上での注意点

プラグイン互換性について

PVAL2構造体を使用する(PVAL構造体を使用しない)
BMSCR構造体は、flagからcolorまでのメンバのみ参照する
オブジェクトの参照、設定は、HspFunc_getobj、HspFunc_setobjを使用する

PVAL構造体の詳細

	呼び出しタイプ3,7     = PVAL構造体 ( ver2.4g以降で使用できるもの )
	呼び出しタイプ$83,$87 = PVAL2構造体 ( ver2.5以降で使用できるもの )

typedef struct PVAL2
{
	//		Memory Val structure (ver2.5 Type)
	//
	short	flag;				// type of val
	short	mode;				// mode (0=normal/1=clone/2=alloced)
	int	len[5];				// length of array 4byte align (dim)
	int	size;				// size of Val (not used)
	char	*pt;				// (direct val) or (ptr to array)
} PVAL2;

typedef struct PVAL
{
	//		Memory Val structure (Old Type)
	//
	short	flag;				// type of val
	short	mode;				// mode (0=normal/1=clone/2=alloced)
	short	len[5];				// length of array 4byte align (dim)
	short	version;			// version check code (2.4 = 0)
	char	*pt;				// (direct val) or (ptr to array)
	PVAL2	*realptr;			// real ptr to ver2.5 PVAL
} PVAL;

	short	flag;		// type of val (2=str/4=num)

	short	mode;		// mode (0=normal/1=clone/2=alloced)

	int	len[5];		// length of array 4byte align (dim)

	char	*pt;		// ptr to Val

	int	size;				// size of Val (not used)

	short	version;			// version check code (2.4 = 0)
	PVAL2	*realptr;			// real ptr to ver2.5 PVAL

BMSCR構造体の詳細

#define objkazz 64
typedef struct BMSCR
{
	//		Bitmap buffer structure
	//
	int		flag;			// used flag
	int		sx;			// X-size
	int		sy;			// Y-size
	int		palmode;		// palmode
	HDC		hdc;			// buffer HDC
	BYTE	*pBit;				// bitmap pointer
	BITMAPINFOHEADER *pbi;			// infoheader
	HBITMAP	dib;				// bitmap handle(DIB)
	HBITMAP	old;				// bitmap handle(OLD)
	RGBQUAD *pal;				// palette table
	HPALETTE hpal;				// palette handle
	HPALETTE holdpal;			// palette handle (old)
	int		pals;			// palette entries
	HWND	hwnd;				// window handle
	HANDLE	hInst;				// Instance of program
	int		infsize;		// *pbi alloc memory size
	int		bmpsize;		// *pBit alloc memory size

	//		Window object setting
	//
	int		type;			// setting type
	int		wid;			// window ID
	short	fl_dispw;			// display window flag
	short	fl_udraw;			// update draw window
	int		wx,wy,wchg;		// actual window size x,y
	int		xx,yy;			// buffer view point x,y
	int		lx,ly;			// buffer view size x,y
	int		cx,cy;			// object cursor x,y
	int		ox,oy,py;		// object size x,y,py
	int		texty;			// text Y-axis size
	int		gx,gy,gmode;		// gcopy size

	HBRUSH	hbr;				// BRUSH handle
	HPEN	hpn;				// PEN handle
	HFONT	hfont;				// FONT handle
	HFONT	holdfon;			// FONT handle (old)
	COLORREF color;				// text color code

	HANDLE	hCld[objkazz];			// buttonのhandle
	int		owid[objkazz];		// buttonのjump ID
	int		owb;			// handleのindex

	int		textspeed;		// slow text speed
	int		cx2,cy2;		// slow text cursor x,y
	int		tex,tey;		// slow text limit x,y
	char	*prtmes;			// slow message ptr

	//		Enhanced in ver2.4
	//
	int		focflg;				// focus set flag

	//		Enhanced in ver2.5
	//
	int		objmode;			// object set mode
	LOGFONT	logfont;			// logical font

	//		Enhanced in ver2.6
	//
	int		style;				// extra window style
	int		gfrate;				// halftone copy rate
	int		tabmove;			// object TAB move mode
	int		sx2;				// actual bitmap X size
	SIZE	printsize;			// print,mes extent size
	char	*owpval[objkazz];	// objectのPVAL Ptr.
	char	owts[objkazz];		// objectのTAB stop flag
} BMSCR;

	int		flag;			// used flag

	int		sx;			// X-size
	int		sy;			// Y-size
	int		palmode;		// palmode

	HDC		hdc;			// buffer HDC

	BYTE	*pBit;				// bitmap pointer

	BITMAPINFOHEADER *pbi;		// infoheader
	HBITMAP	dib;				// bitmap handle(DIB)
	HBITMAP	old;				// bitmap handle(OLD)

	RGBQUAD *pal;				// palette table
	HPALETTE hpal;				// palette handle
	HPALETTE holdpal;			// palette handle (old)
	int		pals;			// palette entries

	HWND	hwnd;				// window handle

	HANDLE	hInst;				// Instance of program

	int		infsize;		// *pbi alloc memory size
	int		bmpsize;		// *pBit alloc memory size

	int		type;			// setting type

		type : 1=off screen buffer
		   	2=background image (full size)
			3=hsp main window (fixed size)
			4=normal window (fixed size)
			5=picture window (flex size)
			6=special window (stretch)
			7=screen saver preview window

	int		wid;			// window ID

	short	fl_dispw;			// display window flag
	short	fl_udraw;			// update draw window

	int		wx,wy,wchg;		// actual window size x,y
	int		xx,yy;			// buffer view point x,y
	int		lx,ly;			// buffer view size x,y

	int		cx,cy;			// object cursor x,y

	int		ox,oy,py;		// object size x,y,py

	int		texty;			// text Y-axis size

	int		gx,gy,gmode;		// gcopy size

	HBRUSH	hbr;				// BRUSH handle
	HPEN	hpn;				// PEN handle

	HFONT	hfont;				// FONT handle
	HFONT	holdfon;			// FONT handle (old)

	COLORREF color;			// text color code

	HANDLE	hCld[objkazz];			// buttonのhandle
	int		owid[objkazz];		// buttonのjump ID
	int		owb;			// handleのindex

	int		textspeed;		// slow text speed

	int		cx2,cy2;		// slow text cursor x,y
	int		tex,tey;		// slow text limit x,y
	char	*prtmes;			// slow message ptr

	//		Enhanced in ver2.4
	//
	int		focflg;				// focus set flag

	//		Enhanced in ver2.5
	//
	int		objmode;			// object set mode
	LOGFONT	logfont;			// logical font

	//		Enhanced in ver2.6
	//
	int		style;				// extra window style
	int		gfrate;				// halftone copy rate
	int		tabmove;			// object TAB move mode
	int		sx2;				// actual bitmap X size
	SIZE	printsize;			// print,mes extent size
	char	*owpval[objkazz];	// objectのPVAL Ptr.
	char	owts[objkazz];		// objectのTAB stop flag

ビットマップ画面への直接書き込み

１．画面とメモリアドレスの対応が上下逆になっています

２．画面の範囲外にあたるメモリに書き込むと一般保護違反が出て止まります

	  (パレットモード(256色)時)

	      x = X座標;
	      y = Y座標;
	      width = (sx+3)&~3;
	      vram_adr = pBit + ( ( sy - 1 - y ) * width ) + x;

	  (フルカラーモード(1670万色)時)

	      x = X座標;
	      y = Y座標;
	      width = ((sx*3)+3)&~3;
	      vram_adr = pBit + ( ( sy - 1 - y ) * width ) + ( x * 3 );

３．ビットマップを書き換えた後は、実際の画面の更新をする必要があります

[一番上に戻る]
Go to ONION software HOMEPAGE