Module ovr

oculus - Nim bindings for the Oculus VR SDK.

This file is part of the Nim I/O package collection. See the file LICENSE included in this distribution for licensing details. GitHub pull requests are encouraged. (c) 2015 Headcrash Industries LLC.

Basic steps to use the API

Setup:

  1. ovrInitialize ovrHMD hmd = ovrHmdCreate (0)
  2. Use hmd members and ovrHmdGetFovTextureSize to determine graphics configuration.
  3. Call ovrHmdConfigureTracking to configure and initialize tracking.
  4. Call ovrHmdConfigureRendering to setup graphics for SDK rendering, which is the preferred approach. Please refer to "Client Distorton Rendering" below if you prefer to do that instead.
  5. If the ovrHmdCapExtendDesktop flag is not set, then use ovrHmdAttachToWindow to associate the relevant application window with the HMD.
  6. Allocate render target textures as needed.

Game Loop:

Shutdown:

Types

OvrBool = cchar
  Source 
OvrVector2i = object
  x*: cint
  y*: cint
A 2D vector with integer components.   Source 
OvrSizei = object
  w*: cint
  h*: cint
A 2D size with integer components.   Source 
OvrRecti = object
  Pos*: OvrVector2i
  Size*: OvrSizei
A 2D rectangle with a position and size. All components are integers.   Source 
OvrQuatf = object
  x*: cfloat
  y*: cfloat
  z*: cfloat
  w*: cfloat
A quaternion rotation.   Source 
OvrVector3f = object
  x*: cfloat
  y*: cfloat
  z*: cfloat
A 3D vector with float components.   Source 
OvrMatrix4f = object
  m*: array[4, array[4, cfloat]]
A 4x4 matrix with float elements.   Source 
OvrPosef = object
  orientation*: OvrQuatf
  position*: OvrVector3f
Position and orientation together.   Source 
OvrPoseStatef = object
  thePose*: OvrPosef           ## The body's position and orientation.
  angularVelocity*: OvrVector3f ## The body's angular velocity in radians
                              ## per second.
  linearVelocity*: OvrVector3f ## The body's velocity in meters per second.
  angularAcceleration*: OvrVector3f ## The body's angular acceleration in
                                  ## radians per second per second.
  linearAcceleration*: OvrVector3f ## The body's acceleration in meters per
                                 ## second per second.
  timeInSeconds*: cdouble      ## Absolute time of this state sample.
A full pose (rigid body) configuration with first and second derivatives.   Source 
OvrFovPort = object
  upTan*: cfloat ## The tangent of the angle between the viewing vector and
               ## the top edge of the field of view.
  downTan*: cfloat ## The tangent of the angle between the viewing vector
                 ## and the bottom edge of the field of view.
  leftTan*: cfloat ## The tangent of the angle between the viewing vector
                 ## and the left edge of the field of view.
  rightTan*: cfloat ## The tangent of the angle between the viewing vector
                  ## and the right edge of the field of view.
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) }

  Source 
OvrHmdType = enum
  none = 0,                     ## No device type.
  dK1 = 3,                      ## Oculus DevKit 1.
  dKHD = 4,                     ## Oculus DevKit HD.
  dK2 = 6,                      ## Oculus DevKit 2.
  other                       ## Unspecified device type.
  Source 
OvrEyeType = enum
  left = 0, right = 1, count = 2
  Source 
OvrHmdStruct = object
Dummy object for internal HMD handles.   Source 
OvrHmdDesc = object
  handle*: ptr OvrHmdStruct     ## Internal handle of this HMD
  hmdType*: OvrHmdType         ## This HMD's type
  productName*: cstring        ## Name string describing the product
  manufacturer*: cstring       ## Name string describing the manufacturer
  vendorId*: cshort            ## HID Vendor of the device
  productId*: cshort           ## ProductId of the device
  serialNumber*: array[24, char] ## Sensor (and display) serial number
  firmwareMajor*: cshort       ## Sensor firmware version (major)
  firmwareMinor*: cshort       ## Sensor firmware version (minor)
  cameraFrustumHFovInRadians*: cfloat ## External tracking camera frustum
                                    ## dimensions (if present)
  cameraFrustumVFovInRadians*: cfloat ## External tracking camera frustum
                                    ## dimensions (if present)
  cameraFrustumNearZInMeters*: cfloat ## External tracking camera frustum
                                    ## dimensions (if present)
  cameraFrustumFarZInMeters*: cfloat ## External tracking camera frustum
                                   ## dimensions (if present)
  hmdCaps*: cuint              ## Capability bits described by ovrHmdCaps
  trackingCaps*: cuint         ## Capability bits described by ovrTrackingCaps
  distortionCaps*: cuint       ## Capability bits described by ovrDistortionCaps
  defaultEyeFov*: array[OvrEyeType.count, OvrFovPort] ## Recommended optical
                                                   ## FOVs for the HMD
  maxEyeFov*: array[OvrEyeType.count, OvrFovPort] ## Maximum optical FOVs for
                                               ## the HMD
  eyeRenderOrder*: array[OvrEyeType.count, OvrEyeType] ## Preferred eye
                                                    ## rendering order for best performance. Can help reduce latency on
                                                    ## sideways-scanned screens
  resolution*: OvrSizei        ## Resolution of the full HMD screen (both eyes) in
                      ## pixels
  windowsPos*: OvrVector2i     ## Location of the application window on the
                         ## desktop (or 0,0)
  displayDeviceName*: cstring  ## Display that the HMD should present on
  displayId*: cint             ## Display identifier (Mac OSX only)
