HSP : HSP3Dish / onion software 2023(c)

# HSP3Dish プログラミングマニュアル

1. HSP3Dishとは
2. HSP3Dishの使用方法
3. HSP3との差異
4. 配置オブジェクトについて（New!）
5. 標準スプライトについて（New!）
6. スクリーンサイズ変更について（New!）
7. viewcalc命令による座標変換について（New!）
8. celbitmap命令による画像データ制御について（New!）
9. gmode命令について
10. gmulcolor命令について
11. gfilter命令について
12. setreq、getreq命令について（New!）
13. マルチタッチ情報の取得について
14. サウンド機能について（New!）
15. http通信機能について
16. サンプルスクリプト
17. HSP3Dishコマンドリスト
18. Windows上での実行ファイル作成
19. 起動設定ファイルについて
20. 物理エンジンOBAQのサポート
21. 他プラットフォームへの変換（New!）
22. テクスチャ上限数について（New!）
23. 拡張プラグイン・外部DLLのサポート
24. 各種入出力への対応について
25. 既知の不具合について
26. 著作権とライセンス
27. 連絡先

## HSP3Dishとは

HSP3Dishは、HSP3の動作環境を様々なデバイス上で構築するための 追加セットです。Windows上で開発したスクリプトを、別なOS上で 動作させるための仕組みを提供します。

Windows上で動作するHSP3Dishランタイムは、通常版のHSP3と比べて機能が制限され、 いくつかの特殊な機能が付加されています。 このHSP3Dishランタイムと同等の機能を、iPhone/iPad、またはandroidといった 異なるシステム上でも実装することで、Windows版で動作するスクリプトを再利用できる 仕組みになっています。

特殊な利用を想定したHSP3DishですがWindows上で使用する上では、 DirectX/OpenGLを使用した高速描画や、アルファチャンネルやPNG形式の標準サポートなど、 通常のHSP3にはないメリットも持ちあわせています。
さらに、3D機能や高度な物理演算をサポートするHGIMG4ランタイムも、HSP3Dishから派生する形で提供されています。

Linux及び小型デバイスRaspberry Pi上で動作する、HSP3 for Linux/Raspberry Piは、別途パッケージ版を配布しています。詳しくは、 HSP3 for Linux/Raspberry Piのページをご覧ください。

HSP3Dishは、新しいHSP3の流れとして今後も進化を続ける予定です。どうぞご期待ください。

公式サイトHSPTV!上に、HSP3Dishについての紹介ページが用意されています。 HSP3Dishについての最新情報や、ユーザー作品や資料など役立つ情報が集められていますので、ぜひご覧ください。

HSP3Dishサポートページ
https://hsp.tv/make/hsp3dish.html

HSP3 for Linux/Raspberry Pi
https://hsp.tv/make/hsp3linux_pi.html

HGIMG4 development
https://hsp.tv/make/hgimg4.html

## HSP3Dishの使用方法

HSP3Dishでは、Windows上で動作するHSP3のスクリプトエディタなど通常のHSP環境をそのまま使用して開発を行ないます。 できる限り、最新版のHSPで作成を行なってください。
HSP3Dish環境で動作するスクリプトを作成する場合は、 最初の行に、以下のコードを追加する必要があります。

    	#include "hsp3dish.as"

HSP3.7β7以降では、以下のような記述も可能です。

    	#use hsp3dish

以降は、通常のHSP3スクリプトと同様にソースを記述することができます。 ただし、マルチプラットフォームで動作させるためには、以下の機能は利用できないことを留意してください。

- 拡張プラグインの命令は未サポート
- COMオブジェクト操作、COM型・Variant型変数は未サポート
- 外部DLL呼び出し機能は未サポート
- モジュール変数に関する機能は未サポート(モジュール機能そのものはサポートされます)

( *Windowsプラットフォームのみで使用する限りは、これらの制約はありません。 )

これらは、Windows以外のプラットフォーム上で再現できない機能を使用しています。 プラットフォームの対応に応じて、機能を利用するようにしてください。

また、スマートフォンのメモリやセキュリティの制約を反映して 以下の機能は限定的になっています。

