IronHSP 仕様書

HSP3 .NET Framework 統合版 — 最終更新: 2026-04-18 (章構成再編 11 章 / 変数型・コンパイラ・ランタイムを正しく分離 / ネイティブコールバック + 環境変数説明拡充 / 全 151 iron_* + 31 C++ DLL + 51 Win32 DLL 6020 関数)

ベース: OpenHSP 3.8beta1 (SVN trunk) / ターゲット: .NET Framework 4.8 / ツールセット: v143 (VS2022)

1. 概要

IronHSP は、HSP3 (Hot Soup Processor 3) をベースに .NET Framework 連携 + 64bit 整数/ポインタ対応 + 構造体・共用体 + UTF-16 ワイド文字列 + COM コールバック + Win32/DirectX/.NET 相互運用 を加えた大幅拡張版です。hsp3net ランタイム系 (hsp3_net_64.exe / hsp3cl_net_64.exe / hspcmp_net_64.exe) にすべての新機能が集約され、バニラ HSP とは #include "hsp3_net_64.as" で明示的に切替える構成です (64bit 版が主、32bit 版はサブセット)。

2. ビルド構成

2.1 ランタイム

2.2 コンパイラ・デバッガ

2.3 プラグイン

3. 変数型システム

IronHSP はバニラ HSP3 の変数型 (int / double / str / label / struct / comobj) に加え、5 つの新規変数型を追加しています。本章では全変数型と各拡張型の詳細を解説します。

3.1 int64 型サポート

3.1 新しい変数型

HSPVAR_FLAG_INT64 = 8 として組み込み型に追加されています。HSP スクリプトでは代入によって自動的に型が決まります。

; 通常のintリテラル（32bit）
a = 100

; int64 リテラル（Lサフィックス）
b = 100L

; 32bit範囲を超える値は自動的にint64
c = 3000000000

; 16進数もint64になる（8桁超）
d = $100000000

; int64() 関数で明示的に変換
e = int64("9223372036854775807")
e = int64("0xFFFFFFFFFFFFFFFF")
e = int64("$FEDCBA0987654321")

3.2 新しい命令・関数

3.3 int64 対応済みの既存機能

3.4 型変換

3.5 使用例

; dim64 で配列宣言
dim64 i64, 16
repeat length(i64)
    i64(cnt) = int64("2147483647") + cnt
loop

; dimtype でも同じことが可能
dimtype i64_2, vartype("int64"), 4

; qpeek / qpoke
sdim buf, 64
qpoke buf, 0, int64("9223372036854775807")
mes "qpeek: " + qpeek(buf, 0)

; 文字列を渡すと自動変換
qpoke buf, 0, "0xFFFFFFFFFFFFFFFF"

; #deffunc / #defcfunc
#module
#defcfunc myadd64 int64 p1, int64 p2
    return p1 + p2
#global
r = myadd64(int64("1000000000000"), int64("2000000000000"))
mes r  ; => 3000000000000

3.2 UTF-16 ワイド文字列型 (wstr)

新しい変数型 wstr (HSPVAR_FLAG_WSTR = 10) で UTF-16 LE 文字列を直接扱えます。 Windows API の wchar_t 引数に変換なしで渡す用途を想定しています。

wsdim ws, 256               ; wstr 変数を宣言
ws = L"Unicode文字列"        ; L"..." リテラルで UTF-16 直接代入
ws = "SJIS文字列"            ; str → wstr 自動変換

n = strlen(ws)               ; wcslen() で文字数を返す
ws2 = strmid(ws, 0, 4)      ; wstr → wstr 部分文字列
p = instr(ws, 0, L"検索")   ; wcsstr() で検索
s = "" + ws                  ; wstr → str 自動変換

対応済み関数・命令

自動変換

str と wstr の間は MultiByteToWideChar / WideCharToMultiByte で自動変換されます。 int/double との変換も wcstol / swprintf 等で対応済みです。

詳細は wstr 設計書 を参照してください。

3.3 intptr (プラットフォーム依存整数型)

intptr はプラットフォーム依存サイズの整数型で、x86 ビルドでは 32bit、x64 ビルドでは 64bit のスロットを使用します。 HANDLE や LPxxx 系のポインタ引数を含む DLL 関数を 1 つの HSP source で **両プラットフォーム共通** に書けます。 hsp3net 専用 (vanilla hsp3 では未サポート)。

11.1 用途

従来は x86 / x64 で int / int64 を使い分ける必要があり、 ポインタ系の引数が出てくるたびに #ifdef __hsp64__ 等での切り替えが必要でした。 intptr を使えば 1 行で両対応できます。

11.2 使用可能な #directive

11.3 使用例

#uselib "user32.dll"
#cfunc GetWindowLongPtr "GetWindowLongPtrW" intptr, int
#func  SetWindowLongPtr "SetWindowLongPtrW" intptr, int, intptr

#uselib "kernel32.dll"
#cfunc LoadLibraryW "LoadLibraryW" wstr
#func  FreeLibrary  "FreeLibrary"  intptr
#cfunc GetProcAddress "GetProcAddress" intptr, str

    hmod = LoadLibraryW("user32.dll")    ; intptr 戻り値 → 自動的に platform-sized
    fnPtr = GetProcAddress(hmod, "MessageBoxW")
    FreeLibrary hmod                      ; intptr 引数 → 自動的に正しいサイズで渡る

3.4 連想配列 (MAP 型)

IronHSP では 文字列キーで値にアクセスできる連想配列 (MAP) を変数型として組み込みサポートしています。 内部は std::unordered_map<std::string, std::string> で実装されており、キー・値ともに文字列として保持されます。 代入時に int / double / int64 は自動的に文字列へ変換されます。

変数の作成

dimmap mymap     ; 連想配列を作成

値の読み書き

; 書き込み — map("key") = value
mymap("name") = "HSP"
mymap("year") = "2026"
mymap("score") = 100        ; int → "100" に自動変換

; 読み取り — map("key") で文字列が返る
mes mymap("name")            ; → "HSP"

; 変数キー
key = "name"
mes mymap(key)               ; → "HSP"

ヘルパー関数・命令

全キーの列挙

n = mapcount(mymap)
repeat n
    k = mapkey(mymap, cnt)
    mes k + " = " + mymap(k)
loop

注意事項

