C Interface to the Oculus PC SDK tracking and rendering library. More...
#include "OVR_CAPI_Keys.h"
#include "OVR_Version.h"
#include "OVR_ErrorCode.h"
#include <stdint.h>
Go to the source code of this file.
C Interface to the Oculus PC SDK tracking and rendering library.
Defines explicitly unused space for a struct.
When used correcly, usage of this macro should not change the size of the struct. Compile-time and runtime behavior with and without this defined should be identical.
Signature of the logging callback function pointer type.
Specifies the maximum number of layers supported by ovr_SubmitFrame.
/see ovr_SubmitFrame
Describes button input types.
Button inputs are combined; that is they will be reported as pressed if they are pressed on either one of the two devices. The ovrButton_Up/Down/Left/Right map to both XBox D-Pad and directional buttons. The ovrButton_Enter and ovrButton_Return map to Start and Back controller buttons, respectively.
Specifies which controller is connected; multiple can be connected at once.
Debug HUD is provided to help developers gauge and debug the fidelity of their app's stereo rendering characteristics.
Using the provided quad and crosshair guides, the developer can verify various aspects such as VR tracking units (e.g. meters), stereo camera-parallax properties (e.g. making sure objects at infinity are rendered with the proper separation), measuring VR geometry sizes and distances and more.
App can toggle the debug HUD modes as such:
The app can modify the visual properties of the stereo guide (i.e. quad, crosshair) using the ovr_SetFloatArray function. For a list of tweakable properties, see the OVR_DEBUG_HUD_STEREO_GUIDE_* keys in the OVR_CAPI_Keys.h header file.
Specifies which eye is being used for rendering.
This type explicitly does not include a third "NoStereo" monoscopic option, as such is not required for an HMD-centered API.
Provides names for the left and right hand array indexes.
HMD capability bits reported by device.
Enumerates all HMD types that we support.
The currently released developer kits are ovrHmd_DK1 and ovrHmd_DK2. The other enumerations are for internal use only.
Initialization flags.
Identifies flags used by ovrLayerHeader and which are passed to ovr_SubmitFrame.
Layer HUD enables the HMD user to see information about a layer.
App can toggle layer HUD modes as such:
Describes layer types that can be passed to ovr_SubmitFrame.
Each layer type has an associated struct, such as ovrLayerEyeFov.
Logging levels.
Performance HUD enables the HMD user to see information critical to the real-time operation of the VR application such as latency timing, and CPU & GPU performance metrics.
App can toggle performance HUD modes as such:
Bit flags describing the current status of sensor tracking.
The values must be the same as in enum StatusBits
The bindings required for texture swap chain.
All texture swap chains are automatically bindable as shader input resources since the Oculus runtime needs this to read them.
Misc flags overriding particular behaviors of a texture swap chain.
The format of a texture.
The type of texture resource.
Describes touch input types.
These values map to capacitive touch values reported ovrInputState::Touch. Some of these values are mapped to button bits for consistency.
Specifies sensor flags.
/see ovrTrackerPose
Tracking capability bits reported by the device.
Used with ovr_GetTrackingCaps.
Specifies the coordinate system ovrTrackingState returns tracking poses in.
Used with ovr_SetTrackingOriginType()
Clears the ShouldRecenter status bit in ovrSessionStatus.
Clears the ShouldRecenter status bit in ovrSessionStatus, allowing further recenter requests to be detected. Since this is automatically done by ovr_RecenterTrackingOrigin, this is only needs to be called when application is doing its own re-centering.
Commits any pending changes to an ovrTextureSwapChain, and advances its current index.
Creates a handle to a VR session.
Upon success the returned ovrSession must be eventually freed with ovr_Destroy when it is no longer needed. A second call to ovr_Create will result in an error return value if the previous session has not been destroyed.
Example code
Destroys the session.
MirrorTexture creation is rendering API-specific.
ovr_CreateMirrorTextureDX and ovr_CreateMirrorTextureGL can be found in the rendering API-specific headers, such as OVR_CAPI_D3D.h and OVR_CAPI_GL.h Destroys a mirror texture previously created by one of the mirror texture creation functions.
Destroys an ovrTextureSwapChain and frees all the resources associated with it.
Reads a boolean property.
Gets the dimension of the Boundary System's "play area" or "outer boundary".
Gets the geometry of the Boundary System's "play area" or "outer boundary" as 3D floor points.
Returns if the boundary is currently visible.
Note: visibility is false if the user has turned off boundaries, otherwise, it's true if the app has requested boundaries to be visible or if any tracked device is currently triggering it. This may not exactly match rendering due to fade-in and fade-out effects.
Returns controller types connected to the system OR'ed together.
Gets the Haptics engine playback state of a specific Touch controller.
Reads a float property.
Reads a float array property.
Calculates the recommended viewport size for rendering a given eye within the HMD with a given FOV cone.
Higher FOV will generally require larger textures to maintain quality. Apps packing multiple eye views together on the same texture should ensure there are at least 8 pixels of padding between them to prevent texture filtering and chromatic aberration causing images to leak between the two eye views.
Example code
Returns information about the current HMD.
ovr_Initialize must have first been called in order for this to succeed, otherwise ovrHmdDesc::Type will be reported as ovrHmd_None.
Returns the most recent input state for controllers, without positional tracking info.
Reads an integer property.
Returns information about the most recent failed return value by the current thread for this library.
This function itself can never generate an error. The last error is never cleared by LibOVR, but will be overwritten by new errors. Do not use this call to determine if there was an error in the last API call as successful API calls don't clear the last ovrErrorInfo. To avoid any inconsistency, ovr_GetLastErrorInfo should be called immediately after an API function that returned a failed ovrResult, with no other API functions called in the interim.
Retrieves performance stats for the VR app as well as the SDK compositor.
If the app calling this function is not the one in focus (i.e. not visible in the HMD), then outStats will be zero'd out. New stats are populated after each successive call to ovr_SubmitFrame. So the app should call this function on the same thread it calls ovr_SubmitFrame, preferably immediately afterwards.
Gets the time of the specified frame midpoint.
Predicts the time at which the given frame will be displayed. The predicted time is the middle of the time period during which the corresponding eye images will be displayed.
The application should increment frameIndex for each successively targeted frame, and pass that index to any relevant OVR functions that need to apply to the frame identified by that index.
This function is thread-safe and allows for multiple application threads to target their processing to the same displayed frame.
In the even that prediction fails due to various reasons (e.g. the display being off or app has yet to present any frames), the return value will be current CPU time.
Computes the distortion viewport, view adjust, and other rendering parameters for the specified eye.
Returns status information for the application.
Reads a string property.
Strings are UTF8-encoded and null-terminated.
Gets the current index in an ovrTextureSwapChain.
Gets the description of the buffers in an ovrTextureSwapChain.
TextureSwapChain creation is rendering API-specific.
ovr_CreateTextureSwapChainDX and ovr_CreateTextureSwapChainGL can be found in the rendering API-specific headers, such as OVR_CAPI_D3D.h and OVR_CAPI_GL.h Gets the number of buffers in an ovrTextureSwapChain.
Returns global, absolute high-resolution time in seconds.
The time frame of reference for this function is not specified and should not be depended upon.
Gets information about Haptics engine for the specified Touch controller.
Returns the number of attached trackers.
The number of trackers may change at any time, so this function should be called before use as opposed to once on startup.
Returns a given attached tracker description.
ovr_Initialize must have first been called in order for this to succeed, otherwise the returned trackerDescArray will be zero-initialized. The data returned by this function can change at runtime.
Returns the ovrTrackerPose for the given attached tracker.
Gets the tracking origin state.
Returns tracking state reading based on the specified absolute system time.
Pass an absTime value of 0.0 to request the most recent sensor reading. In this case both PredictedPose and SamplePose will have the same value.
This may also be used for more refined timing of front buffer rendering logic, and so on. This may be called by multiple threads.
Returns the version string representing the LibOVRRT version.
The returned string pointer is valid until the next call to ovr_Shutdown.
Note that the returned version string doesn't necessarily match the current OVR_MAJOR_VERSION, etc., as the returned string refers to the LibOVRRT shared library version and not the locally compiled interface version.
The format of this string is subject to change in future versions and its contents should not be interpreted.
Identify client application info.
The string is one or more newline-delimited lines of optional info indicating engine name, engine version, engine plugin name, engine plugin version, engine editor. The order of the lines is not relevant. Individual lines are optional. A newline is not necessary at the end of the last line. Call after ovr_Initialize and before the first call to ovr_Create. Each value is limited to 20 characters. Key names such as 'EngineName:' 'EngineVersion:' do not count towards this limit.
Initializes LibOVR.
Initialize LibOVR for application usage. This includes finding and loading the LibOVRRT shared library. No LibOVR API functions, other than ovr_GetLastErrorInfo and ovr_Detect, can be called unless ovr_Initialize succeeds. A successful call to ovr_Initialize must be eventually followed by a call to ovr_Shutdown. ovr_Initialize calls are idempotent. Calling ovr_Initialize twice does not require two matching calls to ovr_Shutdown. If already initialized, the return value is ovr_Success.
LibOVRRT shared library search order:
Example code
Re-centers the sensor position and orientation.
This resets the (x,y,z) positional components and the yaw orientation component. The Roll and pitch orientation components are always determined by gravity and cannot be redefined. All future tracking will report values relative to this new reference position. If you are using ovrTrackerPoses then you will need to call ovr_GetTrackerPose after this, because the sensor position(s) will change as a result of this.
The headset cannot be facing vertically upward or downward but rather must be roughly level otherwise this function will fail with ovrError_InvalidHeadsetOrientation.
For more info, see the notes on each ovrTrackingOrigin enumeration to understand how recenter will vary slightly in its behavior based on the current ovrTrackingOrigin setting.
Requests boundary to be visible.
Resets the look and feel of the Boundary System to its default state.
Resets the accumulated stats reported in each ovrPerfStatsPerCompositorFrame back to zero.
Only the integer values such as HmdVsyncIndex, AppDroppedFrameCount etc. will be reset as the other fields such as AppMotionToPhotonLatency are independent timing values updated per-frame.
Writes or creates a boolean property.
If the property wasn't previously a boolean property, it is changed to a boolean property.
Sets the look and feel of the Boundary System.
Sets constant vibration (with specified frequency and amplitude) to a controller.
Note: ovr_SetControllerVibration cannot be used interchangeably with ovr_SubmitControllerVibration.
This method should be called periodically, vibration lasts for a maximum of 2.5 seconds.
Writes or creates a float property.
If the property wasn't previously a float property, it's changed to a float property.
Writes or creates a float array property.
Writes or creates an integer property.
If the property wasn't previously a boolean property, it is changed to an integer property.
Writes or creates a string property.
Strings are UTF8-encoded and null-terminated.
Sets the tracking origin type.
When the tracking origin is changed, all of the calls that either provide or accept ovrPosef will use the new tracking origin provided.
Shuts down LibOVR.
A successful call to ovr_Initialize must be eventually matched by a call to ovr_Shutdown. After calling ovr_Shutdown, no LibOVR functions can be called except ovr_GetLastErrorInfo or another ovr_Initialize. ovr_Shutdown invalidates all pointers, references, and created objects previously returned by LibOVR functions. The LibOVRRT shared library can be unloaded by ovr_Shutdown.
Submits a Haptics buffer (used for vibration) to Touch (only) controllers.
Note: ovr_SubmitControllerVibration cannot be used interchangeably with ovr_SetControllerVibration.
Submits layers for distortion and display.
ovr_SubmitFrame triggers distortion and processing which might happen asynchronously. The function will return when there is room in the submission queue and surfaces are available. Distortion might or might not have completed.
Example code
Tests collision/proximity of position tracked devices (e.g.
HMD and/or Touch) against the Boundary System. Note: this method is similar to ovr_BoundaryTestPoint but can be more precise as it may take into account device acceleration/momentum.
Tests collision/proximity of a 3D point against the Boundary System.
Writes a message string to the LibOVR tracing mechanism (if enabled).
This message will be passed back to the application via the ovrLogCallback if it was registered.