BUILDING

--------

(optionally, if needed, do "autoreconf -i")

	./configure --enable-ilservice

	make all

	sudo make install

	make check

In case you omit the "--enable-ilservice", the service(s) will not be built.

Compiling with --enable-ilservice requires that you have Bellagio 

(http://omxil.sourceforge.net/) installed, and that pkgconfig finds its .pc

files.

If necessary, set PKG_CONFIG_PATH to where ever you installed Bellagio to.

Typically that would be done with something like:

	export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig

After you have successfully built and installed the service, you get three 

binaries into /usr/local/bin:

	point2pointilservice

	ilservice

	standardstructtestilservice

If you didn't compile the services, you only get the proxy libraries under 

	/usr/local/lib 

and you get the "omxproxystandardstructtest" test under

	test/standardstructs/app

and you get the "simpletest" test under

	test/simpletest

The libilproxyloader.so can be used with Bellagio core as a component loader.

If you don't want to use Bellagio, you can use libilproxy.so, which provides

a minimal OpenMAX IL Core interface for your IL Client.

By default the proxy uses direct TCP sockets for its IPC. 

If you want to use NoTA H_IN3 as the IPC transport library, you must run 

configure with --enable-hin3proxy or with --enable-hin3spproxy (for linking

against HIN3 single process libs). The NoTA H_IN3 transport has been tested with

a single Ubuntu 8.04 PC running with TCP L_IN with loopback device. 

Using the normal, not single process libraries, requires starting two H_IN

daemons, one for the IL client and one for the IL service. Use NOTA_IN_DAEMON 

environment variable to define the socket both for the daemons and the 

applications.

STANDARDSTRUCTTESTILSERVICE		

---------------------------

The "standardstructtestilservice" is to be used only to run against the 

"omxproxystandardstructtest" found at:

	test/standardstructs/app

With this test you can verify that all the OpenMAX IL standard structures can be

passed over the proxy. Note that by default the proxy logging level is so low

that a successful run will not show much output. Use a higher debug level in 

file "omx_proxy_debug.h" if you want to see the test progress. First start the

service, then start the test.

SIMPLETEST

----------

This is very simple test which basically only verifies that your proxy is 

properly set up with your IL implementation library and can connect to the IL

service. It enumerates the IL component names which it can see in the IL

service, and prints their names. Use a higher debug level (omx_proxy_debug.h)

if you want to see more tracing.

To run the test, simply:

1) run /usr/local/bin/point2pointilservice

2) run test/simpletest/simpletest 

ILSERVICE

---------

The "ilservice" is the full featured version of the proxy IL service, which is

able to create connections and tunnels between other ilservices. Normally you

would not use this unless you want to experiment with having some components 

in one IL service and some other components in another. Basically using this

requires that you use Bellagio as the IL Core library on the client side, and

instantiate multiple proxy component loaders in it. Then just start your 

ilservices with a sequential command line argument starting with connection 

id 832 (..833, 834..)

POINT2POINTILSERVICE

--------------------

The "point2pointilservice" is the minimal version of the proxy IL service. You

simply link it against your OpenMAX IL implementation and run the executable.

This is what you would most likely typically use as your IL service.

TESTING WITH BELLAGIO

---------------------

NOTE: This only applies to the Bellagio 0.9.1 release!

Get Bellagio sources, make them, install it. Register the Bellagio components

with omxregister-bellagio. Make the test applications. See that you get the

audiodectest to play your ogg-files, you likely will need libasound, 

libasound-dev, libvorbis and libvorbis-dev libraries (in Ubuntu). Once ogg files

are playing fine with Bellagio, replace the Bellagio libomxil library for the

"omxaudiodectest" in its Makefile.am with libilproxy.

If you want to use pkg-config, you can put this into Bellagio configure.ac:

	PKG_CHECK_MODULES([ILPROXY], [libilproxy])

Then you could use $(ILPROXY_LIBS) and $(ILPROXY_CFLAGS) in the Bellagio test

application's Makefile.am to make things simpler.

Once you have Bellagio audiodectest compiled against libilproxy and doing an

	ldd omxaudiodectest

In the respective folder where the binary executable is, verify that you really

have it correctly linked against libilproxy and all libraries are found. If 

all libraries are not found, you might want to try:

	export LD_LIBRARY_PATH=/usr/local/lib

Alternatively, you could of course install to /usr or use ld.so.conf and 

ldconfig.

Finally, when ldd shows that all libraries are found, just fire up the 

"point2pointilservice" and run the omxaudiodectest. It should send commands

over the proxy, and if you have full logging (0x77) in omx_proxy_debug.h, 

