1 /*
2  * Copyright 2016-2017, Björn Ståhl
3  * License: 3-Clause BSD, see COPYING file in arcan source repository.
4  * Reference: http://arcan-fe.com
5  */
6 
7 /*
8  * Launch the binary specified through arcan_db_kv(arcan, ext_vr) with an
9  * inherited extended frameserver context using the protocol header defined in
10  * shmif/vr_platform.h and the [bridge_arg] being the packed argstr to expose
11  * through ARCAN_ARG.
12  *
13  * The event-context provided in [evctx] will be used to send appear/ disappear
14  * events which covers the _vid mapping of the associated null_surface device
15  * that will have its object- space position and orientation mapped and
16  * continously updated prior to rendering and to ticks.
17  *
18  * The [tag] provided will be added to relevant events, primarily for VM
19  * mapping (Lua, ...)
20  */
21 struct arcan_vr_ctx;
22 struct arcan_vr_ctx* arcan_vr_setup(
23 	const char* bridge_arg, struct arcan_evctx* evctx, uintptr_t tag);
24 
25 enum arcan_ffunc_rv arcan_vr_ffunc FFUNC_HEAD;
26 
27 /*
28  * Try and force- reset the devices bound to the platform controller.
29  */
30 arcan_errc arcan_vr_reset(struct arcan_vr_ctx*);
31 
32 /*
33  * Take two rendertarget outputs and associate a camera with each of them,
34  * using the parameters provided. They will be linked with the correct fov,
35  * ipd and other parameters. The contents of each rendertarget will not have
36  * any distortion applied yet, that is done in the final compositioning stage
37  * by either setting up a distortion shader or using a provided distortion
38  * mesh.
39  */
40 arcan_errc arcan_vr_camtag(struct arcan_vr_ctx*,
41 	arcan_vobj_id left, arcan_vobj_id right);
42 
43 /*
44  * (implemented in 3dbase.c), used to create or release a mapping between
45  * a 3d model and a VR context. Shouldn't be called directly - use maplimb.
46  */
47 arcan_errc arcan_3d_bindvr(arcan_vobj_id id, struct arcan_vr_ctx* vrref);
48 
49 arcan_errc arcan_vr_maplimb(
50 	struct arcan_vr_ctx*, unsigned ind, arcan_vobj_id vid,
51 	bool use_position, bool use_orientation);
52 
53 /*
54  * Used when breaking the association between a limb in a VR context and
55  * a 3D model as the model has been destroyed. Only reasonable to call from
56  * the destructor of a 3d model.
57  */
58 arcan_errc arcan_vr_release(struct arcan_vr_ctx*, arcan_vobj_id ind);
59 
60 /*
61  * Associate a model-carrying VID with a limb index. The limb must have been
62  * announced in respect to a plug/unplug action. If the limb disappears from
63  * the provider, the mapping will be released. If the model is destroyed, the
64  * limb index will be freed. If there already is a mapping on the limb, the
65  * previous one will be removed first. If model refers to an invalid id, the
66  * association will still be dropped.
67  */
68 arcan_errc arcan_vr_maplimb(
69 	struct arcan_vr_ctx*, unsigned ind, arcan_vobj_id model,
70 	bool use_position, bool use_orientation);
71 
72 /*
73  * Retrieve the values used for representing the display and
74  * lens parameters and store in [dst]
75  */
76 struct vr_meta;
77 arcan_errc arcan_vr_displaydata(struct arcan_vr_ctx*, struct vr_meta* dst);
78 
79 /*
80  * mark the current position / orientation as the reference frame
81  */
82 arcan_errc arcan_vr_setref(struct arcan_vr_ctx* ctx);
83 
84 /*
85  * Clean/ free the contents of the vr- context and associated
86  * processes. This will not explicitly delete the null_surfaces,
87  * these will continue to live in vid- space.
88  */
89 arcan_errc arcan_vr_shutdown(struct arcan_vr_ctx*);
90