PN984-MG3500-Programming-Getting-Started-Guide

.....
November 14, 2008
Document Release 1.0
Document Number: PN984
Mobilygen Corporation
2900 Lakeside Drive #100
Santa Clara, CA 95054
www.mobilygen.com
MG3500 PROGRAMMING GETTING STARTED GUIDE
1237 East Argues Avenue, Sunnyvale, CA 94085

Copyright ©
2008 Mobilygen Corporation. All Rights Reserved. This product and related
documentation are protected by copyright and distributed under licenses controlling its use,
copying, and distribution. No part of this product or its related documentation may be
reproduced in any form or by any means except under such licenses and this copyright
notice.
Mobilygen Corporation makes no representations or warranties with respect to the contents
or use of this manual, and specifically disclaims any express or implied warranties of
merchantability or fitness for any particular purpose.
Mobilygen Corporation makes no representations or warranties with respect to Mobilygen®
Linux®
, and specifically disclaims any express or implied warranties of merchantability or
fitness for any particular purpose. Mobilygen is a registered trademark of Mobilygen
Corporation. All other names mentioned herein — trademarks, registered trademarks, and
service marks — are the property of their respective owners.

.....
i
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PREFACE
Welcome to the MG3500 Programming Getting Started Guide.
This document provides an overview of the MG3500 Mobiapp
application, an overview of the Lua scripting language that is
embedded within MG3500 Mobiapp, how to interface with
Mobiapp, and some sample scripts.
The following topics are covered in Preface:
• “Document Overview”
• “MG3500 Codec Documentation Set”
• “Revision History”
• “References”
• “Contact”

ii Mobilygen Inc. Confidential and Proprietary
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DOCUMENT OVERVIEW
The following are the chapters in this guide:
• Chapter 1," Overview of Programming MG3500 Codec."
• Chapter 2," Codec Objects Definitions."
• Chapter 3," Lua Scripting Language."
• Chapter 4," From Lua to C."
• Chapter 5," Writing Scripts."
• Chapter 6," Setting up Codec Objects."
• Chapter 7," Sample Scripts."
MG3500 CODEC DOCUMENTATION SET
• MG3500 Mobiapp Reference Manual
• MG3500 Codec Firmware API Reference Manual
REVISION HISTORY
This document was prepared by Mobilygen Corporation.
REFERENCES
The following are references to books, documents, and Web sites for three subjects.
[1] Lerusalimschy, Roberto, “Programming In Lua, Second Edition, May 2006.” Lua.org,
December 2003, ISBN 8590379825.
[2] Lerusalimschy, Roberto; de Figueiredo, L. H.; Celes, W., “Lua 5.1 Reference Manual.”
Lua.org, August 2006. ISBN 85-903798-3-3. http://www.lua.org/manual/5.1/.
[3] Mobilygen Corporations, “En-ViE Codec Firmware API Functional Specification, Version
1.0.”
CONTACT
You may contact us at support@mobilygen.com.
Revision Documentation Release Date Notes
Internal: 0.6
External: 1:0
September 21, 2008 First internal release
Second external release

.....
iii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONTENTS
PREFACE......................................................................................... i
Document Overview .................................................................................................... ii
MG3500 Codec Documentation Set .......................................................................... ii
Revision History ............................................................................................................ ii
References ....................................................................................................................... ii
Contact............................................................................................................................ ii
1 Overview of Programming MG3500 Codec ............................ 1
Overview of Mobiapp .................................................................................................2
Mobiapp Architecture ................................................................................................... 2
Other Mobiapp Components ...................................................................................... 3
Overview of Mobiapp User Interfaces .....................................................................4
Lua Scripting .................................................................................................................. 4
C Programs ..................................................................................................................... 4
Overview of Mobiapp C Objects ..............................................................................5
Codec Proxies Object Types ....................................................................................... 5
Live Video PreProcessor (lvpp) ....................................................................... 6
Audio Encoder ................................................................................................... 6
AVC Encoder ..................................................................................................... 6
AVC Decoder ..................................................................................................... 6
Stereo Audio Input ............................................................................................ 7
Host Video Output ............................................................................................ 7
Audio Video Output Composition ................................................................. 7
SAIN .................................................................................................................... 7

iv
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mobiapp Host Object Types ....................................................................................... 7
ReadStreamer ...................................................................................................... 8
WriteStreamer ..................................................................................................... 8
H4V Bitstream Writer ....................................................................................... 8
ADTS Bitstream Writer .................................................................................... 8
Audio Elementary Stream Bitstream Writer .................................................. 8
NetWriter ............................................................................................................. 8
2 Codec Objects Definitions ......................................................... 9
System Control Object Type Definition ................................................................10
Syntax ............................................................................................................................10
System Control Creating Read/Write Streamers ....................................................10
Browsing Object Using FOR Loop ..........................................................................10
Example .............................................................................................................10
ObjectHandles Table ..................................................................................................11
Example .............................................................................................................11
AVC Encoder (avcenc) Definition ..........................................................................12
Example .............................................................................................................12
Methods .............................................................................................................13
Example 1...........................................................................................................13
Example 2...........................................................................................................13
Audio Video Synchronizer (avsn) Definition ........................................................14
Audio Video Output Compositor (avoc) Definition ...........................................14
Read And Write Streamers (rs/ws) Definition ......................................................15
3 Lua Scripting Language .......................................................... 17
Introduction to Lua ...................................................................................................18
Lua and Mobiapp ........................................................................................................18
Lua Advantages ............................................................................................................18
Learning Lua Scripting ..............................................................................................19
Variables and functions ..............................................................................................19
Control Structures ......................................................................................................20
Tables ............................................................................................................................20

.....
v
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Objects ..........................................................................................................................21
Lua Built-ins ................................................................................................................23
Built-in Lua Libraries ..................................................................................................23
Built-in Lua Scripts ......................................................................................................23
4 From Lua to C .......................................................................... 25
Overview of Lua to C ...............................................................................................26
The Lua Application Program Interface ................................................................26
Lua Stacks .....................................................................................................................26
Lua Chunks ...................................................................................................................27
Lua Macros ...................................................................................................................27
Lua States ......................................................................................................................27
Calling API Functions .....................................................................................27
Releasing Lua State ..........................................................................................27
Mobiapp Interaction via C Programs .....................................................................28
Lua Interpreter Plugin ................................................................................................28
Mobiapp Lua Interface Files ......................................................................................28
Lua Objects Bindings ................................................................................................29
C Functions Definition ...............................................................................................29
Registering C Functions .............................................................................................29
Lua to C Sample Script .............................................................................................30
Built-in Scripts ............................................................................................................32
Built-in scripts Location ..................................................................................32
5 Writing Scripts ......................................................................... 33
Steps for Writing Scripts ...........................................................................................34
Prepare to Write Scripts ............................................................................................34
Initialize the Board .....................................................................................................34
Configuring System Parameters Example ...............................................................35
Set up Objects ............................................................................................................35
Setting up Objects Example ......................................................................................36
Bind Objects ...............................................................................................................36
Loading Libraries Example ........................................................................................36

vi
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Start Objects ...............................................................................................................37
Starting Objects Example ...........................................................................................37
Functions ...........................................................................................................37
Preview ...............................................................................................................38
Stop .....................................................................................................................38
Record to file .....................................................................................................38
Estop ..................................................................................................................39
Play from File ....................................................................................................39
Stop Decoder ...................................................................................................40
6 Setting up Codec Objects ........................................................ 41
Objects Creation ........................................................................................................42
Creating an Object Syntax 42
Creating Read/Write Streamers Syntax 42
Objects Configuration ...............................................................................................43
Configuring a Single Object Syntax ..........................................................................43
Configuring Multiple Objects Syntax: configure() Method ..................................43
Configuring Multiple Objects Syntax: setVPortMode () Method ........................44
Objects Activation .....................................................................................................45
Setting up Live Video Pre-Processor (lvpp) Object .............................................46
Creating the lvpp Object ............................................................................................46
Configuring and Activating lvpp Object ..................................................................48
Setting up Non-Real Time Video Pre-Processor (nvpp) Object ........................49
Creating nvpp Object ..................................................................................................49
Configuring nvpp Object ............................................................................................49
Setting up Stereo Audio Input (sain) Object .........................................................50
Creating sain Object ....................................................................................................50
Setting up Audio Video Decoder (avdec) Object .................................................51
Creating avdec Object .................................................................................................51
Configuring avdec Object ..........................................................................................51
Setting up Audio Video Encoder (avenc) Object .................................................52
Creating avenc Object .................................................................................................52
Configuring avcenc Object ........................................................................................52

.....
vii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up Audio Video Synchronizer (avsn) Object ...........................................53
Creating avsn Object ...................................................................................................53
Setting up Audio Video Output Compositor (avoc) Object ...............................54
Creating avoc Object ..................................................................................................54
Configuring avoc Object ............................................................................................54
Setting up Read/Write Streamer (rs/ws) Objects .................................................55
7 Sample Scripts .......................................................................... 57
Encoding Pipeline Sample Scripts ...........................................................................58
Basic Encoding Pipeline Sample Script ....................................................................58
Multi-channel Encoding Pipeline Sample Script ....................................................58
Composing Audio Video Channel Sample Script .................................................60
Creating and Initializing avoc Sample Script .........................................................61
Adding and Configuring vc to avoc Sample Script ..............................................62
Setting up Video Output Timing ................................................................................ 6

