Utilities

Smaller pieces of auxiliary utilities code. More...

Collaboration diagram for Utilities:

Files
file	u_bitwise.c
	Functions for manipulating tightly packed data as bits.
file	u_bitwise.h
	Functions for manipulating tightly packed data as bits.
file	u_debug.c
	Small debug helpers.
file	u_debug.h
	Small debug helpers.
file	u_device.c
	Misc helpers for device drivers.
file	u_device.h
	Misc helpers for device drivers.
file	u_distortion_mesh.c
	Code to generate disortion meshes.
file	u_distortion_mesh.h
	Code to generate disortion meshes.
file	u_documentation.h
	Header with just documentation.
file	u_file.c
	Very simple file opening functions.
file	u_file.h
	Very simple file opening functions.
file	u_format.c
	Format helpers and block code.
file	u_format.h
	Format helpers and block code.
file	u_frame.c
	xrt_frame helpers.
file	u_frame.h
	xrt_frame helpers.
file	u_hashmap.cpp
	Hashmap for integer values header.
file	u_hashmap.h
	Hashmap for integer values header.
file	u_hashset.cpp
	Hashset struct header.
file	u_hashset.h
	Hashset struct header.
file	u_json.c
	Tiny JSON wrapper around cJSON.
file	u_json.h
	Tiny JSON wrapper around cJSON header.
file	u_misc.c
	Very small misc utils.
file	u_misc.h
	Very small misc utils.
file	u_sink.h
	xrt_frame_sink converters and other helpers.
file	u_sink_converter.c
	xrt_frame_sink converters and other helpers.
file	u_sink_deinterleaver.c
	A xrt_frame_sink that deinterleaves stereo frames.
file	u_sink_queue.c
	A xrt_frame_sink queue.
file	u_sink_quirk.c
	A xrt_frame_sink that quirks frames.
file	u_sink_split.c
	A xrt_frame_sink splitter.
file	u_threading.h
	Slightly higher level thread safe helpers.
file	u_time.cpp
	Implementation of a steady, convertible clock.
file	u_time.h
	Time-keeping: a clock that is steady, convertible to system time, and ideally high-resolution.
file	u_var.cpp
	Variable tracking code.
file	u_var.h
	Variable tracking code.

Data Structures
struct	u_panotools_values
	Values to create a distortion mesh from panotools values. More...
struct	u_uv_triplet
	Three UV pairs, one for each color channel in the source image. More...
struct	u_uv_generator
	Generator struct for building meshes, can be implemented by drivers for special meshes. More...
struct	u_hashset_item
	A embeddable hashset item, note that the string directly follows the u_hashset_item. More...
struct	u_var_f32_arr
struct	u_hashmap_int
	A simple uint64_t key to a void pointer hashmap. More...
struct	u_hashset
	Kind of bespoke hashset implementation, where the user is responsible for allocating and freeing the items themselves. More...
struct	time_state
	Time-keeping state structure. More...

Macros
#define	U_CALLOC_WITH_CAST(TYPE, SIZE)   ((TYPE *)calloc(1, SIZE))
	Allocate and zero the give size and casts the memory into a pointer of the given type. More...
#define	U_TYPED_CALLOC(TYPE)   ((TYPE *)calloc(1, sizeof(TYPE)))
	Allocate and zero the space required for some type, and cast the return type appropriately. More...
#define	U_TYPED_ARRAY_CALLOC(TYPE, COUNT)   ((TYPE *)calloc((COUNT), sizeof(TYPE)))
	Allocate and zero the space required for some type, and cast the return type appropriately. More...
#define	U_ZERO(PTR)   memset((PTR), 0, sizeof(*(PTR)))
	Zeroes the correct amount of memory based on the type pointed-to by the argument. More...
#define	U_ZERO_ARRAY(ARRAY)   memset((ARRAY), 0, sizeof(ARRAY))
	Zeroes the correct amount of memory based on the type and size of the static array named in the argument. More...
#define	U_ARRAY_REALLOC_OR_FREE(VAR, TYPE, COUNT)   (VAR) = ((TYPE *)u_realloc_or_free((VAR), sizeof(TYPE) * (COUNT)))
	Re-allocate the space required for some type, and update the pointer - freeing the allocation instead if it can't be resized. More...

