// 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_query.adoc[]

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


*Overview*

This extension enables an application to discover persistent spatial
entities in the area and restore them.
Using the query system, the application can: load persistent spatial
entities from storage.
The query system consists of a set of filters to define the spatial entity
search query and an operation that needs to be performed on the search
results.

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_QUERY_INFO_FB
* ename:XR_TYPE_SPACE_QUERY_RESULTS_FB
* ename:XR_TYPE_SPACE_STORAGE_LOCATION_FILTER_INFO_FB
* ename:XR_TYPE_SPACE_UUID_FILTER_INFO_FB
* ename:XR_TYPE_SPACE_COMPONENT_FILTER_INFO_FB
* ename:XR_TYPE_EVENT_DATA_SPACE_QUERY_RESULTS_AVAILABLE_FB
* ename:XR_TYPE_EVENT_DATA_SPACE_QUERY_COMPLETE_FB

*New Enums*

[open,refpage='XrSpaceQueryActionFB',desc='Type of query being performed',type='enums']
--
include::{generated}/api/enums/XrSpaceQueryActionFB.adoc[]

Specify the type of query being performed.

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

*New Structures*

[open,refpage='XrSpaceQueryInfoBaseHeaderFB',type='structs',desc='Base structure for all query info structures',xrefs='XrSpaceQueryInfoFB']
--
The slink:XrSpaceQueryInfoBaseHeaderFB structure is defined as:

include::{generated}/api/structs/XrSpaceQueryInfoBaseHeaderFB.adoc[]
.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
  This base structure itself has no associated elink:XrStructureType value.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  This base structure itself has no associated elink:XrStructureType value.
****

The slink:XrSpaceQueryInfoBaseHeaderFB is a base structure that is not
intended to be directly used, but forms a basis for specific query info
types.
All query info structures begin with the elements described in the
slink:XrSpaceQueryInfoBaseHeaderFB, and a query info pointer must: be cast
to a pointer to slink:XrSpaceQueryInfoBaseHeaderFB when passing it to the
flink:xrQuerySpacesFB function.

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

[open,refpage='XrSpaceFilterInfoBaseHeaderFB',type='structs',desc='Base structure for all query filter structures',xrefs='']
--
The slink:XrSpaceFilterInfoBaseHeaderFB structure is defined as:

include::{generated}/api/structs/XrSpaceFilterInfoBaseHeaderFB.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.
  This base structure itself has no associated elink:XrStructureType value.
****

The slink:XrSpaceFilterInfoBaseHeaderFB is a base structure that is not
intended to be directly used, but forms a basis for specific filter info
types.
All filter info structures begin with the elements described in the
slink:XrSpaceFilterInfoBaseHeaderFB, and a filter info pointer must: be cast
to a pointer to slink:XrSpaceFilterInfoBaseHeaderFB when populating
slink:XrSpaceQueryInfoFB::pname:filter and
slink:XrSpaceQueryInfoFB::pname:excludeFilter to pass to the
flink:xrQuerySpacesFB function.

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

[open,refpage='XrSpaceQueryInfoFB',type='structs',desc='Query for entities and perform an action on any results',xrefs='XrSpaceQueryInfoBaseHeaderFB']
--
The slink:XrSpaceQueryInfoFB structure is defined as:

include::{generated}/api/structs/XrSpaceQueryInfoFB.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:queryAction is the type of query to perform.
* pname:maxResultCount is the maximum number of entities to be found.
* pname:timeout is the number of nanoseconds before the operation should
  time out.
  A value of dlink:XR_INFINITE_DURATION indicates no timeout.
* pname:filter is NULL or a pointer to a valid structure based on
  slink:XrSpaceFilterInfoBaseHeaderFB.
* pname:excludeFilter is NULL or a pointer to a valid structure based on
  slink:XrSpaceFilterInfoBaseHeaderFB.
****

May be used to query for spaces and perform a specific action on the spaces
returned.
The available actions are enumerated in elink:XrSpaceQueryActionFB.
The filter info provided to the pname:filter member of the struct is used as
an inclusive filter.
The filter info provided to the pname:excludeFilter member of the structure
is used to exclude spaces from the results returned from the filter.
All spaces that match the criteria in pname:filter, and that do not match
the criteria in pname:excludeFilter, must: be included in the results
returned.
This is to allow for a more selective style query.

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

[open,refpage='XrSpaceStorageLocationFilterInfoFB',type='structs',desc='Describes where a spatial entity is stored',xrefs='']
--
The slink:XrSpaceStorageLocationFilterInfoFB structure is defined as:

include::{generated}/api/structs/XrSpaceStorageLocationFilterInfoFB.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:location is the location to limit the query to.
****

Extends a query filter to limit a query to a specific storage location.
Set the pname:next pointer of an slink:XrSpaceFilterInfoBaseHeaderFB to
chain this extra filtering functionality.

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

[open,refpage='XrSpaceUuidFilterInfoFB',type='structs',desc='Filters for entities with specific unique identifiers',xrefs='XrSpaceFilterInfoBaseHeaderFB XrSpaceQueryInfoFB']
--
The slink:XrSpaceUuidFilterInfoFB structure is defined as:

include::{generated}/api/structs/XrSpaceUuidFilterInfoFB.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:uuidCount is the number of UUIDs to be matched.
* pname:uuids is an array of slink:XrUuidEXT that contains the UUIDs to be
  matched.
****

The slink:XrSpaceUuidFilterInfoFB structure is a filter an application can:
use to find slink:XrSpace entities that match specified UUIDs, to include or
exclude them from a query.

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

[open,refpage='XrSpaceComponentFilterInfoFB',type='structs',desc='Filters for entities with specific components enabled',xrefs='XrSpaceFilterInfoBaseHeaderFB XrSpaceQueryInfoFB']
--
The slink:XrSpaceComponentFilterInfoFB structure is defined as:

include::{generated}/api/structs/XrSpaceComponentFilterInfoFB.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:componentType is the elink:XrSpaceComponentTypeFB to query for.
****

The slink:XrSpaceComponentFilterInfoFB structure is a filter an application
can: use to find slink:XrSpace entities which have the pname:componentType
enabled, to include or exclude them from a query.

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

[open,refpage='XrSpaceQueryResultFB',type='structs',desc='Query result',xrefs='']
--
The slink:XrSpaceQueryResultFB structure is defined as:

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

.Member Descriptions
****
* pname:space is the slink:XrSpace handle to the spatial entity found by the
  query.
* pname:uuid is the UUID that identifies the entity.
****

The slink:XrSpaceQueryResultFB structure is a query result returned in the
flink:xrRetrieveSpaceQueryResultsFB::pname:results output parameter of the
flink:xrRetrieveSpaceQueryResultsFB function.

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

[open,refpage='XrSpaceQueryResultsFB',type='structs',desc='Used to retrieve query results',xrefs='']
--
The slink:XrSpaceQueryResultsFB structure is defined as:

include::{generated}/api/structs/XrSpaceQueryResultsFB.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:resultCapacityInput is the capacity of the pname:results array, or 0
  to indicate a request to retrieve the required capacity.
* pname:resultCountOutput is an output parameter containing the count of
  results retrieved, or returns the required capacity in the case that
  pname:resultCapacityInput is insufficient.
* pname:results is a pointer to an array of results, but can: be code:NULL
  if pname:resultCapacityInput is 0.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required pname:results size.
****

The slink:XrSpaceQueryResultsFB structure is used by the
flink:xrRetrieveSpaceQueryResultsFB function to retrieve query results.

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

[open,refpage='XrEventDataSpaceQueryResultsAvailableFB',type='structs',desc='Event indicating a query has produced results',xrefs='']
--
The slink:XrEventDataSpaceQueryResultsAvailableFB structure is defined as:

include::{generated}/api/structs/XrEventDataSpaceQueryResultsAvailableFB.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:requestId is the ID of the asynchronous query request.
****

It indicates a query request has produced some number of results.
If a query yields results this event must: be delivered before the
slink:XrEventDataSpaceQueryCompleteFB event is delivered.
Call flink:xrRetrieveSpaceQueryResultsFB to retrieve those results.

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

[open,refpage='XrEventDataSpaceQueryCompleteFB',type='structs',desc='Event indicating a query has finished',xrefs='']
--
The slink:XrEventDataSpaceQueryCompleteFB structure is defined as:

include::{generated}/api/structs/XrEventDataSpaceQueryCompleteFB.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:requestId is the ID of the asynchronous query request.
* pname:result is an elink:XrResult that determines if the request succeeded
  or if an error occurred.
****

It indicates a query request has completed and specifies the request result.
This event must: be delivered when a query has completed, regardless of the
number of results found.
If any results have been found, then this event must: be delivered after any
slink:XrEventDataSpaceQueryResultsAvailableFB events have been delivered.

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

*New Functions*

[open,refpage='xrQuerySpacesFB',desc='Queries for spatial entities',type='protos',xrefs='']
--
The flink:xrQuerySpacesFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:info is a pointer to the slink:XrSpaceQueryInfoBaseHeaderFB
  structure.
* pname:requestId is an output parameter, and the variable it points to will
  be populated with the ID of this asynchronous request.
****

The flink:xrQuerySpacesFB function enables an application to find and
retrieve spatial entities from storage.
Cast an slink:XrSpaceQueryInfoFB pointer to a
slink:XrSpaceQueryInfoBaseHeaderFB pointer to pass as pname:info.
The application should: keep the returned pname:requestId for the duration
of the request as it is used to refer to the request when calling
flink:xrRetrieveSpaceQueryResultsFB and is used to map completion events to
the request.
This operation is asynchronous and the runtime must: post an
slink:XrEventDataSpaceQueryCompleteFB event when the operation completes
successfully or encounters an error.
If this function returns a failure code, no event is posted.
The runtime must: post an slink:XrEventDataSpaceQueryResultsAvailableFB
before slink:XrEventDataSpaceQueryCompleteFB if any results are found.
Once an slink:XrEventDataSpaceQueryResultsAvailableFB event has been posted,
the application may: call flink:xrRetrieveSpaceQueryResultsFB to retrieve
the available results.

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

[open,refpage='xrRetrieveSpaceQueryResultsFB',desc='Copies query results into an output buffer',type='protos',xrefs='']
--
The flink:xrRetrieveSpaceQueryResultsFB function is defined as:

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

.Parameter Descriptions
****
* pname:session is the slink:XrSession for which the in-progress query is
  valid.
* pname:requestId is the basetype:XrAsyncRequestIdFB to enumerate results
  for.
* pname:results is a pointer to an slink:XrSpaceQueryResultsFB to populate
  with results.
* See the <<fundamentals-buffer-size-parameters>> section for a detailed
  description of retrieving the required size of the results in this
  parameter.
****

Allows an application to retrieve all available results for a specified
query.
Call this function once to get the number of results found and then once
more to copy the results into a buffer provided by the application.
The number of results will not change between the two calls used to retrieve
results.
This function must: only retrieve each query result once.
After the application has used this function to retrieve a query result, the
runtime frees its copy.
The runtime must: return ename:XR_ERROR_VALIDATION_FAILURE if
pname:requestId refers to a request that is not yet complete, a request for
which results have already been retrieved, or if pname:requestId does not
refer to a known request.

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

*Issues*

*Version History*

* Revision 1, 2022-01-22 (John Schofield)
** Initial draft
