Per session-action-context snapshot of all device inputs and outputs, wrapping an xrt_io_cache. More...

#include <oxr/actions/oxr_io_cache.h>

Collaboration diagram for oxr_io_cache:

[legend]

Public Member Functions
XRT_CHECK_RESULT XrResult	oxr_io_cache_init (struct oxr_io_cache cache, struct xrt_system_devices xsysd, struct xrt_space_overseer *xso)
	Create the cache.

void	oxr_io_cache_fini (struct oxr_io_cache *cache)
	Destroy the cache.

XRT_CHECK_RESULT XrResult	oxr_io_cache_recreate (struct oxr_logger log, struct oxr_io_cache cache)
	Recreate the snapshot for the current device layout: re-query info and reallocate the inputs / outputs arrays.

XRT_CHECK_RESULT XrResult	oxr_io_cache_sync (struct oxr_logger log, struct oxr_io_cache cache, bool *out_stale)
	Refresh the snapshot: read all device inputs and outputs into inputs / outputs with a single call.

XRT_NONNULL_ALL const struct xrt_io_cache_device *	oxr_io_cache_find_device (const struct oxr_io_cache *cache, struct xrt_device_id id)
	Find the layout entry of the device with `id` in the current snapshot, returns NULL if the device is not part of it.

XRT_NONNULL_ALL struct xrt_input *	oxr_io_cache_find_input (const struct oxr_io_cache cache, const struct xrt_io_cache_device dev, enum xrt_input_name name)
	Find the input called `name` on `dev` in the current snapshot.

XRT_NONNULL_ALL bool	oxr_io_cache_has_output (const struct oxr_io_cache cache, const struct xrt_io_cache_device dev, enum xrt_output_name name)
	Whether `dev` exposes an output called `name` in the current snapshot.

Static Public Member Functions
static XRT_NONNULL_ALL struct xrt_input *	oxr_io_cache_device_inputs (const struct oxr_io_cache cache, const struct xrt_io_cache_device dev)
	The inputs of `dev` in oxr_io_cache::inputs, `dev` must be an entry in the layout of `cache`.

static XRT_NONNULL_ALL struct xrt_output *	oxr_io_cache_device_outputs (const struct oxr_io_cache cache, const struct xrt_io_cache_device dev)
	The outputs of `dev` in oxr_io_cache::outputs, `dev` must be an entry in the layout of `cache`.

Data Fields
struct xrt_io_cache *	xic
	Backing cache object that reads from / writes to the devices.

struct xrt_io_cache_info	info
	Layout (device table, counts and generation) of the current snapshot.

struct xrt_input *	inputs
	Snapshot arrays, owned here and sized per info; bindings point into these.

struct xrt_output *	outputs

Detailed Description

Per session-action-context snapshot of all device inputs and outputs, wrapping an xrt_io_cache.

One of these lives on every oxr_session_action_context. It is the seam that hides the underlying xrt_device instances from the OpenXR action code: resolved action bindings (oxr_action_input / oxr_action_output) point directly into the inputs / outputs arrays here, and those arrays are refreshed once per xrSyncActions from the backing devices in a single call.

The inputs and outputs arrays are owned here and sized to match the device layout described by info. Because action bindings hold raw pointers into these arrays, the arrays must not move while bindings are live: when the device set changes the arrays are reallocated (see oxr_io_cache_recreate) as an explicit step, bracketed by tearing down and re-resolving the bindings. The backing xic stays alive across that.

Member Function Documentation

◆ oxr_io_cache_device_inputs()

static XRT_NONNULL_ALL struct xrt_input * oxr_io_cache_device_inputs	(	const struct oxr_io_cache *	cache,
		const struct xrt_io_cache_device *	dev
	)

inlinestatic

The inputs of dev in oxr_io_cache::inputs, dev must be an entry in the layout of cache.

References xrt_io_cache_device::first_input, and inputs.

◆ oxr_io_cache_device_outputs()

static XRT_NONNULL_ALL struct xrt_output * oxr_io_cache_device_outputs	(	const struct oxr_io_cache *	cache,
		const struct xrt_io_cache_device *	dev
	)

inlinestatic

The outputs of dev in oxr_io_cache::outputs, dev must be an entry in the layout of cache.

References xrt_io_cache_device::first_output.

◆ oxr_io_cache_find_device()