This is a complete descriptor of the HMD.   Source 
OvrHmd = ptr OvrHmdDesc
Pointer to HMD descriptor objects.   Source 
OvrStatusBits = enum
  orientationTracked = 0x00000001, ## Orientation is currently
                                ## tracked (in use)
  positionTracked = 0x00000002, ## Position is currently tracked
                             ## (false if out of range)
  cameraPoseTracked = 0x00000004, ## Camera pose is currently
                               ## tracked
  positionConnected = 0x00000020, ## Position tracking hardware is
                               ## connected
  hmdConnected = 0x00000080     ## HMD Display is available and
                         ## connected
  Source 
OvrSensorData = object
  accelerometer*: OvrVector3f  ## Acceleration reading in m/s^2.
  gyro*: OvrVector3f           ## Rotation rate in rad/s.
  magnetometer*: OvrVector3f   ## Magnetic field in Gauss.
  temperature*: cfloat         ## Temperature of the sensor in degrees Celsius.
  timeInSeconds*: cfloat       ## Time when the reported IMU reading took place, in
                       ## seconds.
Specifies a reading we can query from the sensor.   Source 
OvrTrackingState = object
  headPose*: OvrPoseStatef ## Predicted head pose (and derivatives) at the
                         ## requested absolute time. The look-ahead interval is
                         ## `(HeadPose.TimeInSeconds - RawSensorData.TimeInSeconds)`.
  cameraPose*: OvrPosef ## Current pose of the external camera (if present).
                      ## This pose includes camera tilt (roll and pitch). For a leveled
                      ## coordinate system use
                      ## `LeveledCameraPose <#OvrTrackingState>`_.
  leveledCameraPose*: OvrPosef ## 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.
  rawSensorData*: OvrSensorData ## The most recent sensor data received
                              ## from the HMD.
  statusFlags*: cuint          ## Tracking status described by
                    ## `OvrStatusBits <#OvrStatusBits>`_.
  lastVisionProcessingTime*: cdouble ## Measures the time from receiving
                                   ## the camera frame until vision CPU processing completes.
  lastVisionFrameLatency*: cdouble ## Measures the time from exposure until
                                 ## the pose is available for the frame, including processing time.
  lastCameraFrameCounter*: cuint ## Tag the vision processing results to a
                               ## certain frame counter number.
Tracking state at a given absolute time (describes predicted HMD pose etc). Returned by ovrHmdGetTrackingState.   Source 
OvrFrameTiming = object
  deltaSeconds*: cfloat ## The amount of time that has passed since the
                      ## previous frame's `ThisFrameSeconds <#OvrFrameTiming>`_ 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]]`.
  thisFrameSeconds*: cdouble ## 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.
  timewarpPointSeconds*: cdouble ## Absolute point when IMU expects to be
                               ## sampled for this frame.
  nextFrameSeconds*: cdouble   ## Absolute time when frame Present followed by
                           ## GPU Flush will finish and the next frame begins.
  scanoutMidpointSeconds*: cdouble ## Time when half of the screen will be
                                 ## scanned out. Can be passed as an absolute time to
                                 ## `ovrHmdGetTrackingState <#ovrHmdGetTrackingState>`_ to get the
                                 ## predicted general orientation.
  eyeScanoutSeconds*: array[2, cdouble] ## Timing points when each eye will be
                                     ## scanned out to display. Used when rendering each eye.
Frame timing data reported by ovrHmdBeginFrameTiming or ovrHmdBeginFrame.   Source 
OvrEyeRenderDesc = object
  eye*: OvrEyeType             ## The eye index this instance corresponds to
  fov*: OvrFovPort             ## The field of view
  distortedViewport*: OvrRecti ## Distortion viewport
  pixelsPerTanAngleAtCenter*: OvrVector2f ## How many display pixels will fit
                                        ## in `tan(angle) = 1`
  hmdToEyeViewOffset*: OvrVector3f ## Translation to be applied to view matrix
                                 ## for each eye offset
Rendering information for each eye. Computed by either ovrHmdConfigureRendering or ovrHmdGetRenderDesc 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:   Source 
OvrRenderAPIType = enum
  none, openGl, androidGles, d3d9, d3d10, d3d11, count
  Source 
OvrRenderAPIConfigHeader = object
  api*: OvrRenderAPIType
  backBufferSize*: OvrSizei
  multisample*: cint
