WVR_SubmitFrame

WVR_EXPORT WVR_SubmitError WVR_SubmitFrame(WVR_Eye eye, const WVR_TextureParams_t * param, const WVR_PoseState_t * pose = NULL, WVR_SubmitExtend extendMethod = WVR_SubmitExtend_Default)

Update scene image to display.

The scene is rendered by developer with both sides of eye. The scene content is in form of index or pointer according to the supported graphics API, such as texture name in OpenGL. Developer can submit the image(s) of both eyes at most once within one Vsync duration to signal the runtime to process. The WVR_TextureParams_t contains the texture which specifies the current scene. This scene is already rendered beforehand. This texture is verified its validness in advance of updating it to display.

A much more accurate polling pose approximating the moment that scene is rendered, provides much more stabilized performance of rendering. The fourth is a flag to specify the internal invoking path. The default process of handing scene fulfills all the basic requirement of updating scene to display. Add-on functionalities will be appended in the future.

The update frequency is limited by the refresh rate of the display. The checkpoints which check if the application can start to render the next frame is set to every middle of two adjacent Vsyncs. Therefore, this API will not return until the next checkpoint is coming. Moreover, the caller will be blocked for one or more checkpoints if the previous frame has not completed the rendering yet.

Return
WVR_SubmitError, the error status of interface WVR_SubmitFrame, the possible status can refer to WVR_RenderError.
Version
API Level 1
Parameters
  • eye: WVR_Eye, eye id to specify the side of scene.
  • param: pointer to struct WVR_TextureParams_t, to aggregate the name of scene texture.
  • pose: pointer to struct WVR_PoseState_t, the pose used for rendering this frame.
  • extendMethod: enum WVR_SubmitExtend, flag to specify invoking path.

Struct and enumeration

The srtuct WVR_TextureParams_t is defined as below.

struct WVR_TextureParams

Texture parameters.

Aggregate the texture related information which needs to be updated to runtime. The texture parameters can be obtained via WVR_GetTexture or assigned a valid texture directly. The WVR_SubmitFrame need this struct as an argument to pass current texture identiy to runtime.

Public Members

WVR_Texture_t id

Correspond to the name of texture to identify texture entity in graphics library such as OpenGL.

WVR_TextureTarget target

Specifies the target to which the texture is bound. The parameter corresponds to the texture targe in graphics library such as OpenGL.

WVR_TextureLayout_t layout

The lower left and upper right UV coordinates pair specifies the presenting region of submitted texture.

The type WVR_Texture_t is defined as below.

typedef void *WVR_Texture_t

WVR_Texture_t: type define the name of texture.

The srtuct WVR_TextureLayout_t is defined as below.

struct WVR_TextureLayout

Texture layout.

Store the lower and upper UV coordinates to specify the region of submitting texture. The left-low coordinates are kept in lowerLeftUVs. The right-up coordinates are kept in upperRightUVs.

Public Members

WVR_Vector2f leftLowUVs

Component 0 and 1 are left-low UV coordinates of the texture.

WVR_Vector2f rightUpUVs

Component 0 and 1 are right-up UV coordinates of the texture.

The srtuct WVR_PoseState_t is defined as below.

struct WVR_PoseState

Describes a single pose in rotation matrix form for a tracked object.

Public Members

bool isValidPose

The label of valid(true)/invalid(false) pose.

WVR_Matrix4f_t poseMatrix

The pose data (ratation, position) in matrix form (refer to WVR_Matrix4f).

WVR_Vector3f_t velocity

The velocity of pose (refer to WVR_Vector3f).

WVR_Vector3f_t angularVelocity

The angular velocity of pose.

bool is6DoFPose

The label of 6 DoF(true)/3 DoF(false) pose.

int64_t timestamp

Absolute time (in nanosecond) of pose.

WVR_Vector3f_t acceleration

The acceleration of pose.

WVR_Vector3f_t angularAcceleration

The angular acceleration of pose.

float predictedMilliSec

Number of milliseconds from now to predict poses.

WVR_PoseOriginModel originModel

The origin model of pose.

WVR_Pose_t rawPose

The raw data of pose from device

enum WVR_Eye

The sides of target scene.

Specify the side of eye for targe scene.

