// Copyright (c) Facebook Technologies, LLC and its affiliates. All rights reserved.
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Contributors*::
    Anton Vaneev, Facebook +
    Cass Everitt, Facebook +
    Federico Schliemann, Facebook +
    Johannes Schmid, Facebook


*Overview*

Passthrough is a way to show a user their physical environment in a
light-blocking VR headset.
Applications may use passthrough in a multitude of ways, including:

* Creating AR-like experiences, where virtual objects augment the user's
  environment.
* Bringing real objects into a VR experience.
* Mapping the playspace such that a VR experience is customized to it.

This extension allows:

* An application to request passthrough to be composited with the
  application content.
* An application to specify the compositing and blending rules between
  passthrough and VR content.
* An application to apply styles, such as color mapping and edge rendering,
  to passthrough.
* An application to provide a geometry to be used in place of the user's
  physical environment.
  Camera images will be projected onto the surface provided by the
  application.
  In some cases where a part of the environment, such as a desk, can be
  approximated well, this provides better visual experience.

*New Object Types*

[open,refpage='XrPassthroughFB',type='handles',desc='Passthrough feature']
--
include::{generated}/api/handles/XrPassthroughFB.adoc[]

slink:XrPassthroughFB represents a passthrough feature.
--

[open,refpage='XrPassthroughLayerFB',type='handles',desc='Passthrough layer']
--
include::{generated}/api/handles/XrPassthroughLayerFB.adoc[]

slink:XrPassthroughLayerFB represents a layer of passthrough content.
--

[open,refpage='XrGeometryInstanceFB',type='handles',desc='Triangle mesh']
--
include::{generated}/api/handles/XrGeometryInstanceFB.adoc[]

slink:XrGeometryInstanceFB represents a geometry instance used in a
passthrough layer.
--

*New Flag Types*

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

[open,refpage='XrPassthroughFlagBitsFB',type='enums',desc='XrPassthroughFlagBitsFB',xrefs='XrPassthroughFlagsFB']
--
Specify additional creation behavior.

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


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

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

[open,refpage='XrPassthroughStateChangedFlagBitsFB',type='enums',desc='XrPassthroughStateChangedFlagBitsFB',xrefs='XrPassthroughStateChangedFlagsFB']
--
Specify additional state change behavior.

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

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

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

[open,refpage='XrPassthroughCapabilityFlagBitsFB',type='enums',desc='XrPassthroughCapabilityFlagBitsFB',xrefs='XrPassthroughCapabilityFlagsFB']
--
Specify passthrough system capabilities.

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


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

*New Enum Constants*

* ename:XR_PASSTHROUGH_COLOR_MAP_MONO_SIZE_FB

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_SYSTEM_PASSTHROUGH_PROPERTIES_FB
* ename:XR_TYPE_PASSTHROUGH_CREATE_INFO_FB
* ename:XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_FB
* ename:XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_FB
* ename:XR_TYPE_GEOMETRY_INSTANCE_CREATE_INFO_FB
* ename:XR_TYPE_GEOMETRY_INSTANCE_TRANSFORM_FB
* ename:XR_TYPE_PASSTHROUGH_STYLE_FB
* ename:XR_TYPE_PASSTHROUGH_COLOR_MAP_MONO_TO_RGBA_FB
* ename:XR_TYPE_PASSTHROUGH_COLOR_MAP_MONO_TO_MONO_FB
* ename:XR_TYPE_PASSTHROUGH_BRIGHTNESS_CONTRAST_SATURATION_FB
* ename:XR_TYPE_EVENT_DATA_PASSTHROUGH_STATE_CHANGED_FB

elink:XrResult enumeration is extended with:

* ename:XR_ERROR_UNEXPECTED_STATE_PASSTHROUGH_FB The state of an object for
  which a function is called is not one of the expected states for that
  function.
* ename:XR_ERROR_FEATURE_ALREADY_CREATED_PASSTHROUGH_FB An application
  attempted to create a feature when one has already been created and only
  one can exist.
