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

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

*Contributors*::
    John Schofield, Facebook +
    Andrew Kim, Facebook +
    Yuichi Taguchi, Facebook +
    Cass Everitt, Facebook


*Overview*

This extension expands on the concept of spatial entities to include a way
for a spatial entity to represent rooms, objects, or other boundaries in a
scene.

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.

*New Object Types*

*New Flag Types*

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

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

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

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_SEMANTIC_LABELS_FB
* ename:XR_TYPE_ROOM_LAYOUT_FB
* ename:XR_TYPE_BOUNDARY_2D_FB
* ename:XR_TYPE_SEMANTIC_LABELS_SUPPORT_INFO_FB

*New Enums*

*New Structures*

[open,refpage='XrExtent3DfFB',type='structs',desc='Represents a rectangular prism',xrefs='']
--
The slink:XrExtent3DfFB structure is defined as:

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

.Member Descriptions
****
* pname:width is the floating-point width of the extent.
* pname:height is the floating-point height of the extent.
* pname:depth is the floating-point depth of the extent.
****

This structure is used for component values that may be fractional
(floating-point).
If used to represent physical distances, values must be in meters.
The width, height, and depth values must be non-negative.

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

[open,refpage='XrOffset3DfFB',type='structs',desc='Represents a point of 3D space',xrefs='']
--
The slink:XrOffset3DfFB structure is defined as:

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

.Member Descriptions
****
* pname:x is the floating-point offset in the x direction.
* pname:y is the floating-point offset in the y direction.
* pname:z is the floating-point offset in the z direction.
****

This structure is used for component values that may be fractional
(floating-point).
If used to represent physical distances, values must be in meters.

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

[open,refpage='XrRect3DfFB',type='structs',desc='Represents a rectangular prism containing a region of space',xrefs='']
--
The slink:XrRect3DfFB structure is defined as:

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

.Member Descriptions
****
* pname:offset is the slink:XrOffset3DfFB specifying the rectangle offset.
* pname:extent is the slink:XrExtent3DfFB specifying the rectangle extent.
****

This structure is used for component values that may be fractional
(floating-point).

The bounding box is defined by an pname:offset and pname:extent.
The pname:offset refers to the coordinate of the minimum corner of the box
in the local space of the slink:XrSpace; that is, the corner whose
coordinate has the minimum value on each axis.
The pname:extent refers to the dimensions of the box along each axis.
The maximum corner can therefore be computed as [eq]#pname:offset +
pname:extent#.

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

[open,refpage='XrSemanticLabelsFB',type='structs',desc='Provides application with semantic usage of a spatial entity',xrefs='']
--
The slink:XrSemanticLabelsFB structure is defined as:

include::{generated}/api/structs/XrSemanticLabelsFB.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, such as slink:XrSemanticLabelsSupportInfoFB.
* pname:bufferCapacityInput is the capacity of the pname:buffer array, in
  bytes, or 0 to indicate a request to retrieve the required capacity.
* pname:bufferCountOutput is the count of bytes written, or the required
  capacity in the case that pname:bufferCapacityInput is insufficient.
* pname:buffer is a pointer to an array of bytes, but can be code:NULL if
  pname:bufferCapacityInput is 0.
  Multiple labels represented by raw string, separated by a comma without
  spaces.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:buffer size.
****

This structure is used by the flink:xrGetSpaceSemanticLabelsFB function to
provide the application with the intended usage of the spatial entity.

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

[open,refpage='XrRoomLayoutFB',type='structs',desc='Provides additional context of a spatial entity representing a room',xrefs='']
--
The slink:XrRoomLayoutFB structure is defined as:

include::{generated}/api/structs/XrRoomLayoutFB.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:floorUuid is the UUID of the spatial entity representing the room
  floor
* pname:ceilingUuid is the UUID of the spatial entity representing the room
  ceiling
* pname:wallUuidCapacityInput is the capacity of the pname:wallUuids array,
  in number of UUIDs, or 0 to indicate a request to retrieve the required
  capacity.
* pname:wallUuidCountOutput is the count of slink:XrUuidEXT handles written,
  or the required capacity in the case that pname:wallUuidCapacityInput is
  insufficient.
* pname:wallUuids is a pointer to an array of slink:XrUuidEXT handles, but
  can be code:NULL if pname:wallUuidCapacityInput is 0.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:wallUuids array size.
****

This structure is used by the flink:xrGetSpaceRoomLayoutFB function to
provide the application with the slink:XrUuidEXT handles representing the
various surfaces of a room.

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

[open,refpage='XrBoundary2DFB',type='structs',desc='Provides additional context of a spatial entity representing a room',xrefs='']
--
The slink:XrBoundary2DFB structure is defined as:

include::{generated}/api/structs/XrBoundary2DFB.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, in
  number of vertices, or 0 to indicate a request to retrieve the required
  capacity.
* pname:vertexCountOutput is the count of slink:XrVector2f written, or the
  required capacity in the case that pname:vertexCapacityInput is
  insufficient.
* pname:vertices is a pointer to an array of slink:XrVector2f, but can: be
  code:NULL if pname:vertexCapacityInput is 0.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:vertices array size.
****

This structure is used by the flink:xrGetSpaceBoundary2DFB function to
provide the application with the slink:XrVector2f vertices representing the
a spatial entity with a boundary.

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

[open,refpage='XrSemanticLabelsSupportInfoFB',type='structs',desc='Specifies additional behaviors of the xrGetSpaceSemanticLabelsFB function',xrefs='']
--
The slink:XrSemanticLabelsSupportInfoFB structure is defined as:

