開発者向けガイド

パラメータの詳細など他ギミックとの連携や外部からの制御などを行いたい開発者向けの情報をまとめています。

パラメータについて

VirtualLens2の内部で利用しているパラメータを読み書きすることによって他のギミックからVirtualLens2の挙動を制御することができます。 以下にアクセス可能なパラメータとその説明を列挙します。

凡例

  • Expression Parameters 関連
    • Registered VRCExpressionParametersに登録されるパラメータです。OSCで直接制御することができます。
    • Unregistered VRCExpressionParametersに登録されないパラメータです。OSCで直接制御することができません。
  • 同期関連
    • Synchronized 他プレイヤーに同期されます。
    • Non-synchronized 他プレイヤーに同期されません。
  • アクセス権限
    • Read/Write 読み書きいずれも利用可能です。
    • Read only 読み取り専用パラメータです。書き換えた場合意図しない挙動をとることがあります。
    • Write only 書き込み専用パラメータです。意味が明文化されていない値をとることがあります。

コア要素

VirtualLens2 Control

Registered Synchronized Write only

他プレイヤーとの状態の同期、メニュー入力の受付、OSCからの制御コマンドの受付に使用されます。 外部からは後述するコマンド送信のためにのみ使用することができます。

コマンドの送信

OSC経由でVRCExpressionParametersに登録されないパラメータを扱いたい場合、このパラメータに以下の表に示す値を書きこむことによって間接的に値を書き換えることができます。

説明
1(Reserved)
2Disable
3Enable
4Auto Leveler: Disable
5Auto Leveler: Horizontal
6Auto Leveler: Vertical
7(Reserved)
8Stabilizer: Disable
9Stabilizer: Weak
10Stabilizer: Medium
11Stabilizer: Strong
12Pickup
13Drop
14Reposition
15(Reserved)
16Reposition Scale: 1x
17Reposition Scale: 3x
18Reposition Scale: 10x
19Reposition Scale: 30x
20Pin: Store 1
21Pin: Store 2
22Pin: Store 3
23Pin: Store 4
24Pin: Load 1
25Pin: Load 2
26Pin: Load 3
27Pin: Load 4
28External Pose: Disabled
29External Pose: Enabled
30Focus Lock: Disabled
31Focus Lock: Enabled
32AF Mode: Point AF
33AF Mode: Face AF
34AF Mode: Selfie AF
35(Reserved)
36Tracking Speed: Immediate
37Tracking Speed: Fast
38Tracking Speed: Medium
39Tracking Speed: Slow
40Focusing Speed: Immediate
41Focusing Speed: Fast
42Focusing Speed: Medium
43Focusing Speed: Slow
44Mesh Visibility: Show
45Mesh Visibility: Hide
46Grid: None
47Grid: 3x3
48Grid: 3x3+Diagonal
49Grid: 6x4
50(Reserved)
51(Reserved)
52Information: Hide
53Information: Show
54Leveler: Hide
55Leveler: Show
56Peaking: Disable
57Peaking: MF Only
58Peaking: Always
59(Reserved)
60Far Plane: Default
61Far Plane: 10x
62Far Plane: 100x
63(Reserved)
64Transfer Mode Permissive
65Transfer Mode: Strict
66Depth Enabler: Disable
67Depth Enabler: Enable

VirtualLens2 Enable

Unregistered Synchronized Read/Write

VirtualLens2が有効化されているかどうかを表します。 有効化されているときは1、そうでないときは0となります。

VirtualLens2 AltMesh

Unregistered Synchronized Read only

カメラモデルの表示が代替メッシュに置き換えられているかどうかを表します。 表示が置き換えられているときは1、そうでないときは0となります。

手持ちかつ手ブレ補正が有効の場合のみローカルとリモートで挙動が異なり、ローカルでは1、リモートでは0となる点に注意してください。

基本機能

VirtualLens2 Zoom

Registered 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

Registered 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

Registered Synchronized Read/Write

露出補正の設定にあわせて 0.0 から 1.0 の範囲で設定されます。

パラメータの値 \( x \) から補正値 \( E \) [EV] への変換は以下の式で行うことができます。 ここで \( E_{r} \) は設定項目中の Exposure range に対応します。

$$ E = (2x-1)E_{r} $$

位置と向きの制御

VirtualLens2 PositionMode

Unregistered Non-synchronized Read only

現在の位置調整モードを表す値が設定されます。値とモードの対応付けは以下のようになっています。

説明
0カメラを直接手に持っている状態です。
1カメラがワールド空間に固定されている状態です。
2再配置 (Reposition) 機能によってカメラ姿勢を制御している状態です。
3ドローン機能によってカメラ姿勢を制御している状態です。

VirtualLens2 AutoLeveler

Unregistered Non-synchronized Read/Write

現在の自動水平出しモードを表す値が設定されます。値とモードの対応付けは以下のようになっています。

説明
0自動水平出し機能は無効となっています。
1横向きとして水平を維持しています。
2縦向きとして水平を維持しています。

VirtualLens2 Stabilizer

Unregistered Non-synchronized Read/Write

手ブレ補正機能が有効化されているかどうかを表します。 有効化されているときは1、そうでないときは0となります。

VirtualLens2 RepositionScale

Unregistered Non-synchronized Read/Write

再配置 (Reposition) 機能利用時の動きのスケーリング係数を設定します。値とモードの対応付けは以下のようになっています。

倍率
01倍
13倍
210倍
330倍

VirtualLens2 LoadPin

