libs/vr/libgvr/deviceparams/CardboardDevice.nolite.proto

syntax = "proto2";

option java_package = "com.google.vrtoolkit.cardboard.proto";
option java_outer_classname = "CardboardDevice";
option optimize_for = SPEED;

package proto;


/**
 * Message describing properties of a VR head mount device (HMD) which uses an
 * interchangeable smartphone as a display (e.g. Google Cardboard).
 *
 * While some properties are certain (e.g. inter_lens_distance), others
 * represent nominal values which may be refined depending on context (e.g.
 * viewport_angles).
 *
 * Lengths are in meters unless noted otherwise.  Fields are _required_
 * unless noted otherwise.
 *
 * Some context on why this set of parameters are deemed necessary and
 * sufficient:
 *    * FOV scale can be reasonably approximated from lens-to-screen distance
 *      and display size (i.e. knowing lens focal length isn't crucial).
 *    * Lenses are assumed to be horizontally centered with respect to
 *      display.
 *    * The display is not necessarily vertically centered.  For interchangeable
 *      phones where the device rests against a tray, we can derive
 *      the vertical offset from tray-to-lens height along with phone-specific
 *      bezel and screen sizes (supplied separately).
 */
message DeviceParams {
  // String identifying the device's vendor (e.g. "Google, Inc.").
  // A device's [vendor, model] pair is expected to be globally unique.
  optional string vendor = 1;

  // String identifying the device's model, including revision info if
  // needed (e.g. "Cardboard v1").  A device's [vendor, model] pair is
  // expected to be globally unique.
  optional string model = 2;

  // Distance from the display screen to the optical center of lenses.
  // This is a required field for distortion rendering, and must be positive.
  optional float screen_to_lens_distance = 3;

  // Horizontal distance between optical center of the lenses.
  // This is a required field for distortion rendering, and must be positive.
  optional float inter_lens_distance = 4;

  // Four-element tuple (left, right, bottom, top) of left eye's view extent
  // angles relative to center, assuming the following:
  //     * eye is aligned with optical center of lens
  //     * display screen is equal or larger than extents viewable through lens
  //     * nominal eye-to-lens distance
  //     * mirrored field of view will be applied to the right eye
  // These values are essentially used as an optimization to avoid rendering
  // pixels which can't be seen.
  // This is a required field for distortion rendering, and angles must be
  // positive.
  repeated float left_eye_field_of_view_angles = 5 [packed = true];

  enum VerticalAlignmentType {
    BOTTOM = 0;  // phone rests against a fixed bottom tray
    CENTER = 1;  // phone screen assumed to be centered w.r.t. lenses
    TOP = 2;     // phone rests against a fixed top tray
  }

  // Set according to vertical alignment strategy-- see enum comments above.
  // NOTE: If you set this to CENTER, see special instructions for the
  // tray_to_lens_distance field below.
  optional VerticalAlignmentType vertical_alignment = 11 [default = BOTTOM];

  // If the phone is aligned vertically within the device by resting against
  // a fixed top or bottom tray, this is the distance from the tray to
  // optical center of the lenses.
  // This is a required field for distortion rendering, and must be positive.
  // NOTE: Due to a bug in initial versions of the SDK's, this field
  // must be set explicitly to .035 when vertical_alignment = CENTER.
  optional float tray_to_lens_distance = 6;

  // Coefficients Ki for pincushion distortion function which maps
  // from position on real screen to virtual screen (i.e. texture) relative
  // to optical center:
  //
  //    p' = p (1 + K1 r^2 + K2 r^4 + ... + Kn r^(2n))
  //
  // where r is the distance in tan-angle units from the optical center,
  // p the input point, and p' the output point.  Tan-angle units can be
  // computed as distance on the screen divided by distance from the
  // virtual eye to the screen.
  repeated float distortion_coefficients = 7 [packed = true];
  // Slots 8, 9 reserved for per-color channel distortion.

  // Optionally, whether the head mount uses a magnet in any part of its
  // design.  Intended as hint as to whether phone's magnetometer is
  // available for tasks such as orientation tracking.
  optional bool has_magnet = 10;

  enum ButtonType {
    // No physical button, and touch screen is not easily accessible.
    NONE = 0;
    // HMD has integrated magnet switch similar to original Cardboard.
    MAGNET = 1;
    // At least a portion of touch screen is easily accessible to user for taps.
    TOUCH = 2;
    // Touch screen is triggered indirectly via integrated button on the HMD.
    INDIRECT_TOUCH = 3;
  }

  // Specify primary input mechanism of the HMD.  Intended for advisory
  // purposes only, to address simple questions such as "can HMD
  // be used with apps requiring a physical button event?" or "what icon
  // should be used to represent button action to the user?".
  optional ButtonType primary_button = 12 [default = MAGNET];

  // Some internal data for Cardboard.  This data is not intended to be
  // set or used by developers, and any data in this proto is not guaranteed
  // to be supported with new SDK updates.
  optional CardboardInternalParams internal = 1729;

  // Optionally, specifies the additional parameters that are necessary for
  // a Daydream-ready headset. This field is non-null if the headset is
  // Daydream-ready.
  // TODO(b/30112366) The inclusion of this message inside a DeviceParams is a
  // somewhat ugly result of some historical choices in the SDK. We should
  // consider refactoring our code to allow us to remove this, and the
  // CardboardInternalParams messages from this proto.
  optional DaydreamInternalParams daydream_internal = 196883;
}

