VPI Backward Compatible Guideline

& Coding Convention

MTK

Copyright © MediaTek Inc. All rights reserved.

 Overview
▪ Why this guideline
▪ Coding guideline of backward compatible
▪ Coding convention
▪ Verification of backward compatible
– RD
– QA

Together, We make the difference.

 Why this guideline
▪ Guarantee VPI is backward compatible
▪ A very important promise of MRE
▪ The old MRE Apps (compiled by old MRE SDK) are able to
run normally on all the new versions of phones
▪ Guarantee VPI Apps are stable
▪ Some bad or wrong coding convention results in unstable
App
▪ Memory leak, memory overflow

▪ As VPI has some differences with native Venus, the

developers should have some special know-how about DLUI
development

Together, We make the difference.

Coding guideline of backward compatible
▪ How to be backward compatible
▪ Make all interfaces exported to MRE to be backward
compatible
▪ Prototype is backward compatible
▪ Behavior is backward compatible

▪ What are interfaces (which are referenced by both

native and MRE)
▪ Interface class
▪ Data types, function pointer types , macros
▪ Enumerations, structures,
▪ Function

Together, We make the difference.

Coding guideline of backward compatible
▪ Interface class
▪ All member functions must be abstract
▪ One interface class maps to one unique interface ID
(IID_IVpiXyz) which is defined in vpi_interface_id.h
▪ The IDs are classified by category: engine/component/app
▪ The interface id name should start with the prefix IID_I followed
by the class name.
▪ Example:- For VpiFrame we have interface id as IID_IVpiFrame.
▪ The interface id should be bigger than 0xFF000000.
▪ Example: #define IID_IVpiFrame 0XFF00102c

▪ CANNOT change the sequence of declaring the member

functions in the interface class
▪ CANNOT add/remove functions in/from the interface class
▪ Adding new interface class is allowed
Together, We make the difference.
Coding guideline of backward compatible
▪ Data types, function pointer types, macros
▪ CANNOT change their definition
▪ Enumerations
▪ Add new members to exist enumeration type
▪ Add new members above VM_END_OF_ENUM(XXX)
▪ Add new enumeration type

Add this to fix the size of the

enumeration type in different
compilers

Together, We make the difference.

 Coding guideline of backward compatible
▪ Structures
▪ Add new members to exist structure type
▪ Add new members in the last of the structure
▪ Add new structure type
▪ If the structure would be extended (add more member data), add
structure header item in the beginning, and handle different size
case in your code
Add this if the
structure
would be
extended

NOTE. If the structure is extended, MRE App (old App) would pass
smaller size of structures to native, please use “_size” item to get
the real size of the structure from App and handle it specially
Together, We make the difference.
Coding guideline of backward compatible
▪ Structures
▪ Add new structure type
▪ Fill in the “_size” item at MRE side by VM_STRUCT_INIT

Fill in “_size” by using

VM_STRUCT_INIT in
helper data type class

Fill in “_size” by using

VM_STRUCT_INIT
before using the structure

Together, We make the difference.

Coding guideline of backward compatible
▪ Function (member function of interface class)
▪ CANNOT change the prototype of the function
▪ To make sure the behavior of the function is backward
compatible, it’s better to add a special marker beside the
corresponding native function
▪ VfxFrame::setPos() /* exported by IVpiFrame::setPos() */
▪ If the prototype or behavior of the corresponding native
function is changed, still need to have special implementation
to keep the original prototype and behavior of the function

Together, We make the difference.

Coding guideline of backward compatible
▪ Universal API for adding new functions
▪ VPI reserves an universal API in IVpiBase
▪ For any new requirements which need to add new functions
into delegator (IVpiXxxDelegator) or VPI interface (IVpiXxx),
you can make use of it, it won’t break the backward
compatible promise
▪ Proto-type
▪ VM_RESULT sendEvent(VMUINT32 eventID, VMUINT32
param0, void *param1)

