Developer Guide

About Parameters

By reading and writing parameters used within VirtualLens2, you can control the behavior of VirtualLens2 from other gadgets. Below is a list of accessible parameters and their explanations.

Legend

• Synchronization
  • Synchronized Synchronized with other players.
  • Non-synchronized Not synchronized with other players.
  • Optional-synchronized Synchronized only if enabled during setup.
• Access control
  • Read/Write Both reading and writing are available.
  • Read only Read-only parameters. Changing them may cause unintended behavior.
  • Write only Write-only parameters. The values they take may not be explicitly defined.

Core Elements

VirtualLens2 Control

Synchronized Write only

Used for synchronization with other players, accepting menu input, and receiving control commands via OSC. It can only be used from external sources for sending commands.

Sending Control Commands

If you need to handle parameters not registered in VRCExpressionParameters via OSC, you can update them by writing following values to VirtualLens2 Control.

Show command lists

VirtualLens2 Enable

Synchronized Read/Write

Indicates whether VirtualLens2 is enabled. It is 1 when enabled and 0 when disabled.

VirtualLens2 AltMesh

Synchronized Read only

Indicates whether the camera model’s display is replaced with an alternate mesh. When the display is replaced, it is 1, otherwise 0.

Note that there is a difference in behavior between local and remote when it is handheld and image stabilization is enabled. In the local context, it is 1, while in the remote context, it is 0.

Basic Functions

VirtualLens2 Zoom

Optional-synchronized Read/Write

Set between 0.0 and 1.0 according to the focal length. You can calculate the conversion from parameter value \( x \) to focal length \( f \) using the following equation. Here, \( f_{\min} \) and \( f_{\max} \) correspond to the Min focal length and Max focal length in the setup items, respectively.

$$ f = f_{\min} \exp \Bigl\{ x \log \frac {f_{\max}} {f_{\min}} \Bigr\} $$

VirtualLens2 Aperture

Optional-synchronized Read/Write

Set between 0.0 and 1.0 according to the aperture (F number). You can calculate the conversion from parameter value \( x \) to F number using the following equation. Here, \( F_{\min} \) and \( F_{\max} \) correspond to the Min F number and Max F number in the setup items, respectively.

$$ F = F_{\min} \exp \Bigl\{ x \log \frac {F_{\max}} {F_{\min}} \Bigr\} $$

VirtualLens2 Exposure

Optional-synchronized Read/Write

Set between 0.0 and 1.0 according to the exposure compensation. You can calculate the conversion from parameter value \( x \) to correction value \( E \) [EV] using the following equation. Here, \( E_r \) corresponds to the Exposure Range in the setup items.

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

Position and Orientation Control

VirtualLens2 PositionMode

Non-synchronized Read only

Indicates the current position adjustment mode. The correspondence between values and modes is as follows:

VirtualLens2 AutoLeveler

Non-synchronized Read/Write

Indicates the current auto-leveling mode. The correspondence between values and modes is as follows:

VirtualLens2 Stabilizer

Non-synchronized Read/Write

Indicates the current image stabilization mode. The correspondence between values and modes is as follows:

VirtualLens2 RepositionScale

Non-synchronized Read/Write

Sets the scaling factor for movement when using the reposition feature. The correspondence between values and multipliers is as follows:

VirtualLens2 LoadPin

Non-synchronized Write only

By writing a value in the range of 1 to 4, the camera is moved to the corresponding pin position.

VirtualLens2 StorePin

Non-synchronized Write only

By writing a value in the range of 1 to 4, the current camera position is registered as the position for the corresponding pin.

VirtualLens2 ExistPin[1-4]

Non-synchronized Read only

Indicates whether the corresponding pin position is registered. It is 1 when registered and 0 when not registered.

VirtualLens2 ExternalPose

Non-synchronized Read/Write

Indicates whether external pose input is enabled. It is 1 when enabled and 0 when disabled.

Focus Control

VirtualLens2 AFMode

Non-synchronized Read/Write

Indicates the autofocus mode. The correspondence between values and modes is as follows:

VirtualLens2 AFSpeed

Non-synchronized Read/Write

Indicates the speed of focus plane adjustment by autofocus. The correspondence between values and settings is as follows:

VirtualLens2 TrackingSpeed

Non-synchronized Read/Write

Indicates the speed at which, when using face detection autofocus, it switches to tracking another face after failing to detect a face. The correspondence between values and settings is as follows:

VirtualLens2 FocusLock

Non-synchronized Read/Write

A flag to temporarily stop updating the focus plane. When it is 1, the update of the focus plane is stopped, and when it becomes 0, it resumes.

VirtualLens2 Distance

Optional-synchronized Read/Write

Indicates the distance to the plane where the focus is set during manual focus, ranging from 0.0 to 1.0. You can calculate the conversion from parameter value \( x \) to distance \( D \) [m] using the following equation. Here, \( D_{\min} \) and \( D_{\max} \) correspond to the Min focus distance and Max focus distance in the setup items.