Platform-independent part of rendering API-configuration data. It is a part of OvrRenderAPIConfig, passed to ovrHmdConfigureXXX.   Source 
OvrRenderAPIConfig = object
  header*: OvrRenderAPIConfigHeader
  platformData*: array[8, ptr cuint]
Contains platform-specific information for rendering.   Source 
OvrTextureHeader = object
  api*: OvrRenderAPIType
  textureSize*: OvrSizei
  renderViewport*: OvrRecti
  pad0*: cuint
Platform-independent part of the eye texture descriptor. It is a part of OvrTexture, passed to ovrHmdEndFrame. If RenderViewport is all zeros then the full texture will be used.   Source 
OvrTexture = object
  header*: OvrTextureHeader
  platformData*: array[8, ptr cuint]
  Source 
OvrDistortionVertex = object
  screenPosNDC*: OvrVector2f   ## [-1,+1],[-1,+1] over the entire framebuffer.
  timeWarpFactor*: cfloat      ## Lerp factor between time-warp matrices. Can be
                        ## encoded in Pos.z.
  vignetteFactor*: cfloat      ## Vignette fade factor. Can be encoded in Pos.w.
  tanEyeAnglesR*: OvrVector2f  ## The tangents of the horizontal and vertical
                            ## eye angles for the red channel.
  tanEyeAnglesG*: OvrVector2f  ## The tangents of the horizontal and vertical
                            ## eye angles for the  green channel.
  tanEyeAnglesB*: OvrVector2f  ## The tangents of the horizontal and vertical
                            ## eye angles for the blue channel.
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.   Source 
OvrDistortionMesh = object
  pVertexData*: ptr OvrDistortionVertex ## The distortion vertices
                                     ## representing each point in the mesh.
  pIndexData*: ptr cushort      ## Indices for connecting the mesh vertices into
                        ## polygons.
  vertexCount*: cuint          ## The number of vertices in the mesh.
  indexCount*: cuint           ## The number of indices in the mesh.
Describes a full set of distortion mesh data, filled in by ovrHmdCreateDistortionMesh. Contents of this data structure, if not nil, should be freed by ovrHmdDestroyDistortionMesh.   Source 
ovrHSWDisplayState = object
  displayed*: OvrBool ## 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.
                    ## ``true`` if the Health & Safety Warning is currently displayed.
  startTime*: cdouble ## Absolute time when the warning was first displayed.
                    ## See `ovrGetTimeInSeconds <#ovrGetTimeInSeconds>`_
  dismissibleTime*: cdouble    ## Earliest absolute time when the warning can
                          ## be dismissed. May be a time in the past.
Used by ovrhmd_GetHSWDisplayState to report the current display state.   Source

Consts

ovrHmdCapPresent: cuint = 0x00000001
The HMD is plugged in and detected by the system.   Source 
ovrHmdCapAvailable: cuint = 0x00000002
The HMD and its sensor are available for ownership use, i.e. it is not already owned by another application.   Source 
ovrHmdCapCaptured: cuint = 0x00000004
Set to 'true' if we captured ownership of this HMD.   Source 
ovrHmdCapExtendDesktop: cuint = 0x00000008
(read only) Means the display driver is in compatibility mode.   Source 
ovrHmdCapDisplayOff: cuint = 0x00000040
Turns off HMD screen and output (only if 'ExtendDesktop' is off).   Source 
ovrHmdCapLowPersistence: cuint = 0x00000080
HMD supports low persistence mode.   Source 
ovrHmdCapDynamicPrediction: cuint = 0x00000200
Adjust prediction dynamically based on internally measured latency.   Source 
ovrHmdCapDirectPentile: cuint = 0x00000400
Write directly in pentile color mapping format   Source 
ovrHmdCapNoVSync: cuint = 0x00001000
Support rendering without VSync for debugging.   Source 
ovrHmdCapNoMirrorToWindow: cuint = 0x00002000
Disables mirroring of HMD output to the window. This may improve rendering performance slightly (only if 'ExtendDesktop' is off).   Source 
ovrHmdCapService_Mask: cuint = 0x000022F0
These flags are currently passed into the service. May change without notice.   Source 
ovrHmdCapWritable_Mask: cuint = 0x000032F0
These bits can be modified by ovrHmdSetEnabledCaps.   Source 
ovrTrackingCapOrientation: cuint = 0x00000010
Supports orientation tracking (IMU).   Source 
ovrTrackingCapMagYawCorrection: cuint = 0x00000020
Supports yaw drift correction via a magnetometer or other means.   Source 
ovrTrackingCapPosition: cuint = 0x00000040
Supports positional tracking.   Source 
ovrTrackingCapIdle: cuint = 0x00000100
Overrides the other flags. Indicates that the application doesn't care about tracking settings. This is the internal default before ovrHmdConfigureTracking <#ovrHmdConfigureTracking> is called.   Source 
ovrDistortionCapChromatic: cuint = 0x00000001
Supports chromatic aberration correction   Source 
ovrDistortionCapTimeWarp: cuint = 0x00000002
Supports timewarp   Source 
ovrDistortionCapVignette: cuint = 0x00000008
Supports vignetting around the edges of the view   Source 
ovrDistortionCapNoRestore: cuint = 0x00000010
Do not save and restore the graphics and compute state when rendering distortion   Source 
ovrDistortionCapFlipInput: cuint = 0x00000020
Flip the vertical texture coordinate of input images   Source 
ovrDistortionCapSRGB: cuint = 0x00000040
Assume input images are in sRGB gamma-corrected color space   Source 
ovrDistortionCapOverdrive: cuint = 0x00000080
Overdrive brightness transitions to reduce artifacts on DK2+ displays   Source 
ovrDistortionCapHqDistortion: cuint = 0x00000100
High-quality sampling of distortion buffer for anti-aliasing   Source 
ovrDistortionCapLinuxDevFullscreen: cuint = 0x00000200
Indicates window is fullscreen on a device when set. The SDK will automatically apply distortion mesh rotation if needed   Source 
ovrDistortionCapComputeShader: cuint = 0x00000400
Using compute shader (DX11+ only)   Source 
ovrDistortionCapProfileNoTimewarpSpinWaits: cuint = 0x00010000
Use when profiling with timewarp to remove false positives   Source 
OVR_MAJOR_VERSION = 0
  Source 