viii
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
OVERVIEW OF
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROGRAMMING MG3500 CODEC
Mobilygen G3500 provides a host reference application called
Mgapp, which in turn has its own plugin called Mobiapp.
The following topics are covered in this chapter:
• “Overview of Mobiapp”
• “Overview of Mobiapp User Interfaces”
• “Overview of Mobiapp C Objects”

O VE R V I E W O F P R OG R A M M I N G M G 3 5 0 0 C O D E C
Overview of Mobiapp
2 Overview of Mobiapp
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OV E R V I E W O F M O B I A P P
Mobiapp is Mgapp’s main application that controls the operations and the datapath of the
Codec. Mobiapp is an instance of Mgapp in a form of a shell script that loads the Mobiapp
shared object (.so) and passes the appropriate command-line arguments to the Mobiapp
plugin’s entry point. If used “as is,” Mobiapp controls the operations of the MG3500 audio
and video Codec while acting as a reference for a customer-developed application.
See-> MG3500 Mobiapp Reference Manual for detailed information about the Mobiapp plugin
application.
Topics in this section are
• “Mobiapp Architecture”
• “Other Mobiapp Components”
MOBIAPP ARCHITECTURE
Mobiapp consists of two main components: Interface Component (Lua Interpreter and C
Programs) as well as C Objects Component. By default, the Interface component represents
the user interface files that implement the Lua interface. These interface files, also known as
Lua Binding, are identified as UI_SRC in the Mobiapp Makefile and include all of the Lua
shell functionality.
The C Object component, however, consists of a set of C functions that implement the
Codec APIs and are indicated as the Core source in the Mobiapp Makefile. These C functions
implement commands and events handlings, bitstreams storage, and retrieval and other
necessary functions.
See-> Section “Overview of Mobiapp User Interfaces,” for a brief introduction to Lua and C
programs to interface with Mobiapp.
See-> Section “Overview of Mobiapp C Objects,” for brief descriptions of the two types of
Codec’s C objects: Proxies and Host.
See-> Section “Other Mobiapp Components,” for references to the boot loader and Codec
commands components of Mobiapp.

.....
Overview of Mobiapp
Overview of Mobiapp 3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OTHER MOBIAPP COMPONENTS
In addition to the Mobiapp interfaces and C objects, two other components comprise
Mobiapp: Boot loader, as well as Codec Command and Event Protocol control.
See-> MG3500 Mobiapp Reference Manual for information on Firmware loader as well as the
commands that implement the Codec commands and event protocols.

Overview of Mobiapp User Interfaces
4 Overview of Mobiapp User Interfaces
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OV E R V I E W O F MO B I A P P US E R IN T E R F A C E S
Mobiapp uses command-line shells as well as the Lua interpreter as its main interface to
control the operations of the MG3500 Codec. Lua interpreter enables Mobiapp to fully test
the entire Codec APIs without using a C compiler or additional tools.
Although the Lua interpreter acts as the user interface of the Mobiapp plugin, building other
user interfaces in C programs that either access the Mobiapp’s C programs objects directly
or use the Lua scripting language through standard and non-interactive mechanisms is also
possible.
• “Lua Scripting”
• “C Programs”
LUA SCRIPTING
Mobiapp uses a Lua interpreter that has been extended with bindings to the C objects.
These Lua bindings allow writing scripts to perform all or some of the Codec operations
without using a compiler or tools other than a text editor. The Lua interpreter is generated
both as an interactive console session and as a server that can execute Lua chunks from a
remote host via a socket interface.
Scripts can be stored in files which can be loaded and executed from the command line
prompt, by using the following command:
mobiapp –f <script path>
See-> Chapter 3," Lua Scripting Language," for more information about the Lua
interpreter.
The Lua Programming Language Manual for complete information about Lua scripting
language.
C PROGRAMS
Using the Lua as the interface to Mobiapp is optional since all of the states and functions
can be achieved through C code to interact with the C objects. You may choose to write
applications that directly use the C objects and completely bypass Lua. However, keep in
mind that the standard use of the Mobiapp reference application is through the Lua
interpreter and shell along with scripts that manipulate the C objects appropriately.

.....
Overview of Mobiapp C Objects
Overview of Mobiapp C Objects 5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
See-> Chapter 4," From Lua to C," for instructions to remove Lua from your system and
write your own C codes to interface with Mobiapp.
OV E R V I E W O F MO B I A P P C OB J E C T S
The MG3500 API is implemented by using a set of Codec’s object types. These Codec
objects are created, controlled, and deleted both by using commands sent from the host to
the Codec and through events that are received by the host and sent by the Codec.
Mobiapp implements a set of host-side objects which are "proxies" for their corresponding
Codec object. This means that when a host object is created, a matching Codec object
associated with that host object will be created as well. Similarly, when an API call is made to
a host object, a corresponding command will be sent to the matching Codec object.
Included in Mobiapp is a set of objects that are written in C. These C objects enable
Mobiapp to both implement the Codec’s API for each of the Codec’s proxy Object types, or
to provide functionality related to bitstreams and meta-data created by the Codec Host-only
Objects.
• Codec Proxies Objects
• Host Objects
See-> MG3500 Mobiapp Reference Manual for detailed information about the Mobiapp C
objects.
CODEC PROXIES OBJECT TYPES
The objects that reside on the host are referred to as “Codec Proxy Objects,” when they
exist primarily to control a Codec object.
See-> Chapter 2," Codec Objects Definitions," for definitions of the C objects.
See-> MG3500 Mobiapp Reference Manual for detailed information on these objects.
The following is a list of all available Codec proxy object types along with brief descriptions
of each object.

6 Overview of Mobiapp C Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIVE VIDEO PREPROCESSOR (LVPP)
LVPP Controls the Video Input (VIP) and Video Pre-Processor (VPP).
AUDIO ENCODER
The audio encoder is a Codec peer object that implements the API of the Codec’s audio encoder
object.
AVC ENCODER
The AVC encoder is a Codec peer object that implements the API of the Codec’s AVC encoder
object. It controls the Audio and Video Encoder.
AVC DECODER
The AVC decoder is a peer object for the Codec’s Audio-Video Decoder.
Mobiapp Object Type LVPP Object Name
Codec API qlvpp.h
C Object lvppapi.h, lvppapi.c
Lua bindings lvpplua.c
Codec API qaudenc.h
C Object audencapi.h, audencapi.c
Lua bindings audenclua.c
Codec API qavcenc.h
C Object avcencapi.h, avcencapi.c
Lua bindings avcenclua.c
Codec API qavdec.h
C Object avdecapi.h, avdecapi.c
Lua bindings avdeclua.c

.....
Overview of Mobiapp C Objects 7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STEREO AUDIO INPUT
The stereo audio input is a Codec peer object that implements the API of the Codec object.
HOST VIDEO OUTPUT
The host-video output object acts as both a proxy for the Codec HVOUT object as well as
implementing an event handler for the HVOUT itself.
AUDIO VIDEO OUTPUT COMPOSITION
This object is a peer object for the Codec’s Audio-Video Output Compositor.
SAIN
The stereo audio input is a Codec peer object that implements the API of the Codec object.
MOBIAPP HOST OBJECT TYPES
While most host objects are proxies for Codec objects, some host objects implement
functionality on their own and do not have a peer Codec object. These objects are typically
related to bitstream management and include the readstreamer and writestreamer objects.
READSTREAMER
The readstreamer is a host-only object that is responsible for reading bitstreams from the
Codec, formatting them appropriately, and then storing or transmitting them to the ultimate
destination.
• C Object—readstreamer.c
• Lua bindings—readstreamerlua.c
Codec API qsain.h
C Object sainapi.h, sainapi.c
Lua bindings sainlua.c
Codec API qhvout.h
C Object hvoutapi.h, hvoutapi.c
Lua bindings hvoutlua.c

8 Overview of Mobiapp C Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WRITESTREAMER
The writestreamer object handles bitstream writer.
• C Object—writestreamer.h, writestreamer.c
• Lua bindings—writestreamerlua.c
H4V BITSTREAM WRITER
The H4V bitstream writer is capable of writing an H.264 elementary video stream when
receiving a AVC QBOX stream from the MG3500.
• C Object—h4vwriter.c
ADTS BITSTREAM WRITER
The ADTS bitstream writer is capable of writing ADTS compliant streams when used with
the AAC-LC audio encoder on the MG3500
• C Object—adtswriter.c
AUDIO ELEMENTARY STREAM BITSTREAM WRITER
The audio elementary stream bitstream writer is designed to write bitstreams from audio
Codecs whose payloads are entirely self-describing.
• C Object—aeswriter.c
NETWRITER
The network bitstream writer is capable of writing raw QBOX or video elementary streams
across IP networks using either UDP or TCP sockets. Unlike RTP which has a control and
data socket pair, the netwriter features only a single data socket.

9
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CODEC OBJECTS DEFINITIONS
The MG3500 API is implemented using a set of Codec object
types that provide a scalable interface. Codec Objects are
comprised of Codec Proxy Objects, including System Control
object as well as Codec Host-only Objects.
• “System Control Object Type Definition”
• “AVC Encoder (avcenc) Definition”
• “Audio Video Synchronizer (avsn) Definition”
• “Audio Video Output Compositor (avoc) Definition”
• “Read And Write Streamers (rs/ws) Definition”

