Bellagio OpenMAX Integration Layer 1.1.1 project
Release 0.9.1

This is an Open Source implementation of the OpenMAX Integration Layer
(IL) API ver. 1.1.1, specified by the Khronos group (see
http://www.khronos.org/openmax).

This package includes the libomxil-bellagio shared library together with the
following OpenMAX components (built as separate shared objects and
loaded at runtime):
CORE FUNCTIONALITIES
- An IL core
- A component loader for static libraries for Linux
- A component loader for Symbian
- A framework of components and ports base 
  implementations for Bellagio Hierarchy

AUDIO
- OMX ALSA sink component
- OMX ALSA source component
- OMX audio decoder based on FFmpeg libraries that supports the
  following audio formats:
  o MP3
  o Ogg Vorbis
  o AAC (only RAW AAC format supported)
- OMX audio decoder based on mad library that supports the MP3 audio
  format
- OMX audio decoder based on libvorbis that supports the Ogg Vorbis
  audio format
- OMX audio volume control
- OMX audio file reader for FFmpeg components
- OMX audio mixer component

VIDEO
- OMX video decoder decoding input MPEG-4 or H.264 format file (in H.264
  format, there is no interlacing support) to produce output .yuv
  file.
- OMX video color converter component converting from decoded output
  .yuv file to produce .rgb file.
- OMX video sink component which uses the frame buffer to display the
  color converter component output .rgb file.
- OMX video capture component which captures video frame using a video
  camera and stores into a file or display using video sink.
- OMX Camera component also captures video having 3 ports. Port 0 is used
  for preview; Port 1 is used for video and image capture; Port 2 is used 
  for video and image thumbnail.
- OMX video encoder encoding input YUV format file or video captured
  using camera component in MPEG-4 video format to produce output .m4v
  file.

IMAGING
- An OpenmAX jpeg encoder and decoder

PARSER
- OMX 3GP parser component. Parses input file/stream for audio and
  video output, which is then fed to audio and video decoder component
  for decoding.

CLOCK
- OMX Clock component. It take audio(default) as input reference clock
  and provide media clock to video sink and other component. It support
  fast forward and rewind.

SYMBIAN COMPONENTS
- Audio mixer
- MMF Output stream audio renderer
- Volume control component

N.B. The 3GP parser can support MPEG-4,H.264 video and MPEG-4,AAC
audio. FFmpeg can't encode (Warning, using MS style audio codec tag,
the file may be unplayable!) Vorbis audio for a 3GP container and so
also not decodable. Because of this Vorbis decoding support has not
been included in the 3GP parser.

BUILD
=====

autoreconf -i
./configure
make
make install
make check

If the pkg-config check fails, verify that the environment variable
PKG_CONFIG_PATH is set, and it points to the directory(ies) containing
the .pc files describing the package to be verified.  Usually it can be
set as (for a bash):

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/:/usr/lib/pkgconfig/

Before attempting to run any test, the OMX components *must* be
registered with the command "omxregister-bellagio".

/usr/local/bin/omxregister-bellagio

That will create a registry file that will contain all the components
installed by default in /usr/local/lib/libomxil-bellagio (read the man
page).

Note: the default location for the installation is TARGET=/usr/local/lib 
for the library, and the component will be installed in TARGET/bellagio 

Now, run the tests.

TEST
====

The following simple test applications are provided:

test/components/audio/omxaudiodectest
test/components/audio_effects/omxvolcontroltest
test/components/video/omxvideodectest
test/components/video/omxvideocapnplay
test/components/video/omxvideoenctest
test/components/parser/omxparsertest
test/components/audio_effects/omxaudiomixertest


AUDIO DECODER , MIXER AND SINK COMPONENT USAGE
----------------------------------------------

Usage: omxaudiodectest [-o outfile] [-stmdgh] filename

       -o outfile: If this option is specified, the decoded stream is
                   written to outfile This option can't be used with
                   '-t'
       -s single_ogg: Use the single role ogg decoder instead of the
                      default one. Can't be used with -m or .mp3 file
       -t: The audio decoder is tunneled with the ALSA sink
       -m: For mp3 decoding use the mad library. Can't be used with -s
           or .ogg file
       -d: If no output is specified, and no playback is specified,
           this flag activated the print of the stream directly on std
           out
       -g: Gain of the audio sink[0...100]
       -h: Displays this help

Usage: omxvolcontroltest [-o outfile] [-g gain] filename

       -o outfile: If this option is specified, the output stream is
                   written to outfile otherwise redirected to std
                   output
       -g: Gain of PCM data [0...100]
       -h: Displays this help

