Function ovr_sys::ovr_SubmitFrame

source · 
pub unsafe extern "C" fn ovr_SubmitFrame(
    session: ovrSession,
    frameIndex: c_longlong,
    viewScaleDesc: *const ovrViewScaleDesc,
    layerPtrList: *const *const ovrLayerHeader,
    layerCount: c_uint
) -> ovrResult
Expand description

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.

session Specifies an ovrSession previously returned by ovr_Create.

frameIndex Specifies the targeted application frame index, or 0 to refer to one frame after the last time ovr_SubmitFrame was called.

viewScaleDesc Provides additional information needed only if layerPtrList contains an ovrLayerType_Quad. If NULL, a default version is used based on the current configuration and a 1.0 world scale.

layerPtrList Specifies a list of ovrLayer pointers, which can include NULL entries to indicate that any previously shown layer at that index is to not be displayed.

Each layer header must be a part of a layer structure such as ovrLayerEyeFov or ovrLayerQuad, with Header.Type identifying its type. A NULL layerPtrList entry in the array indicates the absence of the given layer.

layerCount Indicates the number of valid elements in layerPtrList. The maximum supported layerCount is not currently specified, but may be specified in a future version.

  • Layers are drawn in the order they are specified in the array, regardless of the layer type.

  • Layers are not remembered between successive calls to ovr_SubmitFrame. A layer must be specified in every call to ovr_SubmitFrame or it won’t be displayed.

  • If a layerPtrList entry that was specified in a previous call to ovr_SubmitFrame is passed as NULL or is of type ovrLayerType_Disabled, that layer is no longer displayed.

  • A layerPtrList entry can be of any layer type and multiple entries of the same layer type are allowed. No layerPtrList entry may be duplicated (i.e. the same pointer as an earlier entry).

Example code

// In initialisation
let layer0: ovrLayerEyeFov = foo();
let layer1: ovrLayerQuad = bar();
// In frame loop
let layers = [&layer0.Header as *const _, &layer1.Header as *const _];
let result = ovr_SubmitFrame(session, frame_index, ptr::null(), layers.as_ptr(), 2);

Returns an ovrResult for which OVR_SUCCESS(result) is false upon error and true upon success. Return values include but aren’t limited to:

  • ovrSuccess: rendering completed successfully.
  • ovrSuccess_NotVisible: rendering completed successfully but was not displayed on the HMD, usually because another application currently has ownership of the HMD. Applications receiving this result should stop rendering new content, but continue to call ovr_SubmitFrame periodically until it returns a value other than ovrSuccess_NotVisible.
  • ovrError_DisplayLost: The session has become invalid (such as due to a device removal) and the shared resources need to be released (ovr_DestroyTextureSwapChain), the session needs to destroyed (ovr_Destroy) and recreated (ovr_Create), and new resources need to be created (ovr_CreateTextureSwapChainXXX). The application’s existing private graphics resources do not need to be recreated unless the new ovr_Create call returns a different GraphicsLuid.
  • ovrError_TextureSwapChainInvalid: The ovrTextureSwapChain is in an incomplete or inconsistent state. Ensure ovr_CommitTextureSwapChain was called at least once first.

see ovr_GetPredictedDisplayTime, ovrViewScaleDesc, ovrLayerHeader