// Copyright (c) 2021, Almalence Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_ALMALENCE_digital_lens_control.adoc[]


*Last Modified Date*::
   2021-11-08
*IP Status*::
    No known IP claims.
*Contributors*::
    Ivan Chupakhin, Almalence Inc. +
    Dmitry Shmunk, Almalence Inc.


*Overview*

Digital Lens for VR (DLVR) is a computational lens aberration correction
technology enabling high resolution, visual clarity and fidelity in VR head
mounted displays.
The Digital Lens allows to overcome two fundamental factors limiting VR
picture quality, size constraints and presence of a moving optical element —
the eye pupil.

Features:

* Complete removal of lateral chromatic aberrations, across the entire FoV,
  at all gaze directions.
* Correction of longitudinal chromatic aberrations, lens blur and higher
  order aberrations.
* Increase of visible resolution.
* Enhancement of edge contrast (otherwise degraded due to lens smear).
* Enables high quality at wide FoV.

For OpenXR runtimes DLVR is implemented as implicit API Layer distributed by
Almalence Inc.
as installable package.
DLVR utilize eye tracking data (eye pupil coordinates and gaze direction) to
produce corrections of render frames.
As long as current core OpenXR API does not expose an eye tracking data,
DLVR API Layer relies on 3rd-party eye tracking runtimes.

List of supported eye tracking devices:

* _Tobii_VR4_CARBON_P1_ (HP Reverb G2 Omnicept Edition)
* _Tobii_VR4_U2_P2_ (HTC Vive Pro Eye)


This extension enables the handling of the Digital Lens for VR API Layer by
calling flink:xrSetDigitalLensControlALMALENCE.

*New Object Types*

*New Flag Types*

[open,refpage='XrDigitalLensControlFlagsALMALENCE',type='flags',desc='XrDigitalLensControlFlagsALMALENCE']
--
include::{generated}/api/flags/XrDigitalLensControlFlagsALMALENCE.adoc[]
--

[open,refpage='XrDigitalLensControlFlagBitsALMALENCE',type='enums',desc='XrDigitalLensControlFlagBitsALMALENCE']
--
include::{generated}/api/enums/XrDigitalLensControlFlagBitsALMALENCE.adoc[]

include::{generated}/api/enums/XrDigitalLensControlFlagBitsALMALENCE.comments.adoc[]
--

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_DIGITAL_LENS_CONTROL_ALMALENCE

*New Enums*

*New Structures*

[open,refpage='XrDigitalLensControlALMALENCE',type='structs',desc='The digital lens control structure to be passed to change state of DLVR API Layer']
--
The slink:XrDigitalLensControlALMALENCE structure is defined as:

include::{generated}/api/structs/XrDigitalLensControlALMALENCE.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next must be code:NULL.
  No such structures are defined in core OpenXR or this extension.
* pname:flags is a bitmask of elink:XrDigitalLensControlFlagBitsALMALENCE
  indicating various characteristics desired for the Digital Lens.
****

include::{generated}/validity/structs/XrDigitalLensControlALMALENCE.adoc[]
--

*New Functions*

[open,refpage='xrSetDigitalLensControlALMALENCE',type='protos',desc='Sets DLVR status']
--
The flink:xrSetDigitalLensControlALMALENCE function is defined as:

include::{generated}/api/protos/xrSetDigitalLensControlALMALENCE.adoc[]

.Parameter Descriptions
****
* pname:session is a handle to a running slink:XrSession.
* pname:digitalLensControl is the slink:XrDigitalLensControlALMALENCE that
  contains desired characteristics for the Digital Lens
****

flink:xrSetDigitalLensControlALMALENCE handles state of Digital Lens API
Layer

include::{generated}/validity/protos/xrSetDigitalLensControlALMALENCE.adoc[]
--

*Issues*

*Version History*

* Revision 1, 2021-11-08 (Ivan Chupakhin)
** Initial draft