• 値は内部で 文字列として保持 されます。数値として使う場合は int() / double() で変換してください
• 未登録のキーを読み取ると 空文字列 "" が返ります (エラーにはなりません)
• mapkey() の列挙順序は 挿入順とは限りません (unordered_map のため)
• MAP 変数は通常の配列 (dim) との併用はできません。dimmap で作成した変数は MAP 専用です
• vartype() は 12 (HSPVAR_FLAG_MAP) を返します

4. .NET 連携機能

4.1 .NET 命令一覧

4.2 変数型 HSPVAR_FLAG_NETOBJ

HSPVAR_FLAG_NETOBJ = 9 として登録されるユーザー定義型です。.NET オブジェクトへの参照を HSP 変数として保持します。

内部的には GCHandle によってネイティブポインタとして保持し、GC による回収を防ぎます。delnet または popnet のスコープ管理によって解放されます。

4.3 Hsp3Net クラス（内部 API）

C++/CLI の管理クラス tv::hsp::net::Hsp3Net が .NET 連携の中核です。主要な機能:

• 型生成: プリミティブ型（Int8～Int64, Float, Double, String 等）のラッパー生成
• 配列操作: 多次元配列の生成・値の読み書き・長さ取得
• メンバーアクセス: フィールド・プロパティの読み書き、メソッド呼び出し
• 型変換: キャスト、ジェネリック型パラメータ、ref/out/配列パラメータ修飾
• アセンブリ管理: GAC / ファイル / ソースコードからの動的ロード
• 例外管理: 例外スタックの保持と文字列化

4.4 アセンブリの自動解決

newnet でアセンブリ名を指定する際、以下の順序で自動解決されます:

1. 登録済み辞書（loadnet で明示ロードしたもの）
2. AppDomain.CurrentDomain.GetAssemblies() からアセンブリ名で検索
3. Assembly.LoadWithPartialName で動的ロード
4. 全ロード済みアセンブリからクラス名（フルネーム）で検索

アセンブリ名に空文字列 "" を指定すると、ステップ4のクラス名検索が使われます。基本的な型（System.Object 等）は loadnet なしで使用可能です。

; loadnet 不要 — アセンブリ名に "" を指定
newnet pObj, "", "System.Text.StringBuilder", 0, "Hello"

; mcall でメソッド呼び出し
netres net_ret
mcall pObj, "ToString"

; nettoval で HSP の値に変換（関数形式）
; 第2引数: 2=str, 4=int, 3=double
s = nettoval(net_ret, 2)
mes s  ; => "Hello"

4.5 ジェネリクス

クラス名に `N が含まれる場合、newnet は最初のN個の引数をジェネリック型パラメータとして自動認識します。 型パラメータは netobj 変数または型名文字列で指定できます。

; List<String> を作成
newnet pList, "", "System.Collections.Generic.List`1", 0, "System.String"
mcall pList, "Add", "Alpha"
mcall pList, "Add", "Beta"
netres ret
mcall pList, "get_Count"
v = nettoval(ret, 4)    ; => 2

; Dictionary<String, Int32> を作成
newnet pDict, "", "System.Collections.Generic.Dictionary`2", 0, "System.String", "System.Int32"
tonet pVal, 100
mcall pDict, "Add", "key1", pVal

4.6 enumnet の拡張

enumnet の第2引数は、従来の netobj 変数に加えてアセンブリ名文字列でも指定可能です。 空文字列を指定するとロード済み全アセンブリから自動検索します。

; アセンブリ名文字列で指定
enumnet pFill, "System.Windows.Forms", "System.Windows.Forms.DockStyle", "Fill"

; 空文字列で全アセンブリ自動検索
enumnet pTop, "", "System.Windows.Forms.DockStyle", "Top"

; 従来通り netobj 変数でも指定可能
enumnet pDR, pDockPanel, "WeifenLuo.WinFormsUI.Docking.DockState", "DockRight"

; Enum → int / str 変換
v = nettoval(pFill, 4)   ; => 5 (DockStyle.Fill の整数値)
s = nettoval(pFill, 2)   ; => "Fill"

4.7 フィールドアクセス ($prefix)

netobj 変数の連想配列記法で $ プレフィックスを付けるとフィールドに、付けないとプロパティにアクセスします。 nettoval と組み合わせてフィールド値を直接取得可能です。

; フィールド読み取り
s = nettoval(pObj("$FieldName"), 2)

; フィールド書き込み
pObj("$FieldName") = "new value"

; プロパティアクセス（$なし）
s = nettoval(pObj("Text"), 2)

4.8 formsaddctrl

HSP ウィンドウに .NET コントロールを追加する命令です。GUI版ランタイムのみ対応（CL版では非サポート）。

; formsaddctrl outvar, type, "text", x, y, w, h [, wid]
; type: 0=Button, 1=CheckBox, 2=TextBox, 3=ComboBox, 4=ListBox
formsaddctrl pBtn, 0, "OK", 10, 10, 100, 30
formsaddctrl pChk, 1, "Enable", 10, 50, 120, 24
formsaddctrl pTxt, 2, "input here", 10, 80, 200, 24

4.9 netdelegate (HSPラベル → .NETデリゲート)

HSP のラベル（サブルーチン）を .NET のデリゲートに変換します。 イベントハンドラ登録やコールバック渡しに使用できます。

; EventHandler デリゲートを生成
netdelegate pHandler, "EventHandler", *on_click

; Button.Click に登録
newnet pBtn, "", "System.Windows.Forms.Button", 0
mcall pBtn, "add_Click", pHandler
stop

*on_click
    mes "Button clicked!"
    return

4.10 netlinq (LINQ 操作)

コレクションに対して LINQ 操作を C# ラムダ式文字列で実行します。 内部的に C# コードを動的コンパイルして実行します。

; List<String> を作成
newnet pNames, "", "System.Collections.Generic.List`1", 0, "System.String"
mcall pNames, "Add", "Alice"
mcall pNames, "Add", "Bob"
mcall pNames, "Add", "Charlie"

; Where: 条件フィルタ
netlinq pFiltered, pNames, "Where", "x => x.Length > 3"

; Select: 射影
netlinq pUpper, pNames, "Select", "x => x.ToUpper()"

; OrderBy: ソート
netlinq pSorted, pNames, "OrderBy", "x => x.Length"

; First / Count (引数なし)
netlinq pFirst, pNames, "First", ""
netlinq pCount, pNames, "Count", ""

