// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Last Modified Date*::
    2018-07-05
*IP Status*::
    No known IP claims.
*Contributors*::
    Paul Pedriana, Oculus +
    Alex Turner, Microsoft
*Contacts*::
    Paul Pedriana, Oculus

*Overview*

This extension support the providing of a per-view drawing mask for
applications.
The primary purpose of this is to enable performance improvements that
result from avoiding drawing on areas that are not visible to the user.
A common occurrence in head-mounted VR hardware is that the optical system's
frustum does not intersect precisely with the rectangular display it is
viewing.
As a result, it may be that there are parts of the display that are not
visible to the user, such as the corners of the display.
In such cases it would be unnecessary for the application to draw into those
parts.

*New Object Types*

*New Flag Types*

*New Enum Constants*

*New Enums*


[open,refpage='XrVisibilityMaskTypeKHR',desc='Visibility Mask Type',type='enums']
--
elink:XrVisibilityMaskTypeKHR identifies the different types of mask
specification that is supported.
The application can: request a view mask in any of the formats identified by
these types.

include::{generated}/api/enums/XrVisibilityMaskTypeKHR.adoc[]

.Enumerant Descriptions
****
* ename:XR_VISIBILITY_MASK_TYPE_HIDDEN_TRIANGLE_MESH_KHR refers to a two
  dimensional triangle mesh on the view surface which should: not be drawn
  to by the application.
  slink:XrVisibilityMaskKHR refers to a set of triangles identified by
  vertices and vertex indices.
  The index count will thus be a multiple of three.
  The triangle vertices will be returned in counter-clockwise order as
  viewed from the user perspective.

* ename:XR_VISIBILITY_MASK_TYPE_VISIBLE_TRIANGLE_MESH_KHR refers to a two
  dimensional triangle mesh on the view surface which should: be drawn to by
  the application.
  slink:XrVisibilityMaskKHR refers to a set of triangles identified by
  vertices and vertex indices.
  The index count will thus be a multiple of three.
  The triangle vertices will be returned in counter-clockwise order as
  viewed from the user perspective.

* ename:XR_VISIBILITY_MASK_TYPE_LINE_LOOP_KHR refers to a single
  multi-segmented line loop on the view surface which encompasses the view
  area which should: be drawn by the application.
  It is the border that exists between the visible and hidden meshes
  identified by ename:XR_VISIBILITY_MASK_TYPE_HIDDEN_TRIANGLE_MESH_KHR and
  ename:XR_VISIBILITY_MASK_TYPE_VISIBLE_TRIANGLE_MESH_KHR.
  The line is counter-clockwise, contiguous, and non-self crossing, with the
  last point implicitly connecting to the first point.
  There is one vertex per point, the index count will equal the vertex
  count, and the indices will refer to the vertices.
****
--

*New Structures*

[open,refpage='XrVisibilityMaskKHR',desc='Visibility Mask',type='structs']
--
The slink:XrVisibilityMaskKHR structure is an input/output struct which
specifies the view mask.

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

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:vertexCapacityInput is the capacity of the pname:vertices array, or
  `0` to indicate a request to retrieve the required capacity.
* pname:vertexCountOutput is filled in by the runtime with the count of
  vertices written or the required capacity in the case that
  pname:vertexCapacityInput or pname:indexCapacityInput is insufficient.
* pname:vertices is an array of vertices filled in by the runtime that
  specifies mask coordinates in the z=-1 plane of the rendered view--i.e.
  one meter in front of the view.
  When rendering the mask for use in a projection layer, these vertices must
  be transformed by the application's projection matrix used for the
  respective slink:XrCompositionLayerProjectionView.

* pname:indexCapacityInput is the capacity of the pname:indices array, or
  `0` to indicate a request to retrieve the required capacity.
* pname:indexCountOutput is filled in by the runtime with the count of
  indices written or the required capacity in the case that
  pname:vertexCapacityInput or pname:indexCapacityInput is insufficient.
* pname:indices is an array of indices filled in by the runtime, specifying
  the indices of the mask geometry in the pname:vertices array.
****

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

[open,refpage='XrEventDataVisibilityMaskChangedKHR',desc='Visibility Mask',type='structs']
--
The slink:XrEventDataVisibilityMaskChangedKHR structure specifies an event
which indicates that a given view mask has changed.
The application should: respond to the event by calling
flink:xrGetVisibilityMaskKHR to retrieve the updated mask.
This event is per-view, so if the masks for multiple views in a
configuration change then multiple instances of this event will be sent to
the application, one per view.

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

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:session is the slink:XrSession for which the view mask has changed.
* pname:viewConfigurationType is the view configuration whose mask has
  changed.
* pname:viewIndex is the individual view within the view configuration to
  which the change refers.
****

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

*New Functions*

[open,refpage='xrGetVisibilityMaskKHR',desc='Gets visibility mask',type='protos']
--
The flink:xrGetVisibilityMaskKHR function is defined as:

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

.Parameter Descriptions
****
* pname:session is an slink:XrSession handle previously created with
  flink:xrCreateSession.
* pname:viewConfigurationType is the view configuration from which to
  retrieve mask information.
* pname:viewIndex is the individual view within the view configuration from
  which to retrieve mask information.
* pname:visibilityMaskType is the type of visibility mask requested.
* pname:visibilityMask is an input/output struct which specifies the view
  mask.
****

flink:xrGetVisibilityMaskKHR retrieves the view mask for a given view.
This function follows the <<fundamentals-buffer-size-parameters,two-call
idiom>> for filling multiple buffers in a struct.
Specifically, if either slink:XrVisibilityMaskKHR::pname:vertexCapacityInput
or slink:XrVisibilityMaskKHR::pname:indexCapacityInput is `0`, the runtime
must: respond as if both fields were set to `0`, returning the vertex count
and index count through slink:XrVisibilityMaskKHR::pname:vertexCountOutput
or slink:XrVisibilityMaskKHR::pname:indexCountOutput respectively.
If a view mask for the specified view isn't available, the returned vertex
and index counts must: be `0`.

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

*Issues*

*Version History*

* Revision 1, 2018-07-05 (Paul Pedriana)
** Initial version.
* Revision 2, 2019-07-15 (Alex Turner)
** Adjust two-call idiom usage.