Typedefs
typedef int64_t	timepoint_ns
	Integer timestamp type. More...
typedef int64_t	time_duration_ns
	Integer duration type in nanoseconds. More...

Functions
bool	u_device_setup_split_side_by_side (struct xrt_device *xdev, const struct u_device_simple_info *info)
	Setup the device information given a very simple info struct. More...
void	u_device_dump_config (struct xrt_device *xdev, const char *prefix, const char *prod)
	Dump the device config to stderr. More...
void *	u_device_allocate (enum u_device_alloc_flags flags, size_t size, size_t num_inputs, size_t num_outputs)
	Helper function to allocate a device plus inputs in the same allocation placed after the device in memory. More...
void	u_device_free (struct xrt_device *xdev)
	Helper function to free a device and any data hanging of it. More...
void	u_distortion_mesh_from_gen (struct u_uv_generator *, int num_views, struct xrt_hmd_parts *target)
	Given a u_uv_generator generates num_views meshes, populates target. More...
void	u_distortion_mesh_generator_from_panotools (const struct u_panotools_values *left, const struct u_panotools_values *right, struct u_uv_generator **out_gen)
	Given two sets of panotools values creates a mesh generator, copies the values into it. More...
void	u_distortion_mesh_from_panotools (const struct u_panotools_values *left, const struct u_panotools_values *right, struct xrt_hmd_parts *target)
	Given two sets of panotools values creates the left and th right uv meshes. More...
void	u_distortion_mesh_none (struct xrt_hmd_parts *target)
	Create two distortion meshes with no distortion. More...
const char *	u_format_str (enum xrt_format f)
	Return string for this format. More...
bool	u_format_is_blocks (enum xrt_format f)
	Is this format block based, also returns true for formats that 1x1 blocks. More...
uint32_t	u_format_block_width (enum xrt_format f)
	Returns the width of the block for the given format. More...
uint32_t	u_format_block_height (enum xrt_format f)
	Returns the height of the block for the given format. More...
size_t	u_format_block_size (enum xrt_format f)
	Returns the size of the block for the given format. More...
void	u_format_size_for_dimensions (enum xrt_format f, uint32_t width, uint32_t height, size_t *out_stride, size_t *out_size)
	Calculate stride and size for the format and given width and height. More...
void	u_hashmap_int_clear_and_call_for_each (struct u_hashmap_int *hmi, u_hashmap_int_callback cb, void *priv)
	First clear the hashmap and then call the given callback with each item that was in the hashmap. More...
void	u_hashset_clear_and_call_for_each (struct u_hashset *hs, u_hashset_callback cb, void *priv)
	First clear the hashset and then call the given callback with each item that was in the hashset. More...
struct time_state *	time_state::time_state_create ()
	Create a struct time_state. More...
void	time_state::time_state_destroy (struct time_state **state)
	Destroy a struct time_state. More...
timepoint_ns	time_state::time_state_get_now (struct time_state const *state)
	Get the current time as an integer timestamp. More...
timepoint_ns	time_state::time_state_get_now_and_update (struct time_state *state)
	Get the current time as an integer timestamp and update internal state. More...
void	time_state::time_state_to_timespec (struct time_state const *state, timepoint_ns timestamp, struct timespec *out)
	Convert an integer timestamp to a struct timespec (system time). More...
timepoint_ns	time_state::time_state_from_timespec (struct time_state const *state, const struct timespec *timespecTime)
	Convert a struct timespec (system time) to an integer timestamp. More...
timepoint_ns	time_state::time_state_from_monotonic_ns (struct time_state const *state, uint64_t monotonic_ns)
	Convert a monotonic system time (such as from Portable Timekeeping) to an adjusted integer timestamp. More...
void	u_var_add_root (void *root, const char *c_name, bool number)
	Add a named root object, the u_var subsystem is completely none-invasive to the object it's tracking. More...

Detailed Description

Smaller pieces of auxiliary utilities code.

Macro Definition Documentation

U_ARRAY_REALLOC_OR_FREE

#define U_ARRAY_REALLOC_OR_FREE	(		VAR,
			TYPE,
			COUNT
	)		(VAR) = ((TYPE *)u_realloc_or_free((VAR), sizeof(TYPE) * (COUNT)))