* ename:XR_ERROR_FEATURE_REQUIRED_PASSTHROUGH_FB A feature is required
  before the function can be called.
* ename:XR_ERROR_NOT_PERMITTED_PASSTHROUGH_FB Operation is not permitted.
* ename:XR_ERROR_INSUFFICIENT_RESOURCES_PASSTHROUGH_FB The runtime does not
  have sufficient resources to perform the operation.
  Either the object being created is too large, or too many objects of a
  specific kind have been created.

*New Enums*

[open,refpage='XrPassthroughLayerPurposeFB',desc='Layer purpose',type='enums']
--
Specify the kind of passthrough behavior the layer provides.

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

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

*New Structures*

[open,refpage='XrSystemPassthroughPropertiesFB',type='structs',desc='A passthrough system property',xrefs='']
--
The slink:XrSystemPassthroughPropertiesFB structure is defined as:

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

It describes a passthrough system property.

.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:supportsPassthrough defines whether the system supports the
  passthrough feature.
****

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

*New Structures*

[open,refpage='XrSystemPassthroughProperties2FB',type='structs',desc='Passthrough system properties',xrefs='']
--
The slink:XrSystemPassthroughProperties2FB structure is defined as:

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

Applications can: pass this structure in a call to
flink:xrGetSystemProperties to query passthrough system properties.
Applications should: verify that the runtime implements
apiext:XR_FB_passthrough spec version 3 or newer before doing so.
In older versions, this structure is not supported and will be left
unpopulated.
Applications should: use slink:XrSystemPassthroughPropertiesFB in that case.

.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:capabilities defines a set of features supported by the passthrough
  system.
****

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

[open,refpage='XrPassthroughCreateInfoFB',type='structs',desc='A create structure for passthrough',xrefs='']
--
The slink:XrPassthroughCreateInfoFB structure is defined as:

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

It contains parameters used to specify a new passthrough feature.

.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:flags is a bitmask of elink:XrPassthroughFlagBitsFB that specify
  additional behavior.
****

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

[open,refpage='XrPassthroughLayerCreateInfoFB',type='structs',desc='A create structure for passthrough layers',xrefs='']
--
The slink:XrPassthroughLayerCreateInfoFB structure is defined as:

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

It contains parameters used to specify a new passthrough layer.

.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:passthrough an slink:XrPassthroughFB handle.
* pname:flags elink:XrPassthroughFlagsFB that specify additional behavior.
* pname:purpose elink:XrPassthroughLayerPurposeFB that specifies the layer's
  purpose.
****

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

[open,refpage='XrCompositionLayerPassthroughFB',type='structs',desc='A composition layer for passthrough',xrefs='XrCompositionLayerBaseHeader']
--
The slink:XrCompositionLayerPassthroughFB structure is defined as:

include::{generated}/api/structs/XrCompositionLayerPassthroughFB.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:flags is a bitmask of elink:XrCompositionLayerFlagBits that specify
  additional behavior.
* pname:space is the slink:XrSpace that specifies the layer's space - must:
  be dlink:XR_NULL_HANDLE.
* pname:layerHandle is the slink:XrPassthroughLayerFB that defines this
  layer's behavior.
****

It is a composition layer type that may be submitted in flink:xrEndFrame
where an slink:XrCompositionLayerBaseHeader is specified, as a stand-in for
the actual passthrough contents.

Errata: the third field of this structure is named pname:flags rather than
`layerFlags` as expected and as documented for for the parent type
slink:XrCompositionLayerBaseHeader.

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

[open,refpage='XrGeometryInstanceCreateInfoFB',type='structs',desc='A create structure for geometry instance',xrefs='']
--
The slink:XrGeometryInstanceCreateInfoFB structure is defined as:

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

It contains parameters to specify a new geometry instance.

.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:layer is the slink:XrPassthroughLayerFB.
* pname:mesh is the slink:XrTriangleMeshFB.
* pname:baseSpace is the slink:XrSpace that defines the geometry instance's
  base space for transformations.
* pname:pose is the slink:XrPosef that defines the geometry instance's pose.
* pname:scale is the slink:XrVector3f that defines the geometry instance's
  scale.