Unregistered Non-synchronized Write only

1から4までの範囲の値を書きこむことによって対応する番号のピン位置にカメラを移動させます。

VirtualLens2 StorePin

Unregistered Non-synchronized Write only

1から4までの範囲の値を書きこむことによって対応する番号のピン位置として現在のカメラ位置を登録します。

VirtualLens2 ExistPin[1-4]

Unregistered Non-synchronized Read only

対応する番号のピン位置が登録済みかどうかを表します。登録済みであれば1、そうでなければ0となります。

VirtualLens2 ExternalPose

Unregistered Non-synchronized Read/Write

外部ポーズ入力が有効かどうかを表します。有効であれば1、そうでなければ0となります。

フォーカス制御

VirtualLens2 AFMode

Unregistered Non-synchronized Read/Write

オートフォーカスの方式を表します。値と方式の対応付けは以下のようになっています。

説明
0一点AF (Point AF)
1顔検出AF (Face AF)
2自撮りAF (Selfie AF)

VirtualLens2 AFSpeed

Unregistered Non-synchronized Read/Write

オートフォーカスによるフォーカス平面調整の速度を表します。値と設定の対応付けは以下のようになっています。

説明
0Immediate
1Fast
2Medium
3Slow

VirtualLens2 TrackingSpeed

Unregistered Non-synchronized Read/Write

顔検出オートフォーカス利用中に顔の検出に失敗した後に別の顔に追跡対象を移すまでの速度を表します。値と設定の対応付けは以下のようになっています。

説明
0Immediate
1Fast
2Medium
3Slow

VirtualLens2 FocusLock

Unregistered Non-synchronized Read/Write

一時的にフォーカス平面の更新を停止するためのフラグです。1であればフォーカス平面の更新が停止され、0になったときに再開されます。

VirtualLens2 Distance

Registered 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 Grid

Unregistered Non-synchronized Read/Write

プレビュー画面に表示するグリッドの種類を設定します。値と種類の対応付けは以下のようになっています。

説明
0なし
13x3
23x3 + 対角線
36x4

VirtualLens2 Information

Unregistered Non-synchronized Read/Write

プレビュー画面上に焦点距離やF値などの情報を表示するかどうかを設定します。表示する場合は1、そうでない場合は0となります。

VirtualLens2 Level

Unregistered Non-synchronized Read/Write

プレビュー画面上に水準器を表示するかどうかを設定します。表示する場合は1、そうでない場合は0となります。

VirtualLens2 Peaking

Unregistered Non-synchronized Read/Write

プレビュー画面上でピントのあっている範囲を強調表示する際の条件を設定します。値と条件の対応付けは以下のようになっています。

説明
0常に無効
1マニュアルフォーカス利用時のみ有効
2常に有効

その他の設定

VirtualLens2 Hide

Unregistered Synchronized Read/Write

Hideable Meshes に指定したメッシュの表示状態を制御します。非表示とする場合は1、表示する場合は0となります。

VirtualLens2 FarPlane

Unregistered Non-synchronized Read/Write

遠方側のカリング距離を調整します。値と設定の対応付けは以下のようになっています。

説明
0デフォルト値 (セットアップ時に指定した値)
1デフォルト値×10
2デフォルト値×100

VirtualLens2 TransferMode

Unregistered Non-synchronized Read/Write

VirtualLens2による映像上書きの対象となるカメラの条件を設定します。0であればPermissiveモード、1であればStrictモードとなります。

VirtualLens2 DepthEnabler

Unregistered Non-synchronized Read/Write

デプステクスチャに依存したシェーダを安定して動作させるための機構を制御します。有効であれば1、そうでなければ0となります。

使用例

カメラの出し入れに連動した手の形の変更

VirtualLens2 EnableVirtualLens2 AltMesh を参照することでVirtualLens2が有効かつカメラメッシュが手元に表示されているかを判別することができます。 これらをもとに手の形を変える場合、Gestureレイヤーのハンドサインに対応するレイヤーにステートおよびトランジションを追加することでカメラを握っているようなハンドアニメーションを再生することができます。 なお、VirtualLens2セットアップ時にはGestureレイヤーのパラメータリストは更新されないため、手動で利用するパラメータを Animator Controller に追加する必要があります。

ハンドサイン入力によるフォーカスロック

VRCAvatarParameterDriver を用いて VirtualLens2 FocusLock パラメータを書き換えることでフォーカスロック機能を利用することができます。 これを利用して、FXレイヤーにGestureLeftGestureRightの値に応じてパラメータを制御するレイヤーを追加することで特定のハンドサインによってフォーカスを固定することができるようになります。

外部ポーズ入力

パラメータ VirtualLens2 ExternalPose1 となっている場合、カメラの位置と向きはセットアップ時に External Pose Source で指定したオブジェクトと等しくなり、ドローン利用時と同様にカメラメッシュは代替モデルに置き換えられるようになります。 これを利用することでVirtualLens2以外のアバターギミックからカメラ姿勢を制御することが可能となります。

開発用スクリプト

Animator Controller の自動生成やパッケージングなど開発時に用いているスクリプトとシーンが VirtualLens2/Core/Editor/Generators, VirtualLens2/Core/Scenes 以下に含まれています。 もしVirtualLens2の内部実装に興味があるのであれば参考になるかと思います。 なお、これらのスクリプトを利用する場合、プロジェクトの定義済みマクロとして VL2_DEVELOPMENT を追加し、さらに Animator As Code を導入する必要があります。