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

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

*Contributors*::
    Cass Everitt, Facebook +
    Gloria Kennickell, Facebook +


*Overview*

This extension enables the application to modify and query specific mutable
state associated with a swapchain.

In order to enable the functionality of this extension, the application
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*

*New Enums*

*New Structures*

[open,refpage='XrSwapchainStateBaseHeaderFB',desc='Base header for swapchain update state',type='structs',xrefs='xrUpdateSwapchainFB xrGetSwapchainStateFB']
--
The slink:XrSwapchainStateBaseHeaderFB structure is defined as:

include::{generated}/api/structs/XrSwapchainStateBaseHeaderFB.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.
  No such structures are defined in core OpenXR or this extension.
****

The slink:XrSwapchainStateBaseHeaderFB is a base structure that can be
overridden by a specific stext:XrSwapchainState* child structure.

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

*New Functions*

[open,refpage='xrUpdateSwapchainFB',desc='Updates state for the corresponding swapchain',type='protos',xrefs='xrCreateSwapchain XrSwapchainStateBaseHeaderFB']
--
The flink:xrUpdateSwapchainFB function is defined as:

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

.Parameter Descriptions
****
* pname:swapchain is the slink:XrSwapchain to update state for.
* pname:state is a pointer to a `XrSwapchainState` structure based off of
  slink:XrSwapchainStateBaseHeaderFB.
****

flink:xrUpdateSwapchainFB provides support for an application to update
specific mutable state associated with an slink:XrSwapchain.

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

[open,refpage='xrGetSwapchainStateFB',desc='Query state for the corresponding swapchain',type='protos',xrefs='xrCreateSwapchain XrSwapchainStateBaseHeaderFB xrUpdateSwapchainFB']
--
The flink:xrGetSwapchainStateFB function is defined as:

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

.Parameter Descriptions
****
* pname:swapchain is the slink:XrSwapchain to update state for.
* pname:state is a pointer to a `XrSwapchainState` structure based off of
  slink:XrSwapchainStateBaseHeaderFB.
****

flink:xrGetSwapchainStateFB provides support for an application to query
specific mutable state associated with an slink:XrSwapchain.

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

*Issues*

* Should we add a method to query the current state?

** Yes.
   Given that we allow mutable state to be updated by the application, it is
   useful to have a query mechanism to get the current state for all state
   structures.

*Version History*

* Revision 1, 2021-04-16 (Gloria Kennickell)
** Initial extension description

* Revision 2, 2021-05-13 (Gloria Kennickell)
** Add mechanism to query current state for all state structures.

* Revision 3, 2021-05-27 (Gloria Kennickell)
** Move platform and graphics API specific structs into separate extensions.