****

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

[open,refpage='XrGeometryInstanceTransformFB',type='structs',desc='A geometry transformation',xrefs='']
--
The slink:XrGeometryInstanceTransformFB structure is defined as:

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

It describes a transformation for a geometry instance.

.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:baseSpace is the slink:XrSpace that defines the geometry instance's
  base space for transformations.
* pname:time is the basetype:XrTime that define the time at which the
  transform is applied.
* pname:pose is the slink:XrPosef that defines the geometry instance's pose.
* pname:scale is the slink:XrVector3f that defines the geometry instance's
  scale.
****

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

[open,refpage='XrPassthroughStyleFB',type='structs',desc='A layer style',xrefs='']
--
The slink:XrPassthroughStyleFB structure is defined as:

include::{generated}/api/structs/XrPassthroughStyleFB.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.
* pname:textureOpacityFactor is the opacity of the passthrough imagery in
  the range [0, 1].
* pname:edgeColor is the slink:XrColor4f that defines the edge rendering
  color.
  Edges are detected in the original passthrough imagery and rendered on top
  of it.
  Edge rendering is disabled when the alpha value of pname:edgeColor is
  zero.
****

slink:XrPassthroughStyleFB lets applications customize the appearance of
passthrough layers.
In addition to the parameters specified here, applications may: add one of
the following structures to the structure chain:
slink:XrPassthroughColorMapMonoToRgbaFB,
slink:XrPassthroughColorMapMonoToMonoFB,
slink:XrPassthroughBrightnessContrastSaturationFB.
These structures are mutually exclusive.
The runtime must: return ename:XR_ERROR_VALIDATION_FAILURE if more than one
of them are present in the structure chain.

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

[open,refpage='XrPassthroughColorMapMonoToRgbaFB',type='structs',desc='A layer color map',xrefs='']
--
The slink:XrPassthroughColorMapMonoToRgbaFB structure is defined as:

include::{generated}/api/structs/XrPassthroughColorMapMonoToRgbaFB.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.
* pname:textureColorMap is an array of slink:XrColor4f colors to which the
  passthrough imagery luminance values are mapped.
****

slink:XrPassthroughColorMapMonoToRgbaFB lets applications define a map which
replaces each input luminance value in the passthrough imagery with an RGBA
color value.
The map is applied before any additional effects (such as edges) are
rendered on top.

slink:XrPassthroughColorMapMonoToRgbaFB is provided in the pname:next chain
of slink:XrPassthroughStyleFB.

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

[open,refpage='XrPassthroughColorMapMonoToMonoFB',type='structs',desc='A layer color map',xrefs='']
--
The slink:XrPassthroughColorMapMonoToMonoFB structure is defined as:

include::{generated}/api/structs/XrPassthroughColorMapMonoToMonoFB.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.
* pname:textureColorMap is an array of code:uint8_t grayscale color values
  to which the passthrough luminance values are mapped.
****

slink:XrPassthroughColorMapMonoToMonoFB lets applications define a map which
replaces each input luminance value in the passthrough imagery with a
grayscale color value defined in pname:textureColorMap.
The map is applied before any additional effects (such as edges) are
rendered on top.

slink:XrPassthroughColorMapMonoToMonoFB is provided in the pname:next chain
of slink:XrPassthroughStyleFB.

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

[open,refpage='XrPassthroughBrightnessContrastSaturationFB',type='structs',desc='A color adjustment for passthrough layers',xrefs='']
--
The slink:XrPassthroughBrightnessContrastSaturationFB structure is defined
as:

include::{generated}/api/structs/XrPassthroughBrightnessContrastSaturationFB.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:brightness is the brightness adjustment value in the range [-100,
  100].
  The neutral element is 0.
* pname:contrast is the contrast adjustment value in the range [0,
  Infinity].
  The neutral element is 1.
* pname:saturation is the saturation adjustment value in the range [0,
  Infinity].
  The neutral element is 1.
****