C O D E C O B J E C T S D E F I N I T I O N S
System Control Object Type Definition
10 System Control Object Type Definition
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SY S T E M C O N T R O L OB J E C T TY P E DE F I N I T I O N
The system control object (sysctl0) is responsible for overall system configuration. This
object is created and made available to the Mobiapp application immediately after booting
the media engine. All other objects used in a system are created by users with reference to
the sysctl0 object. The Codec System Control object is a Class Factory.
See-> Factory Method Pattern for more information about the Class Factory type.
SYNTAX
The following structure shows the method used in defining the sysctl0 object:
sysctl0:<classname>Create([args])
Where,
classname is the class to which an object belong, for example LVPP,
args is the arguments that specifies the object.
SYSTEM CONTROL CREATING READ/WRITE STREAMERS
The exceptions to the rule described above are the read and write streamers. The following
syntax shows how they are created:
rs = sysctl0:createReadStreamer ([args])
ws = sysctl0:createWriteStreamer([args])
BROWSING OBJECT USING FOR LOOP
The system control object (sysctl0)is a global variable that is automatically created when
Mobiapp is first booted.
EXAMPLE
print(sysctl0)
This prints the address of the table.
for k, v in pairs(sysctl0) do print(k,v) end
This example shows all the elements of the system control object.

.....
CO D EC O B J E C T S D E F I N I T I O N S
System Control Object Type Definition
System Control Object Type Definition 11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OBJECTHANDLES TABLE
One important table is the “objectHandles.” Every time the System Control object creates
an object, a key is added with the object name.
EXAMPLE
sysctl0:avsnCreate{name = “avsn0”}
When sysctl0 creates an avsn object, users can find a reference to that object by iterating
through the objectHandles table. This is shown below:
for k, v in pairs(sysctl0.objectHandles) do
print(k,v)
end
The for loop shown below lists the methods of the avsn object.
for k, v in pairs(sysctl0.objectHandles.avsn0) do
print(k,v)
end

AVC Encoder (avcenc) Definition
12 AVC Encoder (avcenc) Definition
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AVC EN C O D E R ( A V C E N C ) DE F I N I T I O N
The avcenc object enables encoding pre-processed video input frames. This object can
receive an input from the lvpp or the nvpp. The avcenc object supports a wide variety of
tools which allow the bitstreams generated to conform to the various profiles and levels
specified by the H.264 standard. Additionally, avcenc allows the user to tune parameters to
get the best possible video quality at the lowest bit-rate for a specific video application. The
avcenc has a similar construct to ObjectHandles table.
See-> Section “ObjectHandles Table” for syntax and an example for setting up
ObjectHandles tables.
EXAMPLE
The following defines the variables used in the above example:
name is a name assigned by the user to a particular instance of this object, for
example "avcenc0."
ws associates the encoder object with an instance of the writestreamer. The
host notifies this writestreamer whenever there is a bitstream from this
encoder instance that needs to be written to a file or streamed out.
maxwidth specifies the maximum width of the video frames that will be input to the
encoder. This number can be up to 1920 frames.
maxheight specifies the maximum height (modulo 16) of the video frames that will
be input to the encoder.
numreferenceframes
specifies the number of reference frames used by the encoder. This
number depends on the encoding profile. A minimum of four reference
frames must be used when encoding a baseline profile stream. Main and
high profile streams need a larger number of reference frames.
avcenc0 = sysctl0:avcencCreate({
name = "avcenc0",
ws = ws,
maxwidth = HSIZE,
maxheight = VSIZE16
numreferenceframes = NUM_AVC_REFERENCES,
outputbuffersize = ENC_OUTPUT_BUFFER
});

.....
AVC Encoder (avcenc) Definition
AVC Encoder (avcenc) Definition 13
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
outputbuffersize
specifies in bytes the amount of memory allocated for storing compressed
bitstreams generated by the encoder. A number commensurate with the
encoding bit-rate must be selected.
maxwidth, maxheight, and numreferenceframes determine the amount of memory
allocated to store video frames for an instance of the encoder.
Note: Make sure sufficient amount of memory is allocated for the system to run smoothly.
The video encoder uses several methods which effectively perform the same function as the
Param() method used by the other objects.
METHODS
setVideoEncParam()— general configuration.
setVideoEncRegionParam()— configures parameters specific to video regions.
setVideoEncRateControlParam()— configures parameters specific to encoder rate
control.
Note: The parameters for the different functions are effected using a single activate
command.
EXAMPLE 1
See-> Section “Built-in Lua Libraries,” in Chapter 3," Lua Scripting Language," for more
information about avcenc functions.
The sample Lua scripts distributed with the SDK release use a single function that
encompasses all the initialization required for the video encoder.
EXAMPLE 2
The example below shows the function used to configure avcenc for 720p60 encoding:
See-> The MG3500 Codec Firmware API Reference Manual for a list of the configuration
parameters that may be used with the encoder.
avcenc0:setVideoEncParam({
param=Q_AVCENC_CMP_BITSTREAM_OUTPUT,
value=BITSTREAM_OUTPUT});
avcenc0:activateVideoEncCfg();
avcenc_720p60(avcenc0, PROFILE, AVC_LEVEL, VBITRATE,
gopstruct, FRAME_STRUCTURE)

Audio Video Synchronizer (avsn) Definition
14 Audio Video Synchronizer (avsn) Definition
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AU D I O VI D E O SY N C H R O N I Z E R ( A V S N ) DE F I N I T I O N
The avsn object allows synchronizing audio and video. This object is required in preview
and decode modes. If independent audio and video outputs are required, separate avsn
objects may be created and bound to the appropriate objects upstream.
When bound to an avoc video or audio channel, the avsn must then be in the “running”
state, otherwise failure to do so will lock the pipeline. Conversely, when unbound from an
avsn video or audio channel, the avsn state must be set to the “idle” state.
A quick solution to resolve these types of issues is to use the avsn:query() method.
Underflows are an indication of a problem downstream.
AU D I O VI D E O OU T P U T CO M P O S I T O R (A V O C ) DE F I N I T I O N
The avoc object provides the ability to present video and audio frames. This object can be
used to display a single channel output, switch between channels or display a composed
frame based on the video channel created and bound. Additionally, this object configures
video output timing.
Note: Only video channel are guarantied to be glitch less.
The following steps list general guidelines for configuring the avoc object:
1 Configure the display window and audio parameters, if required.
2 Add and activate audio channels as required by the application.
3 Configure the timing for the display unit.

.....
Read And Write Streamers (rs/ws) Definition
Read And Write Streamers (rs/ws) Definition 15
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RE A D AN D WR I T E ST R E A M E R S (R S /W S ) DE F I N I T I O N
The read and write streamer objects are host-only objects. They read from and write to host
memory when the Codec is decoding or encoding respectively.
Note: An instance of an encoder or decoder object must be associated with a
writestreamer or readstreamer object.
The purpose of the streamers is to dispatch data to bitstream readers or writers which are
registered in the system. It is, then, possible to pipe the data to multiple destinations such as
a file and an RTP session at the same time.
Note: When no bitstream writers are opened, disabling the bitstream output from the avc
encoder is important. Otherwise data will queue up without being consumed.

Read And Write Streamers (rs/ws) Definition
16 Read And Write Streamers (rs/ws) Definition
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LUA SCRIPTING LANGUAGE
Lua is a powerful, fast, light-weight, and embeddable scripting
language. It combines simple procedural syntax with powerful
data description constructs based on associative arrays and
extensible semantics. Mobiapp uses the Lua interpreter that
has been extended with bindings to the C objects.
• “Introduction to Lua”
• “Learning Lua Scripting”
• “Lua Built-ins”

L U A S C R I P T I N G L A N G U A G E
Introduction to Lua
18 Introduction to Lua
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IN T R O D U C T I O N T O LU A
Lua is an object oriented, extensible, and embeddable scripting language. A Lua interpreter
can be extended by bindings to the C objects. The Lua bindings allow for much or all of the
MG3500 Codec operation to be scripted without the use of a compiler or tools other than a
text editor. Lua is dynamically typed, runs by interpreting byte code for a register-based
virtual machine, and has automatic memory management with incremental garbage
collection, making it ideal for configuration, scripting, and rapid prototyping.
See-> The Lua Programming Language Manual for complete information about Lua scripting
language.
LUA AND MOBIAPP
The Lua interpreter can be considered to be the "user interface" of the Mobiapp plugin. It
is, however, possible to build other user interfaces that either access the C objects directly or
that invoke the Lua interpreter through standard, non-interactive mechanisms.
Using Lua in a product is completely optional as all states and functions can be achieved
through C code which interacts with the C objects. You may completely bypass Lua,
however, only when you make use of C objects and write applications that make direct use
of the object. However, keep in mind that the standard use of the reference application is
through the Lua interpreter and shell, along with scripts that manipulate the C objects
appropriately.
LUA ADVANTAGES
Lua is an superior prototyping language because
• No compilation is required; just change and run.
• No memory allocation (garbage collector).
• Built-in associative arrays and hash tables.
• Comprehensive back trace (no core dump to analyze).
• Fast and lightweight scripting language.