OVR_MINOR_VERSION = 4
  Source 
OVR_BUILD_VERSION = 4
  Source 
OVR_VERSION_STRING = "0.4.4"
  Source 
OVR_DK2_LATEST_FIRMWARE_MAJOR_VERSION = 2
  Source 
OVR_DK2_LATEST_FIRMWARE_MINOR_VERSION = 12
  Source

Procs

proc ovrInitializeRenderingShim(): OvrBool {.cdecl, dynlib: dllname,
    importc: "ovr_InitializeRenderingShim".}
Initialize the rendering shim appart from everything else in LibOVR.
result
  • true on success
  • false on failure

This may be helpful if the application prefers to avoid creating any OVR resources (allocations, service connections, etc) at this point. Does not bring up anything within LibOVR except the necessary hooks to enable the Direct-to-Rift functionality.

Either ovrInitializeRenderingShim or ovrInitialize must be called before any Direct3D or OpenGL initilization is done by application (creating devices, etc). ovrInitialize must still be called after to use the rest of LibOVR APIs.

  Source 
proc ovrInitialize(): OvrBool {.cdecl, dynlib: dllname, importc: "ovr_Initialize".}
Initialize all Oculus functionality.
result
  • true on success
  • false on failure

Library init/shutdown, must be called around all other OVR code. No other functions calls besides ovrInitializeRenderingShim are allowed before ovrInitialize succeeds or after ovrShutdown.

  Source 
proc ovrShutdown() {.cdecl, dynlib: dllname, importc: "ovr_Shutdown".}
Shut down all Oculus functionality.   Source 
proc ovrGetVersionString(): cstring {.cdecl, dynlib: dllname,
                                   importc: "ovr_GetVersionString".}
Get the version of libOVR.
result
  • version string representing libOVR version

The returned string is static and remains valid for app lifespan.

  Source 
proc ovrHmdDetect(): cint {.cdecl, dynlib: dllname, importc: "ovrHmd_Detect".}
Detect or re-detects HMDs and reports the total number detected.
result
  • Number of connected head-mounted displays

Users can get information about each HMD by calling ovrHmdCreate with an index.

  Source 
proc ovrHmdCreate(index: cint): OvrHmd {.cdecl, dynlib: dllname,
                                     importc: "ovrHmd_Create".}
Create a handle to an HMD which doubles as a description structure.
index
Index number of the HDM to create
result
  • OvrHmd object on success
  • nil on failure

Index can be [0..(ovrHmdDetect - 1)]. Index mappings can cange after each ovrHmdDetect call. If not nil, then the returned handle must be freed with ovrHmdDestroy.

  Source 
proc ovrHmdDestroy(hmd: OvrHmd) {.cdecl, dynlib: dllname, importc: "ovrHmd_Destroy".}
Destroy a handle to an HMD.
hmd
Handle to a head-mounted display
  Source 
proc ovrHmdCreateDebug(`type`: OvrHmdType): OvrHmd {.cdecl, dynlib: dllname,
    importc: "ovrHmd_CreateDebug".}
Create a fake HMD used for debugging only.
type
The type of HMD to create.
result
  • HMD object on success
  • nil on failure

This is not tied to specific hardware, but may be used to debug some of the related rendering.

  Source 
proc ovrHmdGetLastError(hmd: OvrHmd): cstring {.cdecl, dynlib: dllname,
    importc: "ovrHmd_GetLastError".}
Returns last error for HMD state.
hmd
Handle to a head-mounted display
result
  • error string
  • nil for no error.

String is valid until next call to ovrHmdGetLastError or HMD is destroyed. Pass nil hmd to get global errors (during create etc).

  Source 