Usage: omxaudiomixertest [-o outfile] [-gi gain] -t -r 44100 -n 2 filename1 filename2

       -o outfile: If this option is specified, the output stream is
                   written to outfile otherwise redirected to std
                   output; Can't be used with -t.
       -gi       : Gain of stream i[0..3] data [0...100]
       -t        : The audio mixer is tunneled with the ALSA sink;
                   Can't be used with -o
       -r 44100  : Sample Rate [Default 44100]
       -n 2      : Number of channel [Default 2]
       -h        : Displays this help

VIDEO DECODER, COLOR CONVERTER, SINK AND CAPTURE COMPONENT USAGE
-------------------------------------------------------

Usage: omxvideodectest -o outfile [-t] [-c] [-h] [-f input_fmt] [-s] input_filename

 -o outfile: If this option is specified, the output is written to
             user specified outfile Else, the output is written in the
             same directory of input file the file name looks like
             input_filename_app.yuv/rgb depending on input option If
             the color conv option (-c) is specified then outfile will
             be .rgb file Else outfile will be in .yuv format N.B.:
             This option is not needed if you use the sink component
 -c: Color conv option - input file is decoded and color converted in
     outfile(.rgb file)
 -h: Displays this help
 -f: input format specification in case of color conversion component usage
     The available input formats are -
      - OMX_COLOR_Format24bitRGB888  (default format)
      - OMX_COLOR_Format24bitBGR888
      - OMX_COLOR_Format32bitBGRA8888
      - OMX_COLOR_Format32bitARGB8888
      - OMX_COLOR_Format16bitARGB1555
      - OMX_COLOR_Format16bitRGB565
      - OMX_COLOR_Format16bitBGR565
 -s: Uses the video sink component to display the output of the color
     converter (.rgb file)
 -t: Tunneling option - if this option is selected then by default the
     color converter and video sink components are selected even if
     those two options are not specified - the components are tunneled
     between themselves
input_filename : user specified input file name - please specify the
full path name


Usage: omxvideocapnplay -o outputfile [-t] [-c] [-h] [-f input_fmt] [-s]

       -o outfile: If this option is specified, the output is written
                   to user specified outfile If the color conv option
                   (-c) is specified then outfile will be .rgb file
                   Else outfile will be in .yuv format N.B : This
                   option is not needed if you use the sink component
       -c: Color conv option - input file is decoded and color
           converted in outfile (.rgb file)
       -h: Displays this help
       -f: input format specification in case of color conversion component usage
           The available input formats are -
              - OMX_COLOR_Format24bitRGB888  (default format)
              - OMX_COLOR_Format24bitBGR888
              - OMX_COLOR_Format32bitBGRA8888
              - OMX_COLOR_Format32bitARGB8888
              - OMX_COLOR_Format16bitARGB1555
              - OMX_COLOR_Format16bitRGB565
              - OMX_COLOR_Format16bitBGR565
       -W 176: Width of the frame  [default 176]
       -H 144: Height of the frame [default 144]
       -s: Uses the video sink component to display the output of the
        color converter(.rgb file)
       -t: Tunneling option - if this option is selected then by
           default the color converter and video sink components are
           selected even if those two options are not specified - the
           components are tunneled between themselves

N.B : The input picture resolution can be maximum 640x480 for decoding
and displaying

Usage: omxparsertest -o outfileVideo.yuv outfileAudio.pcm  [-t]  [-h] [-d] input_filename.3gp

       -o outfileVideo.yuv outfileAudio.pcm: If this option is
          specified, the output is written to user specified outfiles
          N.B : This option is not needed if you use the sink
          component
       -h: Displays this help
       -d: Uses the video and ALSA sink component to display the video
       and play the audio output input_filename is the user specified
       input file name
       -t: Tunneling option - if this option is selected then by
           default the color converter, video sink, volume control and
           ALSA sink components are selected even if these options are
           not specified - the components are tunneled between
           themselves

Usage: omxvideoenctest -o outfile [-W 320] [-H 240] [-t] [-C] [-h] [-f input_fmt] input_filename

       -i infile : Input yuv file name

       -o outfile: If this option is specified, the output is written
          to user specified outfile.  Else, the output is written in
          the same directory of input file the file name looks like
          input_filename_app.m4v depending on input option
       -h: Displays this help
       -f: output codec format. The available output formats are -
           - m4v
       -W width
       -H Height
       -C use camera as input source
       -r frame per second
       -t use tunnel between video source and encoder