; チェーン: Where → ToList
netlinq pW, pNames, "Where", "x => x.StartsWith(\"A\")"
netlinq pList, pW, "ToList", ""

4.11 GlobalAccess クラス（メモリ管理）

.NET オブジェクトのネイティブポインタを管理する静的クラスです。

• CreateNativePtr() — GCHandle を確保してネイティブポインタを返す
• GetNativePtrToNetClass() — ポインタから NetClass を復元する
• Free() — GCHandle を解放する
• PushNativePtrCurrentStack() / PopNativePtrCurrentStack() — スコープベースの自動解放

4.12 例外処理とエラー報告

.NET の例外が発生した場合のエラー報告には2つのモードがあります。neterror 命令で切り替えます。

netexerr() 関数

最後に発生した .NET 例外の情報を文字列で返す関数です。引数でモードを指定できます:

使用例 1: stat チェック + netexerr

newnet pObj, "System", "System.NoSuchClass", 0
if stat = -1 {
    mes "エラー: " + netexerr()
    mes "例外型: " + netexerr(1)
}

使用例 2: onerror で一括捕捉

neterror 1
onerror goto *err_handler
newnet pObj, "System", "System.NoSuchClass", 0
stop

*err_handler
    dialog "例外: " + netexerr()
    end

プロパティ代入時の自動型変換

.NET プロパティ/フィールドへの代入時、以下の自動型変換が行われます:

• bool 変換: int 値を代入すると、0 = false / 非0 = true に変換
• Enum 変換: int 値を Enum 型プロパティに代入すると、Enum.ToObject() で自動変換

; int → Enum の自動変換例
pEH("Dock") = 5         ; DockStyle.Fill (int → DockStyle 列挙型)
pBtn("FlatStyle") = 0   ; FlatStyle.Flat (int → FlatStyle 列挙型)
pChk("CheckState") = 1  ; CheckState.Checked

5. WinForms 統合

5.1 screen 命令と Form

IronHSP では screen 命令で生成されるウィンドウは System.Windows.Forms.Form（HspForms2 クラス）です。 HSP の描画命令（mes, boxf, color 等）は HWND 経由の GDI 描画として Form 上にそのまま表示されます。

5.2 GUI オブジェクトの .NET コントロール化

HSP の GUI オブジェクト命令は、.NET の WinForms コントロールとして生成され、Form.Controls コレクションに自動的に登録されます。

.NET コントロールの Win32 コントロール ID は SetWindowLongPtr(GWLP_ID) で設定され、 HSP の既存の WM_COMMAND ベースのイベントルーティングがそのまま動作します。

5.3 getforms による Form アクセス

getforms 命令で HSP ウィンドウ ID から Form インスタンスを .NET オブジェクトとして取得できます。 取得した Form に対して mcall でプロパティの読み書きやメソッド呼び出しが可能です。

; Form を取得
getforms pForm, 0

; Form.Text を読み取り
netres net_ret
mcall pForm, "get_Text"
s = nettoval(net_ret, 2)
mes "Title: " + s

; Form.Text を変更
mcall pForm, "set_Text", "New Title"

; Controls.Count を取得
netres net_controls
mcall pForm, "get_Controls"
netres net_count
mcall net_controls, "get_Count"
cnt = nettoval(net_count, 4)
mes "Controls: " + cnt

; .NET Button を追加
newnet pButton, "", "System.Windows.Forms.Button", 0
mcall pButton, "set_Text", ".NET Button"
mcall pButton, "set_Left", 300
mcall pButton, "set_Top", 10
mcall pButton, "set_Width", 150
mcall pButton, "set_Height", 35
mcall net_controls, "Add", pButton

5.4 HSP と .NET コントロールの共存

HSP の button 等で作成したコントロールと、newnet + mcall で作成した .NET コントロールは 同一の Form 上で共存します。両方とも Form.Controls に登録されます。

5.5 システム変数 hwnd / hinstance / hdc

以下のシステム変数で、現在アクティブなスクリーン (gsel で選択中) の情報を取得できます。

5.6 外部 .NET ライブラリとの連携

NuGet パッケージ等の外部 .NET ライブラリは loadnet (opt=2: ファイルパス) でロードして使用できます。 以下のライブラリで動作確認済みです。

; Newtonsoft.Json の使用例
loadnet "Newtonsoft.Json.dll", 2
newnet pJObj, "Newtonsoft.Json", "Newtonsoft.Json.Linq.JObject", 1
netres rParsed
mcall pJObj, "Parse", "{\"name\":\"IronHSP\",\"version\":3}"
netres rName
mcall rParsed, "get_Item", "name"
mes nettoval(rName, 2)   ; => "IronHSP"

; NAudio の使用例
loadnet "NAudio.Core.dll", 2
newnet pFmt, "", "NAudio.Wave.WaveFormat", 0, 44100, 2
netres rSR
mcall pFmt, "get_SampleRate"
mes nettoval(rSR, 4)     ; => 44100

6. コンパイラ拡張 (hspcmp)

IronHSP のコンパイラ (hspcmp) に追加された言語拡張機能です。構造体定義、DLL 関数の戻り値拡張、COM コールバック、Allman ブレーススタイルなどが含まれます。

6.1 Allman ブレーススタイル

