開発者向けガイド
パラメータについて
VirtualLens2の内部で利用しているパラメータを読み書きすることによって他のギミックからVirtualLens2の挙動を制御することができます。 以下にアクセス可能なパラメータとその説明を列挙します。
OSC 経由での利用について
以下のパラメータは OSC 経由でも操作することが可能ですが、通常は VRChat が OSC アドレスを生成する際にパラメータ名に含まれる" " (スペース) を "_" (アンダースコア) に変換したものを使用するため OSC から操作する場合はそれに沿って読み替えを行う必要があります。
例えば VirtualLens2 Zoom パラメータを操作する場合はアドレスとして /avatar/parameters/VirtualLens2_Zoom を使用するようになります。
凡例
- 同期関連
- Synchronized 他プレイヤーに同期されます。
- Non-synchronized 他プレイヤーに同期されません。
- Optional-synchronized セットアップ時に同期を有効化した場合のみ他プレイヤーに同期されます。
- アクセス権限
- Read/Write 読み書きいずれも利用可能です。
- Read only 読み取り専用パラメータです。書き換えた場合意図しない挙動をとることがあります。
- Write only 書き込み専用パラメータです。意味が明文化されていない値をとることがあります。
コア要素
VirtualLens2 Control
Synchronized Write only
他プレイヤーとの状態の同期、メニュー入力の受付、OSCからの制御コマンドの受付に使用されます。 外部からは後述するコマンド送信のためにのみ使用することができます。
コマンドの送信
Deprecated
VRCSDKの更新によりネットワーク同期しないパラメータをOSCから制御できるようになったためVirtualLens2 Control を利用した制御コマンドの受付は廃止予定となりました。
今後作成するアプリケーションでは対応する変数を直接操作するようにしてください。
OSC経由でVRCExpressionParametersに登録されないパラメータを扱いたい場合、このパラメータに以下の表に示す値を書きこむことによって間接的に値を書き換えることができます。
| 値 | 説明 |
|---|---|
| 1 | (Reserved) |
| 2 | Disable |
| 3 | Enable |
| 4 | Auto Leveler: Disable |
| 5 | Auto Leveler: Horizontal |
| 6 | Auto Leveler: Vertical |
| 7 | (Reserved) |
| 8 | Stabilizer: Disable |
| 9 | Stabilizer: Weak |
| 10 | Stabilizer: Medium |
| 11 | Stabilizer: Strong |
| 12 | Pickup |
| 13 | Drop |
| 14 | Reposition |
| 15 | (Reserved) |
| 16 | Reposition Scale: 1x |
| 17 | Reposition Scale: 3x |
| 18 | Reposition Scale: 10x |
| 19 | Reposition Scale: 30x |
| 20 | Pin: Store 1 |
| 21 | Pin: Store 2 |
| 22 | Pin: Store 3 |
| 23 | Pin: Store 4 |
| 24 | Pin: Load 1 |
| 25 | Pin: Load 2 |
| 26 | Pin: Load 3 |
| 27 | Pin: Load 4 |
| 28 | External Pose: Disabled |
| 29 | External Pose: Enabled |
| 30 | Focus Lock: Disabled |
| 31 | Focus Lock: Enabled |
| 32 | AF Mode: Point AF |
| 33 | AF Mode: Face AF |
| 34 | AF Mode: Selfie AF |
| 35 | (Reserved) |
| 36 | Tracking Speed: Immediate |
| 37 | Tracking Speed: Fast |
| 38 | Tracking Speed: Medium |
| 39 | Tracking Speed: Slow |
| 40 | Focusing Speed: Immediate |
| 41 | Focusing Speed: Fast |
| 42 | Focusing Speed: Medium |
| 43 | Focusing Speed: Slow |
| 44 | Mesh Visibility: Show |
| 45 | Mesh Visibility: Hide |
| 46 | Grid: None |
| 47 | Grid: 3x3 |
| 48 | Grid: 3x3+Diagonal |
| 49 | Grid: 6x4 |
| 50 | (Reserved) |
| 51 | (Reserved) |
| 52 | Information: Hide |
| 53 | Information: Show |
| 54 | Leveler: Hide |
| 55 | Leveler: Show |
| 56 | Peaking: Disable |
| 57 | Peaking: MF Only |
| 58 | Peaking: Always |
| 59 | (Reserved) |
| 60 | Far Plane: Default |
| 61 | Far Plane: 10x |
| 62 | Far Plane: 100x |
| 63 | (Reserved) |
| 64 | Transfer Mode Permissive |
| 65 | Transfer Mode: Strict |
| 66 | Depth Enabler: Disable |
| 67 | Depth Enabler: Enable |
VirtualLens2 Enable
Synchronized Read/Write
VirtualLens2が有効化されているかどうかを表します。
有効化されているときは1、そうでないときは0となります。
VirtualLens2 AltMesh
Synchronized Read only
カメラモデルの表示が代替メッシュに置き換えられているかどうかを表します。
表示が置き換えられているときは1、そうでないときは0となります。
手持ちかつ手ブレ補正が有効の場合のみローカルとリモートで挙動が異なり、ローカルでは1、リモートでは0となる点に注意してください。
基本機能
VirtualLens2 Zoom
Optional-synchronized Read/Write
焦点距離の設定にあわせて 0.0 から 1.0 の範囲で設定されます。
パラメータの値 \( x \) から焦点距離 \( f \) への変換は以下の式で行うことができます。
ここで \( f_{\min}, f_{\max} \) はそれぞれ設定項目中の Min focal length, Max focal length に対応します。
$$ f = f_{\min} \exp \Bigl\{ x \log \frac {f_{\max}} {f_{\min}} \Bigr\} $$
VirtualLens2 Aperture
Optional-synchronized Read/Write
絞り (F値) の設定にあわせて 0.0 から 1.0 の範囲で設定されます。
パラメータの値 \( x \) からF値への変換は以下の式で行うことができます。
ここで \( F_{\min}, F_{\max} \) はそれぞれ設定項目中の Min F number, Max F number に対応します。
$$ F = F_{\min} \exp \Bigl\{ x \log \frac {F_{\max}} {F_{\min}} \Bigr\} $$
VirtualLens2 Exposure
Optional-synchronized Read/Write
露出補正の設定にあわせて 0.0 から 1.0 の範囲で設定されます。
パラメータの値 \( x \) から補正値 \( E \) [EV] への変換は以下の式で行うことができます。
ここで \( E_{r} \) は設定項目中の Exposure range に対応します。
$$ E = (2x-1)E_{r} $$
位置と向きの制御
VirtualLens2 PositionMode
Non-synchronized Read only
現在の位置調整モードを表す値が設定されます。値とモードの対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | カメラを直接手に持っている状態です。 |
| 1 | カメラがワールド空間に固定されている状態です。 |
| 2 | 再配置 (Reposition) 機能によってカメラ姿勢を制御している状態です。 |
| 3 | ドローン機能によってカメラ姿勢を制御している状態です。 |
VirtualLens2 AutoLeveler
Non-synchronized Read/Write
現在の自動水平出しモードを表す値が設定されます。値とモードの対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | 自動水平出し機能は無効となっています。 |
| 1 | 横向きとして水平を維持しています。 |
| 2 | 縦向きとして水平を維持しています。 |
| 3 | カメラの回転を30度刻みでスナップします。 |
VirtualLens2 Stabilizer
Non-synchronized Read/Write
現在の手振れ補正モードを表す値が設定されます。値とモードの対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | Disabled |
| 1 | Weak |
| 2 | Medium |
| 3 | Strong |
VirtualLens2 RepositionScale
Non-synchronized Read/Write
再配置 (Reposition) 機能利用時の動きのスケーリング係数を設定します。値とモードの対応付けは以下のようになっています。
| 値 | 倍率 |
|---|---|
| 0 | 1倍 |
| 1 | 3倍 |
| 2 | 10倍 |
| 3 | 30倍 |
VirtualLens2 LoadPin
Non-synchronized Write only
1から4までの範囲の値を書きこむことによって対応する番号のピン位置にカメラを移動させます。
VirtualLens2 StorePin
Non-synchronized Write only
1から4までの範囲の値を書きこむことによって対応する番号のピン位置として現在のカメラ位置を登録します。
VirtualLens2 ExistPin[1-4]
Non-synchronized Read only
対応する番号のピン位置が登録済みかどうかを表します。登録済みであれば1、そうでなければ0となります。
VirtualLens2 ExternalPose
Non-synchronized Read/Write
外部ポーズ入力が有効かどうかを表します。有効であれば1、そうでなければ0となります。
フォーカス制御
VirtualLens2 AFMode
Non-synchronized Read/Write
オートフォーカスの方式を表します。値と方式の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | 一点AF (Point AF) |
| 1 | 顔検出AF (Face AF) |
| 2 | 自撮りAF (Selfie AF) |
VirtualLens2 AFSpeed
Non-synchronized Read/Write
オートフォーカスによるフォーカス平面調整の速度を表します。値と設定の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | Immediate |
| 1 | Fast |
| 2 | Medium |
| 3 | Slow |
VirtualLens2 TrackingSpeed
Non-synchronized Read/Write
顔検出オートフォーカス利用中に顔の検出に失敗した後に別の顔に追跡対象を移すまでの速度を表します。値と設定の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | Immediate |
| 1 | Fast |
| 2 | Medium |
| 3 | Slow |
VirtualLens2 FocusLock
Non-synchronized Read/Write
一時的にフォーカス平面の更新を停止するためのフラグです。1であればフォーカス平面の更新が停止され、0になったときに再開されます。
VirtualLens2 Distance
Optional-synchronized Read/Write
マニュアルフォーカス時にフォーカスを合わせる平面までの距離が 0.0 から 1.0 の範囲で設定されます。
パラメータの値 \( x \) から距離 \( D \) [m] への変換は以下の式で行うことができます。
ここで \( D_{\min}, D_{\max} \) はそれぞれ設定項目中の Min focus distance, Max focus distance に対応します。
$$ D = D_{\min} \exp \Bigl\{ x \log \frac {D_{\max}} {D_{\min}} \Bigr\} $$
VirtualLens2 TouchOverride
Non-synchronized Read/Write
タッチスクリーン操作をアバターパラメータで模擬するためのフラグです。1がセットされている間は TouchOverrideX と TouchOverrideY で指定された座標がタッチされているとみなされます。
VirtualLens2 TouchOverrideX, VirtualLens2 TouchOverrideY
Non-synchronized Read/Write
TouchOverride パラメータを用いてタッチスクリーン操作をアバターパラメータで模擬する際にタッチしていることにする座標をそれぞれ -1.0 から 1.0 の範囲で設定します。
X座標は左から右に向かって大きく、Y座標は下から上に向かって大きくなります。
画面設定
VirtualLens2 Grid
Non-synchronized Read/Write
プレビュー画面に表示するグリッドの種類を設定します。値と種類の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | なし |
| 1 | 3x3 |
| 2 | 3x3 + 対角線 |
| 3 | 6x4 |
| 4-7 | カスタムグリッド1-4 |
VirtualLens2 Information
Non-synchronized Read/Write
プレビュー画面上に焦点距離やF値などの情報を表示するかどうかを設定します。表示する場合は1、そうでない場合は0となります。
VirtualLens2 Level
Non-synchronized Read/Write
プレビュー画面上に水準器を表示するかどうかを設定します。表示する場合は1、そうでない場合は0となります。
VirtualLens2 Peaking
Non-synchronized Read/Write
プレビュー画面上でピントのあっている範囲を強調表示する際の条件を設定します。値と条件の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | 常に無効 |
| 1 | マニュアルフォーカス利用時のみ有効 |
| 2 | 常に有効 |
マスク設定
VirtualLens2 LocalPlayerMask
Non-synchronized Read/Write
撮影者自身のアバターを映すかどうかを選択します。映す場合は1、映さない場合は0となります。
VirtualLens2 RemotePlayerMask
Non-synchronized Read/Write
撮影者以外のプレイヤーのアバターを映すかどうかを選択します。映す場合は1、映さない場合は0となります。
VirtualLens2 UIMask
Non-synchronized Read/Write
UI要素を映すかどうかを選択します。映す場合は1、映さない場合は0となります。
その他の設定
VirtualLens2 Hide
Synchronized Read/Write
Hideable Meshes に指定したメッシュの表示状態を制御します。非表示とする場合は1、表示する場合は0となります。
VirtualLens2 PreviewHUD
Non-synchronized Read/Write
プレビューHUDの表示状態を制御します。表示する場合は1、非表示とする場合は0となります。
VirtualLens2 FarPlane
Non-synchronized Read/Write
遠方側のカリング距離を調整します。値と設定の対応付けは以下のようになっています。
| 値 | 説明 |
|---|---|
| 0 | デフォルト値 (セットアップ時に指定した値) |
| 1 | デフォルト値×10 |
| 2 | デフォルト値×100 |
VirtualLens2 DepthEnabler
Non-synchronized Read/Write
デプステクスチャに依存したシェーダを安定して動作させるための機構を制御します。有効であれば1、そうでなければ0となります。
アバター設定の読み出し
VirtualLens2 Version
Non-synchronized Read only
VirtualLens2 vX.Y.Z がセットアップされている場合、整数値 X * 10000 + Y * 100 + Z が設定されます。
VirtualLens2 Zoom Min, VirtualLens2 Zoom Max
Non-synchronized Read only
焦点距離の下限 \( f_{\min} \) と上限 \( f_{\max} \) がミリメートル単位の浮動小数点数として設定されます。
VirtualLens2 Aperture Min, VirtualLens2 Aperture Max
Non-synchronized Read only
絞りの開き具合 (F値) の下限 \( F_{\min} \) と上限 \( F_{\max} \) が浮動小数点数として設定されます。
VirtualLens2 Exposure Range
Non-synchronized Read only
露出補正で用いるの補正値の範囲 \( E_r \) が浮動小数点数として設定されます。
VirtualLens2 Resolution X, VirtualLens2 Resolution Y
Non-synchronized Read only
VirtualLens2からの出力として期待される画像の解像度が整数値として設定されます。
使用例
カメラの出し入れに連動した手の形の変更
VirtualLens2 Enable と VirtualLens2 AltMesh を参照することでVirtualLens2が有効かつカメラメッシュが手元に表示されているかを判別することができます。
これらをもとに手の形を変える場合、Gestureレイヤーのハンドサインに対応するレイヤーにステートおよびトランジションを追加することでカメラを握っているようなハンドアニメーションを再生することができます。
なお、VirtualLens2セットアップ時にはGestureレイヤーのパラメータリストは更新されないため、手動で利用するパラメータを Animator Controller に追加する必要があります。
ハンドサイン入力によるフォーカスロック
VRCAvatarParameterDriver を用いて VirtualLens2 FocusLock パラメータを書き換えることでフォーカスロック機能を利用することができます。
これを利用して、FXレイヤーにGestureLeftやGestureRightの値に応じてパラメータを制御するレイヤーを追加することで特定のハンドサインによってフォーカスを固定することができるようになります。
外部ポーズ入力
パラメータ VirtualLens2 ExternalPose が 1 となっている場合、カメラの位置と向きはセットアップ時に External Pose Source で指定したオブジェクトと等しくなり、ドローン利用時と同様にカメラメッシュは代替モデルに置き換えられるようになります。
これを利用することでVirtualLens2以外のアバターギミックからカメラ姿勢を制御することが可能となります。
開発用スクリプト
Animator Controller の自動生成やパッケージングなど開発時に用いているスクリプトとシーンが VirtualLens2/Core/Generators/Editor, VirtualLens2/Core/Scenes 以下に含まれています。
もしVirtualLens2の内部実装に興味があるのであれば参考になるかと思います。
なお、これらのスクリプトを利用する場合、プロジェクトの定義済みマクロとして VL2_DEVELOPMENT を追加し、さらに Animator As Code を導入する必要があります。