slink:XrPassthroughBrightnessContrastSaturationFB lets applications adjust
the brightness, contrast, and saturation of passthrough layers.
The adjustments only are applied before any additional effects (such as
edges) are rendered on top.

The adjustments are applied in CIELAB color space (white point D65) using
the following formulas:

* [eq]#L*' = clamp((L* - 50) × contrast + 50, 0, 100)#
* [eq]#L*'' = clamp(L*' + brightness, 0, 100)#
* [eq]#(a*', b*') = (a*, b*) × saturation#
* Resulting color: (L*'', a*', b*')

slink:XrPassthroughBrightnessContrastSaturationFB is provided in the
pname:next chain of slink:XrPassthroughStyleFB.

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

[open,refpage='XrEventDataPassthroughStateChangedFB',type='structs',desc='An event for passthrough state changes',xrefs='']
--
The slink:XrEventDataPassthroughStateChangedFB structure is defined as:

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

It describes an event data for state changes return by flink:xrPollEvent.

.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:flags elink:XrPassthroughStateChangedFlagsFB that specify additional
  behavior.
****

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

*New Functions*

[open,refpage='xrCreatePassthroughFB',desc='Create a passthrough feature',type='protos',xrefs='']
--
The flink:xrCreatePassthroughFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is the slink:XrSession.
* pname:createInfo is the slink:XrPassthroughCreateInfoFB.
* pname:outPassthrough is the slink:XrPassthroughFB.
****

Creates an slink:XrPassthroughFB handle.
The returned passthrough handle may: be subsequently used in API calls.

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

[open,refpage='xrDestroyPassthroughFB',desc='Destroy a passthrough feature',type='protos',xrefs='']
--
The flink:xrDestroyPassthroughFB function is defined as:

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

.Parameter Descriptions
****
* pname:passthrough is the slink:XrPassthroughFB to be destroyed.
****

Destroys an slink:XrPassthroughFB handle.

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

[open,refpage='xrPassthroughStartFB',desc='Start a passthrough feature',type='protos',xrefs='']
--
The flink:xrPassthroughStartFB function is defined as:

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

.Parameter Descriptions
****
* pname:passthrough is the slink:XrPassthroughFB to be started.
****

Starts an slink:XrPassthroughFB feature.
If the feature is not started, either explicitly with a call to
flink:xrPassthroughStartFB, or implicitly at creation using the behavior
flags, it is considered paused.
When the feature is paused, runtime will stop rendering and compositing all
passthrough layers produced on behalf of the application, and may free up
some or all the resources used to produce passthrough until
flink:xrPassthroughStartFB is called.

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

[open,refpage='xrPassthroughPauseFB',desc='Pause a passthrough feature',type='protos',xrefs='']
--
The flink:xrPassthroughPauseFB function is defined as:

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

.Parameter Descriptions
****
* pname:passthrough is the slink:XrPassthroughFB to be paused.
****

Pauses an slink:XrPassthroughFB feature.
When the feature is paused, runtime will stop rendering and compositing all
passthrough layers produced on behalf of the application, and may free up
some or all the resources used to produce passthrough until
flink:xrPassthroughStartFB is called.

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

[open,refpage='xrCreatePassthroughLayerFB',desc='Create a passthrough layer',type='protos',xrefs='']
--
The flink:xrCreatePassthroughLayerFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is the slink:XrSession.
* pname:createInfo is the slink:XrPassthroughLayerCreateInfoFB.
* pname:outLayer is the slink:XrPassthroughLayerFB.
****

Creates an slink:XrPassthroughLayerFB handle.
The returned layer handle may: be subsequently used in API calls.
Layer objects may be used to specify rendering properties of the layer, such
as styles, and compositing rules.

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

[open,refpage='xrDestroyPassthroughLayerFB',desc='Destroy a passthrough layer',type='protos',xrefs='']
--
The flink:xrDestroyPassthroughLayerFB function is defined as:

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

.Parameter Descriptions
****
* pname:layer is the slink:XrPassthroughLayerFB to be destroyed.
****

Destroys an slink:XrPassthroughLayerFB handle.

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

