→HSP2.6:付属文書に戻る

拡張ランタイム作成リファレンスマニュアル ver0.3

はじめに

このテキストは、Hot Soup Processor ver2.5以降で使用するための拡張ランタイムプログラム(HSP Extended Runtime)作成についての解説をしているものです。拡張ランタイムは、HSPを拡張するための高度な方法です。通常の使用では、まったく理解する必要はありません。より高度にHSPを使用したいという方のための手段ですので、わからない方は読まなくてもOKです。このテキストは、Cまたは、C++言語についての知識がある方、HSPプラグイン(DLL) 作成方法もわかっている方を対象にしています。

HSP拡張ランタイムの規定

HSPから呼び出して使用するためのDLLプログラムを、「HSP拡張プラグイン」と呼びHSPを拡張する方法として提供することができます。このDLLプログラムをHSP本体に埋め込み、実行ファイルがDLLを必要としないものを作成できるようにしたものが「HSP拡張ランタイム」です。

「HSP拡張ランタイム」は、「HSP拡張プラグイン」とともに作成することが可能です。「HSP拡張プラグイン」のソースプログラムがなければ、作成することはできません。

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

「HSP拡張ランタイム」を配布する場合は、HSPに対応した拡張ランタイムである旨をドキュメント等に明記して、 HSP本体の入手先(「Hot Soup Processor Page」または、「ONION software HOMEPAGE」) を併記してもらえると嬉しいです。「HSP拡張ランタイム」の拡張子は、「HRT」を使用してください。

拡張ランタイムの概要

「拡張ランタイム」には、あらかじめHSP本体の機能と、DLLの機能がスタティックにリンクされ、 DLLをロードする必要がないように作られています。このランタイムを使用したスクリプトは、DLLがある時と同じように実行することが可能です。「拡張ランタイム」は、「拡張プラグイン(DLL)」でできることすべてをランタイムに内包することができます。逆に言えば、今のところは「拡張プラグイン (DLL)」でできることしかできません。「拡張ランタイム」では、スクリプトが必要としているDLLと同じ機能を内包している場合は、それを使用して、それ以外のDLLは通常と同じく外部からリンクするように動作します。ユーザーにとっては、DLLがないと使用できなかった命令が、本体のみで使用できるのと同じような感覚になるでしょう。「拡張ランタイム」には、いくつものDLLが持つ機能を同時に内包させることができます。ただし、複数のランタイムを同時にリンクすることはできません。つまり、他の人が作った拡張ランタイムに自分の機能を付加するような使い方はできません。

このテキストでは、DLLを作成するためのツールは、基本的にMicrosoft Visual C++ (6.0以降)を対象にして解説をしています。 LCC-win32、Borland C++、C++ Builderでのランタイム作成については、今のところ不明ですが、不可能ではないと思います。

SDKとサンプルについて

拡張ランタイムの作成には、libディレクトリの「hsp2lib.h」「hsp2lib.lib」を使用してください。「hsp2lib.lib」は、Microsoft Visual C++で使用することができるライブラリファイルです。拡張ランタイム作成のサンプルが、sample.lzhアーカイブに収録されています。

ランタイムの作成 ( Microsoft Visual C++ 6.0以降の場合 )

呼び出されるDLLを作成するには、おおまかに以下の手順で行ないます。

Visual C++で新規作成 -> Win32 Application を選択、新しいプロジェクトを作成します。
HSPのDLLを作るために使用したCまたはC++のソースファイルをプロジェクトに追加します。
DllMain関数を、「DLL名_DllMain」に変更する。
HSPランタイムで必要になる情報を記述したヘッダファイル(.h)を作成してください。
拡張ランタイムのメイン(main.cpp)を作成する。
HSPライブラリ(hsp2lib.lib)をプロジェクトに追加します。
リソーススクリプト(hsp2.rc)、およびアイコンリソース(hsp2.ico)をプロジェクトに追加します。
スタティックリンクするためのライブラリ設定を行ないます。少なくとも、hsp2lib.libのためにwinmm.libが必要になります。
コンパイルして実行ファイルを作成します。
うまくいったら、拡張子をhrtにして実際に拡張ランタイムを使った実行ファイルを作成してテストを行なってみてください。

リソースは、必ずしも付属の「hsp2.rc」である必要はありません。アイコンデータも含めてリソースデータは作成者が自由に設定してかまいません。
配布される拡張ランタイムは、必ずrelease設定のビルドを行なってデバッグ情報が含まれないモジュールファイルで使用してください。
ビルド時の設定は、拡張ランタイムの作成者が設定してください。

拡張ランタイムのためのヘッダファイル作成

以下のような形式でDLLプログラムの情報を記述したヘッダファイルを作成してください。 (以下はsampleにあるgrv.dllのためのヘッダファイルです)

/*
        拡張ランタイムのためのヘッダ
*/

#define grv_Ver 0x0000          //  拡張ランタイムのバージョン(0x0000)
#define grv_Name "grv.dll"      //  DLLのファイル名(小文字で拡張子も含めること)