Values:

WVR_Eye_Left = 0

WVR_Eye_Left: Left eye id.

WVR_Eye_Right = 1

WVR_Eye_Right: Right eye id.

enum WVR_SubmitExtend

Extend the add-on functionality for WVR_SubmitFrame.

WVR_SubmitFrame need this flag to specify invoking path. Currently, the default funcationality is available for the runtime submit texture target process. If the developers have the intention of doing distortion correction by themselves, it is suitable for applying the flag WVR_SubmitExtend_DisableDistortion in this invoking path. The flag WVR_SubmitExtend_PartialTexture is to be applied when presenting a cropped texture. The cropped range of the texture is determined by the WVR_TextureLayout struct in WVR_TextureParams.

Values:

WVR_SubmitExtend_Default = 0x0000

WVR_SubmitExtend_Default: The default process to submit texture to display.

WVR_SubmitExtend_DisableDistortion = 0x0001

WVR_SubmitExtend_DisableDistortion: The render runtime doesn’t make distortion correction for this submit.

WVR_SubmitExtend_PartialTexture = 0x0010

WVR_SubmitExtend_Partial: Present the partial texture.

WVR_SubmitExtend_SystemReserved1 = 1 << 30

**System reserved.

enum WVR_SubmitError

The return type of API WVR_SubmitFrame.

Enumerate the error type of submitting frame.

Values:

WVR_SubmitError_None = 0

WVR_SubmitError_None: No error

WVR_SubmitError_InvalidTexture = 400

WVR_SubmitError_InvalidTexture: The submitted texture is invalid. Make sure texture is correct and not in use.

WVR_SubmitError_ThreadStop = 401

WVR_SubmitError_ThreadStop: The submitted thread stops in the runtime.

WVR_SubmitError_BufferSubmitFailed = 402

WVR_SubmitError_BufferSubmitFailed: The submitted buffer encounters error in the runtime.

WVR_SubmitError_Max = 65535

WVR_SubmitError_Max: Maxium value to reserve bit word among compilers .

How to use

Here is an example for the function:

// Must initialize render runtime once before calling all rendering-related API.
WVR_RenderInitParams_t param = {WVR_GraphicsApiType_OpenGL, WVR_RenderConfig_Default};
WVR_RenderError pError = WVR_RenderInit(&param);
if (pError != WVR_RenderError_None) {
    LOGE("Render init failed - Error[%d]", pError);
}

std::vector<FrameBufferObject*> LeftEyeFBO;
std::vector<FrameBufferObject*> RightEyeFBO;
FrameBufferObject* fbo;

uint32_t RenderWidth = 0, RenderHeight = 0;

WVR_GetRenderTargetSize(&RenderWidth, &RenderHeight);
void* mLeftEyeQ = WVR_ObtainTextureQueue(WVR_TextureTarget_2D, WVR_TextureFormat_RGBA, WVR_TextureType_UnsignedByte, RenderWidth, RenderHeight, 0);
void* mRightEyeQ = WVR_ObtainTextureQueue(WVR_TextureTarget_2D, WVR_TextureFormat_RGBA, WVR_TextureType_UnsignedByte, RenderWidth, RenderHeight, 0);

for (int i = 0; i < WVR_GetTextureQueueLength(mLeftEyeQ); i++) {
    fbo = new FrameBufferObject((int)WVR_GetTexture(mLeftEyeQ, i).id, RenderWidth, RenderHeight);
    LeftEyeFBO.push_back(fbo);
}
for (int j = 0; j < WVR_GetTextureQueueLength(mRightEyeQ); j++) {
    fbo = new FrameBufferObject((int)WVR_GetTexture(mRightEyeQ, j).id, RenderWidth, RenderHeight);
    RightEyeFBO.push_back(fbo);
}