.....
Learning Lua Scripting
Learning Lua Scripting 19
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LE A R N I N G LU A SC R I P T I N G
This section describes the semantics of the Lua scripting language, including Lua variables,
functions, control structure, tables, and objects.
VARIABLES AND FUNCTIONS
In Lua, any string that is not a reserved keyword is considered to be an identifier. When an
identifier is not initialized, it is set by default to “null.”
The print function takes positional parameters and prints them regardless of their type. The
printf function (not built in) can be created as follow.
Functions are first class values which means that they can be stored in variables as illustrated
above with the “foo” identifier which contains the address of printf.
-- prints "Type of myVar is null"
print("Type of myVar is ", type(myVar))
myVar = "Hello world!"
-- prints "Type of myVar is string"
myVar = true
-- prints "Type of myVar is boolean"
myVar = 123.99
-- prints "Type of myVar is 123.99"
-- prints "Type print is function"
print("Type print is ", type(print))
function printf(...)
print(string.format(unpack(arg)))
end
foo=printf
printf("myVar is set to %f and the type is %sn", myVar,
type(myVar))
foo("hello worldn")

20 Learning Lua Scripting
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functions can return more than one value as shown below:
CONTROL STRUCTURES
The most common control structures:
TABLES
Tables are one of the most important constructs in Lua. Everything in Lua is part of a table.
For example, the global name space (called _G), where the variables and functions listed
above are stored, is a table.
The “constructor expression” for a table is {}.
--[[ Formal parameters are declared between ()
Functions can return one or more return value
--]]
function func(arg1, arg2, arg3)
print(arg1, arg2, arg3)
return arg1, arg2, arg3
end
v1, v2, v3 = func(1,2,3)
print(v1,v2,v3) -– prints 1 2 3
-- Generic form of an if statement
if cond1 and (cond2 or cond3) then
elseif cond4 then
else
end
-- Generic for loop
for i=min,max do
...
end
-- Generic while loop
while(cond) do
...
end
a = {}; print(type(a)) -- prints 'table'

.....
Learning Lua Scripting 21
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Use the following to see the list for an in the global namespace:
Where i is an identifier, and v its a value.
Tables can be used as “standard arrays,” “associative arrays,” or a combination of both.
There are two main table iterators in Lua: “ipair” and “pairs.” Ipairs iterates through the
indexed elements of a table while pairs iterates through all elements.
The first index is by convention 1. Hence to print the first element, you may type comb[1]
and to print the first key comb.key or comb[“key”].
Note: Tables are an important concepts since not only they are used to implement objects
but they pass actual parameters to the MG3500 API.
OBJECTS
Objects are in their simplest form tables for which some keys are references to functions.
for i, v in pairs(_G) print(i, v)
array = {1,2,3,4}
assoc = (key1 = 1, k2 = "string", key3 = true)
comb = {1,2, key1 = "string", 4)
> for k, v in ipairs(comb) do print(k,v) end
1 1
2 2
3 4
> for k, v in pairs(comb) do print(k,v) end
1 1
2 2
3 4
key1 string
object = {self = 1}
function object:method1(options)
self.member = options
end
function object.method2(self, options)
self.member = options
end

22 Learning Lua Scripting
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
In this case, the object is a “singleton.”
See-> The Lua Programming Language Manual for more advanced topics on classes and
objects.
There is technically no difference between the first and the second methods: The use of
colon, “:” is a more elegant way to make the self (the reference to the object table in this
particular case) implicit.
Throughout the code script example, you will often see
where
sysctl0 is the reference to an object,
configure is one of its method,
{…} is a table containing its actual arguments.
is equivalent to the first form.
Mobilygen is using tables as a convention to pass parameters. This has the advantage of
removing the constraint of using positional parameters, make this call equivalent to the first
one.
Note: Lua does not require statements to end with a semi-colon, “; ”.
sysctl0:configure({param=Q_SYS_CFG_VIN0_CONTROL,
value=0x00048249});
sysctl0.configure(sysctl0, {param=PARAMNAME, value=VALUE});
sysctl0:configure({value=0x00048249},
param=Q_SYS_CFG_VIN0_CONTROL});

.....
Lua Built-ins
Lua Built-ins 23
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LU A BU I L T -I N S
BUILT-IN LUA LIBRARIES
Included with Lua comes is a set of built in libraries, including the following most important
ones:
1 IO—Input/Output facilities.
2 OS—Basic OS facilities.
3 Table—Table manipulation.
4 String—String operators and manipulation.
5 Math—Math library.
See-> The Lua 5.1 Reference Manual for detailed information about the Lua scripting
language.
BUILT-IN LUA SCRIPTS
The Mobiapp application includes several Lua scripts that are executed automatically at the
startup. The Lua scripts are located in <host>/luascripts/builtin and are executed according
to their numerical sort order given that each script is named with a leading number such as
40board, 60libavcenc, etc.
See-> Chapter 4," From Lua to C," to transition from the Lua scripting language to writing
your own C codes.
See-> Chapter 5," Writing Scripts," to learn how to learn about the steps for writing a Lua
script.

Lua Built-ins
24 Lua Built-ins
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FROM LUA TO C
Lua is a lightweight script language, an extension to an existing
program in C that allows configuring programs and modifying
run-time behavior. Being an extension language, Lua can only be
embedded in a host client, called the host. This host program can
then invoke functions to execute a piece of the Lua code, read
and write Lua variables, and register C functions that are called
upon by Lua code. By using the C functions, Lua can be
enhanced to cope with a wide range of different domains, thereby
creating customized programming languages that share a
syntactical framework.
• “Overview of Lua to C”
• “The Lua Application Program Interface”
• “Mobiapp Interaction via C Programs”
• “Lua Objects Bindings”
• “Lua to C Sample Script”
• “Built-in Scripts”

FR O M L U A TO C
Overview of Lua to C
26 Overview of Lua to C
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OV E R V I E W O F LU A T O C
Lua is the ideal scripting language that enables rapidly prototyping of your Mobiapp system
since it can be dynamically typed, interpreted from bytecodes, and is able to manage
memory automatically with garbage collection.
Alternatively, you may use C programs to call Mobiapp by translating Lua calls to C or C++.
Understanding the Lua Application Program Interface is important since it will provide the
information necessary to transition from Lua to C. It also explains how Lua interfaces with
the Mobiapp plugin.
TH E LU A AP P L I C A T I O N PR O G R A M IN T E R F A C E
This section describes the C API for Lua that are basically a set of C functions available to
the host program that communicates with Lua.
Topics covered in this section are
• “Lua Stacks”
• “Lua Chunks”
• “Lua Macros”
• “Lua States”
LUA STACKS
Lua is intended to be embedded into other applications, which results in providing a robust,
easy to use “C APIs.” The Lua API makes extensive use of a global “stack” which is used to
pass parameters to and from Lua and C functions. Lua, then, provides functions to push and
pop most simple C data types (integers, floats, etc.) to and from the stack, as well as
functions for manipulating tables through the stack. Arranging data between C and Lua
functions is also done using the Lua stack.
To call a Lua function, arguments are pushed onto the stack, and then the “lua_call” is used
to call the actual function. When writing C functions that can be to be directly called from
Lua, the arguments are popped from the stack.
The Lua stack is somewhat different from a traditional stack in that it can be indexed
directly. Negative indices indicate offsets from the top of the stack (for example, -1 is the last
element), while positive indices indicate offsets from the bottom.

.....
FR O M L UA T O C
The Lua Application Program Interface
The Lua Application Program Interface 27
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LUA CHUNKS
A Lua “Chunk” is basically a sequence of statements that refers to each piece of the code
that Lua executes. An example is a file or a single line in an interactive mode.
A chunk may be as simple as a single statement, such as in the "hello world" example, or it
may be composed of a mix of statements and function definitions, which are actually
assignments such as the factorial example. A chunk may be as large as you wish. Because
Lua is used also as a data-description language, chunks with several megabytes are not
uncommon.
LUA MACROS
All API functions and related types and constants are declared in the header file lua.h.
Reference to the term "function" can be considered as a “Lua macro facility” in the API
instead. The macro facility is similar to the C pre-processor although it works on an already
pre-digested token stream and is not a separate program through which Lua code is passed.
All such macros use each of its arguments exactly once (except for the first argument, which
is always a Lua state), and so do not result in hidden side-effects.
The Lua macros have been defined by Mobilygen to simplify binding creation. Their
definition can be found in the luadef.h header file in the Mobiapp plugin source tree.
LUA STATES
The Lua library does not contain any global variables. The entire state of the Lua interpreter
(global variables, stack, etc.) is stored in a dynamically allocated structure of type
“lua_State.” A pointer to this state must be passed as the first argument to every function
in the library, except to lua_open, which in turn creates a Lua state from scratch.
CALLING API FUNCTIONS
Before calling any API function, first create a state by calling lua_open
lua_State *lua_open (void);
RELEASI NG LUA STATE
To release a state created with lua_open, call lua_close
void lua_close (lua_State *L);
This function destroys all objects in the given Lua state by calling the corresponding
garbage-collection methods, if any, while freeing up all dynamic memory used by that state.
Calling this function on many platforms may not be needed since all resources are naturally

