Venus Plug-in Interface (VPI) Development Guide

Copyright © MediaTek Inc. All rights reserved.

Outline
▪ Basics
– Brief introduction to Venus UI engine
– Basic knowledge of MRE
– Brief introduction to VPI
– Brief introduction to VPI architecture
▪ Coding style of VPI
– Hello world
– Write a sample button using VM classes
– Launch a MRE VPI app
▪ VPI working theory
– Why need VPI
– Basic Theory of Query Service
▪ Export interface to MRE
– Export global APIs
– Export classes can’t be inherited
– Export classes can be inherited
Together, We make the difference.
 Brief introduction to Venus UI engine

▪ What’s UI engine
– A software system which provides the mechanisms and interfaces
to applications to organize and display user interface (UI)

▪ Venus UI engine
– An UI engine which provide easy way to display Fancy UI

▪ Fancy UI
– 2D and 3D rendering
• 2D: draw text, image, linear transform, alpha blending…
• 3D: mesh, texture, lighting, shader rendering…
– Animation system

▪ NOTE: Venus MMI is based on Venus UI engine

Together, We make the difference.

Basic knowledge of MRE

▪ MRE (MAUI runtime environment)

▪ A MRE App is a file (*.vxp/*.vso/*.vpp) stored in FAT (phone
or T-card)
▪ When launch a MRE App, it’s dynamically loaded and linking
with native environment (like a DLL on Windows)
▪ If a MRE App wants to use any services provided by native,
the interfaces are passed to MRE App in runtime
– Function pointers
– Pure interface class (C++)

Together, We make the difference.

Basic knowledge of MRE

▪ All interfaces native provides to MRE App must be

backward-compatible
– The old MRE Apps can run normally on new phones

▪ Summary
– Native functionalities can be exported to MRE App by function
pointer or pure interface class (C++), means the interfaces are
dynamically linked with MRE code
– All interfaces exported to MRE App must be backward-compatible,
including its proto type and behaviors

Together, We make the difference.

Brief introduction of VPI

▪ VPI is an interface set for MRE App to write Venus-like UI

code
▪ VPI let MRE App get the same fancy UI abilities as native
Venus App
▪ VPI helps MRE App to shorten the development cycle,
because there is no UI engine for MRE before VPI
▪ So far, you can write MRE widget, live wallpaper, screen lock,
launcher by using VPI
▪ VPI will support writing full screen application in the future

Together, We make the difference.

Brief introduction to VPI architecture
MRE Native

VPI App CP Lib Native Venus App

Helper (VM class)

Query Service
VFX VCP VRT
Venus Wrapper

Platform interfaces

KAL / Data type, macros, data

GDI Others …
MMI FW structures…

Together, We make the difference.

Brief introduction to VPI architecture

▪ “Helper” and “CP lib” are implemented and static linked in

MRE App
▪ “Query service” and “Venus Wrapper” are implemented in
native to provide interfaces to MRE App

Together, We make the difference.

Coding style of VPI
▪ Helloworld

Set frame properties

Create a child frame and

set properties

Together, We make the difference.

Coding style of VPI
Inherit from VMControl,
▪ Write a sample button using VM classes like inheriting from
VfxControl in native

Override onInit() to
do initialization

Set frame
properties

Almost same as
what you do in
native Venus

Override onPenInput()
to get pen event and
do action

Provide signal

Together, We make the difference.

Coding style of VPI
▪ Launch a MRE VPI app

Get the *.vpp file path

from somewhere

Create an instance of
VpiAppLauncher with
the vpp file path

Launch the vpp

Together, We make the difference.

 VPI working theory
▪ Cross compiler problem
compiler A compiler B

MRE

Native
MRE would like to
use native VFX,
but…

X VFX

Cross compiler Can’t static link

Together, We make the difference.
 VPI working theory
▪ Basic theory of Query service
▪ Query Service is a simplified version of Microsoft COM (Component Object Model).
▪ Microsoft asks the different compilers to follow a same rule to process C++ virtual table
▪ The virtual table memory layout are same in Native and MRE even they are compiled by different compilers

▪ COM is a platform-independent, distributed, object-oriented system for creating binary

software components that can interact.
▪ MRE asks Query Service to return a system object (as the interface format) to MRE
APP, and MRE APP can interact with native service. 1. Pure interface class
referenced by both native
and MRE
2. Proto-type and behaviors
Native can not be changed after
release

MRE APP

A function pointer to
getMyService() of native,
Together, We make the difference. not static linked
http://msdn.microsoft.com/en-us/library/ms810016.aspx
 Exporting native interface to MRE
▪ Folder structure (native and MRE)

▪ Native ▪ MRE
Have the same
vpi_xxx_interface.h files

Venus wrapper
(vpi_xxx.cpp/h)

Helper in MRE
(vm_xxx.cpp/h)

Together, We make the difference.

Export global APIs to MRE
Native Plug-in Interface MRE VMAutoAnimate code
IVpiAutoAnimate
.h

Proxy Object IVpiAutoAnimate MRE Code

(VpiAutoAnimateProxy)
(Implement IVpiAutoAnimate) IVpiAutoAnimate* ptr = ObjFactory->createObject(
“VpiAutoAnimate”, NULL);
Function call
ptr->begin(…);
ptr->setDuration(…);
Native global APIs: :
VfxAutoAnimate::begine()
VfxAutoAnimate::setDuration()
…

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 1 : Design the interface to export
▪ Create vpi_auto_animate_interface.h
▪ Declare IVpiAutoAnimate here
▪ Add the exported APIs into IVpiAutoAnimate
▪ Generally, the public functions of VfxAutoAnimate

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Note:
▪ All the exported APIs must be public pure virtual
▪ The data type used in the APIs must be VM series
▪ The interface class must directly or indirectly inherit from IVpiBase

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 2 : Define the interface IDs
▪ Define the interfaces IDs of IVpiAutoAnimate in vpi_interface_id.h
▪ The IDs naming rule is IID_ plus interface class name
▪ Ex. IID_IVpiAutoAnimate
▪ The value of the IDs must be unique and bigger than 0xFF000000

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 3 : Implement the Venus wrapper (Proxy class)
▪ Create vpi_auto_animate.cpp/h
▪ Implement VpiAutoAnimateProxy

Fix template

Implement the methods of

IVpiAutoAnimate
Together, We make the difference.
 Export global APIs to MRE (cont.)
▪ Step 3 : Implement the Venus wrapper (Proxy class)
▪ Implement VpiAutoAnimateProxy Fix template

Cast and return the interface

(IVpiAutoAnimate) pointer

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 4 : Register the proxy to VPI object factory
▪ Go to vpi_object_factory.cpp
▪ Add the proxy entry of VpiAutoAnimateProxy into
gVpiProxyCreationEntryTable[]

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 5 : Copy the VPI interface header files to MRE SDK and MRE
App projects
▪ Copy vpi_auto_animate_interface.h to [MRE SDK]\include\service and
[MRE App project]\include\service
▪ Sync vpi_interface_id.h with MRE SDK and MRE App project
▪ For the new interface ID: IID_IVpiAutoAnimate
▪ Then MRE App can use IVpiAutoAnimate

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Create vm_auto_animate.cpp/h in MRE SDK and MRE App project
▪ Implement VMAutoAnimate
Implement the static functions of IVpiAutoAnimate in
VMAutoAnimate, just call the corresponding function
through s_object

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMAutoAnimate

Create VPI object in init()

Together, We make the difference.

 Export global APIs to MRE (cont.)
▪ Summary and notice
▪ After the above steps, MRE App can use VfxAutoAnimate (by using
VMAutoAnimate) as native

Together, We make the difference.

Export a class can’t be inherited
Native Plug-in Interface MRE VMTextFrame code
IVpiTextFrame
.h

Proxy Object IVpiTextFrame

(VpiTextFrameProxy) MRE Code
(Implement IVpiTextFrame)
IVpiTextFrame* ptr = ObjFactory->createObject(
“VpiTextFrame”, NULL);
Weak pointer
ptr->setString(…); :
:

Native
VfxTextFrame
Object

Together, We make the difference.

 Export a class can’t be inherited
▪ Step 1 : Design the interface to export
▪ Create vpi_text_frame_interface.h
▪ Declare IVpiTextFrame here
▪ Add the exported APIs into IVpiTextFrame
▪ Generally, the public functions of VfxTextFrame

Together, We make the difference.

 Export a class can’t be inherited
▪ Note:
▪ All the exported APIs must be public pure virtual
▪ The data type used in the APIs must be VM series
▪ The interface class must directly or indirectly inherit from IVpiBase

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 2 : Define the interface IDs
▪ Define the interfaces IDs of IVpiTextFrame in vpi_interface_id.h
▪ The IDs naming rule is IID_ plus interface class name
▪ Ex. IID_IVpiTextFrame
▪ The value of the IDs must be unique and bigger than 0xFF000000

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (Proxy class)
▪ Implement VpiTextFrameProxy

Fix template

Implement the
methods of IVpiTextFrame

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (Proxy class)
▪ Implement VpiTextFrameProxy
Fix template

Call the corresponding

methods of native object

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (Proxy class)
▪ Implement VpiTextFrameProxy

Cast and return the interface

(IVpiTextFrame) pointer

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 4 : Register the proxy to VPI object factory
▪ Go to vpi_object_factory.cpp
▪ Add the proxy entry of VpiTextFrameProxy into
gVpiProxyCreationEntryTable[]

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 5 : Copy the VPI interface header files to MRE SDK and MRE
App projects
▪ Copy vpi_text_frame_interface.h to [MRE SDK]\include\service and [MRE
App project]\include\service
▪ Sync vpi_interface_id.h with MRE SDK and MRE App project
▪ For the new interface ID: IID_IVpiTextFrame
▪ Then MRE App can use IVpiTextFrame

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Create vm_text_frame.cpp/h in MRE SDK and MRE App project
▪ Implement VMTextFrame

Declare VMTextFrame

Smart pointer to
IVpiTextFrame *

Implement the APIs in IVpiText Frame and just call

the corresponding method through m_object
Together, We make the difference.
 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMFrame
Fix template

Implement init() and create

VPI object here

Receive VPI object

pointer here

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Summary
▪ After the above steps, MRE App can use VfxTextFrame (by using
VMTextFrame) as native, including creating and operating

Together, We make the difference.

Export a class can be inherited
Native Plug-in Interface MRE VMFrame code
IVpiFrame
.h IVpiFrameDelegator

MRE Code
Proxy Object IVpiFrame
(VpiFrameProxy) IVpiFrame* ptr = ObjFactory->createObject(
(Implement IVpiFrame) “VpiFrame”, delegator);

Weak pointer ptr->setAnchor(…);

IVpiFrameDelegatorSuper ptr->setBounds(…);
ptr->setPos(…);
:
Plug-in Object OR :
(VpiFrame
which inherit IVpiFrameDelegator
IVpiFrameDelegator
VfxFrame)
Default Delegator
Delegator (Override IVpiFrameDelegator)

Native
VfxFrame
Together, We makeObject
the difference.
 Export a class can be inherited (cont.)
▪ Step 1 : Design the interface to export
▪ Create vpi_frame_interface.h
▪ Declare IVpiFrame here
▪ Add the exported APIs into IVpiFrame
▪ Generally, the public functions of VfxFrame
▪ Declare IVpiFrameDelegator
▪ Add the exported delegator APIs into IVpiFrameDelegator
▪ Generally, the protected virtual functions of VfxFrame

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Note:
▪ All the exported APIs must be public pure virtual
▪ The data type used in the APIs must be VM series
▪ The interface class must directly or indirectly inherit from IVpiBase

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 2 : Define the interface IDs
▪ Define the interfaces IDs of IVpiFrame and IVpiFrameDelegator in
vpi_interface_id.h
▪ The IDs naming rule is IID_ plus interface class name
▪ Ex. IID_IVpiFrame
▪ The value of the IDs must be unique and bigger than 0xFF000000

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Create vpi_frame.cpp/h
▪ Implement VpiFrame
▪ Declare an interface class which includes all super methods of
corresponding methods in IVpiFrameDelegator

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy
class)
▪ Implement VpiFrame
▪ Declare VpiFrame

All IVpiXxxDelegatorSuper in
Apply this macro the inheritance

Define VpiClass as VpiFrame

Include vpi_xxx_delegator.h

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Implement VpiFrame
▪ Implement VpiFrame::defaultDelegator
Assign super class and interface

Declare default delegator Callback to delegator

super

Implement delegator methods

Declare 2 methods to receive

delegator owner

Pointer to the delegator super

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Implement VpiFrame
▪ Implement VpiFrame::defaultDelegator

Cast VpiFrame to the corresponding

delegator super and assign to the
super default delegators

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy
class)
▪ Implement VpiFrame
▪ Implement vpi_frame_delegator.h
Include the .h of super delegator

Include the .h of super delegator

Help to pass to super delegator

Query and record the delegator

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy
class)
▪ Implement VpiFrame
▪ Implement vpi_frame_delegator.h Override the virtual functions of
VfxFrame

Set MRE App context before

callback to MRE

Create proxy for the parameter

which will be passed to MRE

Callback to MRE

Implement the delegator super

Together, We make the difference. function
 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Implement VpiFrameProxy

Fix template

Implement the methods of

IVpiFrame

For signals exported to

MRE

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Implement VpiFrameProxy Fix template

Call the corresponding

methods of native object

If has exported signal, connect here

Together, We make the difference. Send command to MRE through

Define the command ID in vpi_cmd_id.h
processCmd()
 Export a class can be inherited (cont.)
▪ Step 3 : Implement the Venus wrapper (VPI class and Proxy class)
▪ Implement VpiFrameProxy

Cast and return the interface

(IVpiFrame) pointer

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 4 : Register the proxy to VPI object factory
▪ Go to vpi_object_factory.cpp
▪ Add the proxy entry of VpiFrameProxy into gVpiProxyCreationEntryTable[]

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 5 : Copy the VPI interface head files to MRE SDK and MRE
App projects
▪ Copy vpi_frame_interface.h to [MRE SDK]\include\service and [MRE App
project]\include\service
▪ Sync vpi_interface_id.h with MRE SDK and MRE App project
▪ For the new interface ID: IID_IVpiFrame
▪ Then MRE App can use IVpiFrame

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Create vm_frame.cpp/h in MRE SDK and MRE App project
▪ Implement VMFrame

Declare VMFrame

Smart pointer to
IVpiFrame *

Together, We make theImplement the APIs in IVpiFrame

difference.
and just call the corresponding
method through m_object
 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMFrame

Provide VMSignal for MRE

Receive signal from native and emit

corresponding VMSignal

Implement the methods in

IVpiFrameDelegator and call the
default delegator methods

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMFrame

Fix template

Implement init() and create

VPI object here

Receive VPI object

pointer here

Register signal

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMFrame

Receive VPI object pointer here

Cast and return the interface

(IVpiFrameDelegator) pointer

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Step 6 : Implement the corresponding VM class in MRE
▪ Implement VMFrame

Receive signal from native, and emit

corresponding MRE signal here

Together, We make the difference.

 Export a class can be inherited (cont.)
▪ Summary and notice
▪ After the above steps, MRE App can use VfxFrame (by using VMFrame) as
native, including creating , overriding and operating
▪ If you are implementing a class inherit from GS_IBase, remember to
implement the queryInterface() function specially, this is very important to
make sure the interfaces are backward compatible

Together, We make the difference.

 Thank you!

Copyright © MediaTek Inc. All rights reserved.