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

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

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


*Overview*

This extension expands on the concept of spatial entities to include a way
for one spatial entity to contain multiple child spatial entities, forming a
hierarchy.

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*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_SPACE_CONTAINER_FB

*New Enums*

*New Structures*

[open,refpage='XrSpaceContainerFB',type='structs',desc='Represents a collection of other spaces, represented by UUIDs, contained by this space',xrefs='']
--
The slink:XrSpaceContainerFB structure is defined as:

include::{generated}/api/structs/XrSpaceContainerFB.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:uuidCapacityInput is the capacity of the pname:uuids array, or 0 to
  indicate a request to retrieve the required capacity.
* pname:uuidCountOutput is an output parameter which will hold the number of
  UUIDs included in the output list, or the required capacity in the case
  that pname:uuidCapacityInput is insufficient
* pname:uuids is an output parameter which will hold a list of space UUIDs
  contained by the space to which the component is attached.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:uuids size.
****

The slink:XrSpaceContainerFB structure can: be used by an application to
perform the two calls required to obtain information about which spatial
entities are contained by a specified spatial entity.

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

*New Functions*

[open,refpage='xrGetSpaceContainerFB',desc='Gets a XrSpaceContainerFB which lists contained spaces',type='protos',xrefs='']
--
The flink:xrGetSpaceContainerFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:space is a handle to an slink:XrSpace.
* pname:spaceContainerOutput is the output parameter that points to an
  slink:XrSpaceContainerFB containing information about which spaces are
  contained by pname:space.
****

The flink:xrGetSpaceContainerFB function is used by an application to
perform the two calls required to obtain information about which spatial
entities are contained by a specified spatial entity.

The ename:XR_SPACE_COMPONENT_TYPE_SPACE_CONTAINER_FB component type must: be
enabled, otherwise this function will return
ename:XR_ERROR_SPACE_COMPONENT_NOT_ENABLED_FB.

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

*Issues*

*Version History*

* Revision 1, 2022-03-09 (John Schofield)
** Initial draft
* Revision 2, 2022-05-31 (John Schofield)
** Fix types of `XrSpaceContainerFB` fields.