For parameter of
pointer type

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding API through universal API
▪ Example. VfxXxx supports someFunction(), add it
to IVpiXxx without modifying IVpiXxx
▪ Step 1: add new event ID range, if no first ID in
your module
▪ Involved file: vpi_id_range.h

New module should

be added in the last

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding API through universal API
▪ Step 2: add new event ID in the interface header
▪ Involved file: vpi_xxx_interface.h

New IDs should be

added in the last

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding API through universal API
▪ Step 3: implement the new event
▪ Involved file: vpi_xxx.h/vpi_xxx.cpp
▪ Override onSendEvent() in the proxy class

Implement the new

functionality and
return success

Remember to call super

class’s implementation
Return fail as the
object is invalid
Together, We make the difference.
Coding guideline of backward compatible
▪ Adding API through universal API
▪ Step 4: implement MRE helper
▪ Involved file: vm_xxx.h/vm_xxx.cpp

MRE App use this

function

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding delegator API through universal API
▪ Example. VfxXxx has new overridable function
onSomeFunction(), add it to IVpiXxxDelegator
without modifying IVpiXxxDelegator
▪ Step 1: add new event ID range, if no ID in your
module
▪ Involved file: vpi_id_range.h

New module should

be added in the last

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding delegator API through universal API
▪ Step 2: add new event ID in the interface header
▪ Involved file: vpi_xxx_interface.h

New IDs should be

added in the last

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding delegator API through universal API
▪ Step 3: implement the new event
▪ Involved file: vpi_xxx.h/vpi_xxx.cpp

Add delegator
super function

Call the new delegator

super function and
return success

Remember to call super

class’s implementation
Together, We make the difference.
Coding guideline of backward compatible
▪ Adding delegator API through universal API
▪ Step 3: implement the new event
▪ Involved file: vpi_xxx_delegator.h

Override the virtual function of VfxXxx

Together, We make the difference.

Coding guideline of backward compatible
▪ Adding delegator API through universal API
▪ Step 4: implement MRE helper
▪ Involved file: vm_xxx.h/cpp
Add the helper virtual function in
MRE, subclass override it

Call back to default

implementation

Handle the event and return

success

Remember to call super

class’s implementation
Together, We make the difference.
 Coding convention
▪ Besides the above coding guideline of backward
compatible, there are some coding convention items
for programmer at MRE side, by following these items,
it will be great for MRE Apps’ stability

Together, We make the difference.

 Coding convention
▪ Make good use of VM helper data type classes
▪ Although some APIs need the data type of vm_xxx_struct,
you can just pass the corresponding data type of VMXxx
class to it, as VMXxx override the related operator

▪ If you need to use vm_xxx_struct directly, and there is

VM_STRUCT_HEADER in this structure, please use
VM_STRUCT_INIT to initialize the structure before using

Together, We make the difference.

 Coding convention
▪ Don’t return local dynamic string through vm_wstring_struct
▪ Example:

vm_wstring_struct only keeps the string

pointer, but the pointed memory will be free
when myString is destructed, then the string
pointer will be dangling pointer

▪ Need other safe ways to return local dynamic string

Together, We make the difference.

 Coding convention
▪ Interface APIs should never return data if it is more than 4
bytes
▪ Due to RVCT compiler bug, the functions of IVpiXxx
should not return, if its return value is bigger than 4
bytes. Instead they should use output argument as
shown in below example
▪ Example:
▪ In IVpiFrameDelegator, instead of function
virtual vm_rect_struct &getBounds() const (X)

we should use
virtual void getBounds(vm_rect_struct *bounds) const (O)

Together, We make the difference.

 Coding convention
▪ Make good use of smart pointer (VMGSPtr) to reduce
memory leak problem
▪ Similar with Microsoft COM, VPI bases on “queryInterface” theory,
so we should handle the life cycle of interface object by
addRef()/release() carefully, so we provide smart pointer “VMGSPtr”
to help invoke addRef()/release() at the required time