// TODO(b/27108179): CardboardInternalParams should be migrated into its own
// file, and not live in this file.

/**
 * Message describing parameters that are used internally by Cardboard
 * and VRToolkit. These parameters don't necessarily fit into the DeviceParams
 * notion of a VR viewer combined with user's phone (e.g. case of viewer with
 * dedicated display, etc.) and are not intended to be used by developers
 * and may or may not be supported or changed without notice on new releases
 * of the Cardboard SDK or VR Toolkit.
 */
message CardboardInternalParams {
  // Used to specify a per-eye post-process transformation -- an optional
  // rotation and x-axis reflection -- to be applied after distortion
  // correction.
  enum OrientationType {
    CCW_0_DEGREES = 0;
    CCW_90_DEGREES = 1;
    CCW_180_DEGREES = 2;
    CCW_270_DEGREES = 3;
    CCW_0_DEGREES_MIRRORED = 4;
    CCW_90_DEGREES_MIRRORED = 5;
    CCW_180_DEGREES_MIRRORED = 6;
    CCW_270_DEGREES_MIRRORED = 7;
  }

  // Specify a post-process transformation that is applied after the distortion
  // function. This field is optional, if not specified, CCW_0_DEGREES is
  // assumed. If repeated, the first orientation is for the left eye, the second
  // is for the right eye.
  //
  // For example, if [CCW_90_DEGREES, CCW_270_DEGREES_MIRRORED] is specified,
  //
  // this input:
  //
  // ***************** *****************
  // *1             2* *1             2*
  // *      *        * *      ***      *
  // *      *        * *      * *      *
  // *      ****     * *      *  *     *
  // *4             3* *4             3*
  // ***************** *****************
  //
  // is rendered on the screen like this:
  //
  // ***************** *****************
  // *2       *     3* *3     *       2*
  // *        *      * *       **      *
  // *        *      * *        *      *
  // *      ***      * *      ***      *
  // *1             4* *4             1*
  // ***************** *****************
  repeated OrientationType eye_orientations = 1 [packed = true];

  // Specify a horizontal offset from the middle of the screen to the center of
  // the lens, in meters. If one is not provided, half of the inter lens
  // distance is used.
  //
  // This is only necessary if the HMD has some sort of periscope effect, where
  // the position of the lenses, relative to the screen, is different than
  // their position relative to the user.
  //
  // For example, in the HMD below, two mirrors reflect the image from the
  // screen to the user, creating a larger inter lens distance than the screen
  // can support.
  //
  // [In the diagram below, S = screen, L = lens]
  //
  // screen_center_to_lens_distance
  //             |--|
  //
  // -------------------------
  // |     SSSSSSSSSSSS      |
  // |        |  |  |        |
  // |   /----/  |  \----\   |
  // |   |       |       |   |
  // |  LLL             LLL  |
  //
  //     |---------------|
  //    inter_lens_distance
  //
  optional float screen_center_to_lens_distance = 2;

  // Optional x-dimension physical pixels per inch of the external display,
  // assuming landscape orientation. If set, this will override OS-reported
  // values.
  optional float x_ppi_override = 3;

  // Optional y-dimension physical pixels per inch of the external display,
  // assuming landscape orientation.  If set, this will override OS-reported
  // values.
  optional float y_ppi_override = 4;

  // Optional string identifying the device's accelerometer and gyroscope.
  // If either field is filled out, the corresponding sensor (gyroscope or
  // accelerometer) will be used for head tracking.
  //
  // Valid strings are usually found in:
  // vendor/<vendorname>/<devicename>/xxx/sensors.cpp
  //
  // For dynamic sensors, this string will be provided in a separate way.
  //
  // NB: Vendors and manufacturers should make the name of the sensor as
  // specific as possible, since if multiple sensors with the same name are
  // connected, the first will be used.
  optional string accelerometer = 5;
  optional string gyroscope = 6;
}

