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.osc.types ExportOscType

• 送受信できる OSC Argument の型の列挙子を表すクラスを返します。
  
• vci.osc.SendMessage や vci.osc.RegisterMethod で送受信する OSC Argument を指定する際に利用します。

vci.osc.IsSendEnabled fun(): bool

• 呼び出し元の VCI インスタンスの OSC Message 送信機能の有効フラグを取得します。
  
• OSC Message 送信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
  • disabled の場合、すべての VCI インスタンスにおいて false が返されます。
  • enabled の場合、すべての VCI インスタンスにおいて true が返されます。
  • creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

main.lua

local isEnabled = vci.osc.IsSendEnabled()
print(isEnabled)

vci.osc.IsReceiveEnabled(): bool

• 呼び出し元の VCI インスタンスの OSC Message 受信機能の有効フラグを取得します。
  
• OSC Message 受信が有効であるかは、VCクライアントの OSC 送信設定によって決定されます。
  • disabled の場合、すべての VCI インスタンスにおいて false が返されます。
  • enabled の場合、すべての VCI インスタンスにおいて true が返されます。
  • creator-only の場合、自身が生成した VCI インスタンスのみ true が返り、それ以外は false が返されます。

main.lua

local isEnabled = vci.osc.IsReceiveEnabled()
print(isEnabled)

vci.osc.SendAsciiString fun(address: string, argument: string)

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

main.lua

vci.osc.SendAsciiString("/test/sendstring", "hello")

vci.osc.SendInt32 fun(address: string, argument: number)

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

main.lua

vci.osc.SendInt32("/test/sendint", 100)

vci.osc.SendFloat32 fun(address: string, argument: number)

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

main.lua

vci.osc.SendFloat32("/test/sendfloat", 3.14)

vci.osc.SendUtf8String fun(address: string, argument: string)

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

main.lua

vci.osc.SendUtf8String("/test/sendutf8", "こんにちわ")

vci.osc.SendMessage fun(address: string)

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

main.lua

vci.osc.SendMessage("/test/sendmessage")

vci.osc.SendMessage fun(address: string, arguments: Table)

arguments テーブルは、以下のフォーマットで記述します。

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, "こんにちわ"},
}

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

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, "こんにちわ"}
})

vci.osc.RegisterMethod fun(address: string, callback: function, argumentTypes: Table)

argumentTypes テーブルは、以下のフォーマットで記述します。

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,
}

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

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})

vci.osc.UnregisterMethod fun(address: string)

• RegisterMethodでaddressに登録した関数の登録を解除します。
• address が null の場合、または不正なフォーマットの OSC Address であった場合、登録解除に失敗します。この時、VCI コンソールにエラーメッセージが表示されます。

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