#include <auxiliary/util/u_misc.h>

Re-allocate the space required for some type, and update the pointer - freeing the allocation instead if it can't be resized.

Use instead of a bare realloc when allocating an array of a type. This includes reallocating C strings: pass char as the type.

Be sure not to parenthesize the type! It will cause an error like "expression expected".

On the other hand, if you get an incompatible types error in assignment, that's a type mismatch, a real bug.

U_CALLOC_WITH_CAST

#define U_CALLOC_WITH_CAST	(		TYPE,
			SIZE
	)		((TYPE *)calloc(1, SIZE))

#include <auxiliary/util/u_misc.h>

Allocate and zero the give size and casts the memory into a pointer of the given type.

Use instead of a bare calloc, but only when U_TYPED_CALLOC and U_TYPED_ARRAY_CALLOC do not meet your needs.

U_TYPED_ARRAY_CALLOC

#define U_TYPED_ARRAY_CALLOC	(		TYPE,
			COUNT
	)		((TYPE *)calloc((COUNT), sizeof(TYPE)))

#include <auxiliary/util/u_misc.h>

Allocate and zero the space required for some type, and cast the return type appropriately.

Use instead of a bare calloc when allocating an array of a type. This includes allocating C strings: pass char as the type.

Referenced by comp_window_direct_create_surface(), comp_window_direct_get_primary_display_mode(), oxr_vk_get_physical_device(), run_func(), and u_device_allocate().

U_TYPED_CALLOC

#define U_TYPED_CALLOC

(

TYPE

)

((TYPE *)calloc(1, sizeof(TYPE)))

#include <auxiliary/util/u_misc.h>

Allocate and zero the space required for some type, and cast the return type appropriately.

Use instead of a bare calloc when allocating a single structure.

Referenced by arduino_create_auto_prober(), client_gl_xlib_compositor_create(), client_vk_compositor_create(), comp_renderer_create(), comp_window_direct_nvidia_create(), comp_window_direct_randr_create(), comp_window_wayland_create(), comp_window_xcb_create(), daydream_create_auto_prober(), dummy_create_auto_prober(), gui_ogl_sink_create(), gui_scene_calibrate(), gui_scene_debug(), gui_scene_main_menu(), hydra_found(), m_ff_vec3_f32_alloc(), ns_create_auto_prober(), oh_create_auto_prober(), os_ble_notify_open(), oxr_sdl2_hack_stop(), p_tracking_init(), psvr_create_auto_prober(), t_hsv_build_convert_table(), t_hsv_build_large_table(), t_hsv_build_optimized_table(), t_hsv_filter_create(), t_stereo_camera_calibration_alloc(), u_distortion_mesh_generator_from_panotools(), u_frame_create_one_off(), u_sink_create_format_converter(), u_sink_create_to_r8g8b8_or_l8(), u_sink_create_to_yuv_or_yuyv(), u_sink_create_to_yuv_yuyv_uyvy_or_l8(), u_sink_deinterleaver_create(), u_sink_queue_create(), u_sink_quirk_create(), u_sink_split_create(), v4l2_fs_create(), xrt_gfx_provider_create_fd(), xrt_gfx_provider_create_gl_egl(), xrt_instance_create(), and xrt_prober_create_with_lists().

U_ZERO

#define U_ZERO

(

PTR

)

memset((PTR), 0, sizeof(*(PTR)))

#include <auxiliary/util/u_misc.h>

Zeroes the correct amount of memory based on the type pointed-to by the argument.

Use instead of memset(..., 0, ...) on a structure or pointer to structure.

Referenced by m_imu_3dof_init(), oxr_classify_sub_action_paths(), oxr_xdev_get_pose_at(), and vk_init_from_given().

U_ZERO_ARRAY

#define U_ZERO_ARRAY

(

ARRAY

)

memset((ARRAY), 0, sizeof(ARRAY))

#include <auxiliary/util/u_misc.h>

Zeroes the correct amount of memory based on the type and size of the static array named in the argument.

Use instead of memset(..., 0, ...) on an array.

Typedef Documentation

time_duration_ns

typedef int64_t time_duration_ns

#include <auxiliary/util/u_time.h>

Integer duration type in nanoseconds.

Logical type of timepoint differences.

See also

