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

WVR_Texture_t depth¶: Correspond to the name of texture to identify texture entity in graphics library such as OpenGL.

WVR_Matrix4f_t *projectionMatrix¶

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 the submitting texture. The lower-left coordinates are kept in lowerLeftUVs. The upper-right coordinates are kept in upperRightUVs.

Public Members

WVR_Vector2f leftLowUVs¶: Component 0 and 1 are lower-left UV coordinates of the texture.

WVR_Vector2f rightUpUVs¶: Component 0 and 1 are upper-right UV coordinates of the texture.

The srtuct WVR_PoseState_t is defined as below.

struct WVR_PoseState¶

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

Public Members

bool isValidPose¶: The label of valid(true) or invalid(false) pose.

WVR_Matrix4f_t poseMatrix¶: The pose data (rotation, position) in matrix form (refer to WVR_Matrix4f).

WVR_Vector3f_t velocity¶: The velocity of the pose (refer to WVR_Vector3f).

WVR_Vector3f_t angularVelocity¶: The angular velocity of the pose.

bool is6DoFPose¶: The label of 6 DoF(true) or 3 DoF(false) pose.

int64_t timestamp¶: Absolute time (in nanosecond) of the pose.

WVR_Vector3f_t acceleration¶: The acceleration of the pose.

WVR_Vector3f_t angularAcceleration¶: The angular acceleration of the pose.

float predictedMilliSec¶: Number of milliseconds from now to predict poses.

WVR_PoseOriginModel originModel¶: The origin model of the pose.

WVR_Pose_t rawPose¶: The raw data of the pose from the device.

enum WVR_Eye¶

The sides of target scene.

Specify the side of eye for target scene.

Values:

WVR_Eye_Left = 0¶: WVR_Eye_Left: Left eye id.

WVR_Eye_Right = 1¶: WVR_Eye_Right: Right eye id.

WVR_Eye_Both = 2¶: WVR_Eye_Both: Both Left and Right eye id.

enum WVR_SubmitExtend¶

Extend the add-on functionality for WVR_SubmitFrame.

WVR_SubmitFrame needs this flag to specify the invoking path. Currently, the default functionality is available for the runtime to submit the texture target process. To do distortion correction, apply the flag WVR_SubmitExtend_DisableDistortion in this invoking path. The flag WVR_SubmitExtend_PartialTexture should 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 the texture to the display.

WVR_SubmitExtend_DisableDistortion = 0x0001¶: WVR_SubmitExtend_DisableDistortion: The render runtime doesn’t correct distortion for this submit.

WVR_SubmitExtend_PartialTexture = 0x0010¶: WVR_SubmitExtend_Partial: Present the partial texture.

WVR_SubmitExtend_SystemReserved1 = 1 << 30¶: **Reserved for the system.

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);
}