Archived Documentation

This version of the guide is out of date. Click here for the latest version.

Oculus API Changes

This section describes API changes for each version release.

Changes Since Release 0.2

The Oculus API has been significantly redesigned since the 0.2.5 release, with the goals of improving ease of use, correctness and supporting a new driver model.

The following is the summary of changes in the API:

  • All of the HMD and sensor interfaces have been organized into a C API. This makes it easy to bind from other languages.
  • The new Oculus API introduces two distinct approaches to rendering distortion: SDK Rendered and Client Rendered. As before, the application is expected to render stereo scenes onto one or more render targets. With the SDK rendered approach, the Oculus SDK then takes care of distortion rendering, frame present, and timing within the SDK. This means that developers don’t need to setup pixel and vertex shaders or worry about the details of distortion rendering, they simply provide the device and texture pointers to the SDK. In client rendered mode, distortion rendering is handled by the application as with previous versions of the SDK. SDK Rendering is the preferred approach for future versions of the SDK.

  • The method of rendering distortion in client rendered mode is now mesh based. The SDK returns a mesh which includes vertices and UV coordinates which are then used to warp the source render target image to the final buffer. Mesh based distortion is more efficient and flexible than pixel shader approaches.

  • The Oculus SDK now keeps track of game frame timing and uses this information to accurately predict orientation and motion.

  • A new technique called Timewarp is introduced to reduce motion-to-photon latency. This technique re-projects the scene to a more recently measured orientation during the distortion rendering phase.

The table on the next page briefly summarizes differences between the 0.2.5 and 0.4 API versions.

Functionality0.2 SDK APIs0.4 SDK C APIs
InitializationOVR::System::Init, DeviceManager, HMDDevice, HMDInfo.ovr_Initialize, ovrHmd_Create, ovrHmd handle and ovrHmdDesc.
Sensor InteractionOVR::SensorFusion class, with GetOrientation returning Quatf. Prediction amounts are specified manually relative to the current time.ovrHmd_ConfigureTracking, ovrHmd_GetTrackingState returning ovrTrackingState. ovrHmd_GetEyePose returns head pose based on correct timing.
Rendering SetupUtil::Render::StereoConfig helper class creating StereoEyeParams, or manual setup based on members of HMDInfo.ovrHmd_ConfigureRendering populates ovrEyeRenderDesc based on the field of view. Alternatively, ovrHmd_GetRenderDesc supports rendering setup for client distortion rendering.
Distortion RenderingApp-provided pixel shader based on distortion coefficients.Client rendered: based on the distortion mesh returned by ovrHmd_CreateDistortionMesh. (or) SDK rendered: done automatically in ovrHmd_EndFrame.
Frame TimingManual timing with current-time relative prediction.Frame timing is tied to vsync with absolute values reported by ovrHmd_BeginFrame or ovr_BeginFrameTiming.

Changes Since Release 0.3

A number of changes were made to the API since the 0.3.2 Preview release.

These are summarized as follows:

  • Removed the method ovrHmd_GetDesc. The ovrHmd handle is now a pointer to a ovrHmdDesc struct.
  • The sensor interface has been simplified. Your application should now call ovrHmd_ConfigureTracking at initialization and ovrHmd_GetTrackingState or ovrHmd_GetEyePose to get the head pose.
  • ovrHmd_BeginEyeRender and ovrHmd_EndEyeRender have been removed. You should now use ovrHmd_GetEyePose to determine predicted head pose when rendering each eye. Render poses and ovrTexture info is now passed into ovrHmd_EndFrame rather than ovrHmd_EndEyeRender.
  • ovrSensorState struct is now ovrTrackingState. The predicted pose Predicted is now named HeadPose. CameraPose and LeveledCameraPose have been added. Raw sensor data can be obtained through RawSensorData.
  • ovrSensorDesc struct has been merged into ovrHmdDesc.
  • Addition of ovrHmd_AttachToWindow. This is a platform specific function to specify the application window whose output will be displayed on the HMD. Only used if the ovrHmdCap_ExtendDesktop flag is false.
  • Addition of ovr_GetVersionString. Returns a string representing the libOVR version.

There have also been a number of minor changes:

  • Renamed ovrSensorCaps struct to ovrTrackingCaps.
  • Addition of ovrHmdCaps::ovrHmdCap_Captured flag. Set to true if the application captured ownership of the HMD.
  • Addition of ovrHmdCaps::ovrHmdCap_ExtendDesktop flag. The display driver is in compatibility mode (read only).
  • Addition of ovrHmdCaps::ovrHmdCap_NoMirrorToWindow flag. Disables mirroring of HMD output to the window. This may improve rendering performance slightly (only if ’Extend-Desktop’ is off).
  • Addition of ovrHmdCaps::ovrHmdCap_DisplayOff flag. Turns off HMD screen and output (only if ’ExtendDesktop’ is off).
  • Removed ovrHmdCaps::ovrHmdCap_LatencyTest flag. Was used to indicate support of pixel reading for continuous latency testing.
  • AdditionofovrDistortionCaps::ovrDistortionCap_Overdriveflag. Overdrivebrightness transitions to reduce artifacts on DK2 displays.
  • Addition of ovrStatusBits::ovrStatus_CameraPoseTracked flag. Indicates that the camera pose is successfully calibrated.