~~NOTOC~~
====== ExportPhotographyCamera(カメラAPI) ======
<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/|こちら]]**になります。
</WRAP>
VCI 上で各種カメラを管理するクラスです。
  * VCI 上に写真撮影用カメラを作成することができます。
    * **写真撮影時、ルームのキャプチャーカメラと同じように撮影結果を画像として保存します**。
    * 一つの VCI 上に作成できる写真撮影用カメラの台数には**上限があります**。
      * 現在の上限は**1台**
  * **UniVCI v0.33.0** 以降で Export される VCI で使用できます。
  * **バーチャルキャスト 2.1.3c** 以降で動作します。
  * 現在、この API は**ルーム上でのみ動作します**。

UniVCI v0.33.0 パッケージ内の ''Assets/VCI-Official-Samples/CameraApiSample'' 以下にサンプル VCI が同梱されてますので、合わせてご確認ください。


^ ExportCameraSystem ^^^
^ 名前 ^ 説明 ^ バージョン ^
| [[vci:script:reference:exportphotographycamera#CreatePhotographyCamera| CreatePhotographyCamera]] | VCI 上にカメラを作成 | |
^ ExportPhotographyCamera ^^^
^ 名前 ^ 説明 ^ バージョン ^
| [[vci:script:reference:exportphotographycamera#GetCameraPreviewTextureId| GetCameraPreviewTextureId]] | プレビュー用のテクスチャの ID を取得 | |
| [[vci:script:reference:exportphotographycamera#GetAspectRatio| GetAspectRatio]] | プレビューと写真のテクスチャのアスペクト比を取得| |
| [[vci:script:reference:exportphotographycamera#TakePhotograph| TakePhotograph]] | 写真を撮影 | |
| [[vci:script:reference:exportphotographycamera#SetOnTakePhotoCallback| SetOnTakePhotoCallback]] | 撮影時に実行されるコールバック関数を登録 | |
|[[vci:script:reference:exportphotographycamera#GetVerticalFieldOfView| GetVerticalFieldOfView]] | 垂直 FOV を取得| |
|[[vci:script:reference:exportphotographycamera#SetVerticalFieldOfView| SetVerticalFieldOfView]] | 垂直 FOV を設定| |
|[[vci:script:reference:exportphotographycamera#GetNearClipPlane| GetNearClipPlane]] | Near Clip Plane までの距離を取得| |
|[[vci:script:reference:exportphotographycamera#SetNearClipPlane| SetNearClipPlane]] | Near Clip Plane までの距離を設定| |
|[[vci:script:reference:exportphotographycamera#ReleaseCamera| ReleaseCamera]] | カメラを破棄| |


===== CreatePhotographyCamera =====
<wrap em>ExportCameraSystem.</wrap>** CreatePhotographyCamera fun(followTransform: ExportTransform): ExportPhotographyCamera**

VCI 上に写真撮影用カメラを生成します。\\
生成された写真撮影用カメラの位置や向きは、**引数に渡した [[https://developer.virtualcast.jp/vci-docs/api/classes/ExportTransform/index.html|ExportTransform]] に追従します**。\\
非同期で生成されるため、全員に表示させる場合は、初期化やメッセージ受信時などにカメラ作成する必要があります。


=== 引数 ===
''followTransform'': ExportTransform
  * 生成されるカメラを追従させる Transform

=== 返り値 ===
''[[https://developer.virtualcast.jp/vci-docs/api/classes/ExportPhotographyCamera/index.html|ExportPhotographyCamera]]''
  * 生成された写真撮影用カメラ
''nil''
  * **生成可能な写真撮影用カメラの台数上限を超え、カメラの生成に失敗した時**に ExportPhotographyCamera の代わりに nil を返します。

=== サンプル ===
<file lua main.lua>

-- 写真撮影用カメラの位置姿勢を追従させるべき GameObject の Transform を取得
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")

-- 写真撮影用カメラを生成する
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor)

-- 以後、変数 camera を通して写真撮影用カメラを操作できるようになる
</file>





===== GetCameraPreviewTextureId =====
<wrap em>ExportPhotographyCamera.</wrap>** GetCameraPreviewTextureId fun(): string**

写真撮影用カメラの**プレビュー用のテクスチャ ID** を取得します。
  * この ID は、 [[vci/script/reference/exportassets/material#SetTexture | ExportMaterial.SetTexture]] に渡すことで使用します。
  * プレビューのテクスチャに表示される映像のフレームレート・画質は、**ルーム上に存在する他カメラ（他 VCI 上に生成された写真撮影用カメラ、フォトキャプチャーカメラ）が多いほど低下します**。

=== 引数 ===
なし

=== 返り値 ===
''string''
  * プレビューテクスチャのテクスチャ ID

''nil''
  * ''ExportPhotographyCamera'' が破棄済みであった場合、string の代わりに nil を返します。
=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラのプレビューを表示する

-- 写真撮影用カメラを生成
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor)

-- プレビューを表示すべき GameObject に、"Display" という名前のマテリアルが割り当てられているとする
local previewMaterialName = "Display"

-- 写真撮影用カメラのプレビューのテクスチャを示すIDを取得
local previewTextureId = camera.GetCameraPreviewTextureId()
-- ID を渡し、プレビューを表示する
vci.assets.material.SetTexture(previewMaterialName, previewTextureId)

</file>

===== GetAspectRatio =====
<wrap em>ExportPhotographyCamera.</wrap>** GetAspectRatio fun(): number**

写真撮影用カメラのプレビューと写真のテクスチャのアスペクト比（横幅を縦幅で割った値）を取得します。\\
現状、すべての写真撮影用カメラのプレビュー/写真テクスチャのアスペクト比は **16:9 固定** です。

=== 引数 ===
なし

=== 返り値 ===
''number''
  * 写真撮影用カメラのプレビューと写真のテクスチャのアスペクト比
''nil''
  * ''ExportPhotographyCamera'' が破棄済みであった場合、number の代わりに nil を返します。
=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラのアスペクト比を取得する

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- アスペクト比を取得
local aspectRatio = camera.GetAspectRatio()
-- アスペクト比を VCI コンソールに表示
-- * 現在、アスペクト比は 16:9 で固定
-- * そのため 16/9 -> 1.777777... が表示される
print(aspectRatio)
</file>

===== TakePhotograph =====
<wrap em>ExportPhotographyCamera.</wrap>** TakePhotograph fun(): bool**

写真を撮影します。\\
    * ローカルマシンの負荷によっては即座に撮影されない場合があります。
    * [[vci:script:reference:exportphotographycamera#SetOnTakePhotoCallback| ExportPhotographyCamera.SetOnTakePhotoCallback]] によって対象のカメラにコールバック関数が紐づけられている場合、写真撮影時にその関数が実行されます。
  * 撮影した写真は、**''TakePhotograph'' が実行されたユーザーの環境上で画像として保存されます**。
    * **画像の保存場所、ファイル名、ファイルフォーマット**は**フォトキャプチャーカメラによって撮影した場合と同じものになります**。
    * **撮影した写真の解像度**は、**フォトキャプチャーカメラの解像度設定に準拠します**。
  * **写真撮影後の0.5秒の間は、再度写真撮影を行うことができません。**

=== 引数 ===
なし

=== 返り値 ===
''bool''
  * 写真撮影の成否
    * 撮影後 0.5 秒以内に再度 ''TakePhotograph'' を実行した場合、写真撮影は行われず false が返されます。
    * それ以外は、写真撮影が実行され true が返されます。
''nil''
  * ''ExportPhotographyCamera'' が破棄済みであった場合、bool の代わりに nil を返します。

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラで写真を撮影する

-- Use すると撮影が実行される "CameraButton" という SubItem があるとする
local cameraButtonName = "CameraButton"

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- "CameraButton" が Use されたら写真を撮影する
-- * SetOnTakePhotograph でコールバック関数がセットされていた場合、撮影成功時にその関数が実行される
function onUse(item)
  if item == cameraButtonName then
    camera.TakePhotograph()
  end
end

</file>

===== SetOnTakePhotoCallback =====
<wrap em>ExportPhotographyCamera.</wrap>** SetOnTakePhotoCallback fun()**

写真撮影時に実行されるコールバック関数を登録します。

=== 引数 ===
''callback'': fun(table photoMetadata)
  * コールバックとして登録する関数
    * ''photoMetadata''は、撮影された写真に関する以下の情報を持ちます。
      * ''photoMetadata.textureId'': 撮影した写真のテクスチャ ID
        * **撮影結果のテクスチャは、5秒後に無効化（テクスチャが真っ黒になる）されます**。
    * 関数以外を渡した場合、コンソールにエラーメッセージを出力します。

=== 返り値 ===
なし

=== サンプル ===
<file lua main.lua>
-- 写真撮影時に実行されるコールバック関数をセットする

-- 撮影結果を表示すべき GameObject に "Photo" というマテリアルが割り当てられているとする
local photoMaterialName = "Photo"

-- 写真撮影時に実行されるコールバック関数を定義
function onTakePhotoCallback(photoMetadata)
  -- photoMetadata テーブルから、撮影結果のテクスチャを示す ID を取得
  local photoTextureId = photoMetadata.textureId
  -- ID を渡して、撮影結果を表示する
  vci.assets.material.SetTexture(photoMaterialName, photoTextureId)
end

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- コールバック関数をセットする
-- * 以後、ExportPhotographyCamera.TakePhotograph が実行されるたび onTakePhotoCallback が実行されるようになる
camera.SetOnTakePhotoCallback(onTakePhotoCallback)

</file>

===== GetVerticalFieldOfView =====
<wrap em>ExportPhotographyCamera.</wrap>** GetVerticalFieldOfView fun(): number**

写真撮影用カメラの垂直 FOV を取得します。
  * 単位は **degrees**
  * デフォルトの値は **30**

=== 引数 ===
なし

=== 返り値 ===
''number''
  * 写真撮影用カメラの垂直 FOV

''nil''
  * ''ExportPhotographyCamera'' が破棄済みであった場合、number の代わりに nil を返します。

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラの垂直 FOV 取得

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- 垂直 FOV を取得
local currentFov = camera.GetVerticalFieldOfView()
-- VCIコンソールにFOVの値が表示される
-- * デフォルト値は30
print(currentFov)
</file>

===== SetVerticalFieldOfView =====
<wrap em>ExportPhotographyCamera.</wrap>** SetVerticalFieldOfView fun(value: number)**

写真撮影用カメラの垂直 FOV を設定します。
  * 単位は **degrees**

=== 引数 ===
''value'': number
  * 設定する垂直 FOV の値
  * 設定可能な値の範囲は **1e-05 ~ 179** です。
      * 範囲外の値を渡した場合、その値は範囲内に clamp されます。

=== 返り値 ===
なし

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラの垂直 FOV を設定

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- 垂直 FOV を 60 に設定
camera.SetVerticalFieldOfView(60)

local currentFov = camera.GetVerticalFieldOfView()
-- VCIコンソールに 60 と表示される
print(currentFov)
</file>

===== GetNearClipPlane =====
<wrap em>ExportPhotographyCamera.</wrap>** GetNearClipPlane fun(): number**

写真撮影用カメラの Near Clip Plane までの距離を取得します。
  * 単位は **world units**（バーチャルキャストでは**メートル**）
  * デフォルトの値は **0.01**

=== 引数 ===
なし

=== 返り値 ===
''number''
  * 写真撮影用カメラの Near Clip Plane までの距離

''nil''
  * ''ExportPhotographyCamera'' が破棄済みであった場合、number の代わりに nil を返します。

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラの Near Clip Plane までの距離を取得

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- Near Clip Plane までの距離を取得
local currentNearClip = camera.GetNearClipPlane()
-- VCI コンソールに Near Clip Plane までの距離が表示される
-- * デフォルトは 0.01
print(currentNearClip)
</file>

===== SetNearClipPlane =====
<wrap em>ExportPhotographyCamera.</wrap>** SetNearClipPlane fun(value: number)**

写真撮影用カメラの Near Clip Plane までの距離を設定します。
  * 単位は **world units**（バーチャルキャストでは**メートル**）

=== 引数 ===
''value'': number
  * 設定する Near Clip Plane までの距離の値
  * 設定可能な値の範囲は **0.01 ~ 100** です。
      * 範囲外の値を渡した場合、その値は範囲内に clamp されます。

=== 返り値 ===
なし

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラの Near Clip Plane までの距離を設定

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor")
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor) 

-- Near Clip Plane までの距離を 10 に設定
camera.SetNearClipPlane(10)

local currentNearClipPlane = camera.GetNearClipPlane()
-- VCI コンソールに 10 と表示される
print(currentNearClipPlane)
</file>

===== ReleaseCamera =====
<wrap em>ExportPhotographyCamera.</wrap>** ReleaseCamera fun()**

  * 写真撮影用カメラを破棄します。
  * 破棄したカメラは、以後操作することができなくなります。

=== 引数 ===
なし

=== 返り値 ===
なし

=== サンプル ===
<file lua main.lua>
-- 写真撮影用カメラの破棄

-- 写真撮影用カメラを生成する
local cameraAnchor = vci.assets.GetTransform("CameraAnchor") 
local camera = vci.cameraSystem.CreatePhotographyCamera(cameraAnchor)

-- 
-- この間、写真撮影用カメラを操作可能
-- 

-- 写真撮影用カメラを破棄する
camera.ReleaseCamera()

-- 以後、該当の写真撮影用カメラを操作することができない

</file>