FR O M L U A TO C
Mobiapp Interaction via C Programs
28 Mobiapp Interaction via C Programs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
released when the host program ends. However, programs that take a long time to run, such
as a daemon or a web server, might need to release states as soon as they are not needed to
avoid growing too large.
MO B I A P P IN T E R A C T I O N V I A C PR O G R A M S
Lua is a scripting language that enables full testing of the entire codec APIs without the use
of a C compiler or tools.With Lua only an editor is necessary.
• “Lua Interpreter Plugin”
• “Mobiapp Lua Interface Files”
LUA INTERPRETER PLUGIN
The mobiapp plugin is not sufficient to build an application since an application framework
or user interface must be added first. Mobilygen supplies a second plugin called “ui_lua”
which implements a Lua interpreter with bindings to the mobiapp plugin, allowing the
codec APIs to be fully scriptable. The name of the Lua plugin ui_lua refers to the Lua
interpreter as the user interface for Mobiapp.
The ui_lua plugin is fully removable and optional from mgapp simply skipping the loading
of the plugin.
MOBIAPP LUA INTERFACE FILES
All types of the MG3500 Codec objects, such as sysctl and avcenc, are implemented using
three different types of files:
• C program files—For example, avcencapi.c.
• Header fils—For example, avcenc.h.
• Lua binding files—For example, avcenclua.c.
See-> Section “Overview of Mobiapp C Objects,” in Chapter 1," Overview of Programming
MG3500 Codec."
See-> Chapter 2," Codec Objects Definitions," for detailed information on the Codec
objects.

.....
FR O M L UA T O C
Lua Objects Bindings
Lua Objects Bindings 29
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LU A OB J E C T S BI N D I N G S
The ui_lua plugin provides a set of Lua bindings that connect the C object APIs to Lua
functions so that each C API is made available as a Lua function call. Since the Lua bindings
are object-oriented, the bindings create and manage Lua objects. Each Lua object contains
in its private data a pointer to an underlying C object which is hidden from a scripting
perspective. The Lua essentially "wraps" the C object and makes that C object directly
scriptable.
The purpose of the Lua binding file, then, is to register C functions with Lua and translate
arguments from the Lua domain to the C domain via the Lua stack.
• “C Functions Definition”
• “Registering C Functions”
C FUNCTIONS DEFINITION
Lua can be extended with functions written in C. These functions must be of type
lua_CFunction, defined as
typedef int (*lua_CFunction) (lua_State *L);
A C function receives a Lua state and returns an integer, which is the number of values it
wants to return to Lua.
REGISTERING C FUNCTIONS
The following macro shows how registering a C function to Lua is done:
In this example, the function receives the name it will have in Lua and a pointer to that
function. Thus, the C function foo above may be registered in Lua as average by calling
#define lua_register(L,n,f)
(lua_pushstring(L, n),
lua_pushcfunction(L, f),
lua_settable(L, LUA_GLOBALSINDEX))
/* lua_State *L; */
/* const char *n; */
/* lua_CFunction f; */
lua_register(L, "average", foo);

FR O M L U A TO C
Lua to C Sample Script
30 Lua to C Sample Script
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The signature of AVCEncoderAPI_Create is identical to the Lua method and any
reference to Lua objects is translated to their corresponding C object using the
CommonAPI_Gelua_CFunctiontCodecObjectId()API.
LU A T O C SA M P L E SC R I P T
Typically, the C implementation simply translates the C API to an opcode or payload which
is then sent to the MG3500 Codec via the QHAL driver. This is illustrated in the example
that follows:
int AVCEncoderAPI_BindVideoInput(AVCENC_HANDLE h, void * vpp)
{
COMMAND cmd;
int rval;
AVCENC_HANDLE_PRIV *this = (AVCENC_HANDLE_PRIV *)h;
STRUCT_Q_AVCENC_CMD_BIND_VIDEO_INPUT *pArgs =
(STRUCT_Q_AVCENC_CMD_BIND_VIDEO_INPUT
*)cmd.arguments;
int ctrlObjID = CommonAPI_GetCodecObjectId(vpp);
CommonAPI_ClearCommand(&cmd);
// build command
cmd.controlObjectId = this->cd.id;
cmd.opcode = Q_AVCENC_CMD_BIND_VIDEO_INPUT;
pArgs->ctrlObjID = ctrlObjID;
// Send request to the main thread
rval = MWare_BlockingSendCommand(this->hmw, &cmd);
return rval;
}

.....
FR O M L UA T O C
Lua to C Sample Script
Lua to C Sample Script 31
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Lua binding for the function listed is the example shown below.
Because C functions (e.g. AVCEncoderAPI_BindVideoInput) can not be called directly, a
stub is defined. By convention, stub functions start with cli<function name> as shown in the
example above. Stubs are registered with Lua at creation time.
/// brief AVCEncoderAPI.bindVideoInput
///
/// usage: filename
///
/// AVCEncoderAPI.bindVideoInput
///
int cliAVCEncoderAPI_BindVideoInput(lua_State *L)
{
AVCENC_HANDLE h;
void * src;
LUA_GET_SELF(h);
src = getHandle(L, "src");
AVCEncoderAPI_BindVideoInput(h, src);
return 0;
}

FR O M L U A TO C
Built-in Scripts
32 Built-in Scripts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BU I L T -I N SC R I P T S
The ui_lua plugin contains several "built-in" Lua scripts. These scripts are included in the
plugin at compile-time and are automatically executed when the scripts are loaded. The
built-in scripts include the board abstraction library that are used to control video input and
output as well as various utilities to help debug and initialize the board.
These higher-level functions that enable encapsulating complex Codec configuration
routines that are known as built-ins are written exclusively in Lua.
Included in Mobiapp at compile time as Lua chunks, these higher-level functions are
compiled and executed at startup time by the Lua interpreter and then embedded in
Mobiapp. At the present time, translating the built-in libraries to C and so making them
accessible from a C program is necessary.
BUI LT-I N SCRI PTS LOCATION
Built-ins can be found under the following location:
<install dir>/merlinsw/host/luascripts/builtin
See-> Chapter 5," Writing Scripts." for learning about the basic steps for writing scripts.
See-> Chapter 7," Sample Scripts." for sample scripts that illustrate the fundamental parts
required to configure and operate the MG3500 Codec.

33
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WRITING SCRIPTS
Writing scripts requires understanding some general rules to
help the user create their own scripts.
• “Steps for Writing Scripts”
• “Prepare to Write Scripts”
• “Initialize the Board”
• “Set up Objects”
• “Bind Objects”
• “Start Objects”

WR I T I N G S C R I P T S
Steps for Writing Scripts
34 Steps for Writing Scripts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ST E P S F O R W R I T I N G S C R I P T S
Writing a script consists of the following steps:
1 “Prepare to Write Scripts”
2 “Initialize the Board”
3 “Set up Objects”
4 “Set up Objects”
5 “Bind Objects”
6 “Start Objects”
P R E P A R E T O W R I T E SC R I P T S
Objects follow a producer-consumer model. Every object has an input port and an output
port and accepts an input type to produce an output. An object may be a producer and a
consumer depending on where it is located in the data path. The relationship between a
producer and consumer can be one-to-one (avcenc), one-to-many (lvpp), or many-to- one
(avsn).
Example of a one-to-one model would be the producer object lvpp bound to consumer
object avcenc. Example of a one-to-many model would be the producer object avcenc
bound to consumer objects hvout and avoc. This also shows that the avcenc object is a
consumer and a producer.
IN I T I A L I Z E T H E BO A R D
Board I/Os configuration is encapsulated into the board object. The board object is defined
as part of the built-in scripts that are compiled in Mobiapp, called “40board.lua.”
This object detects the board types, configures peripherals, sets up clocks, and programs
registers that control audio and video input timing and other objects.
The implementation of board objects is specific to the hardware that is used, in this case the
MG3500 Evaluation Platform as the target hardware. Users may refer to the 40board.lua
file to create their own.

.....
Set up Objects
Set up Objects 35
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONFIGURING SYSTEM PARAMETERS EXAMPLE
The above methods configure the “hdmi” receiver and transmitter on the MG3500 EVP to
format and output the video input and output to 720p resolution.
Caution! The board object is a singleton which is available in the global Lua namespace.
Make note of the usage of “a.” as opposed to “a:” between board and the method being
called, for example board.setVideoOutput versus avcenc0:query().
Tip: To avoid recompiling Mobiapp every time a change is made to the board object, you
may specify the new board object on the Mobiapp command line. When Mobiapp starts, it
will execute the default board detection and map the I/O configuration functions to the
entry points in the board object. At this point, I/Os are not configured.
Mobiapp will then load and execute the board file specified on the command line. Board
detection will be performed one more time and the new code will be mapped to the entries.
Caution! This method will still work even if an error message displays when a new board
type introduced as the first board is detected and fails, which will result in Mobiapp aborting
any execution. Notice that if a new board file is added to the Linux distribution
(dist/linux/mobilygen/drivers/boards), a corresponding entry needs to be added to
the board object.
SE T U P O B J E C T S
After the board is initialized and the system is configured, for the next step objects need to
be created.
The following is an example of how an object is created.
board.setVideoOutput({port=0, format='720p',mode='hdmi'});
board.setVideoInput({port=0, format='720p',mode='hdmi'});
mobiapp –f myboard.lua –f myscript.lua