time_state

timepoint_ns

timepoint_ns

typedef int64_t timepoint_ns

#include <auxiliary/util/u_time.h>

Integer timestamp type.

See also

time_state

time_duration_ns

Function Documentation

time_state_create()

struct time_state * time_state_create

(

)

Create a struct time_state.

Referenced by gui_prober_init().

time_state_destroy()

void time_state_destroy

(

struct time_state **

state

)

Destroy a struct time_state.

Should not be called simultaneously with any other time_state function.

Referenced by gui_prober_teardown().

time_state_from_monotonic_ns()

timepoint_ns time_state_from_monotonic_ns	(	struct time_state const *	state,
		uint64_t	monotonic_ns
	)

Convert a monotonic system time (such as from Portable Timekeeping) to an adjusted integer timestamp.

Adjustments may need to be applied to achieve the other guarantees that e.g. CLOCK_MONOTONIC does not provide: this function performs those adjustments.

Should not be called simultaneously with time_state_get_now_and_update.

time_state_from_timespec()

timepoint_ns time_state_from_timespec	(	struct time_state const *	state,
		const struct timespec *	timespecTime
	)

Convert a struct timespec (system time) to an integer timestamp.

Should not be called simultaneously with time_state_get_now_and_update.

Referenced by oxr_instance_convert_timespec_to_time().

time_state_get_now()

timepoint_ns time_state_get_now

(

struct time_state const *

state

)

Get the current time as an integer timestamp.

Does not update internal state for timekeeping. Should not be called simultaneously with time_state_get_now_and_update.

time_state_get_now_and_update()

timepoint_ns time_state_get_now_and_update

(

struct time_state *

state

)

Get the current time as an integer timestamp and update internal state.

This should be called regularly, but only from one thread. It updates the association between the timing sources.

Should not be called simultaneously with any other time_state function.

Referenced by gui_prober_update().

time_state_to_timespec()

void time_state_to_timespec	(	struct time_state const *	state,
		timepoint_ns	timestamp,
		struct timespec *	out
	)

Convert an integer timestamp to a struct timespec (system time).

Should not be called simultaneously with time_state_get_now_and_update.

Referenced by oxr_instance_convert_time_to_timespec().

u_device_allocate()

void* u_device_allocate	(	enum u_device_alloc_flags	flags,
		size_t	size,
		size_t	num_inputs,
		size_t	num_outputs
	)

#include <auxiliary/util/u_device.h>

Helper function to allocate a device plus inputs in the same allocation placed after the device in memory.

Will setup any pointers and num values.

References xrt_device::num_inputs, U_DEVICE_ALLOC_HMD, U_DEVICE_ALLOC_TRACKING_NONE, U_TYPED_ARRAY_CALLOC, XRT_TRACKING_NAME_LEN, and XRT_TRACKING_TYPE_NONE.

u_device_dump_config()

void u_device_dump_config	(	struct xrt_device *	xdev,
		const char *	prefix,
		const char *	prod
	)

#include <auxiliary/util/u_device.h>

Dump the device config to stderr.

References xrt_fov::angle_down, xrt_fov::angle_left, xrt_fov::angle_right, xrt_fov::angle_up, xrt_view::display, xrt_view::fov, xrt_view::h_meters, xrt_view::h_pixels, xrt_hmd_parts::h_pixels, xrt_device::hmd, xrt_view::lens_center, PRINT_ANGLE, PRINT_INT, PRINT_MAT2X2, PRINT_MM, PRINT_STR, xrt_view::rot, xrt_hmd_parts::screens, xrt_view::viewport, xrt_hmd_parts::views, xrt_view::w_meters, xrt_view::w_pixels, xrt_hmd_parts::w_pixels, xrt_view::x_meters, xrt_view::x_pixels, xrt_view::y_meters, and xrt_view::y_pixels.

u_device_free()

void u_device_free

(

struct xrt_device *

xdev

)

#include <auxiliary/util/u_device.h>

Helper function to free a device and any data hanging of it.

References xrt_hmd_parts::distortion, xrt_device::hmd, and xrt_hmd_parts::mesh.

u_device_setup_split_side_by_side()

bool u_device_setup_split_side_by_side	(	struct xrt_device *	xdev,
		const struct u_device_simple_info *	info
	)