- 出力は単一のスクリーン(ID#0)のみに限られます 　(複数のウインドゥ表示はサポートされていません)
- buffer命令で作成した画像バッファに対する加工ができません 　(画像の割り当ては可能ですが、描画命令を使用できません。 ただし、HGIMG4ランタイムでは限定的にサポートしています)
- デバイス間での完全なフォントの統一が取れません 　(日本語の文字フォントについては機種依存になります)
- notesave、bsave命令などデバイスへの書き出しに制限があります
- buttonを除く配置オブジェクトの一部がサポートされていません。 　(chkbox、inputは限定的にサポートしています)

HSP3Dishでは、多くの命令や関数などを通常のHSP3と同様に使用できますが、 環境の違いを吸収するために、機能が制限されており、Windows版に慣れた 人には面倒な部分もあるかもしれません。今後のバージョンでは、 Windows版との違いを意識することなく、幅広い環境に適用させることを 目標としています。

いくつかの制約は、ネイティブコードを生成するために HSP3ソースコンバーターを通す上で発生しています。 より詳しく知りたい方は、HSP3ソースコンバーターマニュアル(hsp3cnv.txt) を参照してください。

## HSP3との差異

HSP3Dishは、高速描画とマルチプラットフォームを前提として 作成されています。通常のHSP3とは、以下の点で異なっています。

- redraw命令により画面の更新する必要があります

画面の書き換えに関するソースは、redraw 0で描画開始を知らせて、 redraw 1により描画終了タイミングを知らせるようにしてください。 これにより、効率よく各種描画の命令が実行されます。
通常のHSP3とは違い、「redraw 0」を指定することにより、スクリーンが 一旦クリアされますので、それまでに描かれていた内容は残りません。 表示するものを毎回描画する必要があることを意識してください。

    	redraw 0	; 描画を始める(画面クリア)
    	～ここに描画命令を記述します～
    	redraw 1	; 描画を完了する(画面が更新されます)
    	await 1000/60	; 時間待ちを行う(1/60秒で待ちます)

必ず、「redraw 0」と「redraw 1」を記述して、その間に描画命令を 記述する必要があります。HSP3も同様ですが、ループ内では、待ち時間を 入れる必要があります。awaitまたはwait命令でタイミングを調整してください。

- アルファチャンネルの扱い

picload、celload命令によりアルファチャンネルを含む画像ファイルを 読み込むことが可能です。(推奨する画像形式は、PNGファイルです) celput、gcopy等の命令では、アルファチャンネルを含めたコピーが 実行されます。そのため、gmodeによる指定は、いくつか違いが出ます。 詳しくは、「gmode命令について」の項目を参照してください。

- 描画速度の向上

通常のHSP3では、描画のアクセラレーションは限定的でしたが、 HSP3Dish及びHGIMG4では、グラフィックカードの機能を最大限に利用して 高速な描画、及び高品質な回転・拡大・縮小を行ないます。 半透明やアルファチャンネルなどの使用で、違いが顕著に現われます。

- 厳密なタイマー管理

通常のHSPよりも高精度なタイマーによりウェイトの管理が行なわれます。 wait/await命令での待ち時間が、通常のHSPと微妙に異なることがあります。

- 動画再生の非サポート

Windows版以外のプラットフォームでは、mmload/mmplay命令によるavi/mpg/wmv形式の 動画再生はサポートされません。 効果音にwav、BGM(サウンド)にmp3を使用することが可能ですが、 プラットフォームごとにサポートする形式が異なる可能性があります。

## 配置オブジェクトについて

現在すべてのプラットフォームでサポートされている配置オブジェクトは、 button命令によるボタンのみとなっています。 標準のオブジェクトと以下の点が異なっているので注意してください。

    	・標準でbuttonの背景はグレーのグラデーションが使用されます
    	・objimage命令によりbutton背景の画像を変更することが可能です
    	・キーボードによるボタン操作、フォーカス移動はサポートしていません
    	・ボタンの描画はredrawによる画像更新時に行なわれます

Windows/Linuxプラットフォームでは、以下の配置オブジェクトをサポートしています。

    	・チェックボックス(chkbox)
    	・入力ボックス(input)

今後多くのプラットフォームで、配置オブジェクトを幅広くサポートする予定です。

## 標準スプライトについて

HSP3Dish、HGIMG4ランタイムでは、手軽に使用できる標準スプライトをサポートしました。
標準スプライトの命令は、hspdxプラグインとして追加されていた命令と互換があり、2D描画を手軽に扱うことが可能です。

HSP3で2D描画を行う際に、スプライト(矩形の画像)を利用するための手段はいくつか用意されていました。

    		・HSPDXプラグイン
    		・HGIMG/HGIMGXプラグイン
    		・HGIMG3プラグイン
    		・HGIMG4プラグイン
    		・mod_spriteモジュール

この中で、HSPDX、HGIMG、HGIMGXまでのプラグインはHSP2時代のもので、すでに開発が終了しており、 現在のOSや環境で動作させることが困難になっています。
HGIMG3/HGIMG4プラグインには、3D機能とともに高機能な2Dスプライトとしての 機能も持っていますが、座標をすべて実数で管理し、機能が多い代わりに 習得する内容も増えて手軽には扱いずらい所がありました。
今回、最も長い歴史があり、多くのユーザーが使用してきたHSPDXプラグインの 命令をもとに、手軽で扱いやすい2D専用のスプライト命令を拡充しました。
シンプルな命令でスプライトを表示でき、スプライトの画像を自由に登録できる 柔軟なシステムを搭載しています。また、スプライトコールバックやマップ描画など ユニークな仕組みも導入され、元のHSPDXプラグインよりも利便性向上しています。
座標も整数で管理されており、2DゲームやUI表示などで扱いやすいものになっています。 もちろんイベントリストによる自律移動や3Dとの連携については、従来のプラグインを利用することもできます。
標準スプライトは、HSP3Dish、HGIMG4がサポートする全プラットフォームで動作するほか、 HSP3標準ランタイムでもサポートすることを予定しています。
標準スプライトの詳細は、「標準スプライトプログラミングガイド」を参照してください。

## のスクリーンサイズ変更について

HSP3Dish、HGIMG4のWindows/Linux版において、スクリーン(ウインドウ)サイズの動的な変更に対応しました。(HSP3.6β2以降)
いままでは、hsp3dish.iniファイルに記録されたサイズに従って起動時にサイズが固定されていましたが、 多くの方からサイズの変更とフルスクリーン対応の要望を頂き、修正致しました。 HSP3.6より、screen命令,bgscr命令によりスクリーン(ウインドウ)サイズを変更できます。

    	screen p1,p2,p3,p4,p5,p6

    	p1=0～(0) : ウィンドウID
    	p2=1～(640): 初期化する画面サイズX（1ドット単位）
    	p3=1～(480): 初期化する画面サイズY（1ドット単位）
    	p4=0～1(0) : 初期化する画面モード
    	p5=0～(-1) : ウィンドウの配置X（1ドット単位）
    	p6=0～(-1) : ウィンドウの配置Y（1ドット単位）

p1のウインドウIDは、0のみとなります。 p4の初期化モードは、以下の値を指定することができます。

    	  +4(screen_fixedsize) : サイズ固定ウィンドウ
    	  +8(screen_tool)      : ツールウィンドウ
    	 +16(screen_frame)     : 深い縁のあるウィンドウ
    	 +256                  : フルスクリーン

p4に256を指定した場合は、指定された解像度のフルスクリーンとして初期化されます。
また、スクリーンサイズ変更時は、通常ランタイムとは異なり、それまでに読み込んだすべての画像バッファは失われますので注意してください。

## viewcalc命令による座標変換について

HSP3Dish、HGIMG4において、描画時の座標変換を設定するviewcalc命令を追加しました。
viewcalc命令は、2D描画時のX,Y座標に任意の計算を適用することができる強力な機能です。 描画される表示物全体のスケーリングや移動、回転などを行うことができます。

    	viewcalc p1,p2,p3,p4,p5

    	p1(0)   : 設定モード
    	p2(0.0) : パラメーター1(実数)
    	p3(0.0) : パラメーター2(実数)
    	p4(0.0) : パラメーター3(実数)
    	p5(0.0) : パラメーター4(実数)

p1で指定する設定モードには、いくつかの種類があり多彩な変換を行うことが可能です。

    	マクロ名            値   内容
    	-----------------------------------------------------
    	vptype_off           0   座標変換なし(デフォルト)
    	vptype_translate     1   移動パラメーターを指定
    	vptype_rotate        2   回転パラメーターを指定
    	vptype_scale         3   スケールパラメーターを指定
    	vptype_3dmatrix      4   4×4マトリクスによる座標変換
    	vptype_2d            5   2D座標変換を設定
    	vptype_3d            6   3D座標変換を設定

vptype_2dは、基本的な2D座標変換を適用するモードになっています。 パラメーター1～3で、X,Yのスケール(倍率)、回転角度(ラジアン単位)を設定することができます。

    	viewcalc vptype_2d, 2.0, 2.0, 0.0

のように指定した場合は、X,Y方向に2倍のスケールで表示、角度は0となります。
他にも色々なパラメーターを指定できます。詳しくは、viewcalc命令のヘルプを参照してください。

## celbitmap命令による画像データ制御について

HSP3Dish、HGIMG4において、変数バッファの内容を画像データとして扱うためのcelbitmap命令を追加しました。
これまで、HSP3Dishではドット単位の画像データに直接アクセスすることができませんでしたが、この命令によりメモリの内容を画像データとして読み書きできるようになります。

    	celbitmap p1,var,p2

    	p1(0)   : ウインドウID
    	var     : イメージを置き換えるための配列変数
    	p2(0)   : 動作オプション

celbitmap命令を使用する際には、あらかじめbuffer命令により作成したオフスクリーンバッファと、置き換えるための変数バッファを初期化する必要があります。
オフスクリーンバッファは、buffer命令でscreen_offscreenのオプションを指定して作成してください。

    	buffer 2,256,256,screen_offscreen

その後、バッファを置き換えるための変数バッファを作成します。
dim命令により、１次元配列を初期化して作成してください。作成するサイズは、オフスクリーンバッファのXサイズ×Yサイズになります。

    	dim bitmap, 256*256

これで、celbitmap命令を使用する準備が整いました。
celbitmap命令により、オフスクリーンバッファのIDと配列変数を指定することで、変数バッファの内容がそのまま画像イメージとして適用されます。
変数バッファは、1要素あたり1ドットとなります。1ドットは、32bitの要素をR,G,B,Aそれぞれ8bit単位で格納されるRGB形式のデータとなります。(3.6β2版と3.6β3版でRGBの並び順が変更になっています。ご注意ください)
たとえば、「$ff204080」(16進数)を指定した場合は、A=$ff(255)、B=$20(32)、G=$40(64)、R=$80(128)となります。(カッコ内は10進数)
画像データの置き換えは、コストの高い処理になるため、大きなサイズのイメージを置き換える場合、フレームレートが下がることがありますので注意してください。
p2パラメーターにより、置き換えの形式や動作を指定することができます。

    	 値  マクロ             動作
    	---------------------------------------------------------
    	  0  celbitmap_rgb      $aabbggrr形式でデータを保持する
    	  1  celbitmap_bgr      $aarrggbb形式でデータを保持する
    	  16 celbitmap_capture  描画画面の内容を変数に読み出す

通常は、OpenGLの標準に合わせたcelbitmap_rgbの形式が使用されます。オプションにcelbitmap_bgrを指定した場合は、DirectX標準に合わせたARGBの並びになります。
celbitmap_captureを指定した場合は、描画先の画面上のデータを配列変数に読み出します。(読み出しのサイズはオフスクリーンバッファのサイズになります)
※celbitmap_captureオプションは、実験的な実装です。現在は、Windows(DirectX版HGIMG4を除く)、Linux版でのみ使用できますのでご了承ください。

## gmode命令について

hsp3dishでは、celput、gcopy等の画像コピー命令で、アルファチャンネルを含めた コピーが実行されます。そのため、gmodeによるコピーモードの指定は、いくつか違いが出ます。

    	gmode 0,1 : アルファチャンネルなし(無視)
    	gmode 2   : アルファチャンネル有効、半透明レート無効
    	gmode 3,4 : アルファチャンネル有効、半透明レート有効
    	gmode 5   : 色加算・アルファチャンネル有効、半透明レート有効
    	gmode 6   : 色減算・アルファチャンネル有効、半透明レート有効

アルファチャンネルは、PNG形式などの画像データに付加される情報です。 通常のHSPにあるRGBが0の場合に透過するモードや、特定の色コードを透過するモードは選択できませんので注意してください。
現在のバージョンでは、android(NDK)ランタイムにおいてgmode 6(色減算)はサポートされませんのでご注意ください。

コピーモード2以上の場合には、画像に対して特定の値を乗算する「テクスチャ乗算」の設定が可能です。 詳しくは、「gmulcolor命令について」の項目を参照してください。

## gmulcolor命令について

hsp3dish ver3.5b3から、テクスチャ乗算値の設定を行なうためのgmulcolor命令が追加されています。

    		gmulcolor p1,p2,p3
    		-----------------------------------------------
    		p1,p2,p3=0～255(255) : 色コード（R,G,Bの輝度）

p1,p2,p3がそれぞれ、R,G,Bの輝度になります。gcopy,gzoom,celput,grotate命令などでコピーされる画像に対して、指定したR,G,B値が乗算されます。 初期値は、RGBそれぞれ255が指定されています。テクスチャ乗算値を設定することにより、元の画像の色を変化させることができます。 画像コピーの際に、gmode命令で指定されるコピーモードが0または1(アルファチャンネルを反映しない)の場合は、テクスチャ乗算値は無効になるので注意してください。 テクスチャ乗算値は、mes命令による文字の描画、gsquare命令の描画には反映されません。また、boxf,line命令など単色の描画には反映されません。(grotate命令の単色描画も含む)

## gfilter命令について

hsp3dish ver3.3a2から、フィルタリング(テクスチャ補間)の設定を行なう ためのgfilter命令が追加されています。

    	マクロ名        値      内容
    	-------------------------------------------
    	FILTER_NONE     0       補間なし(NEAREST)
    	FILTER_LINEAR   1       直線補間(LINEAR)
    	FILTER_LINEAR2  2       エリア補間(高度な補間処理)

フィルタリングの設定により、画像の拡大・縮小時のドット補間方法を 選ぶことができます。FILTER_NONEを指定することで、補間なし(ニアレスト) の状態になります。FILTER_LINEARは、直線(リニア)補間、FILTER_LINEAR2は より高度な補間方法(バイリニアなど)を選択します。 gfilter命令の設定は、以降のすべての描画命令に適用されます。 また、「redraw 0」による画面クリア時には、フィルタリング設定は FILTER_NONEにリセットされます。

## setreq、getreq命令について

hsp3dish ver3.3a6から、システムの各種設定を行なうためのsetreq、getreq命令が 追加されています。

    		setreq type,val			システムリクエスト設定書き込み

    		type : 設定タイプ(SYSREQ_???)
    		val  : 設定する値

    		getreq var,type			システムリクエスト設定読み出し

    		var  : 結果が代入される変数名
    		type : 設定タイプ(SYSREQ_???)

    	設定タイプ名             読み書き(*)   内容
    ---------------------------------------------------------------------------
    	SYSREQ_MAXMODEL          RW            HGIMG3最大モデル数
    	SYSREQ_MAXOBJ            RW            HGIMG3/4最大オブジェクト数
    	SYSREQ_MAXTEX            RW            HGIMG3/4最大テクスチャ数
    	SYSREQ_MAXMOC            RW            HGIMG3最大MOC数
    	SYSREQ_DXMODE            RW            DirectXモード(Windowsのみ)
    	SYSREQ_DXHWND            R             DirectXウインドウハンドル(Windowsのみ)
    	SYSREQ_DXWIDTH           RW            DirectXフルスクリーンXサイズ(Windowsのみ)
    	SYSREQ_DXHEIGHT          RW            DirectXフルスクリーンYサイズ(Windowsのみ)
    	SYSREQ_COLORKEY          RW            DirectXカラーキー(Windowsのみ)
    	SYSREQ_RESULT            R             DirectX初期化結果(Windowsのみ)
    	SYSREQ_RESVMODE          R             DirectXビデオ初期化結果(Windowsのみ)
    	SYSREQ_PKTSIZE           RW            パケットサイズ(未使用)
    	SYSREQ_MAXEVENT          RW            HGIMG3/4最大イベント数
    	SYSREQ_PTRD3D            R             Direct3Dクラスポインタ(Windows/HGIMG3のみ)
    	SYSREQ_PTRD3DDEV         R             Direct3DDeviceクラスポインタ(Windows/HGIMG3のみ)
    	SYSREQ_MDLANIM           RW            モデルあたりのアニメーション最大数(HGIMG3)
    	SYSREQ_CALCNORMAL        RW            Xファイルモデル法線再計算スイッチ(HGIMG3)
    	SYSREQ_2DFILTER          RW            2D描画時のテクスチャ補間モード(HGIMG3)
    	SYSREQ_3DFILTER          RW            3D描画時のテクスチャ補間モード(HGIMG3)
    	SYSREQ_OLDCAM            RW            カメラ注視モードの動作(HGIMG3)
    	SYSREQ_QUATALG           RW            Xファイルモデルアニメーション補間モード(HGIMG3)
    	SYSREQ_DXVSYNC           RW            フルスクリーンモード時のVSYNC待ちモード(HGIMG3)
    	SYSREQ_DEFTIMER          RW            hgsyncの時間待ちモード(HGIMG3)
    	SYSREQ_NOMIPMAP          RW            テクスチャのMIPMAP生成モード(HGIMG3)
    	SYSREQ_DEVLOST           RW            DirectXデバイスの存在フラグ
    	SYSREQ_MAXEMITTER        RW            HGIMG3エミッター最大数
    	SYSREQ_THROUGHFLAG       RW            X方向のボーダー処理フラグ(HGIMG3)
    	SYSREQ_OBAQMATBUF        RW            OBAQ用マテリアルバッファ数(HGIMG3)
    	SYSREQ_2DFILTER2         RW            2D直接描画時のテクスチャ補間モード(HGIMG3)
    	SYSREQ_FPUPRESERVE       RW            FPU演算精度設定オプション(HGIMG3)
    	SYSREQ_CLSMODE           RW            背景のクリアフラグ
    	SYSREQ_CLSCOLOR          RW            背景クリア色
    	SYSREQ_CLSTEX            RW            背景クリアテクスチャID(HGIMG3)
    	SYSREQ_TIMER             R             ミリ秒単位のタイマー値
    	SYSREQ_PLATFORM          R             HSP3Dishを実行しているプラットフォーム
    	SYSREQ_FPS               R             フレームレート(HGIMG4)
    	SYSREQ_VSYNC             RW            VSync待ちモード(HGIMG4)
    	SYSREQ_MAXMATERIAL       RW            HGIMG4最大マテリアル数
    	SYSREQ_PHYSICS_RATE      RW            OBAQ用物理パラメーター(OBAQ)
    	SYSREQ_MAXOBAQ           RW            OBAQ用オブジェクト最大数(OBAQ)
    	SYSREQ_MAXLOG            RW            OBAQ用コリジョンログ最大数(OBAQ)
    	SYSREQ_DEFAULT_WEIGHT    RW            OBAQ用デフォルトWeight値(OBAQ)
    	SYSREQ_DEFAULT_MOMENT    RW            OBAQ用デフォルトMoment値(OBAQ)
    	SYSREQ_DEFAULT_DAMPER    RW            OBAQ用デフォルトDamper値(OBAQ)
    	SYSREQ_DEFAULT_FRICTION  RW            OBAQ用デフォルトFriction値(OBAQ)
    	SYSREQ_MESCACHE_MAX      RW            メッセージキャッシュ最大数(HSP3Dish)
    	SYSREQ_DLIGHT_MAX        RW            ディレクショナルライト最大数(HGIMG4)
    	SYSREQ_PLIGHT_MAX        RW            ポイントライト最大数(HGIMG4)
    	SYSREQ_SLIGHT_MAX        RW            スポットライト最大数(HGIMG4)
    	SYSREQ_LOGWRITE          RW            終了時のログ出力スイッチ(HGIMG4)
    	SYSREQ_FIXEDFRAME        RW            固定フレームレートスイッチ(HGIMG4)
    	SYSREQ_DRAWNUMOBJ        R             描画されたオブジェクト数(HGIMG4)
    	SYSREQ_DRAWNUMPOLY       R             描画されたポリゴン数(HGIMG4)
    	SYSREQ_USEGPBFONT        RW            gpbフォント使用スイッチ(HGIMG4)
    	SYSREQ_FIXMESALPHA       RW            文字描画alpha値固定モード(HSP3Dish)
    	SYSREQ_OLDBOXF           RW            従来のboxf描画モード(HSP3Dish)

    	(*)項目ごとに、読み(R)書き(W)の可否が異なります

- SYSREQ_CLSMODE、SYSREQ_CLSCOLOR

redraw 0による描画開始時に画面をクリアするかどうかを設定します。 SYSREQ_CLSMODEに1を設定した場合はクリア、0の場合はクリアを行ないません。 スクリプト内で画面のクリアを行なっている場合は、システム側で背景クリアをしない方が 処理速度の向上につながります。 SYSREQ_CLSCOLORでクリアする際の色コードを設定することができます。 色コードは、RGB24bit($rrggbb)を1つにした数値で設定します。

- SYSREQ_TIMER

ミリ秒単位のタイマー値を返します。 プラットフォームごとに返される値は異なりますが、1ミリ秒につき1ずつ値が加算されていきます。

- SYSREQ_PLATFORM

以下のHSP3Dishプラットフォーム値を返します。

    	マクロ名            値  内容
    	-------------------------------------------
    	PLATFORM_WINDOWS    0   Windows版
    	PLATFORM_IOS        1   iOS版
    	PLATFORM_ANDROID    2   android版
    	PLATFORM_WEBGL      3   hsp3dish.js(WebGL/JavaScript)版
    	PLATFORM_LINUX      4   Linux版
    	PLATFORM_RASPBIAN   5   Raspberry Pi(raspbian)版

## マルチタッチ情報の取得について

hsp3dish ver3.4b1から、マルチタッチ情報の取得を行なうmtlist、mtinfo命令が追加されています。 これにより、スマートフォン上で複数のポイントにタッチされている情報を得ることが可能です。 Windows、Linux、html5(ブラウザ)上でも、マルチタッチデバイスが接続されている場合は、複数のタッチ情報を取得可能です。

    		mtlist var			ポイントIDリスト取得

    		var  : 結果が代入される変数名

    		mtinfo var,id			タッチ情報取得

    		var  : 結果が代入される変数名
    		id   : ポイントID

最初に、mtlist命令により現在タッチされているポイントIDリストを取得します。 mtlist命令で指定された変数にポイントIDと呼ばれる整数値が代入されます。 複数のポイントがタッチされている場合は、配列変数としてvar(0),var(1),var(2)…というように 複数のポイントIDが代入されていきます。 配列に代入されたポイントIDの数は、システム変数statに返されます。 システム変数statが0の場合は、何もタッチされていないことを示します。
ポイントIDの値を得た後は、mtinfo命令によりポイントIDに対応する詳細情報を得ることが可能です。 たとえば、「mtinfo a,1」はポイントID1の情報を変数aに代入します。 ここで指定された変数aには、整数型の配列変数として初期化され、以下の内容が代入されます。

    		  a(0)  :  タッチ状態(1=ON/0=OFF)
    		  a(1)  :  タッチされたX座標
    		  a(2)  :  タッチされたY座標
    		  a(3)  :  タッチ識別用ID

これらの情報をもとに、複数のポイントを管理することができます。 タッチ識別用IDは、値そのものに意味はなく、複数タッチされた中で他と異なる値が割り当てられます。 タッチ識別用ID値は、デバイスごとに異なりますので注意してください。
iOS上でマルチタッチ情報を取得する場合は、マルチタッチ入力を許可する設定を含める必要があります。 詳しくは、iOS版プログラミングガイドを参照してください。
尚、マルチタッチをサポートしないWindows上でも、1点のみがタッチされた情報として情報が取得されます。

## サウンド機能について

HSP3Dishでは、標準のHSPの上位互換となるメディア再生機能を持っています。 ただし、Windows固有の機能であるmci命令は、他のデバイスではサポートされません。 また、動画及びavi/mpg/wma/wmv形式の音声ファイルはサポートされません。 iOS、Androidを含むすべてのデバイス上でサポートされている形式は、 SE(効果音)としての.wav、BGM(音楽)のための.mp3となります。

    		mmload	(wav,mp3形式を推奨)
    		mmplay  (HSP標準命令と同様)
    		mmstop  (停止するIDを指定可能、HSP標準命令の上位互換)
    		mmvol	(HSP3Dishのみ、音量の設定)
    		mmpan	(HSP3Dishのみ、パンニングの設定)
    		mmstat	(HSP3Dishのみ、情報の取得)

HSP標準命令と異なり、wav形式による波形再生は、複数のサウンドを多重に鳴らすことが可能です。 長い音声の再生(.mp3形式)は、負荷軽減のため多重に再生することはできません。
それぞれの命令の詳細については、HSP Document Libraryによる命令ヘルプを参照してください。

Windowsでは、oggファイルによるサウンドの再生をサポートしたhspoggプラグインを利用することが可能です。 hspoggプラグインは、mmplayとは別のコマンド(dmmplayなど)を使用してサウンドの再生を行います。
外部のプラグイン等を使用してサウンドを再生する場合は、HSP3Dishに内蔵されたサウンドシステムを 無効にしておくことをお勧めします。複数のサウンドシステムを同時に使用することで、 外部のプラグインに影響が出ることを抑制できます。
HSP3Dishに内蔵されたサウンドシステムの有効・無効を切り替える場合は、「devcontrol "mmsystem",値」の命令を使用してください。

    		devcontrol "mmsystem",0		; 内蔵サウンドシステムを無効化
    		devcontrol "mmsystem",1		; 内蔵サウンドシステムを有効化

命令で指定する値は0(無効)か1(有効)を指定します。screen命令を使用した場合には、内蔵サウンドシステムが再度有効化されるので注意してください。 この拡張コントロールは、Windowsプラットフォームでのみ有効となります。

## http通信機能について

HSP3Dishでは、簡易的なhttp通信機能を持っています。
これにより、web(HTTP)サーバーへのネットワークアクセス及び、データの取得を行なうことができます。 あくまでも、基本的なhttp通信機能をサポートするもので、すべてのwebサーバーとの通信を保証するものではありません。
現在のバージョンでは、Windows,Emscripten(WebGL),androidプラットフォームのみサポートされています。今後のバージョンでは、他のプラットフォームもサポートされる予定です。

    		httpload (HTTP通信の開始)
    		httpinfo (HTTP通信の情報取得)

上記の命令により、web(HTTP)サーバーに対して、標準的なGET,POSTメソッドによるリクエストを行なうことが可能です。 webページの取得、CGIやWEBAPIの呼び出しといった用途に使用することができます。
それぞれの命令の詳細については、HSP Document Libraryによる命令ヘルプを参照してください。

## サンプルスクリプト

HSPフルセットの サンプルディレクトリhsp3dishにサンプルスクリプトが収録されています。 HSP3Dishを使用した例として、参考にしてみてください。

## HSP3Dishコマンドリスト

各命令・関数の互換性については、別途ファイル「support_cmds.txt」を参照してください。 一部の命令は、未実装ですが今後拡充していく予定です。

## Windows上での実行ファイル作成

HSP3Dishのランタイムファイル(hsp3dish.hrt)を使用して、 Windows上で実行可能なプログラムを作成することが可能です。 通常のHSP3にはないメリットもあるため、Windowsに対応したソフトの 作成用途としてもお使い頂けます。

Windows版のHSP3Dishランタイムは、Windows98、Me、2000、XP以降の DirectX8がインストールされた環境で動作します。 (Windows XP以降(Windows Vista,8,10)には、標準で含まれているため 追加でDirectXインストールの必要はありません)
また、Windows版のHGIMG4は、OpenGL及びDirectX9を使用します。 動作環境については、別途HGIMG4のマニュアルを参照してください。

## 起動設定ファイルについて

通常の起動時は、画面のサイズは320x480に固定されています。 これは、iPhone(3G)に合わせたサイズですが、起動設定ファイルを 用意することにより、画面サイズを変更することができます。 (HSP3Dishは、画面サイズは起動時に決定され、screen,width命令での変更はできません)

起動設定ファイルは、「hsp3dish.ini」というファイル名でスクリプトと 同じフォルダに置かれている場合に反映されます。 以下は、設定ファイルの記述例です。

    	; hsp3dish settings
    	wx=320
    	wy=480

行の先頭から「wx=横サイズ」「wy=縦サイズ」を書くことで反映されます。 「;」で開始される行はコメントとみなされます。 異なるデバイスでの動作を想定する場合などに、起動設定ファイルを 用意して実行を行なってください。

HSP3Dishを使用して、Windows用の実行ファイルを作成することが可能ですが、 作成された実行ファイルには起動設定ファイルは適用されません。 HSP3Dishランタイムで、Windows用の実行ファイルを作成する場合は、 画面サイズを#packopt命令で設定するようにしてください。

    	#packopt name "ファイル名"
    	#packopt xsize 320		; 横サイズ
    	#packopt ysize 480		; 縦サイズ

## 物理エンジンOBAQのサポート

HSP3Dishでは、物理エンジンOBAQの機能をサポートしています。 OBAQプラグインが持つ命令と同等の機能をHSP3Dish上で利用可能です。
物理エンジンOBAQの機能は、qreset命令実行後に有効となります。 OBAQプラグイン命令を使用しない場合は、余計なメモリ、CPUリソースを一切使用しません。
詳しい使用方法は、物理エンジンOBAQのマニュアルを参照してください。

※物理エンジンOBAQは、HSP3Dishとは異なるライセンスで運用されています。 OBAQを使用したソフトにより、税務申告が必要な利益が発生する場合(有料アプリによる利益が大きい場合)には、有償ライセンスの取得が必要です。ただし、少数の配布、最低限の必要経費(メディア代金等)のみで配布する場合は無償と考えますので、有償ライセンスの取得は必要ありません。 もちろん無償アプリの場合には、ライセンスの取得は必要ありません。

## 他プラットフォームへの変換

HSP3Dishでは、他のプラットフォームへの変換をサポートしています。 動作の仕組みは以下になります。

1. WindowsのHSP3Dish上でスクリプトを作成
2. 作成したスクリプトをCソースに変換 (HSP3ソースコンバーターを使用、ソースはUTF-8として出力)
3. 別プラットフォーム向けの開発環境でCソースをコンパイル (各プラットフォーム向けライブラリが別途提供されます)
4. アプリケーションの変換完了 (html5版を除いて逐次実行(インタプリタ)ではなくネイティブコードとして実行します)

スクリプトの変換などをサポートするためのツールとして、「HSP3Dish Helper」アプリケーションが用意されています。 「HSP3Dish Helper」は、HSPスクリプトエディタの「ツール」→「HSP3Dish/Cソース変換」のメニューから起動することができます。

詳しくは、それぞれのプラットフォームごとに用意されるマニュアルを参照してください。

- WebGL/JavaScript版(hsp3dish.js)プログラミングガイド（hsp3dish_js.htm）
- iOS版プログラミングガイド（hsp3dish_ios.htm）
- android(NDK)版プログラミングガイド（hsp3dish_ndk.htm）
- HSP3ソースコンバーター・マニュアル（hsp3cnv.txt）

## テクスチャ上限数について

HSP3Dishでは、使用する画像(テクスチャ)の数を無制限に扱うことが可能です。 ただし、プラットフォームやグラフィックス環境によってメモリの上限から制約が発生する場合があります。
また、HGIMG4の場合は、マテリアル数によりテクスチャの上限数が決まります。 詳しくは、HGIMG4プログラミングガイド - 登録の限界数についてをご覧ください。

## 拡張プラグイン・外部DLLのサポート

Windows上のHSP3Dishでは、拡張プラグイン及び・外部DLL呼び出し、COMオブジェクト関連機能をサポートしています。(ActiveX関連機能はサポートしていません) ただし、HSP3Dishのシステム上、利用できないプラグインも存在するので注意してください。

- HSPのウインドウに対して描画を行なうプラグイン(hgimgやhspdxなど)は利用できません
- HSPの配置オブジェクト(ボタンや入力ボックス)を拡張するプラグインは利用できません
- その他、HSPのウインドウに関する情報(BMSCR構造体)を参照するプラグインは正常に動作しない可能性があります

いずれの場合も、拡張プラグイン・外部DLL呼び出し機能は、Windows上でのみサポートされる機能になりますので、他のプラットフォーム(iOSやandroid、WebGLなど)上には変換されません。 HSP3Dishの目的の1つである、マルチプラットフォーム化ができなくなることを理解した上で、利用するようにしてください。

## 各種入出力への対応について

特定のデバイスが持つ独自の機能や、デバイスからの特殊な入力取得についてはdevcontrol命令とその関連命令によってサポートしていきます。 詳しくは、それぞれのデバイスコントロールについての項目を参照してください。 Windows上で動作しないものについては、擬似的にテストできるシステムの作成を検討しています。

## 既知の不具合について

以下は、iOS,androidプラットフォーム上で報告されている不具合です。

- #defcfuncによる複数パラメーターを持つユーザー定義関数の呼び出しで、パラメーター省略時に正しく実行が行なわれない不具合が報告されています
- #defcfuncによるユーザー定義関数の呼び出し内で、awaitやwait、stopなどタスクが停止状態になる命令を実行するとエラー(40)が発生しますので使用を避けてください
- split命令は現在正しく動作していません。getstr命令などにより代用下さい
- PNGデコーダーの違いによりWindows上で表示できる画像が、iOS,androidで表示できない場合があります
- #defcfunc、#deffunc命令によるユーザー定義呼び出し先でgosub命令を使用した際に、呼び出し先のサブルーチンで引数にアクセスできない不具合が報告されています

## 著作権とライセンス

ユーザーが、HSP3Dishを使って作成したオリジナルのソフトウェア(実行ファイル)の権利は、それを作成したユーザーに属します。
商用、非商用を問わず、どのような形態での使用も可能です。また、ライセンス料は必要ありません。

ユーザーが作成したソフトウェアには、onion softwareの著作権表示も、HSPを使っている旨を表示する義務もありません。 オリジナルのソフトウェアに対してonion softwareが著作権を主張することはありません。 HSPを使用して作られた2次的な開発システム(ゲーム作成システム等)に関しては、そのシステムを作った作者の責任において運用して下さい。

HSP3Dishは、インタプリタ言語Hot Soup Processor(HSP)の一部であり、著作権はonion softwareにあります。 onion softwareは本プログラムによって生じた、いかなる損害についても保証いたしません。 自己の責任の範囲で使用してください。

HSP3Dishは、OpenHSP技術からの派生により作成されています。 HSP3Dish及びOpenHSPに含まれるファイル及びソースコードは、BSDライセンスのもと自由に添付・複製・改編・再配布することが できます。その際にはライセンス表記(License_j.txt)を明示するようにしてください。

製作したソフトウェアを商用として運用することを検討されている方で、有償によるサポートをご希望の方は メールにてinfo@hsp.tvまでご連絡下さい。詳細をご案内させていただきます。