[open,refpage='xrPassthroughLayerPauseFB',desc='Pause a passthrough layer',type='protos',xrefs='']
--
The flink:xrPassthroughLayerPauseFB function is defined as:

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

.Parameter Descriptions
****
* pname:layer is the slink:XrPassthroughLayerFB to be paused.
****

Pauses an slink:XrPassthroughLayerFB layer.
Runtime will not render or composite paused layers.

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

[open,refpage='xrPassthroughLayerResumeFB',desc='Resume a passthrough layer',type='protos',xrefs='']
--
The flink:xrPassthroughLayerResumeFB function is defined as:

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

.Parameter Descriptions
****
* pname:layer is the slink:XrPassthroughLayerFB to be resumed.
****

Resumes an slink:XrPassthroughLayerFB layer.

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

[open,refpage='xrPassthroughLayerSetStyleFB',desc='Set style on a passthrough layer',type='protos',xrefs='']
--
The flink:xrPassthroughLayerSetStyleFB function is defined as:

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

.Parameter Descriptions
****
* pname:layer is the slink:XrPassthroughLayerFB to get the style.
* pname:style is the slink:XrPassthroughStyleFB to be set.
****

Sets an slink:XrPassthroughStyleFB style on an slink:XrPassthroughLayerFB
layer.

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

[open,refpage='xrCreateGeometryInstanceFB',desc='Create a triangle mesh',type='protos',xrefs='']
--
The flink:xrCreateGeometryInstanceFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is the slink:XrSession.
* pname:createInfo is the slink:XrGeometryInstanceCreateInfoFB.
* pname:outGeometryInstance is the slink:XrGeometryInstanceFB.
****

Creates an slink:XrGeometryInstanceFB handle.
Geometry instance functionality requires apiext:XR_FB_triangle_mesh
extension to be enabled.
An slink:XrGeometryInstanceFB connects a layer, a mesh, and a
transformation, with the semantics that a specific mesh will be instantiated
in a specific layer with a specific transformation.
A mesh can be instantiated multiple times, in the same or in different
layers.

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

[open,refpage='xrDestroyGeometryInstanceFB',desc='Destroy a geometry instance',type='protos',xrefs='']
--
The flink:xrDestroyGeometryInstanceFB function is defined as:

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

.Parameter Descriptions
****
* pname:instance is the slink:XrGeometryInstanceFB to be destroyed.
****

Destroys an slink:XrGeometryInstanceFB handle.
Destroying an slink:XrGeometryInstanceFB does not destroy a mesh and does
not free mesh resources.
Destroying a layer invalidates all geometry instances attached to it.
Destroying a mesh invalidates all its instances.

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

[open,refpage='xrGeometryInstanceSetTransformFB',desc='Create a triangle mesh',type='protos',xrefs='']
--
The flink:xrGeometryInstanceSetTransformFB function is defined as:

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

.Parameter Descriptions
****
* pname:instance is the slink:XrGeometryInstanceFB to get the transform.
* pname:transformation is the slink:XrGeometryInstanceTransformFB to be set.
****

Sets an slink:XrGeometryInstanceTransformFB transform on an
slink:XrGeometryInstanceFB geometry instance.

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

*Issues*

*Version History*

* Revision 1, 2021-09-01 (Anton Vaneev)
** Initial extension description
* Revision 2, 2022-03-16 (Johannes Schmid)
** Introduce slink:XrPassthroughBrightnessContrastSaturationFB.
** Revise the documentation of slink:XrPassthroughStyleFB and its
   descendants.
* Revision 3, 2022-07-14 (Johannes Schmid)
** Introduce a new struct for querying passthrough system capabilities:
   slink:XrSystemPassthroughProperties2FB.
** Introduce a new flag bit that enables submission of depth maps for
   compositing: ename:XR_PASSTHROUGH_LAYER_DEPTH_BIT_FB.
* Revision 4, 2024-06-03 (Rylie Pavlik, Collabora)
** Correct registry for `XrCompositionLayerPassthroughFB`, note errata
   regarding field name.
