Simple type ovrHmd is used in ovrHmd_* calls.
Distortion capability bits reported by device. Used with ovrHmd_ConfigureRendering and ovrHmd_CreateDistortionMesh.
Specifies which eye is being used for rendering. This type explicitly does not include a third "NoStereo" option, as such is not required for an HMD-centered API.
HMD capability bits reported by device. i.e. it is not already owned by another application. rendering performance slightly (only if 'ExtendDesktop' is off). Support rendering without VSync for debugging. These flags are currently passed into the service. May change without notice.
Enumerates all HMD types that we support.
These types are used to hide platform-specific details when passing render device, OS, and texture data to the API.
Bit flags describing the current status of sensor tracking.
Tracking capability bits reported by the device. Used with ovrHmd_ConfigureTracking. Overrides the other flags. Indicates that the application doesn't care about tracking settings. This is the internal default before ovrHmd_ConfigureTracking is called.
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. Windows: SwapChain associated with this window will be displayed on the HMD. Specify 'destMirrorRect' in window coordinates to indicate an area of the render target output that will be mirrored from 'sourceRenderTargetRect'. Null pointers mean "full size". @note Source and dest mirror rects are not yet implemented.
Begins a frame, returning timing information. This should be called at the beginning of the game rendering loop (on the render thread). Pass 0 for the frame index if not using ovrHmd_GetFrameTiming.
Called at the beginning of the frame on the rendering thread. Pass frameIndex == 0 if ovrHmd_GetFrameTiming isn't being used. Otherwise, pass the same frame index as was used for GetFrameTiming on the main thread.
Configures rendering and fills in computed render parameters. This function can be called multiple times to change rendering settings. eyeRenderDescOut is a pointer to an array of two ovrEyeRenderDesc structs that are used to return complete rendering information for each eye.
All tracking interface functions are thread-safe, allowing tracking state to be sampled from different threads. ConfigureTracking starts sensor sampling, enabling specified capabilities, described by ovrTrackingCaps. - supportedTrackingCaps specifies support that is requested. The function will succeed even if these caps are not available (i.e. sensor or camera is unplugged). Support will automatically be enabled if such device is plugged in later. Software should check ovrTrackingState.StatusFlags for real-time status. - requiredTrackingCaps specify sensor capabilities required at the time of the call. If they are not available, the function will fail. Pass 0 if only specifying supportedTrackingCaps. - Pass 0 for both supportedTrackingCaps and requiredTrackingCaps to disable tracking.
Creates a handle to an HMD which doubles as a description structure. Index can [0 .. ovrHmd_Detect()-1]. Index mappings can cange after each ovrHmd_Detect call. If not null, then the returned handle must be freed with ovrHmd_Destroy.
Creates a 'fake' HMD used for debugging only. This is not tied to specific hardware, but may be used to debug some of the related rendering.
Generate distortion mesh per eye. Distortion capabilities will depend on 'distortionCaps' flags. Users should render using the appropriate shaders based on their settings. Distortion mesh data will be allocated and written into the ovrDistortionMesh data structure, which should be explicitly freed with ovrHmd_DestroyDistortionMesh. Users should call ovrHmd_GetRenderScaleAndOffset to get uvScale and Offset values for rendering. The function shouldn't fail unless theres is a configuration or memory error, in which case ovrDistortionMesh values will be set to null. This is the only function in the SDK reliant on eye relief, currently imported from profiles, or overriden here.
Used to free the distortion mesh allocated by ovrHmd_GenerateDistortionMesh. meshData elements are set to null and zeroes after the call.
Detects or re-detects HMDs and reports the total number detected. Users can get information about each HMD by calling ovrHmd_Create with an index.
Dismisses the HSW display if the warning is dismissible and the earliest dismissal time has occurred. Returns true if the display is valid and could be dismissed. The application should recognize that the HSW display is being displayed (via ovrhmd_GetHSWDisplayState) and if so then call this function when the appropriate user input to dismiss the warning occurs.
Ends a frame, submitting the rendered textures to the frame buffer. - RenderViewport within each eyeTexture can change per frame if necessary. - 'renderPose' will typically be the value returned from ovrHmd_GetEyePose, but can be different if a different head pose was used for rendering. - This may perform distortion and scaling internally, assuming is it not delegated to another thread. - Must be called on the same thread as BeginFrame. - *** This Function will call Present/SwapBuffers and potentially wait for GPU Sync ***.
Marks the end of client distortion rendered frame, tracking the necessary timing information. This function must be called immediately after Present/SwapBuffers + GPU sync. GPU sync is important before this call to reduce latency and ensure proper timing.
Get boolean property. Returns first element if property is a boolean array. Returns defaultValue if property doesn't exist.
Returns capability bits that are enabled at this time as described by ovrHmdCaps. Note that this value is different font ovrHmdDesc::HmdCaps, which describes what capabilities are available for that HMD.
Returns the predicted head pose to use when rendering the specified eye. - Must be called between ovrHmd_BeginFrameTiming and ovrHmd_EndFrameTiming. - If the pose is used for rendering the eye, it should be passed to ovrHmd_EndFrame.
Computes timewarp matrices used by distortion mesh shader, these are used to adjust for head orientation change since the last call to ovrHmd_GetEyePose when rendering this eye. The ovrDistortionVertex::TimeWarpFactor is used to blend between the matrices, usually representing two different sides of the screen. Must be called on the same thread as ovrHmd_BeginFrameTiming.
Get float property. Returns first element if property is a float array. Returns defaultValue if property doesn't exist.
Get float[] property. Returns the number of elements filled in, 0 if property doesn't exist. Maximum of arraySize elements will be written.
Calculates the recommended texture size for rendering a given eye within the HMD with a given FOV cone. Higher FOV will generally require larger textures to maintain quality. - pixelsPerDisplayPixel specifies the ratio of the number of render target pixels to display pixels at the center of distortion. 1.0 is the default value. Lower values can improve performance.
Thread-safe timing function for the main thread. Caller should increment frameIndex with every frame and pass the index where applicable to functions called on the rendering thread.
Returns the current state of the HSW display. If the application is doing the rendering of the HSW display then this function serves to indicate that the the warning should be currently displayed. If the application is using SDK-based eye rendering then the SDK by default automatically handles the drawing of the HSW display. An application that uses application-based eye rendering should use this function to know when to start drawing the HSW display itself and can optionally use it in conjunction with ovrhmd_DismissHSWDisplay as described below.
Get integer property. Returns first element if property is an integer array. Returns defaultValue if property doesn't exist.
Returns last error for HMD state. Returns null for no error. String is valid until next call or GetLastError or HMD is destroyed. Pass null hmd to get global errors (during create etc).
Returns non-null string once with latency test result, when it is available. Buffer is valid until next call.
Computes the distortion viewport, view adjust, and other rendering parameters for the specified eye. This can be used instead of ovrHmd_ConfigureRendering to do setup for client rendered distortion.
Computes updated 'uvScaleOffsetOut' to be used with a distortion if render target size or viewport changes after the fact. This can be used to adjust render size every frame if desired.
Get string property. Returns first element if property is a string array. Returns defaultValue if property doesn't exist. String memory is guaranteed to exist until next call to GetString or GetStringArray, or HMD is destroyed.
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. ovrHmd_GetEyePose relies on this internally. This may also be used for more refined timing of FrontBuffer rendering logic, etc.
Does latency test processing and returns 'TRUE' if specified rgb color should be used to clear the screen.
Re-centers the sensor orientation. Normally this will recenter the (x,y,z) translational components and the yaw component of orientation.
Initializes and resets frame time tracking. This is typically not necessary, but is helpful if game changes vsync state or video mode. vsync is assumed to be on if this isn't called. Resets internal frame index to the specified number.
Modify bool property; false if property doesn't exist or is readonly.
Modifies capability bits described by ovrHmdCaps that can be modified, such as ovrHmd_LowPersistance.
Modify float property; false if property doesn't exist or is readonly.
Modify float[] property; false if property doesn't exist or is readonly.
Modify integer property; false if property doesn't exist or is readonly.
Set string property
Used for 2D rendering, Y is down orthoScale = 1.0f / pixelsPerTanAngleAtCenter orthoDistance = distance from camera, such as 0.8m
Used to generate projection from ovrEyeDesc::Fov.
Returns global, absolute high-resolution time in seconds. This is the same value as used in sensor messages.
Returns version string representing libOVR version. Static, so string remains valid for app lifespan
Initializes all Oculus functionality.
Shuts down all Oculus functionality.
Waits until the specified absolute time.
Describes a full set of distortion mesh data, filled in by ovrHmd_CreateDistortionMesh. Contents of this data structure, if not null, should be freed by ovrHmd_DestroyDistortionMesh.
Describes a vertex used by the distortion mesh. This is intended to be converted into the engine-specific format. Some fields may be unused based on the ovrDistortionCaps flags selected. TexG and TexB, for example, are not used if chromatic correction is not requested.
Rendering information for each eye. Computed by either ovrHmd_ConfigureRendering() or ovrHmd_GetRenderDesc() based on the specified FOV. Note that the rendering viewport is not included here as it can be specified separately and modified per frame through: (a) ovrHmd_GetRenderScaleAndOffset in the case of client rendered distortion, or (b) passing different values via ovrTexture in the case of SDK rendered distortion.
Field Of View (FOV) in tangent of the angle units. As an example, for a standard 90 degree vertical FOV, we would have: { UpTan = tan(90 degrees / 2), DownTan = tan(90 degrees / 2) }. The tangent of the angle between the viewing vector and the top edge of the field of view. The tangent of the angle between the viewing vector and the bottom edge of the field of view. The tangent of the angle between the viewing vector and the left edge of the field of view. The tangent of the angle between the viewing vector and the right edge of the field of view.
Frame timing data reported by ovrHmd_BeginFrameTiming() or ovrHmd_BeginFrame(). The amount of time that has passed since the previous frame's ThisFrameSeconds value (usable for movement scaling). This will be clamped to no more than 0.1 seconds to prevent excessive movement after pauses due to loading or initialization. It is generally expected that the following holds: ThisFrameSeconds < TimewarpPointSeconds < NextFrameSeconds < EyeScanoutSeconds[EyeOrder[0]] <= ScanoutMidpointSeconds <= EyeScanoutSeconds[EyeOrder[1]]. Absolute time value when rendering of this frame began or is expected to begin. Generally equal to NextFrameSeconds of the previous frame. Can be used for animation timing. Absolute point when IMU expects to be sampled for this frame. Absolute time when frame Present followed by GPU Flush will finish and the next frame begins. Time when when half of the screen will be scanned out. Can be passed as an absolute time to ovrHmd_GetTrackingState() to get the predicted general orientation. Timing points when each eye will be scanned out to display. Used when rendering each eye.
Used by ovrhmd_GetHSWDisplayState to report the current display state. If true then the warning should be currently visible and the following variables have meaning. Else there is no warning being displayed for this application on the given HMD.
This is a complete descriptor of the HMD. Internal handle of this HMD. This HMD's type. Name string describing the product: "Oculus Rift DK1", etc. HID Vendor and ProductId of the device. Sensor (and display) serial number. Sensor firmware version. External tracking camera frustum dimensions (if present). Capability bits described by ovrHmdCaps. Capability bits described by ovrTrackingCaps. Capability bits described by ovrDistortionCaps. These define the recommended and maximum optical FOVs for the HMD. Preferred eye rendering order for best performance. Can help reduce latency on sideways-scanned screens. Resolution of the full HMD screen (both eyes) in pixels. Location of the application window on the desktop (or 0,0). Display that the HMD should present on. TBD: It may be good to remove this information relying on WindowPos instead. Ultimately, we may need to come up with a more convenient alternative, such as API-specific functions that return adapter, or something that will work with our monitor driver. Windows: (e.g. "\\\\.\\DISPLAY3", can be used in EnumDisplaySettings/CreateDC). MacOS:
A 4x4 matrix with float elements.
A full pose (rigid body) configuration with first and second derivatives.
Position and orientation together.
A quaternion rotation.
A 2D rectangle with a position and size. All components are integers.
Platform-independent part of rendering API-configuration data. It is a part of ovrRenderAPIConfig, passed to ovrHmd_Configure.
Contains platform-specific information for rendering.
Specifies a reading we can query from the sensor.
A 2D size with integer components.
Platform-independent part of the eye texture descriptor. It is a part of ovrTexture, passed to ovrHmd_EndFrame. If RenderViewport is all zeros then the full texture will be used.
Contains platform-specific information about a texture.
Tracking state at a given absolute time (describes predicted HMD pose etc). Returned by ovrHmd_GetTrackingState. Predicted head pose (and derivatives) at the requested absolute time. The look-ahead interval is equal to (HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds). Current pose of the external camera (if present). This pose includes camera tilt (roll and pitch). For a leveled coordinate system use LeveledCameraPose. Camera frame aligned with gravity. This value includes position and yaw of the camera, but not roll and pitch. It can be used as a reference point to render real-world objects in the correct location. The most recent sensor data received from the HMD. Tracking status described by ovrStatusBits.
A 2D vector with float components.
A 2D vector with integer components.
A 3D vector with float components.