XRT_NONNULL_ALL const struct xrt_io_cache_device * oxr_io_cache_find_device	(	const struct oxr_io_cache *	cache,
		struct xrt_device_id	id
	)

Find the layout entry of the device with id in the current snapshot, returns NULL if the device is not part of it.

References xrt_io_cache_info::devices, xrt_io_cache_device::id, and info.

◆ oxr_io_cache_find_input()

XRT_NONNULL_ALL struct xrt_input * oxr_io_cache_find_input	(	const struct oxr_io_cache *	cache,
		const struct xrt_io_cache_device *	dev,
		enum xrt_input_name	name
	)

Find the input called name on dev in the current snapshot.

The snapshot names are primed by oxr_io_cache_recreate, so this works for both statically-backed devices and cache-only devices (controllers).

References xrt_io_cache_device::input_count.

◆ oxr_io_cache_fini()

void oxr_io_cache_fini ( struct oxr_io_cache * cache )

Destroy the cache.

Call once, when the owning session action context is destroyed.

References inputs, and xic.

◆ oxr_io_cache_has_output()

XRT_NONNULL_ALL bool oxr_io_cache_has_output	(	const struct oxr_io_cache *	cache,
		const struct xrt_io_cache_device *	dev,
		enum xrt_output_name	name
	)

Whether dev exposes an output called name in the current snapshot.

References xrt_io_cache_device::output_count.

◆ oxr_io_cache_init()

XRT_CHECK_RESULT XrResult oxr_io_cache_init	(	struct oxr_io_cache *	cache,
		struct xrt_system_devices *	xsysd,
		struct xrt_space_overseer *	xso
	)

Create the cache.

Call once, when the owning session action context is created.

References xic, and XRT_SUCCESS.

◆ oxr_io_cache_recreate()

XRT_CHECK_RESULT XrResult oxr_io_cache_recreate	(	struct oxr_logger *	log,
		struct oxr_io_cache *	cache
	)

Recreate the snapshot for the current device layout: re-query info and reallocate the inputs / outputs arrays.

The backing xic is kept alive.

Call this as an explicit step after oxr_io_cache_sync reports the cache is stale, and only after the action bindings that point into the old arrays have been torn down; rebind afterwards so bindings point into the new arrays.

References info, xrt_io_cache_info::input_count, inputs, xrt_io_cache_info::output_count, oxr_error(), OXR_IO_CACHE_RECREATE_MAX_ATTEMPTS, U_TYPED_ARRAY_CALLOC, xic, and XRT_SUCCESS.

◆ oxr_io_cache_sync()

XRT_CHECK_RESULT XrResult oxr_io_cache_sync	(	struct oxr_logger *	log,
		struct oxr_io_cache *	cache,
		bool *	out_stale
	)

Refresh the snapshot: read all device inputs and outputs into inputs / outputs with a single call.

Call once per xrSyncActions.

This never reallocates. If the device layout changed since the arrays were sized the read cannot be satisfied, out_stale is set to true and the caller must tear down the bindings, oxr_io_cache_recreate, rebind, and sync again. On a normal refresh out_stale is set to false.

References xrt_io_cache_info::generation_id, info, xrt_io_cache_info::input_count, inputs, xrt_io_cache_info::output_count, oxr_error(), xic, and XRT_SUCCESS.

Field Documentation

◆ info

struct xrt_io_cache_info oxr_io_cache::info

Layout (device table, counts and generation) of the current snapshot.

Referenced by binding_device_from_cache(), oxr_io_cache_find_device(), oxr_io_cache_recreate(), and oxr_io_cache_sync().

◆ inputs

struct xrt_input* oxr_io_cache::inputs

Snapshot arrays, owned here and sized per info; bindings point into these.

Referenced by oxr_io_cache_device_inputs(), oxr_io_cache_fini(), oxr_io_cache_recreate(), and oxr_io_cache_sync().

◆ xic

struct xrt_io_cache* oxr_io_cache::xic

Backing cache object that reads from / writes to the devices.

Referenced by oxr_io_cache_fini(), oxr_io_cache_init(), oxr_io_cache_recreate(), and oxr_io_cache_sync().

The documentation for this struct was generated from the following file:

state_trackers/oxr/actions/oxr_io_cache.h

Public Member Functions

Static Public Member Functions

Data Fields