Bind Objects
36 Bind Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S E T T I N G U P O BJ E C T S E X A M P L E
See-> Chapter 2," Codec Objects Definitions," for descriptions of the two types of objects
provided by Codec, Codec Proxy objects and Host-only objects.
See-> Chapter 6," Setting up Codec Objects," for detailed instructions for setting up the
objects.
BI N D O B J E C T S
The preview( ) function below describes the binding of objects and the order in which they
must be started.
To simplify the configuration process, functions common to an object are compiled into
libraries. These libraries are provided with the reference code and must be made available to
the Lua environment to execute the scripts.
LOADING LIBRARIES EXAMPLE
The following sample script will show several examples of libraries being loaded. Notice that
the MG3500 uses single-buffered and double-buffered configuration parameters.
lvpp0 = sysctl0:lvppCreate{
name ="lvpp0",
slot =0,
port =0,
maxWidth =1280,
maxHeight =720,
numVidFrame =11,
numPMEDSFrame =11,
maxPMEDSFactor =2
}
function preview()
avsn0:bindVideoInput({src=lvpp0});
avsn0:start();
lvpp0:start();
end

.....
Start Objects
Start Objects 37
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
In firmware single-buffered parameters use a “CFG” tag and double-buffered parameters
use a “CMP” tag.
Both types of parameters may be issued at any time during system operation but double-
buffered parameters must be activated before they become effective. In the Lua space, each
object has an activate method associated with that object that conforms the following:
<classname>:activateCfg()
Note: An avsn object must be started before the lvpp object.
ST A R T O B J E C T S
After objects are created, configured, and bounded, they must be started. A data path is
initiated by starting upstream objects first and working downstream. For example, in
“preview” the lvpp object is bound to an avsn object.
STARTING OBJECTS EXAMPLE
This script starts some objects and uses functions to start and stop other objects as required.
The statements below show the start of continuously running objects.
F U N C T IO N S
After these objects are started, functions may be used to create and destroy data paths that
are required for specific tasks. The functions that are used in the script are shown below.
Functions that start a task bind objects and start them in the order required, for example
“preview.” Others that stop a task, for example estop(), shows the sequence of steps that
stop objects before they are unbound.
• Preview
• Stop
• “Record to file”
Q_SYS_CFG_VIN0_CONTROL single buffered configuration parameter
Q_LVPP_CMP_START_VLINE double-buffered configuration parameter
avoc0:start();
ws0:start()
rs0:start();

Start Objects
38 Start Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
• “Estop”
• “Play from File”
• “Stop Decoder ”
P RE VIE W
S T O P
R EC O R D T O F I L E
function preview()
avsn0:bindVideoInput({src=lvpp0});
avsn0:start();
lvpp0:start();
end
function stop()
lvpp0:flush();
avsn0:stop();
avsn0:unbindVideoInput();
end
filenameh4v = "";
filenameqbox = "";
function record(fileName)
avcenc0:bindVideoInput({src=lvpp0});
filenameh4v = string.format("%s.h4v", fileName);
filenameqbox = string.format("%s.qbox", fileName);
ws0:open({type="h4v”, file=filenameh4v, sid =
{videoStreamId}});
ws0:open({type="file", file=filenameqbox, sid =
{videoStreamId}});
avcenc0:record();
lvpp0:start();
end

.....
Start Objects
Start Objects 39
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E S T O P
P L A Y F R O M FI L E
function estop()
lvpp0:flush();
waitForEvents({objid=avcenc0, timeout=1000000, any=0,
events={Q_AVCENC_EV_BITSTREAM_FLUSHED}});
avcenc0:waitForLastBlock();
ws0:close({type="h4v", file=filenameh4v});
ws0:close({type="file", file=filenameqbox});
avcenc0:unbindVideoInput();
end
decodeFile = "";
function play(FileName)
decodeFile = FileName;
avsn0:bindVideoInput({src=avdec0});
avoc0:setVideoChannelSource({ch=vch0, src=avsn0});
avoc0:activateVideoChannelCfg();
startTime = os.time();
avsn0:start();
avdec0:start();
bsr0 = rs0:open({type="qbox", file=FileName,
srcId={videoStreamId, audioStreamId});
waitForEvents({objid=avdec0, timeout=1000000, any=0,
events={Q_AVDEC_EV_VIDEO_END_OF_STREAM}});
endTime = os.time();
totalTime = os.difftime(endTime, startTime);
print(string.format("Decode Time = %d secondsn",
totalTime));
end

40
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S T O P D EC O D E R
function dstop()
rs0:close({type="qbox", file=decodeFile});
avdec0:stop();
avsn0:stop();
waitForEvents({objid=avdec0, timeout=1000000, any=0,
events={Q_AVDEC_EV_VIDEO_END_OF_STREAM}});
avsn0:unbindVideoInput();
avsn0:activateCfg();
end

41
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETTING UP CODEC OBJECTS
Writing scripts requires initialing the board, configuring the
system, and then setting up the Codec objects.
• “Objects Creation”
• “Objects Configuration”
• “Objects Activation”
• “Setting up Live Video Pre-Processor (lvpp) Object”
• “Setting up Non-Real Time Video Pre-Processor (nvpp) Object”
• “Setting up Stereo Audio Input (sain) Object”
• “Setting up Audio Video Decoder (avdec) Object”
• “Setting up Audio Video Encoder (avenc) Object”
• “Setting up Audio Video Synchronizer (avsn) Object”
• “Setting up Audio Video Output Compositor (avoc) Object”
• “Setting up Read/Write Streamer (rs/ws) Objects”

S E T T I N G U P C O D E C O B J E CT S
Objects Creation
42 Objects Creation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
O B J E C T S C R E A T I O N
The system control object sysctl0 enables the creation and configuration of the Codec
objects. This object is created and made available to the application after booting the media
engine.
CREATING AN OBJECT SYNTAX
The following syntax shows the construction methods for creating an object:
CREATING READ/WRITE STREAMERS SYNTAX
The exceptions to the rule described above are the read and write streamers. The following
syntax:
systl0:<classname>Create([arguments])
rs = sysctl0:createReadStreamer ([arguments])
ws = sysctl0:createWriteStreamer([arguments])

.....
S E T T I N G U P C O D E C O BJ E C T S
Objects Configuration
Objects Configuration 43
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
O B J E C T S C O N F I G U R A T I O N
Once objects are created, they need to be configured and then be activated to support the
functionality required of them.
The setParam() method is used for configuration. Use of the setParam() method is
shown below:
CONFIGURING A SINGLE OBJECT SYNTAX
In addition to creating objects, sysctl enables system configuration, video inputs, clocks
for a variety of hardware blocks, outputs, etc. The configure() method of the sysctl0
objects is used for configuring objects. The syntax is shown below:
Note: Notice the omission of the parenthesis. This is a valid Lua construct when using a table
to pass on actual parameter using a key or value pair. In the above example, PLL3 is
programmed to generate a 2.048MHz clock.
See-> The MG3500 Codec Firmware API Reference Manual for a list of parameters that can be
used with this method.
CONFIGURING MULTIPLE OBJECTS SYNTAX: CONFIGURE() METHOD
Most methods have a single purpose, for example configure() writes a “value” to
“param.” The following example configures two control registers, VIN0 and VIN1.
<object ref.>:setParam{
param=<cfg_param>,
value=<value>
}
sysctl0:configure {
param = Q_SYS_CFG_PLL3_CLOCK_HZ,
vale = 2048000
}
sysctl0:configure({
param = Q_SYS_CFG_VIN0_CONTROL,
value = 0x00048249
});
sysctl0:configure({
param = Q_SYS_CFG_VIN1_CONTROL,
value = 0x00000000
});

Objects Configuration
44 Objects Configuration
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONFIGURING MULTIPLE OBJECTS SYNTAX: SETVPORTMODE () METHOD
Other functions take multiple arguments. The setVPortMode() method of the LVPP class
sets up the video input ports and internal muxers to route video as required by the system.
An example of this method used in a multi-channel system is shown below. Arguments
“syncmode” and “syncheight” are not required in systems that have a single video input to a
VIP (video input processor). This is shown in the following example:
See-> The MG3500 Codec Firmware API Reference Manual for more information on the system
control object.
The following are descriptions of the parameters in the above example:
sysctl0:setVPortMode{
port = 0,
live = 1,
interlaced = 1,
bottomfieldfirst = 0,
videocontrol = 0x80101080,
interleave = 1,
syncmode = Q_SYS_CFP_VPORT_SYNC_MODE_MOBI,
syncheight = 525
}
port Refers to the VIP module used. Valid arguments are 0
and 1. Port 0 can only take in a live input (abstracted by
an LVPP objects). Port 1 can take in a live OR non-live
video input (abstracted by an nvpp object). Non-live
video ports can be used for scaling (input frames read
from memory) and can operate faster than real time.
If the system requires just one live video input it
MUST use port 0. Only port 1 can be used as non-live
input so a system that encodes video frames stored in
memory, for example using hvcap(), initializing
port 1 is sufficient. An example of non-live port
initialization is shown below.:
port=1,
live=0
}

.....
Objects Activation
Objects Activation 45
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
O B J E C T S A C T I V A T I O N
Most configuration parameters are double-buffered. This means that after the appropriate
values have been passed on to the parameters, an “activate” command must be issued to the
particular instance of the object so that these values take effect. This is done by using the
activateCfg()method, as shown below:
live Indicates the nature of the video input to the video
input module. Valid arguments are 0 and 1. A value of
1 indicates live video input and 0 indicates non-live
video input.
When connected to live input, a VIN can operate only
at the video input clock speed. A VIP consists of a
video input module and video processing module
which operate on independent clocks. For example,
when connected to an NTSC source VIN will be run
at 27Mhz. VIN can operate up to frequencies of
125MHz.
interlaced when set to 1 indicates that the video source uses
interlaced scans.
bottomfieldfirst when set to 1 indicates that the video source sends the
bottom field first.
videocontrol The register controls several parameters including sync
source and width of video input, 8-bit and 16-bit.
See-> The MG3500 Codec Firmware API Reference
Manual for more information on
Q_SYS_VPORT_MODE.
interleave This indicates the number of interleaved channels in
the video input. Multi-channel designs can have up to
four channels (byte) interleaved in a single input video
stream.
syncmode
syncheight
<object ref>:activateCfg()

