Runtime Management API Reference#

Note

The API reference below is automatically generated from the cxrServiceAPI.h header file using Doxygen.

Defines

NV_CXR_API_VERSION_MAJOR 1#
NV_CXR_API_VERSION_MINOR 0#
NV_CXR_API_VERSION_PATCH 6#

Typedefs

typedef void (*PFN_nv_cxr_get_library_api_version)(uint32_t*, uint32_t*, uint32_t*)#
typedef void (*PFN_nv_cxr_get_runtime_version)(uint32_t*, uint32_t*, uint32_t*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_create)(struct nv_cxr_service**)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_set_string_property)(struct nv_cxr_service*, const char*, size_t, const char*, size_t)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_set_boolean_property)(struct nv_cxr_service*, const char*, size_t, bool)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_set_int64_property)(struct nv_cxr_service*, const char*, size_t, int64_t)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_get_string_property)(struct nv_cxr_service*, const char*, size_t, char*, size_t*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_get_boolean_property)(struct nv_cxr_service*, const char*, size_t, bool*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_get_int64_property)(struct nv_cxr_service*, const char*, size_t, int64_t*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_start)(struct nv_cxr_service*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_stop)(struct nv_cxr_service*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_join)(struct nv_cxr_service*)#
typedef void (*PFN_nv_cxr_service_destroy)(struct nv_cxr_service*)#
typedef nv_cxr_result_t (*PFN_nv_cxr_service_poll_event)(struct nv_cxr_service*, nv_cxr_event_t*)#

Enums

enum nv_cxr_result_t#

Result codes.

Values:

enumerator NV_CXR_SUCCESS = 0#
enumerator NV_CXR_INTERNAL_SERVICE_ERROR = -1#
enumerator NV_CXR_STARTUP_FAILED = -2#
enumerator NV_CXR_NULL_OBJECT = -3#

A pointer to an object, such as the service was null.

enumerator NV_CXR_NULL_PTR = -4#

A pointer to something, not an object was null.

enumerator NV_CXR_SERVICE_ALREADY_STARTED = -5#

Can not call this function once the service has started, since the 1.0.1 version.

enumerator NV_CXR_SERVICE_NOT_STARTED = -6#

Can not call this function at this time, since the 1.0.1 version.

enumerator NV_CXR_PROPERTY_NAME_MALFORMED = -7#

The property name is not currectly formed, since the 1.0.2 version.

enumerator NV_CXR_PROPERTY_NAME_INVALID = -8#

The property name is not a not known one for this type, since the 1.0.2 version.

enumerator NV_CXR_ERROR_PROPERTY_VALUE_INVALID = -9#

The value is not valid for this property, since the 1.0.3 version.

enumerator NV_CXR_ERROR_BUFFER_SIZE_INSUFFICIENT = -10#

The buffer provided is too small for the property value, since the 1.0.3 version.

enumerator NV_CXR_ERROR_PROPERTY_READ_ONLY = -11#

The property is read only, since the 1.0.5 version.

enum nv_cxr_event_type_t#

Event types.

Values:

enumerator NV_CXR_EVENT_NONE = 0#

No event available.

enumerator NV_CXR_EVENT_CLOUDXR_CLIENT_CONNECTED = 1#

The cloudxr client has connected.

enumerator NV_CXR_EVENT_CLOUDXR_CLIENT_DISCONNECTED = 2#

The cloudxr client has disconnected.

enumerator NV_CXR_EVENT_OPENXR_APP_CONNECTED = 3#

The openxr app has connected.

enumerator NV_CXR_EVENT_OPENXR_APP_DISCONNECTED = 4#

The openxr app has disconnected.

Functions

void nv_cxr_get_library_api_version(
uint32_t *major,
uint32_t *minor,
uint32_t *patch,
)#

We use a C API to have a very strict layer of separation to users of this library, internal as well as potential external ones. Having this layer here means that we can do a drop in replacement of the runtime with the exact same release of KitXR (or any other user) meaning we have much less process to go through when we want to update just the runtime.

Returns the verison of the API, useful for langagues that dynamically loads the library to know that the thing they loaded is compatible. This is the version that gates which functions are available to be called at all.