/**
 * Message describing the additional properties of a Daydream-ready headset that
 * are not used for a normal cardboard viewer. These parameters are not intended
 * to be used, or consumed, by developers and may or may not be supported or
 * changed without notice on new releases of the Cardboard SDK or VR Toolkit.
 */
message DaydreamInternalParams {
  // The version of the Daydream-ready specification to which this device
  // conforms.
  optional int32 version = 1;

  // Optionally, specifies the collection of screen alignment markers in the
  // headset.
  repeated ScreenAlignmentMarker alignment_markers = 2;
}

/**
 * Message describing a single screen alignment marker.
 *
 * A screen alignment marker is a capacitive touch point affixed to the headset
 * which is capable of making contact with the screen. The location of the touch
 * point is given in meters, measured along a horizontal axis which passes
 * through the center of both lenses, and a vertical axis which is equidistant
 * from the centers of the lenses. A positive vertical value indicates that the
 * point lies above the horizontal axis, and a positive horizontal value
 * indicates that the point lies to the right, as seen by a user of the headset,
 * of the vertical axis. For example, if the following is a representation of a
 * headset, viewed from the point of view of a user, with three points marked by
 * the numbers 1, 2, and 3.
 *
 * *****************************************************************************
 * *                                    ^                                      *
 * *               _____                |                _____                 *
 * *              /     \               1               /     \                *
 * *             /       \              |              /       \               *
 * *            /         \             |             /         \              *
 * *           /           \            |            /           \             *
 * *          /             \           |           /             \            *
 * *---------|-------*-------|----------+------2---|-------*-------|---------->*
 * *          \             /           |           \             /            *
 * *           \           /            |            \           /             *
 * *            \         /         3   |             \         /              *
 * *             \       /              |              \       /               *
 * *              \_____/               |               \_____/                *
 * *                                    |                                      *
 * *                                    |                                      *
 * *****************************************************************************
 *
 * Then the coordinates of point 1 could be horizontal = 0.0, vertical = 0.035;
 * point 2 could be horizontal = 0.02; and point 3 could be horizontal = -0.01
 * vertical = -0.012
 */
message ScreenAlignmentMarker {
  // The horizontal coordinate of the touch point.
  optional float horizontal = 1;

  // The vertical coordinate of the touch point.
  optional float vertical = 2;
}