#include <auxiliary/util/u_device.h>

Setup the device information given a very simple info struct.

Returns

true on success.

References xrt_fov::angle_down, xrt_fov::angle_left, xrt_fov::angle_right, xrt_fov::angle_up, xrt_hmd_parts::blend_mode, u_device_simple_info::display, xrt_view::display, xrt_hmd_parts::distortion, u_device_simple_info::fov, xrt_view::fov, u_device_simple_info::h_meters, xrt_view::h_meters, u_device_simple_info::h_pixels, xrt_view::h_pixels, xrt_hmd_parts::h_pixels, xrt_device::hmd, xrt_view::lens_center, u_device_simple_info::lens_horizontal_separation_meters, u_device_simple_info::lens_vertical_position_meters, math_compute_fovs(), xrt_hmd_parts::models, xrt_hmd_parts::preferred, xrt_view::rot, xrt_hmd_parts::screens, u_device_rotation_ident, xrt_view::viewport, u_device_simple_info::views, xrt_hmd_parts::views, u_device_simple_info::w_meters, xrt_view::w_meters, u_device_simple_info::w_pixels, xrt_view::w_pixels, xrt_hmd_parts::w_pixels, xrt_view::x_meters, xrt_view::x_pixels, XRT_BLEND_MODE_OPAQUE, XRT_DISTORTION_MODEL_NONE, xrt_view::y_meters, and xrt_view::y_pixels.

u_distortion_mesh_from_gen()

void u_distortion_mesh_from_gen	(	struct u_uv_generator *	,
		int	num_views,
		struct xrt_hmd_parts *	target
	)

#include <auxiliary/util/u_distortion_mesh.h>

Given a u_uv_generator generates num_views meshes, populates target.

References run_func().

u_distortion_mesh_from_panotools()

void u_distortion_mesh_from_panotools	(	const struct u_panotools_values *	left,
		const struct u_panotools_values *	right,
		struct xrt_hmd_parts *	target
	)

#include <auxiliary/util/u_distortion_mesh.h>

Given two sets of panotools values creates the left and th right uv meshes.

This is probably the function you want.

u_distortion_mesh_generator_from_panotools()

void u_distortion_mesh_generator_from_panotools	(	const struct u_panotools_values *	left,
		const struct u_panotools_values *	right,
		struct u_uv_generator **	out_gen
	)

#include <auxiliary/util/u_distortion_mesh.h>

Given two sets of panotools values creates a mesh generator, copies the values into it.

This probably isn't the function you want.

References U_TYPED_CALLOC.

u_distortion_mesh_none()

void u_distortion_mesh_none

(

struct xrt_hmd_parts *

target

)

#include <auxiliary/util/u_distortion_mesh.h>

Create two distortion meshes with no distortion.

References u_uv_generator::calc.

u_format_block_height()

uint32_t u_format_block_height

(

enum xrt_format

f

)

#include <auxiliary/util/u_format.h>

Returns the height of the block for the given format.

References XRT_FORMAT_BITMAP_8X1, XRT_FORMAT_BITMAP_8X8, XRT_FORMAT_L8, XRT_FORMAT_R8, XRT_FORMAT_R8G8, XRT_FORMAT_R8G8B8, XRT_FORMAT_R8G8B8A8, XRT_FORMAT_R8G8B8X8, XRT_FORMAT_UYVY422, XRT_FORMAT_YUV888, and XRT_FORMAT_YUYV422.

Referenced by u_format_size_for_dimensions().

u_format_block_size()

size_t u_format_block_size

(

enum xrt_format

f

)

#include <auxiliary/util/u_format.h>

Returns the size of the block for the given format.

References XRT_FORMAT_BITMAP_8X1, XRT_FORMAT_BITMAP_8X8, XRT_FORMAT_L8, XRT_FORMAT_R8, XRT_FORMAT_R8G8, XRT_FORMAT_R8G8B8, XRT_FORMAT_R8G8B8A8, XRT_FORMAT_R8G8B8X8, XRT_FORMAT_UYVY422, XRT_FORMAT_YUV888, and XRT_FORMAT_YUYV422.

Referenced by u_format_size_for_dimensions().

u_format_block_width()

uint32_t u_format_block_width

