~~NOTOC~~
====== ExportStudio(プリセットアイテム) ======
<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/|こちら]]**になります。
</WRAP>
スタジオ内の情報を取得するのに必要な関数です。\\
主にアイテムの状態に関する情報を取得したり、VCIスクリプトでアイテムを操作するのに使用します。\\
バーチャルキャストのアイテムについては[[virtualcast/item]]から確認してください。

^ 名前 ^ 説明 ^
| **[[vci/script/reference/exportstudio#ExportStudio]]** | スタジオのプリセットアイテムをインスタンス化 |
| **[[vci/script/reference/exportstudio#ExportSystemItem]]** | インスタンス化したオブジェクトを操作 |
| **[[vci/script/reference/exportstudio#ExportSystemCamera]]** | インスタンス化したカメラを操作 |


==== ExportStudio ====


バーチャルキャストのプリセットアイテムごとに**Has関数**と**Get関数**が存在します。\\
  * Has関数 : スタジオ内にアイテムが存在するか確認する関数
  * Get関数 : アイテムのインスタンスを取得する関数
スタジオにアイテムが存在しないのにGetしてしまうとnullになるので、Has関数の結果がtrueの時のみGetするようにします。\\
また、2019/08/29 時点では凸者も取り出し可能なアイテムに関しては取得する事ができません。\\

^ 名前 ^ 引数: 戻り値 ^ 説明 ^
| shared | | [[vci:script:reference:exportshared]]で使用 |
| GetOwner | fun(): ExportAvatar | VCI所有者の[[vci:script:reference:exportavatar|アバター]] を取得します\\ RoomではVCIを生成した人が退室している状況があり、その場合にGetOwnerを実行するとExportAvatarは入手出来ず、nilになります|
| GetLocalAvatar | fun(): ExportAvatar | ローカルマシンのユーザが使用する [[vci:script:reference:exportavatar|アバター]] を取得(v2.0.0a以降) |
| GetAvatars | fun(): ExportAvatar[] | スタジオ内の[[vci:script:reference:exportavatar|アバター]] 一覧を取得 |
| GetMic | fun(): ExportSystemItem | **[[virtualcast:studio:item:microphone|マイク]]** をインスタンス化 |
| HasMic | fun(): bool | **[[virtualcast:studio:item:microphone|マイク]]** がスタジオに存在すれば true |
| GetLightSource | fun(): ExportSystemItem | **[[virtualcast:studio:item:lightsource|光源]]** をインスタンス化 |
| HasLightSource | fun(): bool | **[[virtualcast:studio:item:lightsource|光源]]** がスタジオに存在すれば true |
| GetMirror | fun(): ExportSystemItem | **[[virtualcast:studio:item:mirror|鏡]]** をインスタンス化 |
| HasMirror | fun(): bool | **[[virtualcast:studio:item:mirror|鏡]]** がスタジオに存在すれば true |
| GetHarisen | fun(): ExportSystemItem | **[[virtualcast:studio:item:harisen|ハリセン]]** をインスタンス化 |
| HasHarisen | fun(): bool | **[[virtualcast:studio:item:harisen|ハリセン]]** がスタジオに存在すれば true |
| GetMosaic | fun(): ExportSystemItem | **[[virtualcast:studio:item:mosaic|モザイク]]** をインスタンス化 |
| HasMosaic | fun(): bool | **[[virtualcast:studio:item:mosaic|モザイク]]** がスタジオに存在すれば true |
| GetHammer | fun(): ExportSystemItem | **[[virtualcast:studio:item:picopicohammer|ピコピコハンマー]]** をインスタンス化 |
| HasHammer | fun(): bool | **[[virtualcast:studio:item:picopicohammer|ピコピコハンマー]]** がスタジオに存在すれば true |
| GetWindowCamera | fun(): ExportSystemCamera | **[[virtualcast:studio:item:monitorcamera|モニターカメラ]]** をインスタンス化 |
| HasWindowCamera | fun(): bool | **[[virtualcast:studio:item:monitorcamera|モニターカメラ]]** がスタジオに存在すれば true |
| GetHandiCamera | fun(): ExportSystemCamera | **[[virtualcast:studio:item:handycamera|ハンディカメラ]]** をインスタンス化 |
| HasHandiCamera | fun(): bool | **[[virtualcast:studio:item:handycamera|ハンディカメラ]]** がスタジオに存在すれば true |
| GetAutoFollowCamera | fun(): ExportSystemCamera | **[[virtualcast:studio:item:followingcamera|追従カメラ]]** をインスタンス化 |
| HasAutoFollowCamera | fun(): bool | **[[virtualcast:studio:item:followingcamera|追従カメラ]]** がスタジオに存在すれば true |
| GetSwitchingCamera | fun(): ExportSystemCamera | **[[virtualcast:studio:item:switchingcamera|スイッチングカメラ]]** をインスタンス化 |
| HasSwitchingCamera | fun(): bool | **[[virtualcast:studio:item:switchingcamera|スイッチングカメラ]]** がスタジオに存在すれば true |
| GetNameBoard | fun(idOrName: string): ExportSystemItem | **ネームプレート**をインスタンス化\\ [[vci:script:reference:exportavatar|ExportAvatar]]から取得したユーザー名かIDを指定 |
| HasNameBoard | fun(idOrName: string): bool | **ネームプレート**がスタジオに存在すれば true |

==== ExportSystemItem ====

ExportStudioでインスタンス化したオブジェクトを操作します。

^ 名前 ^ 引数: 戻り値 ^ 説明 ^
| GetName | fun(): string | アイテムの名前を取得 |
| GetLocalPosition | fun(): Vector3 | アイテムの位置を取得\\ (出現時のローカル座標が原点) |
| GetPosition | fun(): Vector3 | アイテムの位置を取得\\ (ワールド座標の(0,0,0)が原点) |
| GetLocalRotation | fun(): Quaternion | アイテムの回転を取得\\ (出現時のローカルの姿勢が基準) |
| GetRotation | fun(): Quaternion | アイテムの回転を取得\\ (ワールド座標基準) |
| GetLocalScale | fun(): Vector3 | アイテムの縮尺を取得 |
| GetRight | fun(): Vector3 | アイテムの右方向(+X)のベクトル |
| GetUp | fun(): Vector3 | アイテムの上方向(+Y)ベクトル |
| GetForward | fun(): Vector3 | アイテムの正面(+Z)ベクトル |
| GetLocalToWorldMatrix | fun(): Matrix4x4 | アイテムのローカル→ワールド座標に変換した行列 |
| SetPosition | fun(position: Vector3): number | アイテムの位置(Position)を変更\\ (ワールド座標) **※1** |
| SetRotation | fun(rotation: Quaternion): number | アイテムの姿勢(Rotation)を変更\\ (ワールド座標) **※1** |
| SetLocalPosition | fun(localPosition: Vector3): number | アイテムの位置(Position)を変更\\ (ローカル座標) **※1** |
| SetLocalRotation | fun(localRotation: Quaternion): number | アイテムの姿勢(Rotation)を変更\\ (ローカル座標) **※1** |
| IsGrabbed | fun(): bool | grabされているなら true |

**※1**\\
''SetPosition'', ''SetRotation'', ''SetLocalPosition'', ''SetLocalRotation'' は**部屋主が出したVCIからのみ実行可能です。**

==== ExportSystemCamera ====

ExportStudioでインスタンス化した**カメラ**を操作します。\\
基本的にSystemItemと同じですが、カメラ固有の関数(GetFieldOfView等)が存在します。

^ 名前 ^ 引数: 戻り値 ^ 説明 ^
| GetFieldOfView | fun(): number | カメラの視野角(FOV)を取得 |
| SetFieldOfView | fun(fov: number): number | カメラの視野角(FOV)を変更 **※1** **※2** |
| GetMinFieldOfView | fun(): number | カメラの最小視野角(FOV)を取得 |
| GetMaxFieldOfView | fun(): number | カメラの最大視野角(FOV)を取得 |
| GetName | fun(): string | アイテムの名前を取得 |
| GetLocalPosition | fun(): Vector3 | アイテムの位置を取得\\ (出現時のローカル座標が原点) |
| GetPosition | fun(): Vector3 | アイテムの位置を取得\\ (ワールド座標の(0,0,0)が原点) |
| GetLocalRotation | fun(): Quaternion | アイテムの回転を取得\\ (出現時のローカルの姿勢が基準) |
| GetRotation | fun(): Quaternion | アイテムの回転を取得\\ (ワールド座標基準) |
| GetLocalScale | fun(): Vector3 | アイテムの縮尺を取得 |
| GetRight | fun(): Vector3 | アイテムの右方向(+X)のベクトル |
| GetUp | fun(): Vector3 | アイテムの上方向(+Y)ベクトル |
| GetForward | fun(): Vector3 | アイテムの正面(+Z)ベクトル |
| GetLocalToWorldMatrix | fun(): Matrix4x4 | アイテムのローカル→ワールド座標に変換した行列 |
| SetPosition | fun(position: Vector3): number | アイテムの位置(Position)を変更\\ (ワールド座標) **※1** |
| SetRotation | fun(rotation: Quaternion): number | アイテムの姿勢(Rotation)を変更\\ (ワールド座標) **※1** |
| SetLocalPosition | fun(localPosition: Vector3): number | アイテムの位置(Position)を変更\\ (ローカル座標) **※1** |
| SetLocalRotation | fun(localRotation: Quaternion): number | アイテムの姿勢(Rotation)を変更\\ (ローカル座標) **※1** |
| IsGrabbed | fun(): bool | grabされているなら true |

**※1**\\
''SetPosition'', ''SetRotation'', ''SetLocalPosition'', ''SetLocalRotation'', ''SetFieldOfView'' は**部屋主が出したVCIからのみ実行可能です。**\\

**※2**\\
FOV設定可能なカメラは下図の通りです。''GetMinFieldOfView''、''GetMaxFieldOfView''で取得可能な最小値、最大値を超えた値は設定できません。

^ カメラ名 ^ FOV設定 ^
| モニターカメラ | 不可 |
| ハンディカメラ | 可 |
| 追従カメラ | 可 |
| スイッチングカメラ | 不可 |

また、これらの関数で扱う値は垂直視野角で、単位は度です。

===ハンディカメラに表示される焦点距離について===
ハンディカメラのプレビュー画面に表示される ''50mm'' といった数値があります。\\
これはズームとともに連動する値で、現実のカメラではよく使われる「焦点距離」という指標です。\\
なおかつアスペクト比の違いを吸収するため、焦点距離の中でも対角換算での焦点距離を使用しています。\\

このようにハンディカメラでは分かりやすさのために焦点距離が使われています。\\
一方で ''SetFieldOfView'' で設定可能な値は垂直換算の FOV です。\\
ハンディカメラのプレビュー画面に表示されている焦点距離を基準に FOV を設定したい場合は\\
次の計算で、対角換算の焦点距離から垂直換算の FOV を算出することができます。\\

$$
FOV = \frac{360}{\pi} \times \arctan{\left(\frac{D}{x \times 2 \sqrt{a^{2}+1}}\right)}  \\
\text{x: 35mm判換算焦点距離[mm]} \\
\text{a: カメラのアスペクト比 (基本的に16/9)} \\
\text{D: 35mmフルサイズセンサーの対角長 (≒43.27[mm])} \\
$$
===== サンプル =====

CameraPositionResetというSubItemをgrabした時に、[[virtualcast:studio:item:handycamera|ハンディカメラ]]の位置を(0,1,0)の位置にリセットするサンプルです。\\


スタジオの中にハンディカメラが存在しない状態で ''vci.studio.GetHandiCamera()'' を実行してしまうと、エラーになります。\\
なので ''vci.studio.HasHandiCamera() == false'' でハンディカメラが存在しない場合は ''return'' をして処理を終了します。\\
\\
''vci.studio.HasHandiCamera() == true'' の場合は ''return'' が実行されずに ''camera.SetPosition(position)'' の行までいくので、カメラがリセットされます。\\
なので、**アイテムが存在するか確認するHas関数の後に、アイテムをインスタンス化するGet関数を実行する**必要があります。


<file lua main.lua>
function onUse(use)
    -- PositionResetをUseした時
    if use == "CameraPositionReset" then
        -- カメラの位置をリセットする
        CameraPositionReset()
    end
end

function CameraPositionReset()
    -- ハンディカメラが存在しない場合終了する
    if vci.studio.HasHandiCamera() == false then
        print("ハンディカメラが存在しないので終了")
        return
    end

    -- リセットする座標
    local position = Vector3.__new(0, 1, 0)
    -- カメラのインスタンス
    local camera = vci.studio.GetHandiCamera()
    -- カメラの位置を変更
    camera.SetPosition(position)
    print("カメラの位置　："..tostring(camera.GetPosition()))
end
</file>

==== 実行結果 ====


<code lua>
カメラの位置 : (0,1,0)
(カメラの座標がワールド座標で(0,1,0)の位置に移動します)
</code>


ケースバイケースではありますが **Has関数がfalseの場合にreturnする** という書き方を推奨します。\\
**trueの場合に実行する** でも問題ないのですが、変数のスコープがif文の中になってしまうこと、さらにif文がネストする可能性が大きいです。\\
**Has関数がfalseの場合に処理をしない** という事は確実に言える事なので、先頭にその処理を持ってくる事で分かりやすくします。\\
このようなプログラム書き方をガード節といいます。