proc ovrHmdAttachToWindow(hmd: OvrHmd; window: pointer; destMirrorRect: ptr OvrRecti;
                         sourceRenderTargetRect: ptr OvrRecti): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_AttachToWindow".}
Platform specific function to specify the application window whose output will be displayed on the HMD.
hmd
Handle to a head-mounted display
window
The window to attach to
destMirrorRect
(see below)
sourceRenderTargetRect
(see below)
result
  • true on success
  • false otherwise

Only used if the ovrHmdCapExtendDesktop 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. nil pointers mean "full size".

Note: Source and dest mirror rects are not yet implemented.

  Source 
proc ovrHmdGetEnabledCaps(hmd: OvrHmd): cuint {.cdecl, dynlib: dllname,
    importc: "ovrHmd_GetEnabledCaps".}
Gets the capability bits that are enabled at this time as described by ovrHmdCapXXX flags.
hmd
Handle to a head-mounted display
result
Bit mask of enabled capabilities

Note that this value is different font OvrHmdDesc.HmdCaps, which describes what capabilities are available for that HMD.

  Source 
proc ovrHmdSetEnabledCaps(hmd: OvrHmd; hmdCaps: cuint) {.cdecl, dynlib: dllname,
    importc: "ovrHmd_SetEnabledCaps".}
Modifies capability bits described by ovrHmdCapXXX that can be modified.
hmd
Handle to a head-mounted display
hmdCaps
Bit mask of capabilities to enable
  Source 
proc ovrHmdConfigureTracking(hmd: OvrHmd; supportedTrackingCaps: cuint;
                            requiredTrackingCaps: cuint): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_ConfigureTracking".}
ConfigureTracking starts sensor sampling, enabling specified capabilities, described by ovrTrackingCaps.
hmd
Handle to a head-mounted display
supportedTrackingCaps
(see below)
result
  • true on success
  • false on failure

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 <#OvrTrackingState> 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.

  Source 
proc ovrHmdRecenterPose(hmd: OvrHmd) {.cdecl, dynlib: dllname,
                                    importc: "ovrHmd_RecenterPose".}
Re-centers the sensor orientation.
hmd
Handle to a head-mounted display

Normally this will recenter the (x,y,z) translational components and the yaw component of orientation.

  Source 