include::{generated}/api/structs/XrSemanticLabelsSupportInfoFB.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:XrSemanticLabelsSupportFlagBitsFB that
  specifies additional behaviors.
* pname:recognizedLabels is a code:NULL terminated string that indicates a
  set of semantic labels recognized by the application.
  Each semantic label must: be represented as a string and be separated by a
  comma without spaces.
  This field must: include at least "OTHER" and must: not be code:NULL.
****

The slink:XrSemanticLabelsSupportInfoFB structure may: be specified in the
pname:next chain of slink:XrSemanticLabelsFB to specify additional behaviors
of the flink:xrGetSpaceSemanticLabelsFB function.
The runtime must: follow the behaviors specified in pname:flags according to
the descriptions of elink:XrSemanticLabelsSupportFlagBitsFB.
The runtime must: return any semantic label that is not included in
pname:recognizedLabels as "OTHER" to the application.
The runtime must: follow this direction only if the runtime reports the
slink:XrExtensionProperties::pname:extensionVersion as 2 or greater,
otherwise the runtime must: ignore this as an unknown chained structure.

If the slink:XrSemanticLabelsSupportInfoFB structure is not present in the
pname:next chain of slink:XrSemanticLabelsFB, the runtime may: return any
semantic labels to the application.

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

*New Functions*

[open,refpage='xrGetSpaceBoundingBox2DFB',desc='Gets the 2D bounding box for a spatial entity',type='protos',xrefs='']
--
The flink:xrGetSpaceBoundingBox2DFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is the slink:XrSpace handle to the spatial entity.
* pname:boundingBox2DOutput is an output parameter pointing to the structure
  containing the 2D bounding box for pname:space.
****

Gets the 2D bounding box for a spatial entity with the
ename:XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB component type enabled.

The bounding box is defined by an slink:XrRect2Df::pname:offset and
slink:XrRect2Df::pname:extent.
The slink:XrRect2Df::pname:offset refers to the coordinate of the minimum
corner of the box in the x-y plane of the given slink:XrSpace's coordinate
system; that is, the corner whose coordinate has the minimum value on each
axis.
The slink:XrRect2Df::pname:extent refers to the dimensions of the box along
each axis.
The maximum corner can therefore be computed as
[eq]#slink:XrRect2Df::pname:offset +
slink:XrRect2Df::pname:extent#.

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

[open,refpage='xrGetSpaceBoundingBox3DFB',desc='Gets the 3D bounding box for a spatial entity',type='protos',xrefs='']
--
The flink:xrGetSpaceBoundingBox3DFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is the slink:XrSpace handle to the spatial entity.
* pname:boundingBox3DOutput is an output parameter pointing to the structure
  containing the 3D bounding box for pname:space.
****

Gets the 3D bounding box for a spatial entity with the
ename:XR_SPACE_COMPONENT_TYPE_BOUNDED_3D_FB component type enabled.

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

[open,refpage='xrGetSpaceSemanticLabelsFB',desc='Gets the semantic labels for a spatial entity',type='protos',xrefs='']
--
The flink:xrGetSpaceSemanticLabelsFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is the slink:XrSpace handle to the spatial entity.
* pname:semanticLabelsOutput is an output parameter pointing to the
  structure containing the slink:XrSemanticLabelsFB for pname:space.
****

Gets the semantic labels for a spatial entity with the
ename:XR_SPACE_COMPONENT_TYPE_SEMANTIC_LABELS_FB component type enabled.

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

[open,refpage='xrGetSpaceBoundary2DFB',desc='Gets the 2D boundary for a spatial entity',type='protos',xrefs='']
--
The flink:xrGetSpaceBoundary2DFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is the slink:XrSpace handle to the spatial entity.
* pname:boundary2DOutput is an output parameter pointing to the structure
  containing the slink:XrBoundary2DFB for pname:space.
****

Gets the 2D boundary, specified by vertices, for a spatial entity with the
ename:XR_SPACE_COMPONENT_TYPE_BOUNDED_2D_FB component type enabled.

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

[open,refpage='xrGetSpaceRoomLayoutFB',desc='Gets the room layout for a spatial entity',type='protos',xrefs='']
--
The flink:xrGetSpaceRoomLayoutFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is the slink:XrSpace handle to the spatial entity.
* pname:roomLayoutOutput is an output parameter pointing to the structure
  containing the slink:XrRoomLayoutFB for pname:space.
****

Gets the room layout, specified by UUIDs for each surface, for a spatial
entity with the ename:XR_SPACE_COMPONENT_TYPE_ROOM_LAYOUT_FB component type
enabled.

If the slink:XrRoomLayoutFB::pname:wallUuidCapacityInput field is zero
(indicating a request to retrieve the required capacity for the
slink:XrRoomLayoutFB::pname:wallUuids array), or if
flink:xrGetSpaceRoomLayoutFB returns failure, then the values of `floorUuid`
and `ceilingUuid` are unspecified and should not be used.

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

*Issues*

*Version History*

* Revision 1, 2022-03-09 (John Schofield)
** Initial draft
* Revision 2, 2023-04-03 (Yuichi Taguchi)
** Introduce slink:XrSemanticLabelsSupportInfoFB.
* Revision 3, 2023-04-03 (Yuichi Taguchi)
** Introduce
   ename:XR_SEMANTIC_LABELS_SUPPORT_ACCEPT_DESK_TO_TABLE_MIGRATION_BIT_FB.
* Revision 4, 2023-06-12 (Yuichi Taguchi)
** Introduce
   ename:XR_SEMANTIC_LABELS_SUPPORT_ACCEPT_INVISIBLE_WALL_FACE_BIT_FB.