Setting up Live Video Pre-Processor (lvpp) Object
46 Setting up Live Video Pre-Processor (lvpp) Object
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P LI V E VI D E O P R E -P R O C E S S O R (L V P P ) OB J E C T
The live video pre-processor lvpp object enables capturing and pre-processing of live input
video data. This object handles cropping, scaling, filtering, and all other functions associated
with the video input module.
CREATING THE LVPP OBJECT
The lvpp object is created with reference to the system control object. The following
example shows how to create lvpp:
The lvpp object allocates memory for captured frames and for setting up the lvpp for pre-
processing. In Lua to C conversion, all arguments except name must be passed on to the C
API layer.
See-> The MG3500 Codec Firmware API Reference Manual for information refer
Q_SYS_CMD_LVPP_CREATE.
lvpp0 = sysctl0:lvppCreate{
name="lvpp”,
slot=0,
port=0,
maxWidth=720,
maxHeight=480,
maxPMEDSFactor=2,
numVidFrame=6
}
name Is an arbitrary name assigned to this object, used for
control in Lua space. As mentioned earlier, a table
indexed by object name can be accessed to retrieve
object references.
Note: Same names can be re-used however, only the last
reference of the object will be available from the
sysctl0.objectHandles table.
slot relates to the number of interleaved channels in a video
input stream. In a multichannel system each
interleaved channel will have a different slot number as
illustrated in Figure 1 Slot Allocation1.

.....
Setting up Live Video Pre-Processor (lvpp) Object 47
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 1 Slot Allocation
Because of the complexity of lvpp, core configuration functions have been defined in the
libvpp.lua.
See-> Section, “Built-in Scripts,” in Chapter 4," From Lua to C."
port Specifies the video input port to be used. Refer to
section MG3500 Codec System Control (sysctl)
Object for more information.
maxwidth Specifies the maximum width of the input frames.
Memory is allocated appropriately.
maxheight Specifies the maximum height of the input frames.
Memory is allocated appropriately.
maxPMEDSFactor Specifies the maximum Pre-Motion Estimation (PME)
Decimation factor.
See-> The MG3500 Codec Firmware API Reference Manual.
numvidframe Number of buffers to allocate for a particular instance
of the lvpp object. Encoding profile, core clock and
GOP structure will have an impact on the numbers of
buffers required.
Setup_VPP(lvpp0, HSIZE, VSIZE, 1, 0, 2, 4)
Ch 0 slot 0
Ch 3 slot 3
Ch 2 slot 2
Ch 1 slot 1
Ch 0 slot 0
Ch 3 slot 3

48 Setting up Live Video Pre-Processor (lvpp) Object
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
After an lvpp object is created, it must then be configured correctly to process the
incoming video. This includes cropping crop(), scaling size(), temporal filtering
filterTemporalMotion(), etc.
See-> The MG3500 Codec Firmware API Reference Manual for detailed descriptions of the
functions supported by the lvpp, and for a list of the configuration parameters.
CONFIGURING AND ACTIVATING LVPP OBJECT
An example of configuring an activating the lvpp object is shown below.
lvpp0:setParam{
param=Q_LVPP_CMP_FIELD_OFFSET,
value=313
}
lvpp0:setParam{
param=Q_LVPP_CMP_START_VLINE,
value=24
}
lvpp0:setParam{
param=Q_LVPP_CMP_START_HPIXEL,
value=0
}
lvpp0:setParam{
param=Q_LVPP_CMP_PIXEL_AR_X,
value=16
}
lvpp0:setParam{
param=Q_LVPP_CMP_PIXEL_AR_Y,
value=15
}
lvpp0:setParam{
param=Q_LVPP_CMP_DEST_PROG,
value=0
}
lvpp0:activateCfg()

.....
Setting up Non-Real Time Video Pre-Processor (nvpp) Object
Setting up Non-Real Time Video Pre-Processor (nvpp) Object 49
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P NO N -RE A L TI M E VI D E O P R E -P R O C E S S O R (N V P P ) OB J E C T
The nvpp object is similar to the nvpp and uses a similar API. The nvpp object requires the
use of a VIP module (always port 1).
CREATING NVPP OBJECT
When port 1 is used with an nvpp object, a live video input cannot be connected to this
object. Instead, input frames to this object are read from memory.
CONFIGURING NVPP OBJECT
The functions and configuration parameters associated with the nvpp are similar to those
used with the lvpp.
See-> The MG3500 Codec Firmware API Reference Manual for a list of configuration
parameters.
port = 1,
live = 0
}
nvpp0 = sysctl0:nvppCreate {
name = "nvpp0",
maxWidth = 720,
maxHeight = 480,
maxPMEDSFactor = 1
}

Setting up Stereo Audio Input (sain) Object
50 Setting up Stereo Audio Input (sain) Object
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P ST E R E O A U D I O IN P U T ( S A I N ) O B J E C T
The sain object is responsible for configuring the audio port for audio capture
(oversampling, sampling rate etc.). Like the video port the audio input module also has two
physical interfaces which are abstracted as ports in software. Unlike the video ports, the
audio ports are identical. Audio signals connected to the AUD0 interface are mapped to
port 0 and signals connected to AUD1 are mapped to port 1.
CREATING SAIN OBJECT
When creating the sain object, it is important to associate the object to the type of audio
encoding used in the system. The audio encoding type will determine the number of audio
samples in a frame.
sain0 = sysctl0:sainCreate{
name="sain0",
port=0
}
Sample configuration and activation of the sain object is
shown below.
sain0:setParam{
param=Q_SAIN_CMP_AUD_SERIAL_MODE,
value=Q_SAIN_CFP_AUD_SERIAL_MODE_I2S
}
sain0:setParam{
param=Q_SAIN_CMP_AUD_MASTER_CLOCK,
value=Q_SAIN_CFP_AUD_MASTER_CLOCK_256FS
}
sain0:setParam{
param=Q_SAIN_CMP_AUD_SAMPLE_RATE,
value=SAMPLERATE
}
sain0:setParam{
param=Q_SAIN_CMP_AUD_SAMPLE_SIZE,
value=16
}
sain0:setParam{
param=Q_SAIN_CMP_AUD_CODEC,
value=SAIN_AUDIO_CODEC
}
sain0:activateCfg()

.....
Setting up Audio Video Decoder (avdec) Object
Setting up Audio Video Decoder (avdec) Object 51
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P AU D I O VI D E O DE C O D E R ( A V D E C ) OB J E C T
The avdec object allows decoding a video-only, audio-only, or an audio-video stream. This
is created as a single object that is initialized with the audio and video decoder type.
The avdec object controls all parameters associated with the H.264, MPEG2, MJPEG
video decoder, audio decoder, and the de-multiplexer.
CREATING AVDEC OBJECT
The avdec object controls all parameters associated with the H.264, MPEG2, MJPEG
video decoder, audio decoder, and the de-multiplexer.
Creation of an AV decoder object is shown below. All arguments except name are passed on
to the firmware API layer.
CONFIGURING AVDEC OBJECT
The avdec object also has a configuration method. The following example shows the
configuration of the audio sample rate and sample size for the output.
See-> The MG3500 Codec Firmware API Reference Manual for more information on the AV
decoder object.
avdec0 = sysctl0:avdecCreate({
name=”avdec0",
atype=Q_AVDEC_CFP_AUDIO_CODEC_QMA,
vtype=Q_AVDEC_CFP_VIDEO_CODEC_AVC,
audioBufferSize=100000,
videoBufferSize=8000000,
maxWidth=1280,
maxHeight=720
});
avdec0:setParam({
param = Q_AVDEC_CMP_AUDIO_SAMPLE_RATE,
value=24000});
avdec0:setParam({
param = Q_AVDEC_CMP_AUDIO_SAMPLE_SIZE,
value=16});
avdec0:activateCfg();

Setting up Audio Video Encoder (avenc) Object
52 Setting up Audio Video Encoder (avenc) Object
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P AU D I O VI D E O EN C O D E R ( A V E N C ) OB J E C T
The avenc object controls all parameters associated with the encoder. Creation of an
avcenc object is shown below. All arguments other than “name” and “ws” are passed on to
the firmware API layer. Creation of an encoder object must be associated with a write
streamer even if it does not write to a file.
CREATING A V E N C OBJECT
The avenc object controls all parameters associated with the encoder. Creation of an
avcenc object is shown below. All arguments other than “name” and “ws” are passed on to
the firmware API layer. Creation of an encoder object must be associated with a write
streamer even if it does not write to a file.
CONFIGURING AVCENC OBJECT
The following function sets up an instance of the encoder, avcenc0, to encode a high-profile
stream at 9Mbps using an IBBrBP GOP structure. This function and others used to
configure the encoder can be found in libavcenc.lua.
• avcenc_720p60—avcenc, profile, level, bitrate_qp, gop_structure, picture_coding.
• avcenc_720p60—avcenc0, "high", 40, 9000000,
Q_AVCENC_CFP_GOP_STRUCTURE_IBBRBP, 0
The bitstreams generated by the encoder in the MG3500 use a native format called the
“qbox.” In this format, packets containing compressed video use a “streamid = 2,” where as
packets containing compressed audio use a “streamed = 1.”
The 60-bit libavcenc.lua library contains functions used by the AVC encoder object.
avcenc0 = sysctl0:avcencCreate({
name = “avcenc0”,
ws = ws0,
maxwidth = 1280,
mightiest = 720,
numreferenceframes = 10
});