proc ovrHmdGetTrackingState(hmd: OvrHmd; absTime: cdouble): OvrTrackingState {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetTrackingState".}
Returns tracking state reading based on the specified absolute system time.
hmd
Handle to a head-mounted display
absTime
(see below)

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. ovrHmdGetEyePoses relies on this function internally. This may also be used for more refined timing of FrontBuffer rendering logic, etc.

  Source 
proc ovrHmdGetFovTextureSize(hmd: OvrHmd; eye: OvrEyeType; fov: OvrFovPort;
                            pixelsPerDisplayPixel: cfloat): OvrSizei {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetFovTextureSize".}
Calculates the recommended texture size for rendering a given eye within the HMD with a given FOV cone.
hmd
Handle to a head-mounted display
eye
?
fov
?
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
result
Texture size

Higher FOV will generally require larger textures to maintain quality.

  Source 
proc ovrHmdConfigureRendering(hmd: OvrHmd; apiConfig: ptr OvrRenderAPIConfig;
                             distortionCaps: cuint;
                             eyeFovIn: array[2, OvrFovPort];
                             eyeRenderDescOut: array[2, OvrEyeRenderDesc]): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_ConfigureRendering".}
Configures rendering and fills in computed render parameters.
hmd
Handle to a head-mounted display
apiConfig
Provides D3D/OpenGL specific parameters. Pass nil to shut down rendering and release all resources
distortionCaps
Desired distortion settings
eyeFovIn
?
eyeRenderDescOut
Pointer to an array of two OvrEyeRenderDesc structs that are used to return complete rendering information for each eye
result
  • true on success
  • false otherwise

This function can be called multiple times to change rendering settings.

  Source 
proc ovrHmdBeginFrame(hmd: OvrHmd; frameIndex: cuint): OvrFrameTiming {.cdecl,
    dynlib: dllname, importc: "ovrHmd_BeginFrame".}
Begins a frame, returning timing information.
hmd
Handle to a head-mounted display
frameIndex
?

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 ovrHmdGetFrameTiming.

  Source 
proc ovrHmdEndFrame(hmd: OvrHmd; renderPose: array[2, OvrPosef];
                   eyeTexture: array[2, OvrTexture]) {.cdecl, dynlib: dllname,
    importc: "ovrHmd_EndFrame".}
Ends a frame, submitting the rendered textures to the frame buffer.
hmd
Handle to a head-mounted display
renderPose
(see below)

eyeTexture

  • RenderViewport within each eyeTexture can change per frame if necessary.
  • renderPose will typically be the value returned from ovrHmdGetEyePoses or ovrHmdGetHmdPosePerEye 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 ovrHmdBeginFrame.

This cunction will call Present/SwapBuffers and potentially wait for GPU Sync.

  Source 
proc ovrHmdGetEyePoses(hmd: OvrHmd; frameIndex: cuint;
                      hmdToEyeViewOffset: array[2, OvrVector3f];
                      outEyePoses: array[2, OvrPosef];
                      outHmdTrackingState: ptr OvrTrackingState) {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetEyePoses".}

Returns predicted head pose in outHmdTrackingState and offset eye poses in outEyePoses as an atomic operation.

hmd
Handle to a head-mounted display
frameIndex
(see below)
hmdToEyeViewOffset
(see below)
outEyePoses
(see below)
outHmdTrackingState
(see below)

Caller need not worry about applying hmdToEyeViewOffset to the returned outEyePoses variables.

  • Thread-safe function where caller should increment frameIndex with every frame and pass the index where applicable to functions called on the rendering thread.
  • hmdToEyeViewOffset[2] can be OvrEyeRenderDesc.HmdToEyeViewOffset returned from ovrHmdConfigureRendering or ovrHmdGetRenderDesc. For monoscopic rendering, use a vector that is the average of the two vectors for both eyes.
  • If frameIndex is not being used, pass in 0.
  • Assuming outEyePoses are used for rendering, it should be passed into ovrHmdEndFrame.
  • If called doesn't need outHmdTrackingState, it can be nil

  Source 
proc ovrHmdGetHmdPosePerEye(hmd: OvrHmd; eye: OvrEyeType): OvrPosef {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetHmdPosePerEye".}
Function was previously called ovrHmdGetEyePose
hmd
Handle to a head-mounted display
eye
(see below)
result
The predicted head pose to use when rendering the specified eye
- Important: Caller must apply HmdToEyeViewOffset before using
OvrPosef for rendering
- Must be called between
ovrHmdBeginFrameTiming and ovrHmdEndFrameTiming
- If the pose is used for rendering the eye, it should be passed to
ovrHmdEndFrame.
  • Parameter eye is used for prediction timing only
  Source 
proc ovrHmdGetRenderDesc(hmd: OvrHmd; eyeType: OvrEyeType; fov: OvrFovPort): OvrEyeRenderDesc {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetRenderDesc".}
Compute the distortion viewport, view adjust, and other rendering parameters for the specified eye.
hmd
Handle to a head-mounted display
eyeType
?
fov
?
result
?

This can be used instead of ovrHmdConfigureRendering to do setup for client rendered distortion.

  Source 
proc ovrHmdCreateDistortionMesh(hmd: OvrHmd; eyeType: OvrEyeType; fov: OvrFovPort;
                               distortionCaps: cuint;
                               meshData: ptr OvrDistortionMesh): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_CreateDistortionMesh".}
Generate distortion mesh per eye.
hmd
Handle to a head-mounted display
eyeType
?
fov
?
distortionCaps
(see below)
meshData
Will hold the created distortion mesh data
result
  • true on success
  • false otherwise

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 ovrHmdDestroyDistortionMesh.

Users should call ovrHmdGetRenderScaleAndOffset to get uvScale and Offset values for rendering. The function shouldn't fail unless theres is a configuration or memory error, in which case the meshData values will be set to null. This is the only function in the SDK reliant on eye relief, currently imported from profiles, or overridden here.

  Source 
proc ovrHmdCreateDistortionMeshDebug(hmd: OvrHmd; eyeType: OvrEyeType;
                                    fov: OvrFovPort; distortionCaps: cuint;
                                    meshData: ptr OvrDistortionMesh;
                                    debugEyeReliefOverrideInMetres: cfloat): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_CreateDistortionMeshDebug".}

hmd
Handle to a head-mounted display
eyeType
?
fov
?
debugEyeReliefOverrideInMetres
?
result
  • true on success
  • false otherwise

  Source 
proc ovrHmdDestroyDistortionMesh(meshData: ptr OvrDistortionMesh) {.cdecl,
    dynlib: dllname, importc: "ovrHmd_DestroyDistortionMesh".}
Used to free the distortion mesh allocated by ovrHmdCreateDistortionMesh.
meshData
Pointer to the mesh to destroy

The meshData elements are set to nil and zeroes after the call.

  Source 
proc ovrHmdGetRenderScaleAndOffset(fov: OvrFovPort; textureSize: OvrSizei;
                                  renderViewport: OvrRecti;
                                  uvScaleOffsetOut: array[2, OvrVector2f]) {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetRenderScaleAndOffset".}
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.   Source 
proc ovrHmdGetFrameTiming(hmd: OvrHmd; frameIndex: cuint): OvrFrameTiming {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetFrameTiming".}
Thread-safe timing function for the main thread.
hmd
Handle to a head-mounted display
frameIndex
?
result
?

Caller should increment frameIndex with every frame and pass the index where applicable to functions called on the rendering thread.

  Source 
proc ovrHmdBeginFrameTiming(hmd: OvrHmd; frameIndex: cuint): OvrFrameTiming {.cdecl,
    dynlib: dllname, importc: "ovrHmd_BeginFrameTiming".}
Called at the beginning of the frame on the rendering thread.
hmd
Handle to a head-mounted display
frameIndex
?
result
?

Pass frameIndex == 0 if ovrHmdGetFrameTiming isn't being used. Otherwise, pass the same frame index as was used for ovrHmdGetFrameTiming on the main thread.

  Source 
proc ovrHmdEndFrameTiming(hmd: OvrHmd) {.cdecl, dynlib: dllname,
                                      importc: "ovrHmd_EndFrameTiming".}
Mark the end of client distortion rendered frame, tracking the necessary timing information.
hmd
Handle to a head-mounted display

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.

  Source 
proc ovrHmdResetFrameTiming(hmd: OvrHmd; frameIndex: cuint) {.cdecl, dynlib: dllname,
    importc: "ovrHmd_ResetFrameTiming".}
Initialize and reset frame time tracking.
hmd
Handle to a head-mounted display
frameIndex
?

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.

  Source 
proc ovrHmdGetEyeTimewarpMatrices(hmd: OvrHmd; eye: OvrEyeType; renderPose: OvrPosef;
                                 twmOut: array[2, OvrMatrix4f]) {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetEyeTimewarpMatrices".}

Compute timewarp matrices used by distortion mesh shader, these are used to adjust for head orientation change since the last call to ovrHmdGetEyePoses 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 ovrHmdBeginFrameTiming.

  Source 
proc ovrHmdGetEyeTimewarpMatricesDebug(hmd: OvrHmd; eye: OvrEyeType;
                                      renderPose: OvrPosef;
                                      twmOut: array[2, OvrMatrix4f];
                                      debugTimingOffsetInSeconds: cdouble) {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetEyeTimewarpMatricesDebug".}
  Source 
proc ovrMatrix4fProjection(fov: OvrFovPort; znear: cfloat; zfar: cfloat;
                          rightHanded: OvrBool): OvrMatrix4f {.cdecl,
    dynlib: dllname, importc: "ovr_Matrix4f_Projection".}
Used to generate projection from OvrEyeDesc.fov.
fov
?
znear
?
zfar
?
rightHanded
?
result
?
  Source 
proc ovrMatrix4fOrthoSubProjection(projection: OvrMatrix4f;
                                  orthoScale: OvrVector2f; orthoDistance: cfloat;
                                  hmdToEyeViewOffsetX: cfloat): OvrMatrix4f {.
    cdecl, dynlib: dllname, importc: "ovr_Matrix4f_OrthoSubProjection".}
Used for 2D rendering, Y is down.
project
?
orthoScale
1.0f / pixelsPerTanAngleAtCenter
orthoDistance
Distance from camera, such as 0.8m

hmdToEyeViewOFfsetX

result
?
  Source 
proc ovrGetTimeInSeconds(): cdouble {.cdecl, dynlib: dllname,
                                   importc: "ovr_GetTimeInSeconds".}
Returns global, absolute high-resolution time in seconds.
result
Resolution time

This is the same value as used in sensor messages.

  Source 
proc ovrWaitTillTime(absTime: cdouble): cdouble {.cdecl, dynlib: dllname,
    importc: "ovr_WaitTillTime".}
Waits until the specified absolute time.   Source 
proc ovrHmdProcessLatencyTest(hmd: OvrHmd; rgbColorOut: array[3, cuchar]): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_ProcessLatencyTest".}
Does latency test processing and returns true if specified RGB color should be used to clear the screen.   Source 
proc ovrHmdGetLatencyTestResult(hmd: OvrHmd): cstring {.cdecl, dynlib: dllname,
    importc: "ovrHmd_GetLatencyTestResult".}
Returns non-null string once with latency test result, when it is available. Buffer is valid until next call.   Source 
proc ovrHmdGetLatencyTest2DrawColor(hmddesc: OvrHmd; rgbColorOut: array[3, cuchar]): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetLatencyTest2DrawColor".}
result
  • the latency testing color in rgbColorOut to render when using a DK2
  • false if this feature is disabled or not-applicable (e.g. DK1)
  Source 
proc ovrHmdGetHSWDisplayState(hmd: OvrHmd; hasWarningState: ptr ovrHSWDisplayState) {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetHSWDisplayState".}
Gets the current state of the HSW display.
hmd
Handle to a head-mounted display
hasWarningState
Will hold the display state

If the application is doing the rendering of the HSW display then this function serves to indicate that 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 ovrHmdDismissHSWDisplay as described below. Example usage for application-based rendering:

var hswDisplayCurrentlyDisplayed = false ## global or class member var
var hswDisplayState: ovrHSWDisplayState
ovrhmdGetHSWDisplayState(hmd, addr(hswDisplayState))

if hswDisplayState.Displayed && !HSWDisplayCurrentlyDisplayed
  # insert model into the scene that stays in front of the user
  hswWDisplayCurrentlyDisplayed = true
  Source 
proc ovrHmdDismissHSWDisplay(hmd: OvrHmd): OvrBool {.cdecl, dynlib: dllname,
    importc: "ovrHmd_DismissHSWDisplay".}
Dismisses the HSW display if the warning is dismissible and the earliest dismissal time has occurred.
hmd
Handle to a head-mounted display
result
  • true if the display is valid and could be dismissed
  • false otherwise

The application should recognize that the HSW display is being displayed (via ovrHmdGetHSWDisplayState) and if so then call this function when the appropriate user input to dismiss the warning occurs. Example usage:

proc processEvent(int key)
  if key == escape
    var hswDisplayState: ovrHSWDisplayState
    ovrhmdGetHSWDisplayState(hmd, addr(hswDisplayState));
    
    if hswDisplayState.Displayed && ovrhmd_DismissHSWDisplay(hmd)
      <remove model from the scene>
      hswDisplayCurrentlyDisplayed = false
  Source 
proc ovrHmdGetBool(hmd: OvrHmd; propertyName: cstring; defaultVal: OvrBool): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetBool".}
Get a boolean property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to get
defaultVal
Default value to return if property doesn't exist
result
  • first element if property is a boolean array
  • defaultValue if property doesn't exist
  Source 
proc ovrHmdSetBool(hmd: OvrHmd; propertyName: cstring; value: OvrBool): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_SetBool".}
Modify a bool property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to set
value
The value to set
result
  • true on success
  • false if property doesn't exist or is readonly
  Source 
proc ovrHmdGetInt(hmd: OvrHmd; propertyName: cstring; defaultVal: cint): cint {.cdecl,
    dynlib: dllname, importc: "ovrHmd_GetInt".}
Get an integer property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to get
defaultVal
Default value to return if property doesn't exist
result
  • first element if property is an integer array
  • defaultValue if property doesn't exist
  Source 
proc ovrHmdSetInt(hmd: OvrHmd; propertyName: cstring; value: cint): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_SetInt".}
Modify an integer property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to set
value
The value to set
result
  • true on success
  • false if property doesn't exist or is readonly
  Source 
proc ovrHmdGetFloat(hmd: OvrHmd; propertyName: cstring; defaultVal: cfloat): cfloat {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetFloat".}
Get a float property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to get
defaultVal
Default value to return if property doesn't exist
result
  • first element if property is a float array
  • defaultValue if property doesn't exist
  Source 
proc ovrHmdSetFloat(hmd: OvrHmd; propertyName: cstring; value: cfloat): OvrBool {.cdecl,
    dynlib: dllname, importc: "ovrHmd_SetFloat".}
Modify a float property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to set
value
The value to set
result
  • true on success
  • false if property doesn't exist or is readonly
  Source 
proc ovrHmdGetFloatArray(hmd: OvrHmd; propertyName: cstring; values: ptr cfloat;
                        arraySize: cuint): cuint {.cdecl, dynlib: dllname,
    importc: "ovrHmd_GetFloatArray".}
Get a float[] property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to get
values
Will hold the array values.
result
  • Number of elements filled in
  • 0 if property doesn't exist

A maximum of arraySize elements will be written.

  Source 
proc ovrHmdSetFloatArray(hmd: OvrHmd; propertyName: cstring; values: ptr cfloat;
                        arraySize: cuint): OvrBool {.cdecl, dynlib: dllname,
    importc: "ovrHmd_SetFloatArray".}
Modify a float[] property.
hmd
Handle to a head-mounted display
propertyName
The name of the property to set
values
The values to set
result
  • true on success
  • false if property doesn't exist or is readonly
  Source 
proc ovrHmdGetString(hmd: OvrHmd; propertyName: cstring; defaultVal: cstring): cstring {.
    cdecl, dynlib: dllname, importc: "ovrHmd_GetString".}
Get string property.
hmd
Handle to a head-mounted display
propertyName
defaultVal
result
  • The first element if property is a string array
  • defaultValue if property doesn't exist

String memory is guaranteed to exist until next call to ovrHmdGetString or ovrHmdGetStringArray, or HMD is destroyed.

  Source 
proc ovrHmdSetString(hmddesc: OvrHmd; propertyName: cstring; value: cstring): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_SetString".}
Set string property   Source 
proc ovrHmdStartPerfLog(hmd: OvrHmd; fileName: cstring; userData1: cstring): OvrBool {.
    cdecl, dynlib: dllname, importc: "ovrHmd_StartPerfLog".}
Start performance logging.
hmd
Handle to a head-mounted display
fileName
The name of the output file
userData1
Optional string to be written with each file entry
result
  • true on success
  • false on failure

If called while logging is already active with the same filename, only the guid will be updated. If called while logging is already active with a different filename, ovrHmdStopPerfLog will be called, followed by ovrHmdStartPerfLog.

  Source 
proc ovrHmdStopPerfLog(hmd: OvrHmd): OvrBool {.cdecl, dynlib: dllname,
    importc: "ovrHmd_StopPerfLog".}
Stop performance logging.   Source

Made with Nim. Generated: 2016-01-30 12:58:21 UTC