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

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

*Last Modified Date*::
    2023-06-12

*IP Status*::
    No known IP claims.

*Contributors*::
    Yuichi Taguchi, Meta Platforms +
    Anton Vaneev, Meta Platforms +
    Andreas Loeve Selvik, Meta Platforms +
    John Kearney, Meta Platforms +


==== Overview

This extension expands on the concept of spatial entities to include a way
for a spatial entity to represent a triangle mesh that describes 3D geometry
of the spatial entity in a scene.
Spatial entities are defined in apiext:XR_FB_spatial_entity extension using
the Entity-Component System.
The triangle mesh is a component type that may: be associated to a spatial
entity.

In order to enable the functionality of this extension, you must: pass the
name of the extension into flink:xrCreateInstance via the
slink:XrInstanceCreateInfo::pname:enabledExtensionNames parameter as
indicated in the <<fundamentals-extensions>> section.


==== Retrieving a triangle mesh

[open,refpage='xrGetSpaceTriangleMeshMETA',desc='Gets an XrSpaceTriangleMeshMETA that represents a triangle mesh',type='protos',xrefs='']
--
The flink:xrGetSpaceTriangleMeshMETA function is defined as:

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

.Parameter Descriptions
****
* pname:space is a handle to an slink:XrSpace.
* pname:getInfo exists for extensibility purposes.
  It is code:NULL or a pointer to a valid
  slink:XrSpaceTriangleMeshGetInfoMETA.
* pname:triangleMeshOutput is the output parameter that points to an
  slink:XrSpaceTriangleMeshMETA.
****

The flink:xrGetSpaceTriangleMeshMETA function is used by the application to
perform the two calls required to obtain a triangle mesh associated to a
spatial entity specified by pname:space.

The spatial entity pname:space must: have the
ename:XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META component type enabled,
otherwise this function will return
ename:XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB.

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

[open,refpage='XrSpaceTriangleMeshGetInfoMETA',type='structs',desc='Input parameter to the xrGetSpaceTriangleMeshMETA function',xrefs='']
--
The slink:XrSpaceTriangleMeshGetInfoMETA structure is defined as:

include::{generated}/api/structs/XrSpaceTriangleMeshGetInfoMETA.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.
****

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

[open,refpage='XrSpaceTriangleMeshMETA',type='structs',desc='Output parameter to the xrGetSpaceTriangleMeshMETA function',xrefs='']
--
The slink:XrSpaceTriangleMeshMETA structure is defined as:

include::{generated}/api/structs/XrSpaceTriangleMeshMETA.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 an input parameter for the application to
  specify the capacity of the pname:vertices array, or 0 to indicate a
  request to retrieve the required capacity.
* pname:vertexCountOutput is an output parameter that will hold the number
  of vertices written in the output array, or the required capacity in the
  case that pname:vertexCapacityInput is insufficient.
  The returned value must: be equal to or larger than 3.
* pname:vertices is a pointer to an array of slink:XrVector3f, but can: be
  code:NULL if pname:vertexCapacityInput is 0.
  The vertices are defined in the coordinate frame of slink:XrSpace to which
  this struct is associated.
* pname:indexCapacityInput is an input parameter for the application to
  specify the capacity of the pname:indices array, or 0 to indicate a
  request to retrieve the required capacity.
* pname:indexCountOutput is an output parameter that will hold the number of
  indices written in the output array, or the required capacity in the case
  that pname:indexCapacityInput is insufficient.
  The returned value must: be a multiple of 3.
* pname:indices is a pointer to an array of code:uint32_t, but can: be
  code:NULL if pname:indexCapacityInput is 0.
  Each element refers to a vertex in pname:vertices.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:vertices and pname:indices
  array sizes.
****

The slink:XrSpaceTriangleMeshMETA structure can: be used by the application
to perform the two calls required to obtain a triangle mesh associated to a
specified spatial entity.

The output values written in the pname:indices array represent indices of
vertices: Three consecutive elements represent a triangle with a
counter-clockwise winding order.

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


*New Object Types*

*New Atom*

*New Flag Types*

*New Enum Constants*

elink:XrSpaceComponentTypeFB enumeration is extended with:

* ename:XR_SPACE_COMPONENT_TYPE_TRIANGLE_MESH_META

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_SPACE_TRIANGLE_MESH_GET_INFO_META
* ename:XR_TYPE_SPACE_TRIANGLE_MESH_META

*New Enums*

*New Structures*

* slink:XrSpaceTriangleMeshGetInfoMETA
* slink:XrSpaceTriangleMeshMETA

*New Functions*

* flink:xrGetSpaceTriangleMeshMETA


*Issues*

*Version History*

* Revision 1, 2023-06-12 (Yuichi Taguchi)
** Initial extension description.