you'll most likely see a lot of debug trace prints. 

You might still end up not hearing any music, because the Bellagio test

applications are made so that they may decide to wait in callbacks for other

callbacks to occur. This happens typically when port settings change due to

the playback content file. There is a kludge in the proxy to circumvent this 

issue of waiting for callbacks in callbacks, it is put behind a compiler flag 

OMX_PROXY_CALLBACK_STRATEGY. See "omx_proxy_types.h". 

Basically, if you configure the proxy with this:

	./configure --enable-ilservice CFLAGS='-DOMX_PROXY_CALLBACK_STRATEGY=4'

(After that, you'll need of course to make clean all install check)

You will enable the callbacks strategy which allows the Bellagio test

applications to sleep in as many callbacks as they wish. Using the thread

spawning callback strategy is however not exactly encouraged nor are we 

encouraging writing OpenMAX IL client applications which require such a callback

strategy. But it is there to support Bellagio.

Also note that the Bellagio 0.9.1 audiodectest has a thread bug related to

sending the first two buffers, which may or may not end up being sent in the

order assumed by the audiodectest application. It will show as an error message

about a corrupt ogg file - if you get that error you already know the proxy is

working fine. Fixing the Bellagio audiodectest first two buffer send order is

left as an exercise to the reader. Hint: the callback from the first buffer 

being emptied may happen before the second buffer is sent.

COMPILER FLAGS

--------------

The proxy has plenty of compiler flags, of which some are explained here. You

can define these at configure time into CFLAGS:

 OMX_PROXY_CALLBACK_STRATEGY - values 1, 2, 4. 

 1) is for direct callbacks, use when you want to minimize thread usage in your

 IL client - note that you can not call any OpenMAX IL functions over the proxy

 from the callback function context. The callback is executed directly in the

 IPC thread, thus waiting for a response from the IL service would cause a 

 deadlock. (you can't sleep in callbacks nor do OpenMAX IL function calls)

 2) is for queued callbacks from a separate thread, the default. It allows you

 to send IL commands over the proxy in the callback context, but you can't wait

 for other callbacks to occur (you can't sleep in callbacks)

 4) is threaded callbacks. Basically only created to support Bellagio, it allows

 you to wait for other callbacks in the context of callbacks, and spawns new

 threads to do that when necessary. (you CAN sleep in callbacks)

 OMX_SKIP64BIT

 This is by default defined in configure.ac. It makes the proxy handle 64bit

 types in 32 bit chunks. You probably want to have this defined, but you can of

 course take it out if you know what you are doing. Search the sources to see

 the effects. 

 IGNORE_CMIMETYPE

 This is by default defined in configure.ac. It makes the proxy skip cmimetype

 field in port definition structures. Most IL implementations have not been able

 to properly handle those fields. If you link the IL service against a proper

 IL implementation and implement your IL clients properly as well, you will want

 to remove this define.

 OMX_PROXY_USE_COMPONENT_TUNNEL_REQUEST

 This is by default defined for the "ilservice" executable, because the 

 distributed IL services need to create tunnels to other IL services instead of

 just issuing an OMX_SetupTunnel to one IL Core.

 By default this is not defined for libilproxyloader, and the proxy will only 

 send the OMX_SetupTunnel function call over to the service. OMX_SetupTunnel is

 faster, it only requires one message to be sent, where as the component tunnel

 request is always two messages.

 Basically you want to define this for the component loader library when you 

 compile the loader to be used with the Bellagio IL Core and run multiple IL

 services. The Bellagio core will call component tunnel request in the proxy.

 To summarize: if you use libilproxy with libilproxyloader, you are stuck in 

 point 2 point operation and you are better off not defining this, as 

 OMX_SetupTunnel is faster. But it should still work if you define it.

 If you use libomxil (Bellagio) with libilproxyloader, you NEED to define this.

DISABLING UNNECESSARY MARSHALING

--------------------------------

In case your IL implementation (or client) does not need the ability to marshall

all different types of OpenMAX structures (used in OMX_GetParameter / 

OMX_SetParameter / OMX_GetConfig / OMX_SetConfig), you might want to choose to 

reduce the size of the proxy by modifying the "WITH_..." #defines in the file

	omx_proxy_with_network_structs.h

If you disable every struct by defining zeroes instead of ones, the stripped

code size of point2pointilservice, for example, drops to roughly half in Ubuntu.

Note that some of the "disabled" structs may still work (memcpy is used instead

of the normal marshaling to a specifically packed/aligned/byteswapped structure)

provided that the packing, alignment and endianness match on both sides of

the proxy.