if (eEye == WVR_Eye_Left) {
    // Left Eye
    LeftEyeFBO.at(mIndex)->bindFrameBuffer();
    LeftEyeFBO.at(mIndex)->glViewportFull();
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    renderScene(WVR_Eye_Left);
    LeftEyeFBO.at(mIndex)->unbindFrameBuffer();
    WVR_TextureParams_t leftEyeTexture = {(WVR_Texture_t)LeftEyeFBO.at(mIndex)->getTextureId()};
    e = WVR_SubmitFrame(WVR_Eye_Left, &leftEyeTexture);
} else {
    // Right Eye
    RightEyeFBO.at(mIndex)->bindFrameBuffer();
    RightEyeFBO.at(mIndex)->glViewportFull();
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    renderScene(WVR_Eye_Right);
    RightEyeFBO.at(mIndex)->unbindFrameBuffer();
    WVR_TextureParams_t rightEyeTexture = {(WVR_Texture_t)RightEyeFBO.at(mIndex)->getTextureId()};
    e = WVR_SubmitFrame(WVR_Eye_Right, &rightEyeTexture);
}

Invoking WVR_GetSyncPose or WVR_GetPoseState multiple times with different predicted time is allowed in programming before calling WVR_SubmitFrame, and in this case, passing the final rendered pose as the third parameter of WVR_SubmitFrame is necessary. Please note that never call these two pose-fetching APIs more than once before calling WVR_SubmitFrame without the pose passed as a parameter. Developer needs to submit both scenes of eyes to trigger render runtime to next steps in normal mode. If the rendered texture is established with multiview extension, the scene is only submitted once each frame regardless of the side of the eye.

if (gMultiview == true) {
    std::vector<FrameBufferObject*> MultiviewFBO;
    FrameBufferObject* fbo;

    // Utilize WVR_TextureTarget_2D_ARRAY as target texture for multiview extension.
    void* MultiviewQ = WVR_ObtainTextureQueue(WVR_TextureTarget_2D_ARRAY, WVR_TextureFormat_RGBA, WVR_TextureType_UnsignedByte, RenderWidth, RenderHeight, 0);

    for (int i = 0; i < WVR_GetTextureQueueLength(MultiviewQ); i++) {
        fbo = new FrameBufferObject((int)WVR_GetTexture(MultiviewQ, i).id, RenderWidth, RenderHeight);
        MultiviewFBO.push_back(fbo);
    }

    MultiviewFBO.at(mIndex)->bindFrameBuffer(gMultiview);
    MultiviewFBO.at(mIndex)->glViewportFull();
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    renderSceneMultiview();
    MultiviewFBO.at(mIndex)->unbindFrameBuffer(gMultiview);

    IndexMultiview = WVR_GetAvailableTextureIndex(MultiviewQ);
    WVR_TextureParams_t multiviewEyeTexture = WVR_GetTexture(MultiviewQ, IndexMultiview);
    WVR_SubmitError e;
    e = WVR_SubmitFrame(WVR_Eye_Left, &multiviewEyeTexture);
}

The fourth argument of API WVR_SubmitFrame can be used to specify the add-on functionality. Developer can disable the distortion correction in the render runtime when submitting textures. Containing the flag WVR_SubmitExtend_DisableDistortion is suitable for submitting the textures which have already been made distortion correction beforehand. Please note that this is an experimental functionality. Edge distortion is noticeable when the performance is low.

if (eEye == WVR_Eye_Left) {
    // Left Eye
    LeftEyeFBO.at(mIndex)->bindFrameBuffer();
    LeftEyeFBO.at(mIndex)->glViewportFull();
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    renderScene(WVR_Eye_Left);
    LeftEyeFBO.at(mIndex)->unbindFrameBuffer();
    WVR_TextureParams_t leftEyeTexture = {(WVR_Texture_t)LeftEyeFBO.at(mIndex)->getTextureId()};
    e = WVR_SubmitFrame(WVR_Eye_Left, &leftEyeTexture, NULL, WVR_SubmitExtend_DisableDistortion);
} else {
    // Right Eye
    RightEyeFBO.at(mIndex)->bindFrameBuffer();
    RightEyeFBO.at(mIndex)->glViewportFull();
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
    renderScene(WVR_Eye_Right);
    RightEyeFBO.at(mIndex)->unbindFrameBuffer();
    WVR_TextureParams_t rightEyeTexture = {(WVR_Texture_t)RightEyeFBO.at(mIndex)->getTextureId()};
    e = WVR_SubmitFrame(WVR_Eye_Right, &rightEyeTexture, NULL, WVR_SubmitExtend_DisableDistortion);
}