void nv_cxr_get_runtime_version(
uint32_t *major,
uint32_t *minor,
uint32_t *patch,
)#

Returns the version of the runtime itself, this is useful for printing into logs to assist debugging.

The major number is also the protocol version, so it can be shown in the app UI to give the user information of which clients are supported.

nv_cxr_result_t nv_cxr_service_create(
struct nv_cxr_service **out_service,
)#

Creates a service object, only one can be alive at a time. The runtime is not started when this object is created, and instead the start function must be used to get the runtime into a state accepting client connections and apps being able to create a XrInstance in the OpenXR API.

nv_cxr_result_t nv_cxr_service_set_string_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
const char *value,
size_t value_length,
)#

Set a property to the given value, can only be set before start has been called or after the runtime has been fully shutdown. If the runtime is running the function will return NV_CXR_SERVICE_ALREADY_STARTED.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_set_boolean_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
bool value,
)#

Set a property to the given value, can only be set before start has been called or after the runtime has been fully shutdown. If the runtime is running the function will return NV_CXR_SERVICE_ALREADY_STARTED.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_set_int64_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
int64_t value,
)#

Set a property to the given value, can only be set before start has been called or after the runtime has been fully shutdown. If the runtime is running the function will return NV_CXR_SERVICE_ALREADY_STARTED.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_get_string_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
char *value,
size_t *value_length,
)#

Get a string property value. The value is copied to the provided buffer. If the buffer is too small, returns NV_CXR_ERROR_BUFFER_SIZE_INSUFFICIENT and sets value_length to the required buffer size.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_get_boolean_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
bool *value,
)#

Get a boolean property value.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_get_int64_property(
struct nv_cxr_service *service,
const char *property_name,
size_t property_name_length,
int64_t *value,
)#

Get an int64_t property value.

Property names can only contain the symboles [a-z][0-9][-_], or the function will return NV_CXR_PROPERTY_NAME_MALFORMED.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_start(struct nv_cxr_service *service)#

Starts the service, currently this function only returns once the service has fully completed starting up accepting connections from both clients and applications. Returns NV_CXR_SERVICE_ALREADY_STARTED if the service has already been started.

Externally syncronized, no other threads must access this object.

nv_cxr_result_t nv_cxr_service_stop(struct nv_cxr_service *service)#

Stops the service, disconnects all applications and clients. This function only signals that the runtime should stop, use nv_cxr_service_join to wait for it to have fully stopped. Will return NV_CXR_SERVICE_NOT_STARTED if the service hasn’t been started, or has been fully stopped with a call to the nv_cxr_service_join function.

This function can be called after and before join returns. If the runtime service is stopped by external factors and a call to join is happening, this may cause NV_CXR_SERVICE_NOT_STARTED to be returned.

nv_cxr_result_t nv_cxr_service_join(struct nv_cxr_service *service)#

Will return when the service has stopped, this is useful if using the service’s built in mechanisms to stop. Once this function returns the service has fully stopped. Will return NV_CXR_SERVICE_NOT_STARTED if the service hasn’t been started.

Externally syncronized, no other thread must access this object, except for stop, see comment on that function.

void nv_cxr_service_destroy(struct nv_cxr_service *service)#

Destroys a service object, the service must been in a fully stop state, either by never calling start, or after a series of successful calls to start and join.

Externally syncronized, no other thread must access this object.

nv_cxr_result_t nv_cxr_service_poll_event(
struct nv_cxr_service *service,
nv_cxr_event_t *event,
)#

Returns the oldest event that has occurred since the start of the service. Each call returns one event and removes it from the internal event queue. If no events are available, returns NV_CXR_EVENT_NONE.

Parameters:

  • service – The service object.

  • event – Pointer to store the retrieved event.

Returns:

NV_CXR_SUCCESS if an event was retrieved, NV_CXR_EVENT_NONE if no events available, or error code.

struct nv_cxr_event_t#
#include <cxrServiceAPI.h>

Event, padded to 4096 bytes. Review the header file for details.

Public Members

nv_cxr_event_type_t type#

The event type.

On this page