API levels - cmbruns/pyopenxr GitHub Wiki

Level 0: pyopenxr ctypes raw_functions API

The lowest level pyopenxr API is the level "0" raw_functions ctypes level. Don't use these unless you need to. If you find yourself needing to use the raw_functions, please open an issue so we can figure out if some change to the level 1 API design is needed.

• Function names exactly match the C language OpenXR API e.g. xrCreateInstance
  • Function return values are error codes. You should check these every time.
  • Function output object are passed as parameters by reference.
• Classes, enums, and constants come from the level 1 pythonic API (see below)

import xr
import xr.raw_functions as xrr

instance = xr.Instance()  # prepare output parameter
result = xrr.xrCreateInstance(
    xr.InstanceCreateInfo(
        enabled_extension_names=[xr.KHR_OPENGL_ENABLE_EXTENSION_NAME],
    ),
    instance
)
if result != xr.Result.SUCCESS:
    raise RuntimeError("call failed")

result = xrr.xrDestroyInstance(instance)  # Clean up
if result != xr.Result.SUCCESS:
    raise RuntimeError("call failed")

Level 1: pyopenxr pythonic API

This is the recommended API.

There is a one-to-one correspondence between level 0 and level 1 functions.

• Functions are named using lower_case_separated_by_underscores. e.g. xr.create_instance()
• Functions are located in the xr module namespace, and thus have their initial "xr" prefix removed.
• Output parameters are generated as return values. Non-success return codes result in exceptions.
• The "two call" paradigm is automatically invoked for functions returning an array.

import xr

instance = xr.create_instance(
    xr.InstanceCreateInfo(
        enabled_extension_names=[xr.KHR_OPENGL_ENABLE_EXTENSION_NAME],
    )
)

xr.destroy_instance(instance)  # Clean up

Atom handle classes like xr.Instance can be used as python context managers, to clean themselves up automatically.

import xr

with xr.Instance(create_info=xr.InstanceCreateInfo(
    enabled_extension_names=[xr.KHR_OPENGL_ENABLE_EXTENSION_NAME],
)) as instance:
    pass
# instance is automatically cleaned up at the end.

Level 2: Extended API

• Includes helper classes and functions not found in the C++ OpenXR API.
• These codes are subject to much more rapid change than the level 1 API. So use them with caution.