~~NOTOC~~
====== ExportOsc(外部との OSC 通信) ======
<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/|こちら]]**になります。
</WRAP>
**[[vci/overview/osc|Open Sound Control プロトコル（OSC）]]**を用いて外部アプリケーションとのメッセージングを行うクラスです。

  * OSC 機能を利用する場合、''タイトル画面>詳細設定''の ''VCI'' タブ内から **OSC 送信機能、OSC 受信機能** を有効化してください。
  * OSC Message の送信/受信先は、''タイトル画面>詳細設定''の ''VCI'' タブ内の **OSCメッセージ受信ポート、OSCメッセージ送信ポート** から設定できます。
    * 受信ポートのデフォルト値は ''19100'' です。
    * 送信ポートのデフォルト値は ''18100'' です。
  * OSC Message の送信は、 ''localhost'' 内でのみ行えます。
  * OSC Message を設定なしで受信できるのは、 ''localhost'' 内のみです。
  * **バーチャルキャスト v2.3.6a** 以降で動作します。
  * 現在、この API は**PC版でのみ動作します**。
  * この API を使ったサンプルは[[vci/sample/oscapi/top|こちらのページ]]にあります。
===== メンバ変数・関数一覧 =====

^ vci.osc ^^
^ 名前 ^ 説明 ^
| [[vci/script/reference/exportosc#types ]] | 送受信できるOSC Argumentの型の列挙子を表すクラスを返す |
| [[vci/script/reference/exportosc#IsSendEnabled ]] | 呼び出し元のVCIインスタンスのOSC Message送信機能の有効フラグを取得 |
| [[vci/script/reference/exportosc#IsReceiveEnabled]] | 呼び出し元のVCIインスタンスのOSC Message受信機能の有効フラグを取得 |
| [[vci/script/reference/exportosc#SendAsciiString]] | ASCII文字列をOSC Messageとして送信 |
| [[vci/script/reference/exportosc#SendInt32 ]] | 32ビット整数をOSC Messageとして送信 |
| [[vci/script/reference/exportosc#SendFloat32 ]] | 32ビット浮動小数をOSC Messageとして送信 |
| [[vci/script/reference/exportosc#SendUtf8String ]] | UTF-8文字列を表すバイト列をOSC Messageとして送信 |
| [[vci/script/reference/exportosc#SendMessage ]] | 引数無しのOSC Messageを送信 |
| [[vci/script/reference/exportosc#SendMessage ]] | 複数個かつ任意の組み合わせのOSC Argumentを持つOSC Messageを送信 |
| [[vci/script/reference/exportosc#RegisterMethod]] | 指定のOSC Addressに送られてきたOSC Messageを受信したときに呼びだされる関数を登録する |
| [[vci/script/reference/exportosc#UnregisterMethod]] | 指定のOSC Addressに登録されている関数の登録を解除する |

===== types =====
<wrap em>vci.osc.types</wrap>** ExportOscType**\\
=== 説明 ===
  * 送受信できる OSC Argument の型の列挙子を表すクラスを返します。\\
  * [[vci:script:reference:exportosc#SendMessage(複数引数を含むメッセージの送信)|vci.osc.SendMessage]] や [[vci:script:reference:exportosc#RegisterMethod|vci.osc.RegisterMethod]] で送受信する OSC Argument を指定する際に利用します。

^列挙子一覧^^
^types.String| ASCII 文字列|
^types.Int32| 32bit 整数|
^types.Float32| 32bit 浮動小数|
^types.BlobAsUtf8| UTF-8 文字列を表すバイト列|

===== IsSendEnabled =====
<wrap em>vci.osc.IsSendEnabled</wrap> **fun(): bool**\\
=== 説明 ===
  * 呼び出し元の VCI インスタンスの OSC Message 送信機能の有効フラグを取得します。\\
  * OSC Message 送信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
    * disabled の場合、すべての VCI インスタンスにおいて false が返されます。
    * enabled の場合、すべての VCI インスタンスにおいて true が返されます。
    * creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

=== サンプル ===

<file lua main.lua>
local isEnabled = vci.osc.IsSendEnabled()
print(isEnabled)
</file>

===== IsReceiveEnabled =====
<wrap em>vci.osc.IsReceiveEnabled()</wrap>**: bool**\\
=== 説明 ===
  * 呼び出し元の VCI インスタンスの OSC Message 受信機能の有効フラグを取得します。\\
  * OSC Message 受信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
    * disabled の場合、すべての VCI インスタンスにおいて false が返されます。
    * enabled の場合、すべての VCI インスタンスにおいて true が返されます。
    * creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

=== サンプル ===

<file lua main.lua>
local isEnabled = vci.osc.IsReceiveEnabled()
print(isEnabled)
</file>

===== SendAsciiString =====
<wrap em>vci.osc.SendAsciiString</wrap> **fun(address: string, argument: string)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|
^argument| OSC Argument として送信する string|

=== 説明 ===
  * ''argument'' をASCII文字列に変換し、''address'' に OSC Message として送信します。
    * こちらの関数では**英字文字列のみ送信することができます。**日本語文字列を送信したい場合、[[vci:script:reference:exportosc#SendUtf8String|vci.osc.SendUtf8String]] を利用してください。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
  * ''argument'' が null の場合、送信に失敗します。この際、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendAsciiString("/test/sendstring", "hello")
</file>

===== SendInt32 =====
<wrap em>vci.osc.SendInt32</wrap> **fun(address: string, argument: number)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|
^argument| OSC Argument として送信する number|

=== 説明 ===
  * ''argument'' を 32bit 整数に変換し、''address'' に OSC Message として送信します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendInt32("/test/sendint", 100)
</file>

===== SendFloat32 =====
<wrap em>vci.osc.SendFloat32</wrap> **fun(address: string, argument: number)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|
^argument| OSC Argument として送信する number|

=== 説明 ===
  * ''argument'' を 32bit 浮動小数に変換し、''address'' に OSC Message として送信します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendFloat32("/test/sendfloat", 3.14)
</file>

===== SendUtf8String =====
<wrap em>vci.osc.SendUtf8String</wrap> **fun(address: string, argument: string)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|
^argument| OSC Argument として送信する string|

=== 説明 ===
  * ''argument'' を UTF-8 としてエンコードしたバイト列に変換し、''address'' に OSC Message として送信します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
  * ''argument'' が null の場合、送信に失敗します。この際、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendUtf8String("/test/sendutf8", "こんにちわ")
</file>

===== SendMessage(引数無しメッセージの送信) =====
<wrap em>vci.osc.SendMessage</wrap> **fun(address: string)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|

=== 説明 ===
  * ''address'' に引数無しの OSC Message を送信します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendMessage("/test/sendmessage")
</file>

===== SendMessage(複数引数を含むメッセージの送信) =====
<wrap em>vci.osc.SendMessage</wrap> **fun(address: string, arguments: Table)**\\

=== 引数 ===
^address| OSC Message の送信先の OSC Address|
^arguments| 送信する OSC Argument の型と値を列挙したテーブル|

''arguments'' テーブルは、以下のフォーマットで記述します。
<file lua arguments_table.lua>
-- {
--   {(OSC Argumentの型), (OSC Argumentの値)}
--   ..., 送信するOSC Argumentの個数分繰り返す
-- }

-- 例：String, Int32, Float32, BlobAsUtf8をOSC Messageとして送信する
arguments = 
{
  {vci.osc.types.String, "hello"},
  {vci.osc.types.Int32, 10},
  {vci.osc.types.Float32, 3.14},
  {vci.osc.types.BlobAsUtf8, "こんにちわ"},
}
</file>

=== 説明 ===
  * ''arguments''テーブルで指定した複数の OSC Argumentを一つの OSC Message として''address''に送信します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、送信に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
vci.osc.SendMessage("/test/sendMultiple", 
{
  {vci.osc.types.String, "hello"},
  {vci.osc.types.Int32, 10},
  {vci.osc.types.Float32, 3.14},
  {vci.osc.types.BlobAsUtf8, "こんにちわ"}
})
</file>

===== RegisterMethod =====
<wrap em>vci.osc.RegisterMethod</wrap> **fun(address: string, callback: function, argumentTypes: Table)**\\

=== 引数 ===
^address| OSC Message の受信を待ち受ける OSC Address|
^callback| OSC Message を受信したときに実行されるコールバック|
^argumentTypes| 受信する OSC Message に含まれる OSC Argument の型を順番に列挙したテーブル|

''argumentTypes'' テーブルは、以下のフォーマットで記述します。
<file lua argument_types_table.lua>
-- {
--   (OSC Argumentの型), 
--   ..., 受信する OSC Message の OSC Argument の個数分繰り返す
-- }

-- 例：String, Int32, Float32, BlobAsUtf8を受信する場合
argumentTypes = 
{
  vci.osc.types.String,
  vci.osc.types.Int32,
  vci.osc.types.Float32,
  vci.osc.types.BlobAsUtf8,
}
</file>

=== 説明 ===
  * ''arguments''に OSC Message が送られてきたときに呼びだされる関数を登録します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、登録に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
  * VC クライアント側で予約済みの一部 OSC Address に対して関数の登録を試みた場合、登録に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。
  * 同一の OSC Address に対して、同じ VCI インスタンスから一つのみ関数を登録できます。
    * 別 VCI インスタンスからの登録であった場合、重複は許容されます。
    * 同じ OSC Address に複数の関数が重複して登録されている場合、その OSC Address に OSC Message が到達したときに登録されているすべての関数が実行されます。

<file lua main.lua>
-- ASCII string を一個受信する
function echo(content)
  print(content)
end

vci.osc.RegisterMethod("/test/echo", echo, {vci.osc.types.String})

-- float を二個受信する
function show_point(x, y)
  print(x..", "..y)
end

vci.osc.RegisterMethod("/test/showPoint", show_point, {vci.osc.types.Float32, vci.osc.types.Float32})
</file>

===== UnregisterMethod =====
<wrap em>vci.osc.UnregisterMethod</wrap> **fun(address: string)**\\

=== 引数 ===
^address|登録解除したい関数が登録されている OSC Address|

=== 説明 ===
  * [[vci/script/reference/exportosc#RegisterMethod]]で''address''に登録した関数の登録を解除します。
  * ''address'' が null の場合、または不正なフォーマットの OSC Address であった場合、登録解除に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

<file lua main.lua>
-- ASCII string を一個受信する
function echo(content)
  print(content)
end

vci.osc.RegisterMethod("/test/echo", echo, {vci.osc.types.String})

-- VCI が Use されたとき、関数 echo の "/test/echo" への登録を解除する
function onUse(item)
  vci.osc.UnregisterMethod("/test/echo")
end
</file>