(

enum xrt_format

f

)

#include <auxiliary/util/u_format.h>

Returns the width of the block for the given format.

References XRT_FORMAT_BITMAP_8X1, XRT_FORMAT_BITMAP_8X8, XRT_FORMAT_L8, XRT_FORMAT_R8, XRT_FORMAT_R8G8, XRT_FORMAT_R8G8B8, XRT_FORMAT_R8G8B8A8, XRT_FORMAT_R8G8B8X8, XRT_FORMAT_UYVY422, XRT_FORMAT_YUV888, and XRT_FORMAT_YUYV422.

Referenced by u_format_size_for_dimensions().

u_format_is_blocks()

bool u_format_is_blocks

(

enum xrt_format

f

)

#include <auxiliary/util/u_format.h>

Is this format block based, also returns true for formats that 1x1 blocks.

References XRT_FORMAT_BITMAP_8X1, XRT_FORMAT_BITMAP_8X8, XRT_FORMAT_L8, XRT_FORMAT_MJPEG, XRT_FORMAT_R8, XRT_FORMAT_R8G8, XRT_FORMAT_R8G8B8, XRT_FORMAT_R8G8B8A8, XRT_FORMAT_R8G8B8X8, XRT_FORMAT_UYVY422, XRT_FORMAT_YUV888, and XRT_FORMAT_YUYV422.

Referenced by u_frame_create_one_off().

u_format_size_for_dimensions()

void u_format_size_for_dimensions	(	enum xrt_format	f,
		uint32_t	width,
		uint32_t	height,
		size_t *	out_stride,
		size_t *	out_size
	)

#include <auxiliary/util/u_format.h>

Calculate stride and size for the format and given width and height.

References u_format_block_height(), u_format_block_size(), and u_format_block_width().

u_format_str()

const char* u_format_str

(

enum xrt_format

f

)

#include <auxiliary/util/u_format.h>

Return string for this format.

References XRT_FORMAT_BITMAP_8X1, XRT_FORMAT_BITMAP_8X8, XRT_FORMAT_L8, XRT_FORMAT_MJPEG, XRT_FORMAT_R8, XRT_FORMAT_R8G8, XRT_FORMAT_R8G8B8, XRT_FORMAT_R8G8B8A8, XRT_FORMAT_R8G8B8X8, XRT_FORMAT_UYVY422, XRT_FORMAT_YUV888, and XRT_FORMAT_YUYV422.

Referenced by u_sink_create_format_converter().

u_hashmap_int_clear_and_call_for_each()

void u_hashmap_int_clear_and_call_for_each	(	struct u_hashmap_int *	hmi,
		u_hashmap_int_callback	cb,
		void *	priv
	)

#include <auxiliary/util/u_hashmap.h>

First clear the hashmap and then call the given callback with each item that was in the hashmap.

References u_hashmap_int::map.

u_hashset_clear_and_call_for_each()

void u_hashset_clear_and_call_for_each	(	struct u_hashset *	hs,
		u_hashset_callback	cb,
		void *	priv
	)

#include <auxiliary/util/u_hashset.h>

First clear the hashset and then call the given callback with each item that was in the hashset.

References u_hashset::map.

Referenced by oxr_path_destroy_all().

u_var_add_root()

void u_var_add_root	(	void *	root,
		const char *	c_name,
		bool	number
	)

#include <auxiliary/util/u_var.h>

Add a named root object, the u_var subsystem is completely none-invasive to the object it's tracking.

The root pointer is used as a entry into a hashmap of hidden objecrs. When not active all calls are stubs and have no side-effects.

This is intended only for debugging and is turned off by default, as this all very very unsafe. It is just pointers straight into objects, completely ignores ownership or any safe practices.

If it's stupid, but it works, it ain't stupid.

// On create
u_var_add_root((void*)psmv, "PS Move Controller", true);
u_var_add_rgb_u8((void*)psmv, &psmv->led_color, "LED");
u_var_add_bool((void*)psmv, &psmv->print_spew, "Spew");
u_var_add_bool((void*)psmv, &psmv->print_debug, "Debug");

// On destroy, only need to destroy the root object.
u_var_remove_root((void*)psmv);

Referenced by gui_sdl2_imgui_loop(), and oxr_sdl2_hack_stop().