従来の HSP では if / else のブロック開始 { は 同じ行に書く必要がありました:

; 従来の書き方 (K&R スタイル) — vanilla HSP / IronHSP 両方で動作
if n > 0 {
    mes "positive"
} else {
    mes "not positive"
}

IronHSP の hspcmp では、C / C# 等で一般的な Allman ブレーススタイル (改行 {) もサポートします:

; Allman スタイル — IronHSP 専用
if n > 0
{
    mes "positive"
}
else
{
    mes "not positive"
}

サンプル: package/win32/sample/basic/allman_brace.hsp

6.2 構造体・共用体

#defstruct / #defunion プリプロセッサディレクティブで C 言語互換の構造体・共用体を定義できます。 Windows API や DxLib のような C 構造体を直接扱う場合に便利です。 構造体変数は専用の HSPVAR_FLAG_NSTRUCT 変数型として確保され、 代入は同型同サイズのバイト列コピー (memcpy) として処理されます。

#defstruct POINT
#field int x
#field int y
#endstruct

stdim pt, POINT
pt->x = 100
pt->y = 200
mes "x=" + pt->x + " y=" + pt->y
mes "size=" + varsize(POINT)   ; → 8

定義ディレクティブ

サポートするメンバ型

整数型

浮動小数点型

論理型

配列・文字列型

複合型

変数の宣言 (stdim)

構造体型の変数を確保するには stdim 命令を使います。 内部では HSPVAR_FLAG_NSTRUCT 型の PVal が確保されます。

#defstruct VECTOR, pack=1
#field float x
#field float y
#field float z
#endstruct

stdim v, VECTOR              ; 1要素 (12 byte) を確保
stdim arr, VECTOR, 10        ; 構造体配列 (12 byte × 10 要素 = 120 byte)

v->x = 1.5
v->y = 2.5
v->z = 3.5

arr(2)->x = 100.0            ; 配列要素のメンバアクセス

構造体名は定数として扱える

#defstruct で定義した構造体名は、#endstruct の時点で プリプロセッサ定数 (LAB_TYPE_PPVAL) として登録されます。値は構造体の合計バイトサイズです。 このため、構造体名をそのまま整数リテラルのように式の中で使えます。

#defstruct VECTOR, pack=1
#field float x
#field float y
#field float z
#endstruct

mes VECTOR                  ; → 12
mes "size = " + VECTOR      ; → "size = 12"
sdim buf, VECTOR * 100      ; VECTOR バイト × 100 個分のバッファ
memcpy dst, src, VECTOR     ; 1 構造体分コピー

varsize() — 構造体サイズ取得

varsize(STRUCT_NAME) も同じく構造体サイズを返します (プリプロセッサ段階で整数リテラルに置換されます)。 VECTOR 単体の記法と完全に等価ですが、他言語経験者には sizeof() 風の記法が 分かりやすい場合に使えます。

mes "VECTOR size = " + varsize(VECTOR)   ; → 12
sdim buf, varsize(VECTOR) * 100          ; バッファ確保にも使える

varsize(変数名) 形式は従来通り変数の確保バイトサイズを返します (#func 関数名を渡すと varptr と同じ要領で関数のサイズが返ります)。

共用体

共用体は全メンバが同一メモリ領域を共有します。最大メンバのサイズが全体サイズになります。

#defunion VARIANT_DATA
#field int iVal
#field float fVal
#field double dVal
#endunion
; size = 8 (double の 8 bytes が最大)

構造体内にインラインの共用体サブブロックを定義する場合も #defunion / #endunion を使います (構造体名は省略します):

#defstruct MY_VARIANT
#field short vt
#defunion
#field int intVal
#field float fltVal
#field double dblVal
#endunion
#endstruct
; size = 16 (vt[2] + padding[6] + union[8])

#defunion は文脈で動作が変わります:

• トップレベル — #defunion 名前 ... #endunion: 共用体型を定義 (名前は varsize() や型として参照可能)
• #defstruct 内 — #defunion ... #endunion (名前なし): 構造体内のサブ共用体ブロック。 ブロック内の全メンバが同じオフセットを共有します。

配列メンバ

#defstruct MATRIX
#field float m[16]
#endstruct

stdim mat, MATRIX
mat->m(0) = 1.0
mat->m(5) = 1.0

パックアライメント

#defstruct PACKED_STRUCT, pack=1
#field byte flag
#field int value
#endstruct
; size = 5 (パディングなし。pack=1 で詰め詰め配置)

#defstruct DEFAULT_STRUCT
#field byte flag
#field int value
#endstruct
; size = 8 (デフォルト pack=8。flag の後に 3 bytes パディング)

入れ子構造体

#defstruct POINT
#field int x
#field int y
#endstruct

#defstruct RECT
#field POINT topLeft
#field POINT bottomRight
#endstruct

stdim rc, RECT
rc->topLeft->x = 10
rc->topLeft->y = 20
rc->bottomRight->x = 100
rc->bottomRight->y = 200

構造体配列

stdim points, POINT, 10   ; POINT 構造体 10 個分の配列
points(0)->x = 100
points(0)->y = 200
points(1)->x = 300
points(1)->y = 400

DLL 関数への値渡し

#func / #cfunc / #cfuncst のパラメータ型に構造体名を書くと、 構造体を 値渡し (pass by value) で C/C++ 側 DLL に渡せます。 DxLib の VECTOR や Win32 API の POINT, RECT などを直接呼び出せます。

#defstruct VECTOR, pack=1
#field float x
#field float y
#field float z
#endstruct

#uselib "DxLibW.dll"
#func global SetCamPosTarget "dx_SetCameraPositionAndTarget_UpVecY" VECTOR, VECTOR
;                                                                   ↑ 値渡しパラメータ

stdim cpos, VECTOR
cpos->x = 10.0
cpos->y = 50.0
cpos->z = -100.0
stdim ctgt, VECTOR
ctgt->x = 5.0
ctgt->y = 25.0
ctgt->z = 0.0

SetCamPosTarget cpos, ctgt   ; ← 構造体 2 つを値渡し

値渡しと参照渡しの使い分け

同じ C 構造体でも、関数によって「値渡し」と「ポインタ渡し」のどちらで宣言されているかが異なります。 #func 宣言では パラメータ型キーワードで明示的に指定 します:

判断基準:

• 関数が構造体を値で受け取る (C で VECTOR v と書かれている) → VECTOR 等の構造体名を指定
• 関数がポインタで受け取る / 結果を書き戻す (C で VECTOR *v や VECTOR &v) → 従来通り var を指定

DxLib のように構造体値渡しが多用される API では VECTOR, MATRIX などを直接書きます。 逆に Win32 API の GetWindowRect(HWND, LPRECT) のように out 引数として構造体ポインタを取る関数は int, var のままです。

内部実装

1. コンパイラの PP_ReplaceStructParamNames() が #func 行のパラメータリスト中の構造体名を svalN (N = サイズ) に置換。マクロ展開で VECTOR → 12 に化けるのを防ぎます。
2. GetParameterTypeCG() が svalN を MPTYPE_STRUCTVAL (-23) として認識し、 STRUCTPRM->subid に N を格納。
3. ランタイムの code_expand_next() の MPTYPE_STRUCTVAL ハンドラ (hsp3extlib.cpp) が 上記の x86/x64 ABI に従ってバイト列を展開。

内部処理 (構造体パイプライン)

HSP コンパイラ (hspcmp) とランタイム (hsp3) の連携で構造体を処理しています。 プリプロセッサ段階・コード生成段階・実行段階のそれぞれで以下の処理が走ります:

6.3 DLL 関数拡張 (#cfuncd / #cfuncf / #cfuncst)

標準 HSP の #func / #cfunc に加え、IronHSP では戻り値の型に応じた拡張ディレクティブを提供します。

10.1 一覧

10.2 #cfuncd — double 戻り値

C/C++ の DLL 関数が double を返す場合に使用します。

; 構文
#cfuncd global 関数名 "エントリポイント" パラメータ型...

; 例
#uselib "mymath.dll"
#cfuncd global CalcSin "CalcSin" double
#cfuncd global CalcCos "CalcCos" double

; 使用
result = CalcSin(3.14159)  ; result は double 型

戻り値は x87 FPU スタック (x86) または XMM0 レジスタ (x64) から取得し、HSP の double (実数) 型として返されます。

10.3 #cfuncf — float 戻り値

C/C++ の DLL 関数が float を返す場合に使用します。float は HSP 内部で double に変換されます。

; 構文
#cfuncf global 関数名 "エントリポイント" パラメータ型...

; 例
#uselib "mymath.dll"
#cfuncf global GetDistance "GetDistance" float, float, float, float

; 使用
d = GetDistance(0.0, 0.0, 3.0, 4.0)  ; d = 5.0 (double型)

10.4 #cfuncst — 構造体を値で返す DLL 関数

C/C++ の DLL 関数が構造体を値で返す場合に安全に呼び出すための新しいディレクティブです。

背景・問題

標準の #cfunc は戻り値として EAX/RAX（整数 1 つ）しか取得できません。 C/C++ の関数が構造体を値で返す場合、MSVC ABI は隠し第 1 引数（呼び出し元が確保したバッファへのポインタ）を自動挿入し、関数はそこに書き込みます。

// C側: VECTOR を値で返す関数
VECTOR dx_VGet(float x, float y, float z);

// MSVC ABI 実際の呼び出し:
//   x86: push z, push y, push x, push &hidden_buf, call dx_VGet
//   x64: rcx=&hidden_buf, xmm1=x, xmm2=y, xmm3=z, call dx_VGet

#cfunc はこの隠しポインタを挿入しないため、スタック破壊やクラッシュの原因になります。

構文

新構文 (推奨、構造体名指定):

#cfuncst global 構造体名 関数名 "エントリポイント" [パラメータ型...]

旧構文 (サイズ指定、引き続きサポート):

#cfuncst global 関数名 "エントリポイント" 構造体サイズ, パラメータ型...

新構文の特徴

• サイズ自動計算: #defstruct の定義からサイズが自動取得されるため、手動指定が不要
• NSTRUCT 戻り値: 戻り値は HSPVAR_FLAG_NSTRUCT 型として返るため、 標準の '=' 代入経路 (HspVarCoreClearWC + Set) で自動的にコピーされる
• dim 省略可能: strmid(...) の戻り値が代入先変数を自動的に文字列型にするのと同じ要領で、 v = GetCameraTarget() だけで v は自動的に構造体型として確保される (事前の stdim 不要)
• メンバアクセス: 代入後すぐに vec->x のようなメンバアクセスが可能 (PP_DetectCfuncstAssign が変数 → 構造体ID メタデータを記録するため)

使用例 (新構文)

#defstruct VECTOR, pack=1
#field float x
#field float y
#field float z
#endstruct

#uselib "DxLibW.dll"
#cfuncst global VECTOR GetCameraTarget "dx_GetCameraTarget"
#cfuncst global VECTOR GetCameraPosition "dx_GetCameraPosition"

; パターン1: stdim で明示的に確保してから代入
stdim tgt, VECTOR
tgt = GetCameraTarget()
mes "tgt: " + tgt->x + ", " + tgt->y + ", " + tgt->z

; パターン2: dim 省略 (NSTRUCT サイズヒントによる自動確保)
pos = GetCameraPosition()
mes "pos: " + pos->x + ", " + pos->y + ", " + pos->z

使用例 (旧構文)

; DxLib の VECTOR 構造体 (12バイト: float x, y, z)
#uselib "DxLibW.dll"
#cfuncst global VGet "dx_VGet" 12, float, float, float
#cfuncst global VAdd "dx_VAdd" 12, var, var

; 使用
p = VGet(1.0, 2.0, 3.0)
; 旧構文では戻り値は HSPVAR_FLAG_NSTRUCT になるが、
; メンバ名 → 構造体ID 紐付けはないので -> アクセスはできない
; (構造体名指定の新構文を推奨)

内部実装

入れ子呼び出しの安全性

#cfuncst 関数は式の中で入れ子にできます:

result = VAdd(VGet(1,0,0), VGet(0,1,0))
; VGet(1,0,0) → slot 0
; VGet(0,1,0) → slot 1
; VAdd        → slot 2 (自身の戻り値用) + slot 0,1 を引数として参照
; すべてのスロットが DLL 呼び出し時点で有効

内部ではスタック方式のバッファプール（16 スロット × 4096 バイト = 64KB）を使用:

• 各 #cfuncst 呼び出しは新しいスロットを確保（sret_ring_index++, sret_depth++）
• 呼び出し完了で sret_depth--
• 最外レベル（sret_depth == 0）に戻った時点で sret_ring_index = 0 にリセット → 全スロット解放
• 入れ子が 16 段を超えると HSPERR_STACK_OVERFLOW エラー

パラメータ型一覧

#cfuncst は #cfunc と同じパラメータ型キーワードが使えます:

10.5 全ディレクティブ比較

10.6 可変長引数 (...) IronHSP

C の printf 系のような 可変長引数 (variadic) DLL 関数を HSP から直接呼べます。 パラメータリスト末尾に ... を記述すると、呼び出しごとに異なる数・型の引数を渡せます。

#uselib "msvcrt.dll"
#cfunc crt_sprintf "sprintf" var, str, ...

sdim s, 256
n = crt_sprintf(s, "%d + %.2f", 42, 3.14)
mes s   ; → "42 + 3.14"

; 引数の数・型は呼び出しごとに変えられる
n = crt_sprintf(s, "%s=%d", "count", 100)
mes s   ; → "count=100"

構文

; 命令版 (stat に戻り値)
#func global myfunc "entry_name" 固定パラメータ, ...

; 関数版 (戻り値 = int)
#cfunc global myfunc "entry_name" 固定パラメータ, ...

; double 戻り値
#cfuncd global myfunc "entry_name" 固定パラメータ, ...

型推論ルール

可変長部分の各引数は、HSP の式評価結果から自動的に型が決まります:

制限事項

• 可変長引数は最大 64 個まで (固定パラメータ含む)
• ... はパラメータリストの末尾にのみ記述可能 (C 言語と同じ制約)
• x64 の variadic ABI (float/double を整数レジスタにもコピー) は自動で処理される
• #func (命令版) と #cfunc (関数版) の両方で使用可能

6.4 COM コールバック (#defcbcom)

IDropTarget や IBindStatusCallback のように HSP 側で実装して外部 COM API に渡す COM コールバックインターフェースを宣言・実装するための言語拡張。 hsp3net 専用。

IUnknown の QueryInterface / AddRef / Release は runtime が自動実装するので、 ユーザーは vtable index 3 以降の実メソッドだけを HSP ラベルにマッピングすればよい。 動的 vtable トランポリンは x86 / x64 両対応。

12.1 構文

#defcbcom <CLASS_NAME> <IFACE_NAME>
    #cbmethod <vtable_idx> <ret_type> <arg_types...>, *<label>
    ...
#endcbcom

12.2 引数型

12.3 callback 実行コンテキスト関数

12.4 使用例 (IBindStatusCallback)

#define IID_IBindStatusCallback "{79eac9c1-baf9-11ce-8c82-00aa004ba90b}"
#usecom IBindStatusCallback IID_IBindStatusCallback "{}"

#defcbcom MyBSC IBindStatusCallback
    #cbmethod 3  int int, comobj,                  *bsc_start
    #cbmethod 4  int intptr,                       *bsc_priority
    #cbmethod 5  int int,                          *bsc_lowres
    #cbmethod 6  int int, int, int, wstr,          *bsc_progress
    #cbmethod 7  int int, wstr,                    *bsc_stop
    #cbmethod 8  int intptr, intptr,               *bsc_bindinfo
    #cbmethod 9  int int, int, intptr, intptr,     *bsc_data
    #cbmethod 10 int intptr, comobj,               *bsc_object
#endcbcom

#uselib "urlmon.dll"
#cfunc URLDownloadToFile "URLDownloadToFileW" intptr, wstr, wstr, intptr, comobj

    newcomcb cb, "MyBSC", "session_1"
    hr = URLDownloadToFile(0, "https://www.example.com/", "ex.html", 0, cb)
    delcom cb
    end

*bsc_progress
    mes "[" + comcbtags() + "] " + comprm(0) + "/" + comprm(1)
    comret 0 : return

*bsc_start    : comret 0 : return
*bsc_priority : comret 0 : return
*bsc_lowres   : comret 0 : return
*bsc_stop     : comret 0 : return
*bsc_bindinfo : comret 0 : return
*bsc_data     : comret 0 : return
*bsc_object   : comret 0 : return

7. ランタイム拡張

IronHSP のランタイムに追加されたコア機能です。ネイティブコールバックによる関数ポインタ生成と、環境変数・コマンドライン引数の組み込みサポートを提供します。

7.1 ネイティブコールバック (setcallback / callbackarg)

Win32 API には EnumWindows, EnumFontFamiliesEx, SetTimer, qsort など、C 関数ポインタをコールバックとして受け取る API が多数存在します。バニラ HSP ではこれらを直接呼ぶ手段がありませんでしたが、IronHSP の setcallback 命令を使うと HSP のラベルを C 関数ポインタに変換 でき、任意のコールバック API を利用できます。

.NET は不要で、hsp3net の全ランタイム (GUI / CL / 32bit / 64bit) で動作します。

API リファレンス

戻り値の仕組み

コールバックラベル内で return N を実行すると、stat に N が設定されます。thunk はラベル実行後に hsp_thunk_getstat() を呼んで stat の値を C の戻り値として返します。たとえば EnumWindows では return 1 で列挙続行、return 0 で停止です。

例 1: EnumWindows でウィンドウ列挙

; EnumWindows: BOOL CALLBACK EnumWindowsProc(HWND, LPARAM)
#uselib "user32.dll"
#func EnumWindows "EnumWindows" int, int

setcallback pFunc, *on_enum, 2   ; 引数2個のコールバック
enum_count = 0
EnumWindows pFunc, 0
mes "ウィンドウ数: " + enum_count
stop

*on_enum
    hwnd_val = callbackarg(0)    ; 第1引数 (HWND)
    lparam_val = callbackarg(1)  ; 第2引数 (LPARAM)
    enum_count++
    return 1                     ; 1 → 列挙続行、0 → 停止

例 2: EnumFontFamiliesEx でフォント列挙

; EnumFontFamiliesExW: int CALLBACK EnumFontFamExProc(LOGFONTW*, TEXTMETRICW*, DWORD, LPARAM)
#uselib "gdi32.dll"
#func EnumFontFamiliesExW "EnumFontFamiliesExW" int, var, int, int, int

; LOGFONTW 構造体は 92 バイト、lfFaceName は offset 28 (wchar_t[32])
setcallback pFunc, *on_font, 4

sdim lf, 92
EnumFontFamiliesExW hdc, lf, pFunc, 0, 0
stop

*on_font
    ; 第1引数 = LOGFONTW* ポインタ
    ptr_lf = callbackarg(0)
    dupptr buf_lf, ptr_lf, 92
    ; lfFaceName (offset 28, wchar_t[32] = 64 bytes)
    sdim wname, 64
    memcpy wname, buf_lf, 64, 0, 28
    ; UTF-16 → UTF-8 変換
    sdim uname, 128
    WideCharToMultiByte 65001, 0, wname, -1, uname, 128, 0, 0
    mes uname
    return 1

例 3: タイマーコールバック

; SetTimer: VOID CALLBACK TimerProc(HWND, UINT, UINT_PTR, DWORD)
#uselib "user32.dll"
#func SetTimer "SetTimer" int, int, int, int
#func KillTimer "KillTimer" int, int

setcallback pTimer, *on_timer, 4
SetTimer hwnd, 1, 1000, pTimer   ; 1秒間隔

*on_timer
    mes "Timer fired!"
    return

内部実装: 動的 thunk 生成

setcallback は VirtualAlloc(NULL, size, MEM_COMMIT|MEM_RESERVE, PAGE_EXECUTE_READWRITE) で実行可能メモリを確保し、プラットフォーム固有のマシン語を動的に書き込みます。

処理フローは以下の通りです:

C API がコールバック呼び出し
  ↓
thunk マシン語が引数を args[] に退避
  ↓
hsp_thunk_bridge(thunk) を呼び出し
  ↓
  hsp_callback_current = thunk  (現在のコンテキストを設定)
  code_callback(thunk->label)   (HSP ラベルにジャンプ)
  ↓
  HSP ラベル内で:
    callbackarg(n) → thunk->args[n] を返す
    return N       → hspctx->stat = N
  ↓
hsp_thunk_getstat() → stat の値を EAX/RAX に返す
  ↓
C API に戻り値が返る

7.2 環境変数・コマンドライン引数

バニラ HSP には環境変数操作やコマンドライン引数の構造化パースが存在しません。IronHSP では以下の命令・関数を組み込みで提供しています。全て UTF-8 で処理され、日本語を含むパスや値も正しく扱えます。

環境変数操作

; PATH 環境変数を取得
path_val = getenv("PATH")
mes path_val

; 自作の環境変数を設定
setenv "MY_APP_MODE", "production"
mes getenv("MY_APP_MODE")           ; → "production"

; 未定義の場合のデフォルト値
port = getenv("PORT", "3000")       ; PORT 未定義なら "3000"

; 存在確認
if hasenv("USERPROFILE") {
    mes "home = " + getenv("USERPROFILE")
}

; 削除
delenv "MY_APP_MODE"

コマンドライン引数

内部で CommandLineToArgvW(GetCommandLineW()) を初回呼び出し時に 1 回だけ実行し、結果を UTF-8 変換してキャッシュします。以降の呼び出しではキャッシュから即座に返します。

; 全引数を表示
n = getcmdargc()
mes "引数 " + n + " 個:"
repeat n
    mes "  [" + cnt + "] " + getcmdarg(cnt)
loop

; 名前付き引数 (Python の argparse 風)
; 実行例: program.exe --port 8080 --name "テスト" --verbose
port = getcmdargi("--port", 3000)       ; → 8080
name = getcmdargs("--name", "default")  ; → "テスト"
verbose = hascmdarg("--verbose")        ; → 1

mes "port=" + port + " name=" + name + " verbose=" + verbose

8. Win32 API 大幅拡充 (CsWin32 bridge)

OpenHSP 標準同梱の package/win32/common/user32.as / kernel32.as / gdi32.as 等は古く (sptr ベース、構造体未対応、x64 で破綻ぎりぎり、ANSI/Unicode 判別曖昧)、 kernel32.dll の 1449 exports に対して 67 関数 (4%) しかカバーできていなかった。これを Microsoft の win32metadata + Microsoft.Windows.CsWin32 source generator を経由した自動生成パイプラインで 体系的に再構築した。

15.2 ディレクトリ構成

tools/cswin32_bridge/                ← Plain DllImport 用 (allowMarshaling=false)
├── Win32Gen.csproj                 ← .NET 8 + Microsoft.Windows.CsWin32 source generator
├── NativeMethods.txt               ← 生成したい API 一覧 (~5300 行、コメントアウト含む)
├── NativeMethods.json              ← CsWin32 オプション
├── NativeMethods_full.txt          ← dump_exports.py の出力 (ROM)
├── dump_exports.py                 ← dumpbin /exports → 候補抽出
├── filter_unsupported.py           ← PInvoke001/003/005 警告から非対応 API をコメントアウト
├── gen_from_cswin32.py             ← C# パース → .as / .hs 出力
├── split_for_translation.py        ← docs_en.json → per-DLL チャンク
├── merge_translations.py           ← per-DLL .ja.json → docs_ja.json マージ
├── docs_en.json                    ← 英語 doc 中間キャッシュ (25341 entries)
├── docs_ja.json                    ← 日本語訳キャッシュ (25422 entries)
└── translate_chunks/               ← 翻訳 subagent 用ワークスペース

tools/cswin32_bridge_com/            ← COM インターフェース用 (allowMarshaling=true)
├── Win32Com.csproj
├── NativeMethods.txt               ← IShellLinkW / IFileDialog / IDropTarget / ID2D1Factory /
│                                       IDWriteFactory / IWICImagingFactory / IDXGIFactory 等
├── gen_com_from_cswin32.py         ← [ComImport] interface → #usecom + #comfunc
├── docs_en.json (2951 entries)
└── docs_ja.json (2951 entries)

package/win32/common/
├── win32_types_gen2.as             ← 共有: 734 NSTRUCT + 608 enum 定数 (各 DLL .as が #include)
├── kernel32_gen2.as (881 funcs)
├── user32_gen2.as   (606 funcs)
├── advapi32_gen2.as (419 funcs)
├── oleaut32_gen2.as (404 funcs)
├── gdi32_gen2.as    (384 funcs)
├── ... (合計 30 DLL)
└── com_misc_gen2.as                ← 118 COM interface (#usecom + #comfunc)

package/hsphelp/
├── win32_kernel32_gen2.hs          ← 日本語 MSDN ヘルプ (HSP3 .hs 形式)
├── win32_user32_gen2.hs
├── ... (合計 30 DLL + com_misc)

15.3 パイプライン

1. dump_exports.py: C:\Windows\System32\*.dll を dumpbin /exports で走査 → 5631 候補抽出 → NativeMethods_full.txt
2. NativeMethods.txt として配置 → dotnet build -c Release で CsWin32 が obj/generated/.../*.g.cs に C# P/Invoke 署名 + XML doc コメントを emit
3. filter_unsupported.py: PInvoke001 / 003 / 005 警告から非対応 API を // removed: <reason> でコメントアウト (削除せず audit 用に残す)
4. iterate (2)→(3) until clean (実測 3 round)
5. gen_from_cswin32.py: C# を regex parse → 型マッピング → <dll>_gen2.as + win32_<dll>_gen2.hs を SJIS / CRLF で emit、docs_en.json も dump
6. 翻訳パス: split_for_translation.py で per-DLL チャンク化 → 並列 subagent で翻訳 → merge_translations.py で docs_ja.json に集約
7. (5) を再実行すると docs_ja.json をルックアップして日本語版 .hs を出力

15.4 採用根拠 (vs libclang 直接 parse)

初期は libclang Python binding で Windows SDK ヘッダを直接 parse する案 (tools/gen_winapi_as.py) を検討したが、以下の理由で CsWin32 経由に切り替えた:

• typedef 保持: libclang は cursor.type.spelling で HWND が int に脱糖される (token hack で回避は可能だが脆弱)。CsWin32 は型情報を完全に保持
• A/W 自動選択: libclang では #define MessageBox MessageBoxW を追跡する必要があるが、win32metadata は最初から W バリアントを別エントリで持っている
• 定数 enum 群: libclang では #define SW_HIDE 0 系を全部マクロ展開で拾う必要があるが、win32metadata は SHOW_WINDOW_CMD enum として整理済み
• parse error ゼロ: libclang は winuser.h で 20 件の parse error が出る
• MSDN doc: CsWin32 は api-docs.msgpack 経由で MSDN の関数 / 引数 / 戻り値説明を XML コメントとして埋め込む。これがそのまま .hs ファイルの源泉になる
• COM サポート: allowMarshaling=true モードで [ComImport] 属性付き C# interface を生成 → #usecom / #comfunc 形式に変換可

15.5 カバー DLL 一覧 (関数数)

Phase E (commit 31765549, 2026-04-14) で +12 DLL / +395 関数 追加: ws2_32 (90), iphlpapi (194), urlmon (71), d2d1, dwrite, windowscodecs, dxgi, d3d11, xaudio2_8, dinput8, secur32, bonus xaudio2_8。

Phase F (commit 92722d93, 2026-04-14) で +9 DLL / +1287 関数 追加: gdiplus (627, GDI+ 高レベル 2D), opengl32 (353, OpenGL 1.1 + wgl*), glu32 (52, GLU ユーティリティ), httpapi (42, HTTP Server API), xmllite (6, fast XML), wlanapi (59), wer (20), powrprof (84, Power), wtsapi32 (44, Terminal Services)。

15.6 COM インターフェース (118 / 1238 method)

tools/cswin32_bridge_com/ は allowMarshaling=true オプションで CsWin32 を駆動する。[ComImport] 属性付きの flat な C# interface が生成され、これを gen_com_from_cswin32.py がパースして HSP の #usecom + #comfunc 形式に変換する。CsWin32 は親インターフェースのメソッドを new 修飾子付きで flatten 出力するので、vtable スロット計算は本文内のメソッド順 = base + index (IUnknown ベースなら base=3、IDispatch ベースなら base=7) で済む。

カバーされている主要 COM:

• シェル / ダイアログ: IShellLinkW, IPersistFile, IModalWindow, IFileDialog, IFileOpenDialog, IFileSaveDialog, IShellItem, IShellItemArray, IFileDialogEvents
• ドラッグ&ドロップ / クリップボード: IDropTarget, IDropSource, IDataObject, IEnumFORMATETC
• OLE / バインド: IBindStatusCallback, IBindCtx, IMoniker, IRunningObjectTable, IPersistFile, IPropertyStore, IPropertyDescriptionList, IStream
• Direct2D: ID2D1Factory, ID2D1RenderTarget, ID2D1HwndRenderTarget, ID2D1BitmapRenderTarget, ID2D1Bitmap, ID2D1SolidColorBrush, ID2D1LinearGradientBrush, ID2D1RadialGradientBrush, ID2D1Geometry, ID2D1PathGeometry, ID2D1RectangleGeometry, ID2D1RoundedRectangleGeometry, ID2D1EllipseGeometry, ID2D1StrokeStyle 等
• DirectWrite: IDWriteFactory, IDWriteTextFormat, IDWriteTextLayout, IDWriteFontCollection, IDWriteFontFamily, IDWriteFont, IDWriteFontFace, IDWriteTextAnalyzer, IDWriteInlineObject 等
• WIC: IWICImagingFactory, IWICBitmap, IWICBitmapSource, IWICBitmapDecoder, IWICBitmapFrameDecode, IWICBitmapEncoder, IWICBitmapFrameEncode, IWICFormatConverter, IWICStream, IWICBitmapLock, IWICBitmapClipper, IWICBitmapScaler, IWICColorContext, IWICPalette 等
• DXGI: IDXGIFactory, IDXGIAdapter, IDXGIDevice, IDXGISwapChain, IDXGIOutput, IDXGISurface

15.7 既知の制約

• comdlg32 の OPENFILENAMEW 系構造体は AnyCPU 非互換 (PInvoke005) で GetOpenFileName / GetSaveFileName / ChooseColor / ChooseFont / PrintDlg は生成不可 → 代替として IFileOpenDialog / IFileSaveDialog COM インターフェースを使う想定
• POINTL など 8byte 値渡し構造体は COM パーサが現状 int にフォールバック (将来 intptr 経由で対応予定)
• Winsock (ws2_32) は sockaddr 系の union 多用構造体が特殊で未対応
• DirectX のうち d3d11 / d3d12 / xaudio2 等の重量級 COM 階層は今回は対象外 (Direct2D / DirectWrite / WIC / DXGI のみ)

9. プラグイン & モジュール リファレンス

IronHSP が提供する 151 個の iron_* モジュール、31 個の C++ プラグイン DLL、hspd2d / DxLib / OpenCV 統合 の詳細は別ドキュメントに記載しています:

10. 注意事項・既知の制限

; double を返す DLL 関数の呼び出し例
#uselib "msvcrt.dll"
#cfuncd _sin "sin" double
#cfuncd _cos "cos" double
#cfuncd _sqrt "sqrt" double

mes _sin(3.14159265)    ; => 0.000000 (≈sin(π))
mes _cos(0.0)           ; => 1.000000
mes _sqrt(2.0)          ; => 1.414214

; #cfuncst global VECTOR GetCameraTarget "dx_GetCameraTarget" 相当を
; varptr + callfuncst で組み立てる例

stdim retbuf, VECTOR              ; 戻り値バッファ
dim   prm, 1
prm(0) = varptr(retbuf)           ; prmbuf[0] = 隠しポインタ
addr   = varptr(GetCameraTarget)  ; 関数アドレス (#func 経由で取得)

stdim v, VECTOR
v = callfuncst(prm, addr, 1, varsize(VECTOR))
mes "v = " + v->x + ", " + v->y + ", " + v->z

11. 変更履歴

64bit ビルド対応一覧