FRAME BUFFER SUPPORT
--------------------

The video sink component, if used by specifying the -s option mentioned
above, the uses machine's available framebuffer /dev/fb0.

Users are requested to check if there is framebuffer support in their
machine by command "fbset -i".

If the output looks like - "open /dev/fb0 - no such file or directory"
then there is no frame buffer support. Go to /etc/grub.conf file
in your machine, append in the kernel argument the following arguments,
separated by spaces: video=vesafb vga=0x305

Save the file, restart the machine, type the "fbset -i" command and you
can see there is framebuffer support having following configurations:

  framebuffer name : VESA VGA
  Resolution - 1024x768
  Pixel Depth - 8
  rgba - 8/0,8/0,8/0,8/0

The users having in their machine, framebuffer of different
configuration, are also request to change the configuration as
mentioned above.

EXAMPLE COMMANDS FOR AUDIO APPLICATION
--------------------------------------

1. omxaudiodectest reference_stream.mp3
2. omxaudiodectest -t reference_stream.mp3
3. omxaudiodectest -m reference_stream.mp3
4. omxaudiodectest -m -t reference_stream.mp3
5. omxaudiodectest -m -f reference_stream.mp3
6. omxaudiodectest -m -f -t reference_stream.mp3

7. omxaudiodectest reference_stream.ogg
8. omxaudiodectest -s reference_stream.ogg
9. omxaudiodectest -s -t reference_stream.ogg

10. omxaudiodectest  reference_stream.aac
11. omxaudiodectest -t reference_stream.aac

12. omxvolcontroltest -o outfile.pcm -g 70 infile.pcm

13. omxaudiomixertest -o outfile.pcm -g0 70 g1 80 -r 44100 -n 2 filename1.pcm filename2.pcm
14. omxaudiomixertest -t -g0 70 g1 80 -r 44100 -n 2 filename1.pcm filename2.pcm

EXAMPLE COMMANDS FOR VIDEO APPLICATION
--------------------------------------

1. omxvideodectest -c -s temp_qcif.m4v
2. omxvideodectest -c -s -f OMX_COLOR_Format16bitRGB565 temp_qcif.m4v
3. omxvideodectest -o out.rgb -c input_cif.264
4. omxvideodectest -o out -c -f OMX_COLOR_Format16bitRGB565 temp_qcif.m4v
5. omxvideodectest -o out.yuv temp_qcif.m4v
6. omxvideodectest -t input_cif.264
7. omxvideodectest -t -f OMX_COLOR_Format16bitRGB565 temp_qcif.m4v

8. omxvideoenctest -o outfile.m4v [-W 320] [-H 240] [-t] [-C] [-h] [-f input_fmt] input_filename.yuv


EXAMPLE COMMANDS FOR PARSER APPLICATION
---------------------------------------

1. omxparsertest -o outfileVideo.yuv outfileAudio.pcm  reference_stream.3gp
2. omxparsertest -d reference_stream.3gp
3. omxparsertest -t reference_stream.3gp

HOW TO ADD A NEW COMPONENT
--------------------------

- Add, in the src/components directory, a directory that will contain
  your component.

- Put your source and header files in there.

- Add a file named library_entry_point.c if you want to develop a
  component loaded by the default component loader. This file must
  contains a function named omx_component_library_Setup.  See the
  other library entry points for reference.

- Edit the configure.in file and add new rules according to your
  needs.  In particular, you may want to add some library dependencies
  that are needed by the src/Makefile.am Also, remember to add the
  path of your Makefile in the AC_OUTPUT directive.

- Edit the src/components/Makefile.am file and add rules for building
  your component.

- Edit the src/Makefile.am file and add rules for building your
  component.

- Create a src/components/yourcomponentdirectory/Makefile.am file.

- If you have some test programs, put their sources into the 'test'
 directory.  Edit the test/Makefile.am file to add rules for building
 them.

In order to add the new directories to the build tree, the autotools
must be used (the version supported is automake-1.9).

The command to be executed with this distribution is: "autoreconf -i"

- Check correct building of your tests with:
 make check

- To build RPM:

 make dist
 sudo cp libomxil-bellagio-0.3.5.tar.gz /usr/src/redhat/SOURCES/
 sudo rpmbuild -ba libomxil-bellagio.spec

This version has been tested on:

- FC6 2.6.20-1.2933.fc6 (with FFmpeg 0.4.9-0.37.20070503, libmad
  0.15.1b, libvorbis 1.1.2-1)
- UBUNTU 2.6.17-11-generic

Last modified: Mar 07, 2008.