HSP : HSP3Dish / onion software 2017(c)

HSP3Dish プログラミングマニュアル・基本仕様ガイド

HSP3Dishとは
HSP3Dishの使用方法
HSP3との差異
button命令について
gmode命令について
gmulcolor命令について
gfilter命令について
setreq、getreq命令について
マルチタッチ情報の取得について
サウンド機能について
http通信機能について(new)
サンプルスクリプト
HSP3Dishコマンドリスト
Windows上での実行ファイル作成
起動設定ファイルについて
物理エンジンOBAQのサポート
他プラットフォームへの変換
拡張プラグイン・外部DLLのサポート
各種入出力への対応について
既知の不具合について
著作権とライセンス
連絡先

HSP3Dishとは

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

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

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

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

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

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

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

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

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

HSP3Dishの使用方法

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

	#include "hsp3dish.as"

以降は、通常のHSP3スクリプトと同様にソースを記述することができます。ただし、HSP3Dish環境に適用させるために、いくつかの制約があります。大きな制約は以下の通りです。

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

これらは、Windows以外のプラットフォーム上で再現できない機能を持っているため、マルチプラットフォームを前提としたプログラムでは使用できません。 Windows版のHSP3Dishのみを使用する場合は、これらの機能も利用することができます。

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

出力は単一のスクリーン(ID#0)のみに限られます　(複数のウインドゥ表示はサポートされていません)
スクリーンサイズを変更できません　(デバイスが定めたサイズで自動的に初期化されます)
buffer命令で作成した画像バッファに対する加工ができません　(画像の割り当ては可能ですが、描画命令を使用できません)
デバイス間での完全なフォントの統一が取れません　(日本語の文字フォントについては機種依存になります)
notesave、bsave命令などデバイスへの書き出しに制限があります

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

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

HSP3との差異

提供されているHSP3Dishは、OpenGLやDirectXによる高速描画を前提として作成されています。通常のHSP3とは、以下の点で異なっています。

redraw 0により画面がクリアされます

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

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

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

描画速度の向上

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

厳密なタイマー管理

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

動画再生の非サポート

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

実数演算の精度

実数(浮動小数点演算)の精度が、HSP3Dishでは単精度(32bit)扱いとなります。これは、デバイスの演算能力や実行速度などを考慮したもので、標準のHSP実数(64bit)よりも低い精度になることを考慮しておいてください。通常の使用上は特に問題のない範囲だと考えられます。

button命令について

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

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

これ以外のオブジェクトについては、今後順次サポートしていく予定です。

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_CLSMODE        RW        背景のクリアフラグ
	SYSREQ_CLSCOLOR       RW        背景クリア色
	SYSREQ_TIMER          R         ミリ秒単位のタイマー値
	SYSREQ_PLATFORM       R         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命令が追加されています。これにより、スマートフォン(iOS,Android)上で複数のポイントにタッチされている情報を得ることが可能です。 Windows上でも、Windows7以降のマルチタッチデバイスが接続されている場合は、複数のタッチ情報を取得可能です。

		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による命令ヘルプを参照してください。

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では、他のプラットフォームへの変換をサポートしています。動作の仕組みは以下になります。

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

スクリプトの変換などをサポートするためのツールとして、「HSP3Dish Helper」アプリケーションが用意されています。詳しくは、それぞれのプラットフォームごとに用意されるマニュアルを参照してください。

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

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

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

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

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

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

既知の不具合について

#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までご連絡下さい。詳細をご案内させていただきます。