.....
Setting up Audio Video Synchronizer (avsn) Object
Setting up Audio Video Synchronizer (avsn) Object 53
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The following commands assign and activate the ID’s that should be used with the stream
generated by the encoder. In this case the stream will contain video only.
See-> The MG3500 Codec Firmware API Reference Manual for information on qbox and on the
AVC encoder object.
S E T T I N G U P AU D I O VI D E O S Y N C H R O N I Z E R (A V S N ) OB J E C T
The avsn object is used to synchronize audio and video. Audio is master and video frames
are dropped or repeated to achieve synchronization.
CREATING AVSN OBJECT
Creation of a simple object is shown below:
See-> The MG3500 Codec Firmware API Reference Manual for information about the AVSN
object.
videoStreamId = 2;
avcenc0:setStreamID({streamid=videoStreamId});
avcenc0:activateCfg();
avsn0 = sysctl0:avsnCreate({name="avsn0”});

Setting up Audio Video Output Compositor (avoc) Object
54 Setting up Audio Video Output Compositor (avoc) Object
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
S E T T I N G U P A U D I O V I D E O O U T P U T C O M P O S I T O R (A V O C ) O B J E C T
The avoc object controls all parameters associated with the compositor that handles the
display of video and audio frames.
The following example shows how avoc is configured for 720P 60 output.
See-> The MG3500 Codec Firmware API Reference Manual for information on avoc.
CREATING AVOC OBJECT
The avoc object controls all parameters associated with the compositor that handles the
display of video and audio frames.
CONFIGURING AVOC OBJECT
The following configures the avoc object for 720P 60 output:
See-> The MG3500 Codec Firmware API Reference Manual for information about the avoc
object.
avoc0 = sysctl0:avocCreate({name="avoc0"});
avoc0:setOutput720p60();
avoc0:setParam({param=Q_AVOC_CMP_VID_0_DISPLAY_WIDTH,
value=1280});
avoc0:setParam({param=Q_AVOC_CMP_VID_0_DISPLAY_HEIGHT,
value=720});
avoc0:activateCfg();
avoc0:setParam(
{param=Q_AVOC_CMP_VID_0_DISPLAY_WIDTH,value=1280});
avoc0:setParam(
{param=Q_AVOC_CMP_VID_0_DISPLAY_HEIGHT, value=720});

.....
Setting up Read/Write Streamer (rs/ws) Objects
Setting up Read/Write Streamer (rs/ws) Objects 55
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SE T T I N G U P RE A D /WR I T E ST R E A M E R (R S /W S ) OB J E C T S
The read and write streamer objects are host-only objects. They read from and write to host
memory when the Codec is decoding or encoding respectively. An instance of an encoder or
decoder object “must” be associated with a writestreamer/readstreamer.
Note: Creating a “Bitstream Writer” object is optional, in which case the encoded bitstream
is not saved to a storage device.
rs0 = sysctl0:createReadStreamer({name="rs0"});
ws0 = sysctl0:createWriteStreamer({name="ws0"});

Setting up Read/Write Streamer (rs/ws) Objects
56 Setting up Read/Write Streamer (rs/ws) Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

57
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
.....
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SAMPLE SCRIPTS
This chapter walks through a few sample scripts in order to
illustrate what is necessary to configure operate the MG3500
Codec.
• “Encoding Pipeline Sample Scripts”
• “Composing Audio Video Channel Sample Script”
• “Creating and Initializing avoc Sample Script”
• “Adding and Configuring vc to avoc Sample Script”

S A M P L E S C R I P T S
Encoding Pipeline Sample Scripts
58 Encoding Pipeline Sample Scripts
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EN C O D I N G P I P E L I N E SA M P L E SC R I P T S
The avencode.lua script consists of a single channel AV encode and display. This example
shows how to setup a basic single encode pipeline.
This script is available with every release under
<install dir>/merlinsw/host/luascripts/supported
BASIC ENCODING PIPELINE SAMPLE SCRIPT
Figure 1 - Single Channel AV Encoding and Display
MULTI-CHANNEL ENCODING PIPELINE SAMPLE SCRIPT
The dvr.lua script shows how to leverage the first encode pipeline to create a multi-
channel encode pipeline based on the same structure.
This script is available with every release under
<install dir>/merlinsw/host/luascripts/supported

.....
Encoding Pipeline Sample Scripts
Encoding Pipeline Sample Scripts 59
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 2 - Multi-Channel Encoding Pipeline

Composing Audio Video Channel Sample Script
60 Composing Audio Video Channel Sample Script
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CO M P O S I N G AU D I O VI D E O CH A N N E L SA M P L E SC R I P T
In the composition mode, video channels bound to Audio Video Synchronizer avsn is
composed and displayed. More video channels may exist but will not be presented if their
source (normally an avsn) is not bound. This concept is useful when switching between
“presentation grids.” For example, five video channels can be created to show four encoders
in preview mode and one decoder output. Switching to a grid of 1 x 2 consists in setting the
source of the unwanted video channels to 0.
Note: An avsn may be connected to more than one video channel at once. It is however
important to remember to maintain the appropriate avsn state based on the number of
connections.
Figure 3 - Audio Video Output Composition
avsn1
®
avsn2
®
avsn3
®
avsn0
®
avsn1
®
avsn2
avsn3
avsn0
®

.....
Creating and Initializing avoc Sample Script
Creating and Initializing avoc Sample Script 61
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C R E A T I N G A N D I N I T I A L I Z I N G A V O C SA M P L E SC R I P T
The example below shows the creation and initialization of the avoc object.
Note: Unlike the avcenc object, avoc has separate activate methods for each method it
supports.
The snippet below uses the setParam() method and is activated using activateCfg().
This configures the display size and audio output.
avoc0:setParam({param=Q_AVOC_CMP_VID_0_DISPLAY_WIDTH,
value=HSIZE});
avoc0:setParam({param=Q_AVOC_CMP_VID_0_DISPLAY_HEIGHT,
value=VSIZE});
avoc0:setParam({param=Q_AVOC_CMP_AUD_SERIAL_MODE,
value=Q_AVOC_CFP_AUD_SERIAL_MODE_I2S});
avoc0:setParam({param=Q_AVOC_CMP_AUD_MASTER_CLOCK,
value=Q_AVOC_CFP_AUD_MASTER_CLOCK_256FS});
avoc0:setParam({param=Q_AVOC_CMP_AUD_SAMPLE_RATE,
value=SAMPLERATE});
avoc0:setParam({param=Q_AVOC_CMP_AUD_SAMPLE_SIZE,
value=16});

Adding and Configuring vc to avoc Sample Script
62 Adding and Configuring vc to avoc Sample Script
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AD D I N G A N D CO N F I G U R I N G V C T O A V O C SA M P L E SC R I P T
The example below adds and configures a video channel to the avoc object. This uses the
setVideoChannelParam() method for configuration and
activateVideoChannelCfg() for activation.
-- Create Video Channel-channel is an ID
vch0 = avoc0:addVideoChannel();
-- Define the source area. In most cases, this correspond to the full
video frame -- size
avoc0:setVideoChannelParam{
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_SRC_WIDTH,
value = HSIZE}
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_SRC_ HEIGHT,
value = VSIZE}
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_SRC_OFFSET_X,
value = SRC_OFFSET_X}
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_SRC_OFFSET_Y,
value = SRC_OFFSET_Y}

.....
Adding and Configuring vc to avoc Sample Script
Adding and Configuring vc to avoc Sample Script 63
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SETTING UP VIDEO OUTPUT TIMING
Video output timing is setup using built-in functions. The example below configures all
timing and other related parameters for a 720p60 display.
See-> The MG3500 Codec Firmware API Reference Manual for a list of configuration
parameters.
-- Define the destination area with respect to the entire display size.
-- The offset is the position of the channel on the composed frame.
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_DST_WIDTH,
value = HSIZE}
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_DST_ HEIGHT,
value = HSIZE}
-- If the whole frame is not to be rendered, specify the
ch = vch0,
param = Q_AVOC_CMP_VIDEO_CHANNEL_DST_OFFSET_X,
value = HSIZE}
ch = vch0,
param = Q Q_AVOC_CMP_VIDEO_CHANNEL_DST_OFFSET_Y,
value = HSIZE}
avoc0:activateVideoChannelCfg();
avoc0:setVideoChannelSource({ch=vch0, src=avsn0});
-- Remember to start the avsn
avsn0:start()

64
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PN984-MG3500-Programming-Getting-Started-Guide

More Related Content

What's hot (18)

Viewers also liked (20)

Similar to PN984-MG3500-Programming-Getting-Started-Guide (20)

More from Sholeh Gregory (8)

PN984-MG3500-Programming-Getting-Started-Guide