// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Last Modified Date*::
    2023-05-08
*IP Status*::
    No known IP claims.
*Contributors*::
    Cass Everitt, Facebook +
    Robert Blenkinsopp, Ultraleap

*Overview*

On some platforms, before loading can occur the loader must be initialized
with platform-specific parameters.

Unlike other extensions, the presence of this extension is signaled by a
successful call to flink:xrGetInstanceProcAddr to retrieve the function
pointer for flink:xrInitializeLoaderKHR using dlink:XR_NULL_HANDLE as the
pname:instance parameter.

If this extension is supported, its use may: be required on some platforms
and the use of the flink:xrInitializeLoaderKHR function must: precede other
OpenXR calls except flink:xrGetInstanceProcAddr.

This function exists as part of the loader library that the application is
using and the loader must: pass calls to flink:xrInitializeLoaderKHR to the
active runtime, and all enabled API layers that expose a
flink:xrInitializeLoaderKHR function exposed either through their manifest,
or through their implementation of flink:xrGetInstanceProcAddr.

If the flink:xrInitializeLoaderKHR function is discovered through the
manifest, flink:xrInitializeLoaderKHR will be called before
`xrNegotiateLoaderRuntimeInterface` or `xrNegotiateLoaderApiLayerInterface`
has been called on the runtime or layer respectively.

*New Object Types*

*New Flag Types*

*New Enum Constants*

*New Enums*

*New Structures*
[open,refpage='XrLoaderInitInfoBaseHeaderKHR',desc='Initializes OpenXR loader',type='structs']
--
The slink:XrLoaderInitInfoBaseHeaderKHR structure is defined as:

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


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

*New Functions*
[open,refpage='xrInitializeLoaderKHR',desc='Initializes loader',type='protos']
--
To initialize an OpenXR loader with platform or implementation-specific
parameters, call:

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

.Parameter Descriptions
****
* pname:loaderInitInfo is a pointer to an
  slink:XrLoaderInitInfoBaseHeaderKHR structure, which is a polymorphic type
  defined by other platform- or implementation-specific extensions.
****
--
*Issues*

*Version History*

* Revision 2, 2023-05-08 (Robert Blenkinsoppp)
** Explicitly state that the call to flink:xrInitializeLoaderKHR should be
   passed to the runtime and enabled API layers.
* Revision 1, 2020-05-07 (Cass Everitt)
** Initial draft