Together, We make the difference.

 Coding convention
▪ Make good use of smart pointer (VMGSPtr) to reduce
memory leak problem
▪ Use case 1: receive and keep one interface pointer
▪ Receive an interface pointer, you want to keep it and use
it later

Initialize the “framePtr” by

“frame” directly, and use
“framePtr” as the pointer to
IVpiFrame

Together, We make the difference.

 Coding convention
▪ Make good use of smart pointer (VMGSPtr) to reduce
memory leak problem
▪ Use case 2: cast an interface pointer to another type
▪ Receive an interface pointer, you want to cast it to another
type of interface

Cast IVpiControl pointer to IVpiFrame

pointer, if succeed, you can use the smart
pointer as IVpiFrame pointer

Together, We make the difference.

 Coding convention
▪ Make good use of smart pointer (VMGSPtr) to reduce
memory leak problem
▪ Use case 3: use smart pointer to get interface pointer

Use smart pointer to get interface, and it will help

release the interface object

Together, We make the difference.

 Coding convention
▪ Make use of VPI pointer helper (IVpiPtrHelper) to cast VM
pointer to IVpi pointer
▪ We have VM pointer and IVpi pointer, sometime we need to cast it
with each other, IVpiPtrHelper can help you to do the casting easily
▪ Use case 1: the function parameter type is IVpiXxxxPtr
▪ If the function parameter type is IVpiXxxPtr, you can pass either
VMXxx pointer or IVpiXxx pointer to it

The both two are working

Together, We make the difference.

 Coding convention
▪ Make use of VPI pointer helper (IVpiPtrHelper) to cast VM
pointer to IVpi pointer
▪ Use case 2: cast VM pointer to IVpi pointer

Cast VMFrame pointer to IVpiFrame pointer

▪ Accordingly, there is helper to cast IVpi pointer to VM pointer

If return NULL, means the IVpi pointer doesn’t

have corresponding VM object

Together, We make the difference.

 Coding convention
▪ “Query interface” rules – reference counting principles
▪ Same with Microsoft COM, we use reference count to maintain
interface object life cycle, so there are same rules need to follow
▪ Basically, most of cases, we should use smart pointer (VMGSPtr)
to reduce the problem rate, so please try to use smart pointer in
advance
▪ Reference counting rule: AddRef must be called for every new
copy of an interface pointer, and Release called for every
destruction of an interface pointer

Together, We make the difference.

 Coding convention
▪ “Query interface” rules – reference counting principles
▪ Out-parameter rule : the function which returns interface pointer
through out-parameter, must call addRef() of the interface before
returning, the caller to this function need to call release() of the
interface when the pointer is destructed
Function can not return interface pointer through return
value, must use out-parameter to avoid problem

Call addRef() before

returning the pointer

Use smart pointer, don’t

need to call release()
Call release() before the
pointer is destructed
Together, We make the difference.
 Coding convention
▪ “Query interface” rules – reference counting principles
▪ In-parameter rule : The copy of an interface pointer that is
passed as an actual parameter to a function has a lifetime that is
nested in that of the pointer used to initialize the value. Therefore,
the actual parameter need not be separately reference counted

Don’t need to addRef() and

release() for cell

Together, We make the difference.

 Coding convention
▪ “Query interface” rules – reference counting principles
▪ In-out-parameter rule : release the passed-in interface pointer
before changing it to point to another interface, and call addRef()
after change immediately

Together, We make the difference.

Verification of backward compatible

▪ RD
▪ After any VPI related modifications, it’s better to verify some
MPed VPI Apps before check-in
▪ Implement the VPI regression test-bed (TBD)
▪ QA
▪ Before every major MP, QA should verify all MPed old VPI
Apps on the latest load to make sure VPI is backward
compatible

Together, We make the difference.

 Thanks!

Copyright © MediaTek Inc. All rights reserved.