Codec Engine Examples

Introduction

The Codec Engine (CE) product includes many examples. This article describes the layout of these examples, as well as details that map examples and the features they demonstrate.

Physical Layout

The examples are largely grouped by the Codec Engine Roles that users play. This includes:

• Algorithm Developer (ti/sdo/ce/examples/codecs/* and ti/xdais/dm/examples/*)
• Server Integrator (ti/sdo/ce/examples/servers/*)
• Engine Integrator and Application Developer (ti/sdo/ce/examples/apps*)

In addition, an example (scale) is provided that demonstrates how to integrate an algorithm that isn't one of the VISA (Video, Image, Speech, Audio) classes. Now that the IUNIVERSAL algorithm class is available, the approach taken in this scale example is no longer recommended, though it is still supported.

Finally, notice that CE (and other Multimedia Framework Products (MFP) content) often redistribute examples from other products when reuse is possible. For example, the XDAIS product provides several example codecs (in the ti.xdais.dm.examples namespace). The CE example applications leverage these example XDAIS codecs, and as a result, rather than requiring end users to download XDAIS, the XDAIS examples are redistributed with CE. This sometimes leads to confusion ("Why is the ti/xdais/dm/examples/auddec1_copy example shipped in both XDAIS and CE?"), but leads to a better out of the box experience as all dependent example code is present in each standalone product.

Features

This section describes the various features exemplified through the examples.

Multi-platform Support

Most examples are written in portable C to support building for many different environments. For example, the example codecs can be built for C64+, C674, ARM Linux glibc and uClibc runtimes, X86 Linux glibc runtime, and many others.

The generated binaries follow the naming conventions described here.

Apps support both Local and Remote Config

The example applications support both client app (that use a remote server) and local app configurations. The configuration scripts provided with each app typically include:

• local.cfg scripts for single-processor, local-codecs configuration
• remote.cfg scripts for multi-processor, remote-codecs configuration

Typically the remote scripts use either Engine.createFromServer() or utilize the CE's Runtime Config feature.

Async APIs

The Codec Engine VISA APIs support 'asynchronous' process calls for remote algorithms. That is, you can call *_processAsync(), which will enqueue a job on the remote processor and return immediately. You can return "sometime later" and call *_processWait(), which will block until 1) the remote process() call completes, or 2) timeout. You can queue up multiple *_processAsync() calls.

There is only one example that demonstrates these async semantics, though all VISA interfaces support the feature and behave similarly. The example is in $(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/apps/audio1_copy/async.

LAD

The Link Arbiter Daemon is a feature used when multiple applications want to use the same remote Server. (Note that it's only needed on DSP Link-based systems. Systems using SysLink, and by extension CE 3.x+ releases, do not require LAD.)

There is an example that shows how to configure executables to use LAD in $(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/apps/speech_copy_LAD.

Build

The CE releases include a examples/build_instructions.html file that describes the build mechanics for each release. As customer feedback is integrated, the approach occasionally changes. Refer to the build_instructions.html provided with CE for details about building the examples with your release.

Changes in CE 2.24

Significant changes were made to clean up the example build process in the CE 2.24 release. This section describes some of those changes and the rationale behind them.

xdcpaths.mak and config.bld

xdcpaths.mak and config.bld were significantly restructured.

user.bld was (finally!) removed.

More Details Needed

Pre-built Examples

In CE 2.24, most pre-built example executables were removed from the product. This was driven by the fact that the DSP Link releases used had incompatible version numbers between the WinCE and Linux releases. If a Server was built with Linux-Link, the version "1.61.03" would be built into it. If a Server was built with WinCE-Link, the version "1.61.04" would be built into it.

The Link version is built into both the ARM and DSP executables, and a run-time check is made to ensure they match. Since the Codec Engine product couldn't easily pre-built Servers that would satisfy both WinCE and Linux customers (one of them would have a version mis-match!), it didn't provide any.

Pragmatically, this only resulted in the removal of the pre-built Servers and the previously provided pre-built video_copy example application. The pre-built codecs continued to be supplied as they are all BSD licensed and are unaffected by the DSP Link version issue.

This significantly decreased the size of the CE product.

Pre-built Linux Modules

As WinCE support was added in CE 2.24, there was risk of distributing GPL content (pre-built .ko drivers) to WinCE customers. As a precaution, all pre-built .ko drivers were no longer provided.

This also decreased the size of the CE product.

More TBD

See Also

• Codec Engine Examples Memory Map
• Codec Engine FAQ
• Codec Engine Roadmap