1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/1-init.rst	Sun Mar 08 05:30:02 2015 +0200
     1.3 @@ -0,0 +1,57 @@
     1.4 +Initialization
     1.5 +--------------
     1.6 +
     1.7 +Before calling any other function you need to initialize the VR library by
     1.8 +calling ``vr_init``. Similarly, ``vr_shutdown`` frees up all resources held by
     1.9 +the library.
    1.10 +
    1.11 +Libgoatvr has a number of backend modules for interfacing with VR headsets, and
    1.12 +there might be multiple modules compiled with your version of libgoatvr. If you
    1.13 +don't want to rely on the built-in defaults, you might want to enumerate and
    1.14 +select which module to use.
    1.15 +
    1.16 +The following example initializes the library, and prints the list of available
    1.17 +VR modules:
    1.18 +
    1.19 +.. code:: c
    1.20 +
    1.21 + #include <stdio.h>
    1.22 + #include <goatvr.h>
    1.23 + 
    1.24 + int main(void)
    1.25 + {
    1.26 + 	int i, nmod;
    1.27 + 
    1.28 + 	if(vr_init() == -1) {
    1.29 + 		fprintf(stderr, "failed to initialize goatvr\n");
    1.30 + 		return 1;
    1.31 + 	}
    1.32 + 
    1.33 + 	nmod = vr_module_count();
    1.34 + 	printf("There are %d modules:\n", nmod);
    1.35 + 	for(i=0; i<nmod; i++) {
    1.36 + 		printf(" %2d - %s\n", i, vr_module_name(i));
    1.37 + 	}
    1.38 + 	vr_shutdown();
    1.39 + 	return 0;
    1.40 + }
    1.41 + 
    1.42 +Running this on my computer, with the Oculus Rift DK2 connected, and oculusd
    1.43 +running, produces this output::
    1.44 +
    1.45 + initialized LibOVR 0.4.4
    1.46 + 1 Oculus HMD(s) found
    1.47 +  [0]: Oculus VR - Oculus Rift DK2
    1.48 + using vr module: libovr
    1.49 + There are 2 modules:
    1.50 +   0 - libovr
    1.51 +   1 - null
    1.52 +
    1.53 +The first four lines come from the initialization of the ``libovr`` module which
    1.54 +is selected by default if it's available. If however I turn off the DK2 or stop
    1.55 +the daemon, then I'm getting just the ``null`` module in this list.
    1.56 +
    1.57 +If you'd like to override the default selected module, and use the ``null``
    1.58 +module instead of ``libovr``, which is useful during development to avoid having
    1.59 +to put the HMD on and off all the time, you can call ``vr_use_module(1)``, or
    1.60 +``vr_use_module_named("null")``.