/*
        DllMain関数の宣言をする
        (DllMainを「DLL名_DllMain」に変更したもの)
*/
int WINAPI grv_DllMain(HINSTANCE hInst, DWORD dwReason, LPVOID lpvReserved);

extern "C" {
        /*
                DLLで使用されている関数のプロトタイプ宣言をする
                (Cの形式でexternする)
        */
        BOOL WINAPI grv_ini(int,int,int,int);
        BOOL WINAPI grv_work(int,int,int,int);
        BOOL WINAPI grv_offset(int,int,int,int);
        BOOL WINAPI grv_hcopy(int,int,int,int);
        BOOL WINAPI grv_copy(int,int,int,int);
        BOOL WINAPI grv_cls(int,int,int,int);
        BOOL WINAPI grv_cput(int,int,int,int);
        BOOL WINAPI grv_prt(int,int,int,int);
        BOOL WINAPI grv_spput(int,int,int,int);
        BOOL WINAPI grv_spexe(int,int,int,int);
}

static  char *grv_hspfnc[] = {

        /*
                HSPのスクリプトで定義されている命令の名前(小文字)と
                それに対応する関数を指定する。
                「"HSP定義命令名", (char *)DLL関数名,」
                のように指定してください。
                「NULL, NULL」が最後の行になります。
        */
        "grv_ini", (char *)grv_ini,
        "grv_work", (char *)grv_work,
        "grv_offset", (char *)grv_offset,
        "grv_hcopy", (char *)grv_hcopy,
        "grv_copy", (char *)grv_copy,
        "grv_cls", (char *)grv_cls,
        "grv_cput", (char *)grv_cput,
        "grv_prt", (char *)grv_prt,
        "grv_spput", (char *)grv_spput,
        "grv_spexe", (char *)grv_spexe,

        NULL, NULL
};

拡張ランタイムのためのmain.cpp作成

以下のような形式でメインプログラムを作成してください。 (以下はsampleにあるgrv.dllのためのmain.cppファイルです)

/*--------------------------------------------------------
        HSP enhanced runtime source
  --------------------------------------------------------*/

#include &ltwindows.h>
#include &ltstdio.h>
#include &ltstring.h>

#include "hspdll.h"             //  必ずincludeしてください
#include "hsp2lib.h"            //  必ずincludeしてください

/*
  拡張ランタイムのためのヘッダをinclude
*/
#include "grv.h"

/*
  拡張ランタイムのためのメインプログラム
*/
int APIENTRY WinMain ( HINSTANCE hInstance,
                                           HINSTANCE hPrevInstance,
                                           LPSTR lpCmdParam,
                                           int iCmdShow )
{
        int stat;
        HSPCMD_INFO info;

        info.ver = grv_Ver;             /* ヘッダで定義したもの */
        info.hspfnc = grv_hspfnc;       /* ヘッダで定義したもの */
        strcpy( info.name, grv_Name );  /* ヘッダで定義したもの */
        HSPSetFunc( &info );            /* DLL関数を登録する */

        /* DLL初期化関数を呼び出す */
        grv_DllMain( hInstance, DLL_PROCESS_ATTACH, NULL );

        /* HSPメイン部分を呼び出し */
        stat = HSPWinMain( hInstance, hPrevInstance, lpCmdParam, iCmdShow );

        /* DLL終了関数を呼び出す */
        grv_DllMain( hInstance, DLL_PROCESS_DETACH, NULL );

        return stat;
}

HSPSetFunc関数でDLL関数を最初に登録します。複数のDLLを登録するには、その回数だけHSPSetFunc関数を呼び出して下さい。また、初期化と終了処理のため、 DllMainをメインから呼び出す必要があります。これも、登録したDLLの個数だけ行なって下さい。

JPEG読み込み機能削除版ランタイム作成について

ライブラリファイル「hsp2lib.lib」の替わりに「hsp2clib.lib」をリンクすることで、 JPEG読み込み機能を持たないHSPランタイムになります。 JPEG読み込み機能が必要ない場合に、ランタイムサイズ削減することが可能です。「hsp2clib.lib」は、Microsoft Visual C++で使用することができるライブラリファイルです。

リリースノート(ver0.2)

拡張ランタイム最初のリリースとなります。拡張ランタイムを使うことで、実質上はいままでと大きく変わることはありません。メリットはただ1つ、DLLなしで動作するEXEファイルが作成できるということです。しかし、この方法には弱点もあります。DLLごとにランタイムを作成しなければならないという点です。つまり、任意のDLLだけを選んで内包するわけにはいかないということになります。色々な部分でまだ改良の余地がありますが、ユーザーの方や、 HSPプラグインを作成しているユーザーの方たちに受け入れてもらえると嬉しいです。作成にあたり、tomさんにご協力いただきました。その他、ご意見やテストをしていただいたユーザーの方々に感謝致します。

おにたま

HSP2.6:hsp2lib