$$ D = D_{\min} \exp \Bigl\{ x \log \frac {D_{\max}} {D_{\min}} \Bigr\} $$

VirtualLens2 TouchOverride

Non-synchronized Read/Write

This flag is used to simulate touchscreen operations through avatar parameters. While set to 1, the coordinates specified by TouchOverrideX and TouchOverrideY are considered touched.

VirtualLens2 TouchOverrideX, VirtualLens2 TouchOverrideY

Non-synchronized Read/Write

When simulating touchscreen operations through the TouchOverride parameter, set the coordinates considered as touched in the range of -1.0 to 1.0 for both X and Y. The X coordinate increases from left to right, and the Y coordinate increases from bottom to top.

Screen Settings

VirtualLens2 Grid

Non-synchronized Read/Write

Sets the type of grid to display on the preview screen. The correspondence between values and types is as follows:

VirtualLens2 Information

Non-synchronized Read/Write

Sets whether to display information such as focal length and F number on the preview screen. It is 1 when displayed and 0 when not displayed.

VirtualLens2 Level

Non-synchronized Read/Write

Sets whether to display a level on the preview screen. It is 1 when displayed and 0 when not displayed.

VirtualLens2 Peaking

Non-synchronized Read/Write

Sets the condition for emphasizing the range with correct focus on the preview screen. The correspondence between values and conditions is as follows:

Mask Settings

VirtualLens2 LocalPlayerMask

Non-synchronized Read/Write

Select whether to reflect the shooter’s own avatar. Set to 1 if reflecting, 0 if not.

VirtualLens2 RemotePlayerMask

Non-synchronized Read/Write

Select whether to reflect avatars of players other than the shooter. Set to 1 if reflecting, 0 if not.

VirtualLens2 UIMask

Non-synchronized Read/Write

Select whether to reflect UI elements. Set to 1 if reflecting, 0 if not.

Other Settings

VirtualLens2 Hide

Synchronized Read/Write

Controls the visibility of meshes specified in Hideable Meshes. Set to 1 to hide and 0 to show.

VirtualLens2 PreviewHUD

Non-synchronized Read/Write

Controls the visibility of the preview HUD. Set to 1 to show and 0 to hide.

VirtualLens2 FarPlane

Non-synchronized Read/Write

Adjusts the culling distance on the far side. The correspondence between values and settings is as follows:

VirtualLens2 DepthEnabler

Non-synchronized Read/Write

Controls a mechanism to ensure the stable operation of shaders that depend on depth textures. It is 1 when enabled and 0 when disabled.

Reading Avatar Settings

VirtualLens2 Version

Non-synchronized Read only

If VirtualLens2 vX.Y.Z is set up, the integer value X * 10000 + Y * 100 + Z is set.

VirtualLens2 Zoom Min, VirtualLens2 Zoom Max

Non-synchronized Read only

Sets the lower and upper limits for the focal length, \( f_{\min} \), and \( f_{\max} \) in millimeters as floating-point numbers.

VirtualLens2 Aperture Min, VirtualLens2 Aperture Max

Non-synchronized Read only

Sets the lower and upper limits for the aperture (F number), \( F_{\min} \), and \( F_{\max} \) as floating-point numbers.

VirtualLens2 Exposure Range

Non-synchronized Read only

Sets the range of correction values, \( E_r \), used for exposure correction as a floating-point number.

VirtualLens2 Resolution X, VirtualLens2 Resolution Y

Non-synchronized Read only

Sets the expected resolution of images from VirtualLens2 as integers.

Usage Examples

Changing Hand Shape with Enabling and Disabling VirtualLens2

By referring to VirtualLens2 Enable and VirtualLens2 AltMesh, you can determine if VirtualLens2 is enabled and the camera mesh is displayed at the hand position. Based on these, if you want to change the hand shape, you can add states and transitions to the hand animation corresponding to the hand sign in the Gesture layer. If Gesture layers' parameter lists are not updated during VirtualLens2 setup, you need to manually add the parameters you want to use to the Animator Controller.

Focus Lock via Hand Sign Input

By using VRCAvatarParameterDriver to rewrite the VirtualLens2 FocusLock parameter, you can use the focus lock feature. Using this, you can add a layer to control parameters based on GestureLeft and GestureRight values to fix focus with specific hand signs.

External Pose Input

If the parameter VirtualLens2 ExternalPose is 1, the camera’s position and orientation will match the object specified in “External Pose Source” during setup, and the camera mesh will be replaced with an alternate model, as in the case of using the drone feature. This allows you to control the camera posture from Avatar Gadgets other than VirtualLens2.

Development Scripts

Scripts used for development, such as generating Animator Controllers and packaging, can be found in VirtualLens2/Core/Generators/Editor and VirtualLens2/Core/Scenes. If you are interested in the internal implementation of VirtualLens2, these scripts may be helpful. To use these scripts, you need to add VL2_DEVELOPMENT as a predefined macro in your project and introduce Animator As Code.