A single OpenXR handle, which is a child of a parent handle holder, if any. More...

#include <oxr/common/oxr_handle_base.h>

Inheritance diagram for oxr_handle_base:

[legend]

Collaboration diagram for oxr_handle_base:

[legend]

Public Member Functions
XrResult	oxr_handle_destroy (struct oxr_logger log, struct oxr_handle_base hb)
	Destroy the handle's object.

Data Fields
uint64_t	debug
	Magic (per-handle-type) value for debugging.

struct oxr_handle_parent_base *	parent
	Pointer to this object's parent handle holder, if any.

enum oxr_handle_state	state
	Current handle state.

oxr_handle_destroyer	destroy
	Destroy the object this handle refers to.

Protected Member Functions
XrResult	oxr_handle_init (struct oxr_logger log, struct oxr_handle_base hb, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base *parent)
	Initialize a handle, and if a parent is specified, update its child list to include this handle.

XrResult	oxr_handle_destroy_internal (struct oxr_logger log, struct oxr_handle_base hb, int level)
	Destroys a single handle, removing it from its parent if it has one.

Related Symbols
(Note that these are not member symbols.)
typedef XrResult(*	oxr_handle_destroyer) (struct oxr_logger log, struct oxr_handle_base hb)
	Function pointer type for a handle destruction function.

XrResult	oxr_handle_allocate_and_init (struct oxr_logger log, size_t size, uint64_t debug, oxr_handle_destroyer destroy, struct oxr_handle_parent_base parent, void **out)
	Allocate some memory for use as a handle, and initialize it as a handle.

const char *	oxr_handle_state_to_string (enum oxr_handle_state state)
	Returns a human-readable label for a handle state.

#define	OXR_ALLOCATE_HANDLE(LOG, OUT, DEBUG, DESTROY, PARENT) oxr_handle_allocate_and_init(LOG, sizeof(OUT), DEBUG, DESTROY, PARENT, (void *)&OUT)
	Allocates memory for a handle and evaluates to an XrResult.

#define	OXR_ALLOCATE_HANDLE_OR_RETURN(LOG, OUT, DEBUG, DESTROY, PARENT)
	Allocate memory for a handle, returning in case of failure.

Detailed Description

A single OpenXR handle, which is a child of a parent handle holder, if any.

Each object referenced by an OpenXR handle should have one of these as its first element, thus "extending" this class.

Member Function Documentation

◆ oxr_handle_destroy()

XrResult oxr_handle_destroy	(	struct oxr_logger *	log,
		struct oxr_handle_base *	hb
	)

Destroy the handle's object.

This should be how all handle-associated objects are destroyed.

References oxr_handle_destroy_internal().

◆ oxr_handle_destroy_internal()

XrResult oxr_handle_destroy_internal	(	struct oxr_logger *	log,
		struct oxr_handle_base *	hb,
		int	level
	)

protected

Destroys a single handle, removing it from its parent if it has one.

oxr_handle_destroy wraps this to provide some extra output and start level at 0. level, which is reported in debug output, is the current depth of recursion.

References oxr_handle_parent_base::children, oxr_error(), oxr_handle_array_remove(), OXR_HANDLE_STATE_DESTROYED, and parent.

Referenced by oxr_handle_array_destroy(), oxr_handle_destroy(), and oxr_handle_parent_base::oxr_handle_parent_destroy_internal().

◆ oxr_handle_init()

XrResult oxr_handle_init	(	struct oxr_logger *	log,
		struct oxr_handle_base *	hb,
		uint64_t	debug,
		oxr_handle_destroyer	destroy,
		struct oxr_handle_parent_base *	parent
	)

protected

Initialize a handle, and if a parent is specified, update its child list to include this handle.

Friends And Related Symbol Documentation

◆ OXR_ALLOCATE_HANDLE

#define OXR_ALLOCATE_HANDLE	(	LOG,
		OUT,
		DEBUG,
		DESTROY,
		PARENT
	)	oxr_handle_allocate_and_init(LOG, sizeof(OUT), DEBUG, DESTROY, PARENT, (void *)&OUT)

Parameters

LOG	pointer to struct oxr_logger
OUT	the pointer to handle struct type you already created.
DEBUG	Magic per-type debugging constant
DESTROY	Handle destructor function
PARENT	a parent handle, if any

Use when you want to do something other than immediately returning in case of failure. If returning immediately is OK, see OXR_ALLOCATE_HANDLE_OR_RETURN().

◆ OXR_ALLOCATE_HANDLE_OR_RETURN

#define OXR_ALLOCATE_HANDLE_OR_RETURN	(	LOG,
		OUT,
		DEBUG,
		DESTROY,
		PARENT
	)

        do {                                                                                                           \
                /* static assert that out has field 'handle' of type struct oxr_handle_base */                         \
                ASSERT_HANDLE_TYPE(OUT, typeof(*OUT), struct oxr_handle_base);                                         \
                XrResult allocResult = OXR_ALLOCATE_HANDLE(LOG, OUT, DEBUG, DESTROY, PARENT);                          \
                if (allocResult != XR_SUCCESS) {                                                                       \
                        return allocResult;                                                                            \
                }                                                                                                      \
        } while (0)

Allocate memory for a handle, returning in case of failure.

Parameters

LOG	pointer to struct oxr_logger
OUT	the pointer to handle struct type you already created.
DEBUG	Magic per-type debugging constant
DESTROY	Handle destructor function
PARENT	a parent handle, if any

Will return an XrResult from the current function if something fails. If that's not OK, see OXR_ALLOCATE_HANDLE().

Referenced by oxr_action_create(), oxr_space_action_create(), oxr_space_xdev_pose_create(), and oxr_swapchain_common_create().

◆ oxr_handle_allocate_and_init()

XrResult oxr_handle_allocate_and_init	(	struct oxr_logger *	log,
		size_t	size,
		uint64_t	debug,
		oxr_handle_destroyer	destroy,
		struct oxr_handle_parent_base *	parent,
		void **	out
	)

Mainly for internal use - use OXR_ALLOCATE_HANDLE instead which wraps this.

◆ oxr_handle_destroyer

typedef XrResult(* oxr_handle_destroyer) (struct oxr_logger *log, struct oxr_handle_base *hb)

◆ oxr_handle_state_to_string()

const char * oxr_handle_state_to_string ( enum oxr_handle_state state )

References OXR_HANDLE_STATE_DESTROYED, OXR_HANDLE_STATE_LIVE, and OXR_HANDLE_STATE_UNINITIALIZED.

Field Documentation

◆ debug

uint64_t oxr_handle_base::debug

Magic (per-handle-type) value for debugging.

Referenced by oxr_verify_action_sets_array(), and oxr_verify_active_action_sets_sync().

◆ destroy

oxr_handle_destroyer oxr_handle_base::destroy

Destroy the object this handle refers to.

◆ parent

struct oxr_handle_parent_base* oxr_handle_base::parent

Pointer to this object's parent handle holder, if any.

Referenced by oxr_handle_destroy_internal().

◆ state

enum oxr_handle_state oxr_handle_base::state

Current handle state.