Deinterlacer Algorithm on C64x+downloads.isee.biz › pub › files ›...

Deinterlacer Algorithm on C64x+

User’s Guide

April 2010

IMPORTANT NOTICE

Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI’s terms and conditions of sale supplied at the time of order acknowledgment. TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed. TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards. TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information pub-lished by TI regarding third-party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI. Reproduction of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additional restrictions. Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all ex-press and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements. TI products are not authorized for use in safety-critical applications (such as life support) where a failure of the TI product would reasonably be expected to cause severe personal injury or death, unless officers of the parties have executed an agreement specifically governing such use. Buyers represent that they have all necessary expertise in the safety and regulatory ramifications of their applications, and acknowledge and agree that they are solely responsible for all legal, regulatory and safety-related requirements concerning their products and any use of TI prod-ucts in such safety-critical applications, notwithstanding any applications-related information or support that may be provided by TI. Further, Buyers must fully indemnify TI and its representatives against any damages arising out of the use of TI products in such safety-critical applica-tions. TI products are neither designed nor intended for use in military/aerospace applications or environments unless the TI products are specifically designated by TI as military-grade or "enhanced plastic." Only products designated by TI as military-grade meet military specifications. Buyers acknowledge and agree that any such use of TI products, which TI has not designated as military-grade is solely at the Buyer's risk, and that they are solely responsible for compliance with all legal and regulatory requirements in connection with such use. TI products are neither designed nor intended for use in automotive applications or environments unless the specific TI products are designated by TI as compliant with ISO/TS 16949 requirements. Buyers acknowledge and agree that, if they use any non-designated products in automo-tive applications, TI will not be responsible for any failure to meet such requirements. Following are URLs where you can obtain information on other Texas Instruments products and application solutions

Products Applications Amplifiers amplifier.ti.com Audio www.ti.com/audio Data Converters dataconverter.ti.com Automotive www.ti.com/automotive DLP® Products www.dlp.com Communications and Telecom www.ti.com/communications DSP dsp.ti.com Computers and Peripherals www.ti.com/computers Clocks and Timers www.ti.com/clocks Consumer Electronics www.ti.com/consumer-apps Interface interface.ti.com Energy www.ti.com/energy Logic logic.ti.com Industrial www.ti.com/industrial Power Mgmt power.ti.com Medical www.ti.com/medical Microcontrollers microcontroller.ti.com Security www.ti.com/security RFID www.ti-rfid.com Space, Avionics & Defense www.ti.com/space-avionics-defense RF/IF and ZigBee® Solutions www.ti.com/lprf Video & Imaging www.ti.com/video Wireless www.ti.com/wireless-apps

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265 Copyright © 2010, Texas Instruments Incorporated

Preface

Read This First

About This Manual

This document describes how to install and work with Texas Instruments (TI) Deinterlacer algorithm implementation on the C64x+ platform. It also provides a detailed Application Programming Interface (API) reference and information on the sample application that accompanies this component.

TI’s codec implementations are based on the eXpressDSP Digital Media (XDM) standard. XDM is an extension of the eXpressDSP Algorithm Inter-face Standard (XDAIS).

Intended Audience

This document is intended for system engineers who want to integrate TI’s codec’s with other software to build a multimedia system based on the C64x+ platform.

This document assumes that you are fluent in the C language, have a good working knowledge of Digital Signal Processing (DSP), digital signal proc-essors, and DSP applications. Good knowledge of eXpressDSP Algorithm Interface Standard (XDAIS) and eXpressDSP Digital Media (XDM) standard will be helpful.

How to Use This Manual

This document includes the following chapters:

� Chapter 1 - Introduction, introduces the XDAIS and XDM standards. It also provides an overview of the codec and lists its supported features.

� Chapter 2 - Installation Overview, describes how to install, build, and run the codec.

� Chapter 3 - Sample Usage, describes the sample usage of the codec.

� Chapter 4 - API Reference, describes the data structures and interface functions used in the codec.

� Chapter 5 - Frequently Asked Questions, provides answers to few frequently asked questions related to using this decoder.

� Appendix A – Revision History, highlights the changes in this release.

� Appendix B – Making xDM Compliant, highlights the steps for con-verting xDAIS compliant algorithm to xDM compliant algorithm using IUNIVERSAL interfaces.

Read This First

iv

Related Documentation From Texas Instruments

The following documents describe TMS320 devices and related support tools. To obtain a copy of any of these TI documents, visit the Texas In-struments website at www.ti.com.

� TMS320 DSP Algorithm Standard Rules and Guidelines (literature number SPRU352) defines a set of requirements for DSP algorithms that, if followed, allow system integrators to quickly assemble produc-tion-quality systems from one or more such algorithms.

� TMS320 DSP Algorithm Standard API Reference (literature number SPRU360) describes all the APIs that are defined by the TMS320 DSP Algorithm Interoperability Standard (also known as XDAIS) specifica-tion.

� Technical Overview of eXpressDSP - Compliant Algorithms for DSP Software Producers (literature number SPRA579) describes how to make algorithms compliant with the TMS320 DSP Algorithm Standard, which is part of TI’s eXpressDSP technology initiative.

� Using the TMS320 DSP Algorithm Standard in a Static DSP System (literature number SPRA577) describes how an eXpressDSP-compliant algorithm may be used effectively in a static system with limited mem-ory.

� TMS320c64x+ Megamodule (literature number SPRAA68) describes the enhancements made to the internal memory and describes the new features, which have been added to support the internal memory archi-tecture's performance and protection.

� TMS320c64x+ Megamodule (literature number SPRAA68) describes the enhancements made to the internal memory and describes the new features, which have been added to support the internal memory archi-tecture's performance and protection.

� TMS320C64x+ DSP Megamodule Reference Guide (literature number SPRU871) describes the C64x+ megamodule peripherals.

� TMS320C64x to TMS320C64x+ CPU Migration Guide (literature num-ber SPRAA84) describes migration from the Texas Instruments TMS320C64x™ digital signal processor (DSP) to the TMS320C64x+™ DSP.

� TMS320C6000 Optimizing Compiler v 6.0 Beta User's Guide (literature number SPRU187N) explains how to use compiler tools such as com-piler, assembly optimizer, standalone simulator, library-build utility, and C++ name demangler.

� TMS320C64x/C64x+ DSP CPU and Instruction Set Reference Guide (literature number SPRU732) describes the CPU architecture, pipeline, instruction set, and interrupts of the C64x and C64x+ DSPs.

� DaVinci Technology - Digital Video Innovation Product Bulletin (Rev. A) (literature number SPRT378A)

� The DaVinci Effect: Achieving Digital Video Without Complexity White Paper (literature number SPRY079)

Read This First

v

� DaVinci Benchmarks Product Bulletin (literature number SPRT379)

� DaVinci Technology for Digital Video White Paper (literature number SPRY067)

� The Future of Digital Video White Paper (literature number SPRY066)

Abbreviations

The following abbreviations are used in this document.

Table 1-1. List of Abbreviations

Abbreviation Description

BIOS TI’s simple RTOS for DSPs

D1 720x480 or 720x576 resolutions in pro-gressive scan

DMA Direct Memory Access

DMAN DMA Manager

HDTV High Definition Television

MB Macro Block

MD Motion Detection

PAL Phase Alternate Line

NTSC National Television Standards Committee

I2P Interlace to Progressive

RTOS Real Time Operating System

XDAIS eXpressDSP Algorithm Interface Standard

XDM eXpressDSP Digital Media

YUV Color space in luminance and chromi-nance form

Text Conventions

The following conventions are used in this document:

� Text inside back-quotes (‘‘) represents pseudo-code.

� Program source code, function and macro names, parameters, and command line commands are shown in a mono-spaced font.

Read This First

vi

Product Support

When contacting TI for support on this codec, quote the product name (Deinterlacer algorithm on C64x+) and version number. The version number of the codec is included in the title of the release notes that accompanies this codec.

Trademarks

Code Composer Studio, OMAP, DSP/BIOS, eXpressDSP, TMS320, TMS320C64x, TMS320C6000, OMAP3x and TMS320C64x+ are trade-marks of Texas Instruments.

All trademarks are the property of their respective owners.

vii

Contents

Read This First ................................................................................................................iii

About This Manual..................................................................................................... iii Intended Audience..................................................................................................... iii How to Use This Manual............................................................................................ iii Related Documentation From Texas Instruments...................................................... iv Abbreviations.............................................................................................................. v Text Conventions........................................................................................................ v Product Support......................................................................................................... vi Trademarks ............................................................................................................... vi

Contents .........................................................................................................................vii

Figures.............................................................................................................................ix

Tables...............................................................................................................................xi

Introduction ...................................................................................................................1-1

1.1 Overview of XDAIS and XDM ..........................................................................1-2 1.1.1 XDAIS Overview ................................................................................................1-2 1.1.2 XDM Overview ...................................................................................................1-2

1.2 Overview of DEINTERLACER Algorithm..........................................................1-4 1.3 Supported Services and Features....................................................................1-4

Installation Overview ....................................................................................................2-6

2.1 System Requirements......................................................................................2-7 2.1.1 Hardware............................................................................................................2-7 2.1.2 Software .............................................................................................................2-7

2.2 Installing the Component .................................................................................2-7 2.3 Before Building the Sample Test Application .................................................2-10

2.3.1 Installing DSP/BIOS .........................................................................................2-10 2.3.2 Installing Codec Engine (CE) ...........................................................................2-10

2.4 Building and Running the Sample Test Application........................................2-10 2.4.1 Build options.....................................................................................................2-11

2.5 Configuration Files.........................................................................................2-12 2.5.1 Generic Configuration File ...............................................................................2-12 2.5.2 Deinterlacer Configuration File.........................................................................2-13

2.6 Standards Conformance and User-Defined Inputs.........................................2-13 2.7 Uninstalling the Component ...........................................................................2-13

Sample Usage..............................................................................................................3-15

3.1 Overview of the Test Application....................................................................3-16 3.1.1 Parameter Setup ..............................................................................................3-17 3.1.2 Algorithm Instance Creation and Initialization..................................................3-17 3.1.3 Process Call .....................................................................................................3-19 3.1.4 Algorithm Instance Deletion .............................................................................3-20

3.2 Handshaking Between Application and Algorithm ..........................................3-20

viii

3.3 Sample Test Application ................................................................................3-21 API Reference................................................................................................................4-1

4.1 Symbolic Constants and Enumerated Data Types ...........................................4-2 4.2 Data Structures................................................................................................4-6

4.2.1 Common XDM Data Structures..........................................................................4-6 4.2.2 Deinterlacer Algorithm Data Structures ...........................................................4-11

4.3 Interface Functions ........................................................................................4-16 4.3.1 Creation APIs ...................................................................................................4-16 4.3.2 Initialization API................................................................................................4-17 4.3.3 Control API .......................................................................................................4-18 4.3.4 Data Processing API ........................................................................................4-19 4.3.5 Termination API................................................................................................4-21

Frequently Asked Questions........................................................................................5-1

ix

Figures

Figure 2-1. Component Directory Structure ................................................................2-8

Figure 3-1. Test Application Sample Implementation...............................................3-16

Figure 3-2. Process Call..............................................................................................3-19

Figure 3-5. Interaction Between Application and Codec. .........................................3-21

x

This page is intentionally left blank

xi

Tables

Table 1-1. List of Abbreviations ......................................................................................v

Table 2-1. Component Directories ...............................................................................2-8

Table 3-1. Process () Implementation. .......................................................................3-22

Table 4-1. List of Enumerated Data Types...................................................................4-2

Table 5-1. FAQs for Deinterlacer Algorithm on C64x+................................................5-1

xii


Chapter 1

Introduction

This chapter provides a brief introduction to XDAIS and XDM. It also provides an overview of TI’s implementation of deinterlacer algorithm on C64x platform and its supported features.

Topic Page

1.1 Overview of XDAIS and XDM 1-2

1.2 Overview of DEINTERLACER Algorithm 1-4

1.3 Supported Services and Features 1-4

Introduction

2

1.1 Overview of XDAIS and XDM

TI’s multimedia codec implementations are based on the eXpressDSP Digital Media (xDM) standard. XDM is an extension of the eXpressDSP Algorithm In-terface Standard (xDAIS).

1.1.1 XDAIS Overview

An eXpressDSP-compliant algorithm is a module that implements the abstract interface IALG. The IALG API takes the memory management function away from the algorithm and places it in the hosting framework. Thus, an interaction occurs between the algorithm and the framework. This interaction allows the client application to allocate memory for the algorithm and also share memory between algorithms. It also allows the memory to be moved around while an algorithm is operating in the system. To facilitate these functionalities, the IALG interface defines the following APIs:

� algAlloc()

� algInit()

� algActivate()

� algDeactivate()

� algFree()

The algAlloc() API allows the algorithm to communicate its memory re-quirements to the client application. The algInit() API allows the algorithm to initialize the memory allocated by the client application. The algFree() API allows the algorithm to communicate the memory to be freed when an in-stance is no longer required.

Once an algorithm instance object is created, it can be used to process data in real-time. The algActivate() API provides a notification to the algorithm instance that one or more algorithm processing methods is about to be run zero or more times in succession. After the processing methods have been run, the client application calls the algDeactivate() API prior to reusing any of the instance’s scratch memory.

The IALG interface also defines two more optional APIs algNumAlloc() and algMoved(). For more details on these APIs, see TMS320 DSP Algorithm Standard API Reference (SPRU360).

1.1.2 XDM Overview

In the multimedia application space, you have the choice of integrating any codec into your multimedia system. For example, if you are building a DSP side algorithm, you can IUNIVERSAL APIs for simple integration in your sys-tem. To enable easy integration with the client application, it is important that all codec’s with similar functionality use similar APIs. xDM was primarily de-fined as an extension to xDAIS to ensure uniformity across different classes of codec’s (for example audio, video, image, and speech).

Introduction

3

The XDM standard defines the following two APIs:

� control()

� process()

The control() API provides a standard way to control an algorithm instance and receive status information from the algorithm in real-time. The process() API does the basic processing (encode/decode) of data.

Apart from defining standardized APIs for multimedia codec’s, xDM also stan-dardizes the generic parameters that the client application must pass to these APIs. The client application can define additional implementation specific pa-rameters using extended data structures.

The following figure depicts the xDM interface to the client application.

As depicted in the figure, xDM is an extension to xDAIS forms an interface be-tween the client application and the codec component. xDM insulates the cli-ent application from component-level changes. Since TI’s multimedia algorithms are xDM compliant, it provides you with the flexibility to use any TI algorithm without changing the client application code. For example, if you have developed a client application using an xDM-compliant Deinterlacer al-gorithm, then you can easily replace I2P with another xDM-compliant algo-rithm like FIR.

Client Application

XDAIS Interface (IALG)

TI’s Codec Algorithms

XDM Interface

Introduction

4

1.2 Overview of DEINTERLACER Algorithm It is well known that interlaced video format suffers from edge flicker, interline flicker and line crawling. De-interlacing is designed to reduce the visual arti-fices list above. It becomes very important because HDTV systems support progressive to improve the video quality recently. Various de-interlacing tech-niques have been proposed. Line doubling and average are the fundamental de-interlacing techniques. The edge-based linear average (ELA) performs interpolation in the direction of the highest sample correlation and exhibit good performance. However, ELA method does not performance well in static area. Based on the ELA, several approaches are developed. Motion adaptive technique processes the static area by temporal filtering and motion area by spatial filtering. The most com-plicated video de-interlacing methods use motion compensation, which is very computationally intensive. The performance of MC-based video de-interlacing technique highly depends on the accuracy of motion estimation. This algorithm implements an efficient motion-adaptive deinterlacing method for VLIW DSP architecture based on ELA and temporal interpolation. First, a pixel wise motion index is calculated between two adjacent fields with the same parity. Second, the pixel is classified as “static” or “moving”. This motion index is used to combine the information from previous field with the same parity and the information from the current filed directionally.

The Deinterlacing function described here is intended to provide a simple function (algorithms) to interlaced video format to Progressive video format. This function is provided as XDM algorithm. The provision of separate algo-rithms allows the application to selectively include algorithms, and control the sequence in which they are executed.

1.3 Supported Services and Features

This user guide accompanies TI’s implementation of Deinterlacer on C64x+ platform. This version of the codec has following supported features:

� eXpressDSP Digital Media (xDM 1.0) complaint

� Supports YUV422 interlaced frames

� Outputs are available in YUV 422 progressive format

� Supports DMA based framework

� Supports use of C64x+

Introduction

5


Installation Overview

6

Chapter 2


This chapter provides a brief description on the system requirements and in-structions for installing the codec component. It also provides information on building and running the sample test application.

Topic Page

2.1 System Requirements 2-7

2.2 Installing the Component 2-7

2.3 Before Building the Sample Test Application 2-9

2.4 Building and Running the Sample Test Application 2-10

2.5 Configuration Files 2-12

2.6 Standards Conformance and User-Defined Inputs 2-13

2.7 Uninstalling the Component 2-13


7

2.1 System Requirements

This section describes the hardware and software requirements for the normal functioning of the codec component.

The product I2P is supported on platforms characterized by the following Software and Hardware requirements.

2.1.1 Hardware

Hardware requirements for running the I2P module are as follow.

A. TI’s C64x+: OMAP EVM or Davinci.

B. XDS510 JTAG scan-based emulator.

2.1.2 Software

The following are the software requirements for the normal functioning of the codec:

� Development Environment: This project is developed, build and de-bugged using Code Composer Studio version 3.3.81. It has been tested with OMAP3x EVM.

� Code Generation Tools: This project is compiled, assembled, archived, and linked using the code generation tools version 6.1.12.

� XDS 510 emulation drivers.

2.2 Installing the Component

The codec component is released as a compressed archive. To install the co-dec, extract the contents of the zip file onto your local hard disk. The zip file extraction creates a top-level directory called c64xplus_deinterlacer_01_00_00_07 under which another directory named OMAP3x is created.

Figure 2-1 shows the sub-directories created in the c64xplus_deinterlacer_01_00_00_07 directory.


8

Figure 2-1. Component Directory Structure

Table 2-1. Component Directories

Sub-Directory Description

\c64xplus_deinterlacer_01_00_00_07\Inc Contains XDM related header files which allow interface to the codec library

\c64xplus_deinterlacer_01_00_00_07\Lib Contains generated algorithm library file

\c64xplus_deinterlacer_01_00_00_07\Docs Contains user guide and datasheet

\c64xplus_deinterlacer_01_00_00_07\Client\Build Contains the sample test application project (.pjt) file

\c64xplus_deinterlacer_01_00_00_07\Client\Test\Src Contains application C files

\c64xplus_deinterlacer_01_00_00_07\Client\Test\Inc Contains header files needed for the application code

\c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Input

Contains input test vectors


9

Sub-Directory Description

\c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Output

Contains output generated by the codec

\c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Reference

Contains Reference output frames

\c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Config

Contains configuration parameter file

\c64xplus_deinterlacer_01_00_00_07\Src Contains algorithm source files and header files

\c64xplus_deinterlacer_01_00_00_07\Build_I2P Contains the algorithm project (.pjt) file

\c64xplus_deinterlacer_01_00_00_07\linuxtestapp Contains Linux side test application for deinter-lacer

\c64xplus_deinterlacer_01_00_00_07\utilities Contains utilities for generating RTSC package and adding new algorithm to codec server


10

2.3 Before Building the Sample Test Application

This codec is accompanied by a sample test application. To run the sample test application, you need DSP/BIOS, TI Codec Engine (CE). This version of the codec is validated with DSP/BIOS version 5.33.02, Codec Engine (CE) version 2.24, and XDAIS version 6.25

2.3.1 Installing DSP/BIOS

You can download DSP/BIOS from the TI’s external website:

https://www-a.ti.com/downloads/sds_support/targetcontent/bios/index.html

Install DSP/BIOS at the same location where you have installed Code Composer Studio. For example:<install directory>\CCStudio_v3.3

Set system environment variable BIOS_INSTALL_DIR to point to the loca-tion where the <bios_directory> is present.

The sample test application may use the following DSP/BIOS files:

� Header file, bcache.h available in the <install directory>\CCStudio_v3.3\<bios_directory>\packages \ti\bios\include directory.

� Library file, biosDM420.a64P available in the <install directory>\CCStudio_v3.3\<bios_directory>\packages\ti\bios\lib directory.

2.3.2 Installing Codec Engine (CE)

Download CE version 2.24 or newer from TI’s external website:

https://www-a.ti.com/downloads/sds_support/targetcontent/CE/index.html

The codec uses framework components and XDIAS version that are a part of CE 2.24 or newer.

1) Extract the CE zip file to the same location where you have installed Code Composer Studio. For example: <install direc-tory>\CCStudio_v3.3.

2) Set a system environment variable named FC_INSTALL_DIR pointing to <install directory>\CCStudio_v3.3\<ce_directory>\cetools.

3) Set a system environment variable named XDAIS_INSTALL_DIR point-ing to <install direc-tory>\CCStudio_v3.3\<ce_directory>\cetools\packages\ti\xdais.

2.4 Building and Running the Sample Test Application

This codec is accompanied by a sample test application. The application will run in TI’s Code Composer Studio development environment. To build and run the sample application in Code Composer Studio, follow these steps:

1) Extract the .zip file.


11

2) Verify that you have installed TI’s Code Composer Studio version 3.3 with SR 3.0 and code generation tools version 6.1.12. Start the Code Com-poser Studio to view the Parallel Debug Manager (PDM) window.

3) In the PDM window, open the window by double clicking on CortexA_0, load the GEL file omap3430_cortexA.gel and click on Debug >Connect.

4) Reset the DSP by enabling IVA22_GEM_startup

5) In the PDM window, open the window by double clicking on C6400PLUS, click on Debug >Connect.

6) Open the test application project file in C6400PLUS window, i2p_test.pjt in Code Composer Studio. This file is available in the \Deinterlacer\Client\Build sub-directory.

7) Select Project > Build to build the sample test application. For build op-tions refer, section 2.4.1.This will also build the dependent project i2p_tic64xplus.pjt stored at location \Deinterlacer\Build_I2P and create the final executable file, i2p_test.out at \Deinterlacer\Client\Build\Out sub-directory.

8) Select File > Load, browse to the \Client\Build\Out sub-directory, select the codec executable created in step 5, and load it into Code Composer Studio in preparation for execution.

9) Select Debug > Run to execute the sample test application on DSP. The sample test application takes the input files stored in the \Deinterlacer\Client\Test\TestVecs\Input sub-directory, runs the deinter-lacer, and dumps the output files at \Deinterlacer\Client\Test\TestVecs\Output sub-directory. \Deinterlacer \Client\Test\TestVecs\Reference sub-directory contains reference frames for compare.

10) The output can be viewed in any YUV player, which supports YUV 4:2:2 UY player option. One such kind of tool is PCView.

2.4.1 Build options

Compiler options: Basic: � Target version : C64x+ (-mv6400+) � Opt speed Vs Size : Speed more critical (-ms0) � Opt Level : file(-o3) Advanced: � Interrupt Threshold (-mi) : -mi1000 Files: � Asm directory (-fs) : give the path of ASM directory in Build folder � Obj directory (-fr) : give the path of Obj directory in Build folder If required check the option: keep generated asm files (-k) in “Assembly” category. Include Search Path (-i): Give the path for include files of cgtools, xDAIS,

xDM and files provided with the deliverable.


12

Linker Options: Output filename (-0) : Mention the path of \Build\Out directory for

placing .out file. Map filename : Mention the path of \Build\Map directory for

placing .map file. Include Libraries (-l) : rts64plus.lib (provided in the cgtools folder of

CCS 3.2) and include the library provided in \c64xplus_deinterlacer_01_00_00_07\Lib direc-tory.

Now build the project with the above options. Run the project and see the output .yuv file in \c64xplus_deinterlacer_01_00_00_07\ClientTest\TestVecs\Ouput di-rectory.

2.5 Configuration Files

This codec is shipped along with two configuration files:

� Generic configuration file (Testvecs.cfg) – specifies input and reference files for the sample test application.

� Decoder configuration file (Testparams.cfg) – specifies the configuration parameters required for the Decoder.

2.5.1 Generic Configuration File

The sample test application shipped along with the codec uses the configura-tion file, Testvecs.cfg for determining the input and reference files for running the codec and checking for compliance. The Testvecs.cfg file is available in the \Client\Test\TestVecs\Config sub-directory.

The format of the Testvecs.cfg file is:

Config Input Output

where:

� Config is the Decoder configuration file. For details, see Section 2.5.2.

� Input is the input file name with complete path

� Output is the output file name.

A sample Testvecs.cfg file is as shown: ..\..\Test\TestVecs\Config\Testparams.cfg

/* Test Parameters File */

..\..\Test\TestVecs\Input\Sample_720x576_YUV422ILE.yuv

/* Input File */

..\..\Test\TestVecs\Output\Sample_720x576_YUV422P.yuv

/* Output File */


13

2.5.2 Deinterlacer Configuration File

The I2P configuration file, Testparams.cfg contains the configuration parame-ters required for the deinterlacer. The Testparams.cfg file is available in the \Client\Test\TestVecs\Config sub-directory.

A sample Testparams.cfg file is as shown: # New Input File Format is as follows

# <ParameterName> equales to <ParameterValue> # Comment

#

############################################################

# Parameters

############################################################

ImageWidth = 720 # Image width in Pels, must be

multiple of 16

ImageHeight = 576 # Image height in Pels, must be

multiple of 16

StartingFrame = 0 # Frame to start the deinterlac-

ing

FramesToDeinterlace = 1 # Number of frames to be deinter-

laced

Any field in the II2P_Params structure (see section 4.2.1.6) can be set in the Testparams.cfg file using the syntax shown above. If you specify additional fields in the Testparams.cfg file, ensure to modify the test application appro-priately to handle these fields.

The following parameters are specified in this file, with each parameter on a new line:

� Video frame width

� Video frame height

� Starting frame for deinterlace

� Number of frames to deinterlace

2.6 Standards Conformance and User-Defined Inputs

To check the conformance of the codec for the input files shipped along with the codec, compare the outputs dumped in the \c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Output folder with the corresponding reference files present in the \c64xplus_deinterlacer_01_00_00_07\Client\Test\TestVecs\Reference folder.

2.7 Uninstalling the Component

To uninstall the component, delete the codec directory from your hard disk.


14


Sample Usage

15

Chapter 3

Sample Usage

This chapter provides a detailed description of the sample application that accompanies this codec component.

Topic Page

3.1 Overview of the Test Application 3-16

3.2 Handshaking Between Application and Algorithm 3-20

3.3 Sample Test Application 3-21

Sample Usage

16

3.1 Overview of the Test Application

The test application is an IUniversal base class of the deinterlacer library. The main test application files are test_main.c and i2p_test.h. These files are available in the \c64xplus_deinterlacer_01_00_00_07\Client\Test\Src and \c64xplus_deinterlacer_01_00_00_07\Client\Test\Inc sub-directories respec-tively.

Figure 3-1 depicts the sequence of APIs exercised in the sample test applica-tion.

Figure 3-1. Test Application Sample Implementation

Sample Usage

17

The test application is divided into four logical blocks:

1) Parameter setup

2) Algorithm instance creation and initialization

3) Process call

4) Algorithm instance deletion

3.1.1 Parameter Setup

Each codec component requires various codec configuration parameters to be set at initialization. For example, a video codec requires parameters such as video height, video width, and so on. The test application obtains the re-quired parameters from the Deinterlacer configuration files.

In this logical block, the test application does the following:

1) Opens the generic configuration file, Testvecs.cfg and reads the Deinter-lacer configuration file name (Testparams.cfg), input file name, and output file name.

2) Opens the Deinterlacer configuration file, (Testparams.cfg) and reads the various configuration parameters required for the algorithm.

For more details on the configuration files, see Section 2.5.

3) Sets the II2P_Params structure based on the values it reads from the Testparams.cfg file.

4) Reads the input bit-stream into the application input buffer.

After successful completion of the above steps, the test application does the algorithm instance creation and initialization.

3.1.2 Algorithm Instance Creation and Initialization

In this logical block, the test application accepts the various initialization pa-rameters and returns an algorithm instance pointer. The following APIs are called in sequence:

1) algNumAlloc() - To query the algorithm about the number of memory records it requires.

2) algAlloc() - To query the algorithm about the memory requirement to be filled in the memory records.

3) algInit() - To initialize the algorithm with the memory structures pro-vided by the application.

Sample Usage

18

A sample implementation of the create function that calls algNumAlloc(), algAlloc(), and algInit() in sequence is provided in the ALG_create() function implemented in the alg_create.c file.

After successful creation of the algorithm instance, the test application does allocate DMA channels to algorithm. This requires initialization of DMA Re-source Manager Module (DMAN3) and grant of DMA resources. This is im-plemented by calling DMAN3 interface functions in the following sequence:

1) DMAN3_init() - To initialize the DMAN module.

2) DMAN3_grantDmaChannels() - To adds one or several algorithms to the DMA Manager. The DMA Manager will grant DMA resources to the algo-rithms as a result. This function is called when initializing xDAIS algorithm instances resource manager.

Note:

DMAN3 function implementations are provided in dman3.a64P library.

Sample Usage

19

3.1.3 Process Call

After algorithm instance creation and initialization, the test application does the following:

1) Gets the dynamic parameters (if they change during run-time) by calling the control() function with the XDM_GETPARAMS command.

2) Sets the input and output buffer descriptors required for the proc-ess()function call. The input and output buffer descriptors are defined based on out requirement.

3) Implements the process call based on the non-blocking mode of opera-tion. The behavior of the algorithm could be controlled using various dy-namic parameters. The inputs to the process() functions are input and output buffer descriptors, pointer to the IDEINTER_InArgs and IDEIN-TER_OutArgs structures.

Figure 3-2. Process Call

Note:

� The process call returns control to the application after the initial setup related tasks are completed

� Application can schedule a different task to use the freed up ARM resource

� All service requests from DSP handled through interrupts

� Application resumes the suspended process call after last service request for DSP 0/1 has been handled

� Application can now complete concluding portions of the process call and return

The control() and process() functions should be called only within the scope of the algActivate() and algDeactivate() XDAIS functions which activate and deactivate the algorithm instance respectively. Once an algorithm is activated, there could be any ordering of control() and proc-ess() functions. The following APIs are called in sequence:

ARM Sys-tem appli-cation

Process call frame n

DSP Tasks

DSP level tasks for frame n

ARM deinter-lace Task

Transfer of tasks on ARM

DSP level tasks for frame n+1

Process call frame n+1

ARM system tasks

DSP Busy

Interrupt between DSP and ARM

Sample Usage

20

1) algActivate() - To activate the algorithm instance.

2) control() (optional) - To query the algorithm on status or setting of dy-namic parameters and so on, using the six available control commands.

3) process() - To call the deinterlacer with appropriate input/output buffer and arguments information.

4) control() (optional) - To query the algorithm on status or setting of dy-namic parameters and so on, using the six available control commands.

5) algDeactivate() - To deactivate the algorithm instance.

6) The for loop encapsulates frame level process() call and updates the input buffer pointer every time before the next call. The for-loop breaks off either when an error condition occurs or when the input buffer exhausts or number of frames done. It also protects the process()call from file op-erations by placing appropriate calls for cache operations as well. The test application does a cache invalidate for the valid input buffers before process() and a cache write back invalidate for output buffers after process().

In the sample test application, after calling algDeactivate(), the output data is dumped to a file.

3.1.4 Algorithm Instance Deletion

Once deinterlaceing is complete, the test application delete the current algo-rithm instance. The following APIs are called in sequence:

1) algNumAlloc() - To query the algorithm about the number of memory records it used.

2) algFree() - To query the algorithm to get the memory record information and then free them up for the application.

A sample implementation of the delete function that calls algNumAlloc() and algFree()in sequence is provided in the ALG_delete() function im-plemented in the alg_create.c file.

After successful execution of the algorithm, the test application release re-sources and frees up the DMAN3 resource manager for the algorithm. This is implemented by calling DMAN3 interface functions in the following sequence:

1) DMAN3_releaseDmaChannels() - To removes logical channel resources from one or several algorithm instances. This function is to be used whenever the DMAN3_grantDMAChannels() function is used to grant DMA resources to the algorithms.

2) DMAN3_exit() – To finalize the DMAN module.

3.2 Handshaking Between Application and Algorithm

Application provides the algorithm with its implementation of functions for the deinterlacer task to move to SEM-pend state, when the execution happens in

Sample Usage

21

the co-processor. The algorithm calls these application functions to move the deinterlacer task to SEM-pend state. Compliance conversion is based on IUNIVERSAL API’s see Appendix - B

Figure 3-3. Interaction Between Application and Codec.

Note:

� Process call architecture shares Host resource among multiple threads.

� ISR ownership is with the Host layer resource manager – outside the codec.

� The actual codec routine to be executed during ISR is provided by the codec.

� Codec is OS independent.

The functions to be implemented by the application are:

1) UNIVERSAL_create(hEngine, codecName, (IUNIVERSAL_Params

*)&i2pParams);

This function is called by the application to create algorithm instance by passing the appropriate parameters.

2) I2P_TI_process(IUNIVERSAL_Handle handle, XDM1_BufDesc

*inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs,

IDEINTER_InArgs *inArgs, IDEINTER_OutArgs *outArgs)

This function is called by the algorithm for doing deinterlace.

3.3 Sample Test Application

The test application exercises the IUNIVERSAL base class of the Deinter-

lacer Algorithm.

Algorithm

process()

Application Side

Application

#include <../universal.h>

UNIVERSAL_create(hEngine, co-

decName,

(IUNIVERSAL_Params *)&i2pParams);

UNIVERSAL_process(hDeinterlace,

&universalInBufDesc,

&universalOutBufDesc, NULL,

(IUNIVERSAL_InArgs *)&inputArgs,

(IUNIVERSAL_OutArgs *)&outputArgs);

I2P_TI_process(IUNIVERSAL_H

andle handle, XDM1_BufDesc

*inBufs,

XDM1_BufDesc *outBufs,

XDM1_BufDesc *inOutBufs,

IDEIN-

TER_InArgs *inArgs, IDEIN-

TER_OutArgs *outArgs)

{

… … … …

}

Sample Usage

22

Table 3-1. Process () Implementation. /* Main Function acting as a client for Video Decode Call*/

/*------------- Deinterlacer Algorithm creation -------------*/

hDeinterlace = UNIVERSAL_create(hEngine, codecName, IUNIVER-

SAL_Params *)&i2pParams);

/* Get run-time parameters if any */

UNIVERSAL_control(hDeinterlace, XDM_SETPARAMS, &dynPrms,

&universalStatus);

for(frameCount = inParams[2];

frameCount<(inParams[2]+(inParams[3])); frameCount++) {

Reading frame from a file……………………………

/* call the i2p frame apply */

UNIVERSAL_process(hDeinterlace, &universalInBufDesc,

&universalOutBufDesc, NULL, (IUNIVERSAL_InArgs *)&inputArgs,

(IUNIVERSAL_OutArgs *)&outputArgs);

Writing the frame into a file……………

} /* for end */

/* end of Do-While loop - which decodes frames*/

UNIVERSAL_delete((UNIVERSAL_Handle)codec);

Note:

This sample test application does not depict the actual function parame-ter or control code. It shows the basic flow of the code.

Chapter 4

API Reference

This chapter provides a detailed description of the data structures and in-terfaces functions used in the codec component.

Topic Page

4.1 Symbolic Constants and Enumerated Data Types 4-2

4.2 Data Structures 4-6

4.3 Interface Functions 4-16

API Reference

2

4.1 Symbolic Constants and Enumerated Data Types

This section summarizes all the symbolic constants specified as either #define macros and/or enumerated C data types. For each symbolic constant, the semantics or interpretation of the same is also provided.

Table 4-1. List of Enumerated Data Types

Group or Enumeration Class Symbolic Constant Name Description or Evaluation

II2P_FOUR20 For YUV420 planar format Not applicable for deinterlacer

II2P_FOUR22 For YUV422 planar format Not applicable for deinterlacer

II2P_FOUR22_ILE For YUV422 interleaved Fixed

II2P_VideoFormat_e

II2P_FOUR44 For YUV444 format

II2P_VD4

Content type is not applicable

II2P_VD3 Progressive video content

II2P_Alg

II2P_ELA Progressive video content

II2P_GETSTATUS Query algorithm instance to fill Status structure if any.

II2P_Cmd

II2P_SETSTATUS Set run-time dynamic parameters through the dynamic params struc-ture if any.

XDM_BYTE Big endian stream

XDM_LE_16 16-bit little endian stream Not applicable for deinterlacer algo-rithm.

XDM_LE_32 32-bit little endian stream Not applicable for deinterlacer algo-rithm.

XDM_LE_64 64 bit little endian stream Not applicable for deinterlacer algo-rithm.

XDM_BE_16 16 bit big endian stream Not applicable for deinterlacer algo-rithm.

XDM_DataFormat


API Reference

3



XDM_CHROMA_NA Chroma format not applicable

XDM_YUV_420P YUV 4:2:0 planar

XDM_YUV_422P YUV 4:2:2 planar. Not applicable for deinterlacer algo-rithm.

XDM_YUV_422IBE YUV 4:2:2 interleaved (big endian). Not applicable for deinterlacer algo-rithm.

XDM_YUV_422ILE YUV 4:2:2 interleaved (little endian) Not applicable for deinterlacer algo-rithm.



XDM_GRAY Gray format. Not applicable for deinterlacer algo-rithm.

XDM_RGB RGB color format. Not applicable for deinterlacer algo-rithm.

XDM_YUV_420SP YUV 420 semi_planar format.(Luma 1st plane, CbCr interleaved 2nd plane) Not applicable for deinterlacer algo-rithm.

XDM_ARGB8888 Alpha plane. Not applicable for deinterlacer algo-rithm.

XDM_RGB555 RGB 555 color format. Not applicable for deinterlacer algo-rithm.

XDM_ChromaFormat

XDM_RGB565 RGB 565 color format. Not applicable for deinterlacer algo-rithm.

API Reference

4


XDM_YUV_444ILE YUV 4:4:4 interleaved (little endian). Not applicable for deinterlacer algo-rithm.

XDM_CHROMAFORMAT_DEFAULT

Default value is set to XDM_YUV_422ILE

Not applicable for deinterlacer algo-rithm.

XDM_GETSTATUS Query algorithm instance to fill Status structure

XDM_SETPARAMS Set run-time dynamic parameters through the dynamic params struc-ture

XDM_RESET

Reset the algorithm

XDM_SETDEFAULT Initialize all fields in params struc-ture to default values specified in the library .

XDM_FLUSH Handle end of stream conditions. This command forces algorithm in-stance to output data without addi-tional input. Not applicable for deinterlacer algo-rithm.

XDM_GETBUFINFO Query algorithm instance regarding the properties of input and output buffers Not applicable for deinterlacer algo-rithm.

XDM_CmdId

XDM_GETVERSION Query the algorithm’s version. The result is returned in the data field of the respective _Status struc-ture. Not applicable for deinterlacer algo-rithm.

XDM_GETCONTEXTINFO Query a split codec part for its con-text needs. Not applicable for deinterlacer algo-rithm.

XDM_AccessMode XDM_ACCESSMODE_READ The algorithm read from the buffer using the CPU. Not applicable for deinterlacer algo-rithm.

API Reference

5


XDM_ACCESSMODE_WRITE The algorithm wrote from the buffer using the CPU. Not applicable for deinterlacer algo-rithm.

XDM_PARAMSCHANGE Bit 8 � 1 - Sequence parameters

change � 0 - Ignore

XDM_APPLIEDCONCEALMENT Bit 9 � 1 - Applied concealment � 0 - Ignore

XDM_INSUFFICIENTDATA Bit 10 � 1 - Insufficient data � 0 - Ignore

XDM_CORRUPTEDDATA Bit 11 � 1 - Data problem/corruption � 0 - Ignore

XDM_CORRUPTEDHEADER Bit 12 � 1 - Header problem/corruption � 0 - Ignore

XDM_UNSUPPORTEDINPUT Bit 13 � 1 - Unsupported

feature/parameter in input � 0 - Ignore

XDM_UNSUPPORTEDPARAM Bit 14 � 1 - Unsupported input

parameter or configuration � 0 - Ignore

XDM_ErrorBit

XDM_FATALERROR Bit 15 � 1 - Fatal error (stop encoding) � 0 - Recoverable error

Note:

The remaining bits that are not mentioned in XDM_ErrorBit are interpreted as:

� Bit 16-32:Reserved

� Bit 0-7:Codec and implementation specific

� Only Bit 0 is presently used by algorithm to signal junk data error. This bit is set and algorithm has no output frames, if input data does not contain start code for any of the following:

n Sequence Header

n Group of Pictures header

API Reference

6

n Picture header

n Sequence End code

The algorithm can set multiple bits to 1 depending on the error condition.

4.2 Data Structures

This section describes the XDM defined data structures, which are common across codec classes. These XDM data structures can be extended to define any implementation specific parameters for a codec component.

4.2.1 Common XDM Data Structures

This section includes the following common XDM data structures:

� XDM_BufDesc

� XDM1_BufDesc

� XDM_SingleBufDesc

� XDM1_SingleBufDesc

� IUNIVERSAL_Fxns

� IUNIVERSAL_Params

� IUNIVERSAL_DynamicParams

� IUNIVERSAL_InArgs

� IUNIVERSAL_Status

� IUNIVERSAL_OutArgs

API Reference

7

4.2.1.1 XDM_BufDesc

║ Description

This structure defines the buffer descriptor for input and output buffers. ║ Fields

Field Data Type Input/ Output

Description

**bufs XDAS_Int8 Input Pointer to the vector containing buffer addresses

numBufs XDAS_Int32 Input Number of buffers

*bufSizes XDAS_Int32 Input Size of each buffer in bytes

4.2.1.2 XDM1_BufDesc

║ Description

This structure defines the buffer descriptor for input and output buffers. ║ Fields


Description

numBufs XDAS_Int32 Input Number of buffers

descs[XDM_MAX

_IO_BUFFERS]

XDM1_SingleBufDesc Input Array of buffer descriptors.

4.2.1.3 XDM_SingleBufDesc

║ Description

This structure defines the buffer descriptor for single input and output buff-ers.

║ Fields


Description

*buf XDAS_Int8 Input Pointer to the buffer

bufSize XDAS_Int32 Input Size of the buffer in bytes

API Reference

8

4.2.1.4 XDM1_SingleBufDesc

║ Description

This structure defines the buffer descriptor for single input and output buff-ers.

║ Fields


Description

*buf XDAS_Int8 Input Pointer to the buffer

bufSize XDAS_Int32 Input Size of the buffer in bytes

accessMask XDAS_Int32 Output If the buffer was not accessed by the algorithm proces-sor (for example, it was filled by DMA or other hardware accelerator that does not write through the algorithm's CPU), then bits in this mask should not be set.

4.2.1.5 IUNIVERSAL_Fxns

║ Description

This structure contains pointers to all the XDAIS and XDM interface func-tions.

║ Fields


Description

ialg IALG_Fxns Input Structure containing pointers to all the XDAIS interface functions. For more details, see TMS320 DSP Algorithm Stan-dard API Reference (literature number SPRU360).

*process XDAS_Int32 Input Pointer to the process() function

*control XDAS_Int32 Input Pointer to the control() function

4.2.1.6 IUNIVERSAL_Params

║ Description

This structure defines the creation parameters for an algorithm instance ob-ject. Defines the creation time parameters for all IUNIVERSAL instance ob-jects.

║ Fields

API Reference

9


Description

size XDAS_Int32 Input Size of the basic or extended (if being used) data structure in bytes.

4.2.1.7 IUNIVERSAL_DynamicParams

║ Description

This structure defines the run-time parameters for an algorithm instance ob-ject. This structure defines the codec parameters that can be modified after creation via control() calls.

║ Fields


Description


Note:

� It is not necessary that a given implementation support all dynamic parameters to be configurable at run time. If a particular algorithm does not support run-time updates to a parameter that the application is attempting to change at runtime, it may indicate this as an error.

4.2.1.8 IUNIVERSAL_InArgs

║ Description

This structure defines the run-time input arguments for an algorithm instance object. Defines the input arguments for all IUNIVERSAL instance process function.

║ Fields


Description

Size XDAS_Int32 Input Size of the basic or extended (if being used) data structure in bytes.

API Reference

10

4.2.1.9 IUNIVERSAL_Status

║ Description

This structure defines parameters that describe the status of an algorithm instance object. Defines instance status parameters (read-only).

║ Fields


Description


extendedError XDAS_Int32 Output Extended error code. See XDM_ErrorBit enumeration for

details.

data XDM_SingleBufDesc Output Buffer information structure for information passing buffer.

4.2.1.10 IUNIVERSAL_OutArgs

║ Description

This structure defines the run-time output arguments for an algorithm in-stance object.

║ Fields


Description


extendedError XDAS_Int32 Output Extended error code. See XDM_ErrorBit enumera-

tion for details.

API Reference

11

4.2.2 Deinterlacer Algorithm Data Structures

This section includes the following Deinterlacer Algorithm specific data structures:

� II2P_InputObject

� II2P_OutputObject

� II2P_Fxns

� II2P_Params

� IDEINTER_InArgs

� II2P_Status

� IDEINTER_OutArgs

4.2.2.1 II2P_InputObject

║ Description

This structure defines the input parameters of the deinterlace algorithm

║ Fields

Field Data Type Input/ Out-put

Description

width XDAS_UInt16 Input Width of interlaced frame

height XDAS_UInt16 Input numLines of interlaced Frame (Height)

fn XDAS_UInt8 Input Pointer to an even/odd image line in current video frame. (input + pitch) points to the image line in alternative field. (input + 2*pitch) points to the even/odd line with the same parity as input points to.

fn_3 XDAS_UInt8 Input Pointer to an image line in previous frame with the same parity as (in-put+pitch) points to

outBuf_Fn XDAS_UInt8 Input Outbuf function pointer

imageFormat II2P_VideoFormat_e

Input Format of input video 422ILE / 420Planar

curFrame_y XDAS_UInt8 Input Pointer to first y line of current frame for planar input

curFrame_cb XDAS_UInt8 Input Pointer to first cb line of current frame for planar input

curFrame_cr XDAS_UInt8 Input Pointer to first cr line of current frame for planar input

API Reference

12


Description

curFrame_yuv_ile XDAS_UInt8 Input Pointer to first byte of current frame for ILE

pitch_cur_frame XDAS_UInt16 Input Offset to the next line in the current frame

prevFld XDAS_UInt8 Input Pointer to the previous field

prevFld_y XDAS_UInt8 Input Pointer to first y line of previous frame for planar input

prevFld_cb XDAS_UInt8 Input Pointer to first cb line of previous frame for planar input

prevFld_Cr XDAS_UInt8 Input Pointer to first cr line of previous frame for planar input

pitch_prev_fld XDAS_UInt16 Input Offset to the next alternate line in the previous frame

outFrame XDAS_UInt8 Input Pointer to the output field

outFrame_y XDAS_UInt8 Input Pointer to first y line of output frame for planar output

outFrame_cb XDAS_UInt8 Input pointer to first cb line of output frame for planar output

outFrame_cr XDAS_UInt8 Input pointer to first cr line of output frame for planar output

pitch_out_frame XDAS_UInt16 Input Offset to the next alternate line in the output frame

useHistoryData XDAS_Bool Input Flag that indicates to I2P whether the previous frame/field are present for the deinterlacing algorithm (TRUE or FALSE)

mvs XDAS_UInt16 Input Pointer to an array of motion vectors out of the video decoder, based on which the threshold for motion detection will be calculated. Assigned to NULL if not present and algorithm uses its own threshold value for motion detection.

nmvs XDAS_UInt16 Input number of motion vectors

4.2.2.2 II2P_OutputObject

║ Description

This structure defines the output parameters of the deinterlace algorithm

API Reference

13

║ Fields


Description

outBuf_Fn XDAS_UInt8 Input Pointer to the de-interlaced line, Must double-word aligned.

Status XDAS_Bool Input Status of the algorithm for checking whether its done the process correctly or not

4.2.2.3 II2P_Fxns

║ Description

This structure contains pointers to all the XDAIS and XDM interface func-tions.

║ Fields


Description

Ialg IALG_Fxns Input Structure containing pointers to all the XDAIS interface functions. For more details, see TMS320 DSP Algorithm Stan-dard API Reference (literature number SPRU360).

*process XDAS_Int32 Input Pointer to the process() function

*control XDAS_Int32 Input Pointer to the control() function

4.2.2.4 II2P_Params

║ Description

This structure defines the creation parameters for an algorithm instance ob-ject. Set this data structure to NULL, if you are not sure of the values to be

specified for these parameters. ║ Fields


Description


Width XDAS_Int32 Input Maximum video height to be supported in pixels

Default value = 720

API Reference

14


Description

Height XDAS_Int32 Input Maximum video width to be supported in pixels

Default value = 576

videoFormat XDAS_Int32 Input Format of the video input default it is 422 inter-leaved Fixed

threshold XDAS_Int32 Input Threshold value Default value = 0x01010101 Not applicable to this release

algSelect II2P_Alg Input Select the algorithm Not applicable to this release

Note:

� Deinterlacer Algorithm does not use the width and height fields

for creating the algorithm instance.

� Maximum video height and width supported are 720 pixels and 576 pixels respectively.

4.2.2.5 IDEINTER_InArgs

║ Description

This structure defines the run-time input arguments for an algorithm in-stance object.

║ Fields


Description

universalInArgs IUNIVERSAL_InArgs Input Size of the extended (if being used) IUNIVERSAL_INARGS data structure in bytes.

inObject II2P_InputParams_t Input Input parameters for deinterlacer algo-rithm

API Reference

15

4.2.2.6 II2P_Status

║ Description

This structure defines parameters that describe the status of an algorithm instance object.

║ Fields


Description


threshold XDAS_UInt32 Output Threshold for deinterlacer algorithm

algSelect II2P_Alg Output Algorithm seclection flag

4.2.2.7 IDEINTER_OutArgs

║ Description

This structure defines the run-time output arguments for an algorithm in-stance object.

║ Fields


Description

universalOutArgs IUNIVER-

SAL_OutArgs

Input Size of the extended (if being used) IUNIVER-SAL_OutArgs data structure in bytes.

outObject II2P_OutputPa

rams_t

Output Output Object structure for deinterlacer algo-rithm.

done XDAS_UInt32 Output Flag for checking wheather process complete all the steps properly

API Reference

16

4.3 Interface Functions

This section describes the application programming interfaces used in the Deinterlacer Algorithm. The I2P APIs are logically grouped into the follow-ing categories:

� Creation – algNumAlloc(), algAlloc()

� Initialization – algInit()

� Control – Control()

� Data processing – algActivate(), process(), algDeactivate()

� Termination – algFree()

You must call these APIs in the following sequence:

1) algNumAlloc()

2) algAlloc()

3) algInit()

4) algActivate()

5) process()

6) algDeactivate()

7) algFree()

control() can be called any time after calling the algInit() API.

4.3.1 Creation APIs

Creation APIs are used to create an instance of the component. The term creation could mean allocating system resources, typically memory.

║ Name

algNumAlloc() – determine the number of buffers that an algorithm requires ║ Synopsis

XDAS_Int32 algNumAlloc(Void); ║ Arguments

Void

║ Return Value

XDAS_Int32; /* number of buffers required */ ║ Description

algNumAlloc() returns the number of buffers that the algAlloc() method requires. This operation allows you to allocate sufficient space to call the al-gAlloc() method.

algNumAlloc() may be called at any time and can be called repeatedly without any side effects. It always returns the same result. The algNumAl-loc() API is optional.

For more details, see TMS320 DSP Algorithm Standard API Reference. ║ See Also

API Reference

17

algAlloc()

║ Name

algAlloc() – determine the attributes of all buffers that an algorithm re-quires

║ Synopsis

XDAS_Int32 algAlloc(const IALG_Params *params, IALG_Fxns

**parentFxns, IALG_MemRec memTab[]); ║ Arguments

IALG_Params *params; /* algorithm specific attributes */

IALG_Fxns **parentFxns;/* output parent algorithm functions */

IALG_MemRec memTab[]; /* output array of memory records */

║ Return Value

XDAS_Int32 /* number of buffers required */

║ Description

algAlloc() returns a table of memory records that describe the size, align-ment, type, and memory space of all buffers required by an algorithm. If suc-cessful, this function returns a positive non-zero value indicating the number of records initialized.

The first argument to algAlloc() is a pointer to a structure that defines the creation parameters. This pointer may be NULL; however, in this case, al-gAlloc(), must assume default creation parameters and must not fail.

The second argument to algAlloc() is an output parameter. algAlloc() may return a pointer to its parent’s IALG functions. Since the client does not require a parent object to be created, this pointer must be set to NULL.

The third argument is a pointer to a memory space of size nbufs * sizeof(IALG_MemRec) where, nbufs is the number of buffers re-turned by algNumAlloc() and IALG_MemRec is the buffer-descriptor struc-ture defined in ialg.h.

After calling this function, memTab[] is filled up with the memory requirements of an algorithm.


algNumAlloc(), algFree()

4.3.2 Initialization API

Initialization API is used to initialize an instance of the Deinterlacer algorithm. The initialization parameters are defined in the II2P_Params structure (see Data Structures section for details).

║ Name

API Reference

18

algInit() – initialize an algorithm instance ║ Synopsis

XDAS_Int32 algInit(IALG_Handle handle, IALG_MemRec memTab[], IALG_Handle p, IALG_Params *algParams);

║ Arguments

IALG_Handle handle; /* handle to the algorithm instance*/

IALG_memRec memTab[]; /* array of allocated buffers */

IALG_Handle p; /* handle to the parent instance */

IALG_Params *algParams; /* algorithm initialization parameters */

║ Return Value

IALG_EOK; /* status indicating success */

IALG_EFAIL; /* status indicating failure */

║ Description

algInit() performs all initialization necessary to complete the run-time crea-tion of an algorithm instance object. After a successful return from algInit(), the instance object is ready to be used to process data.

The first argument to algInit() is a handle to an algorithm instance. This value is initialized to the base field of memTab[0].

The second argument is a table of memory records that describe the base address, size, alignment, type, and memory space of all buffers allocated for an algorithm instance. The number of initialized records is identical to the number returned by a prior call to algAlloc().

The third argument is a handle to the parent instance object. If there is no parent object, this parameter must be set to NULL.

The last argument is a pointer to a structure that defines the algorithm initiali-zation parameters. All fields in the params structure must be set as described in IALG_Params structure (see Data Structures section for details).


algAlloc(), algMoved()

4.3.3 Control API

Control API is used for controlling the functioning of Deinterlacer algorithm during run-time. This is done by changing the status of the controllable pa-rameters of the codec during run-time. These controllable parameters are de-fined in the II2P_Status data structure (see Data Structures section for details).

║ Name

control() – change run-time parameters of the Deinterlacer algorithm and query the decoder status

║ Synopsis

API Reference

19

XDAS_Int32 (*control)( IUNIVERSAL_Handle handle, IUNIVERSAL_Cmd id, IUNIVERSAL_DynamicParams *params, IUNIVERSAL_Status *status);

║ Arguments

IUNIVERSAL_Handle handle; /* handle to the Deinterlacer module instance */

IUNIVERSAL_Cmd id; /* Deinterlacer specific specific control commands*/

IUNIVERSAL_DynamicParams *params /* I2P run-time parameters */

IUNIVERSAL_Status *status /* I2P module instance status parameters */

║ Return Value



║ Description

This function changes the run-time parameters of Dienterlacer Algorithm and queries the status of decoder. control() must only be called after a suc-cessful call to algInit() and must never be called after a call to algFree().

The first argument to control() is a handle to the Deinterlacer Algorithm in-stance object.

The second argument is a command ID. See XMI_CmdId in enumeration table for details.

The third and fourth arguments are pointers to the IUNIVERSAL_DynamicParams and IUNIVERSAL_Status data structures re-spectively.

║ See Also

algInit()

4.3.4 Data Processing API

Data processing API is used for processing the input data using the Deinter-lacer Algorithm.

║ Name

algActivate()– initialize scratch memory buffers prior to processing. ║ Synopsis

Void algActivate(IALG_Handle handle);

║ Arguments

IALG_Handle handle; /* algorithm instance handle */

║ Return Value

Void

║ Description

algActivate() initializes any of the instance’s scratch buffers using the per-sistent memory that is part of the algorithm’s instance object.

API Reference

20

The first (and only) argument to algActivate() is an algorithm instance handle. This handle is used by the algorithm to identify various buffers that must be initialized prior to calling any of the algorithm’s processing methods.

For more details, see TMS320 DSP Algorithm Standard API Reference. (lit-erature number SPRU360).

║ See Also

algDeactivate()

║ Name

process() – basic video decoding call ║ Synopsis

XDAS_Int32 (*process)(IUNIVERSAL_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs, IUNIVERSAL_InArgs *inArgs, IUNIVERSAL_OutArgs *outArgs);

║ Arguments

IUNIVERSAL_Handle handle; /* handle to the I2P module instance */

XDM1_BufDesc *inBufs; /* pointer to input buffer descriptor data structure */

XDM_BufDesc *outBufs; /* pointer to output buffer descriptor data structure */

XDM_BufDesc *inOutBufs; /* pointer to in-output buffer de-scriptor data structure */

IUNIVERSAL_InArgs *inargs /* pointer to the I2p module run-time input arguments data structure */

IUNIVERSAL_OutArgs *outargs /* pointer to the I2P module runtime output arguments data structure */

║ Return Value



║ Description

This function does the basic deinterlaceing. The first argument to process() is a handle to the I2P module instance object.

The second, third and forth arguments are pointers to the input, output and in-out buffer descriptor data structures respectively (see XDM_BufDesc data structure for details). The fourth argument is a pointer to the IUNIVERSAL_InArgs data structure that defines the runtime input arguments for the I2p module instance object.

Note:

Prior to each decode call, ensure that all fields are set as described in XDM_BufDesc and IUNIVERSAL_InArgs structures.

The last argument is a pointer to the IUNIVERSAL_OutArgs data structure that defines the runtime output arguments for the I2P module instance object.

API Reference

21

The algorithm may also modify the output buffer pointers. The return value is IALG_EOK for success or IALG_EFAIL in case of failure. The extendedError field of the IUNIVERSAL_OutArgs structure contains further error conditions flagged by the algorithm.

║ See Also

control()

║ Name

algDeactivate()– save all persistent data to non-scratch memory ║ Synopsis

Void algDeactivate(IALG_Handle handle);

║ Arguments

IALG_Handle handle; /* algorithm instance handle */

║ Return Value

Void

║ Description

algDeactivate() saves any persistent information to non-scratch buffers using the persistent memory that is part of the algorithm’s instance object.

The first (and only) argument to algDeactivate() is an algorithm instance handle. This handle is used by the algorithm to identify various buffers that must be saved prior to next cycle of algActivate() and processing.


algActivate()

4.3.5 Termination API

Termination API is used to terminate the Deinterlacer Algorithm and free up the memory space that it uses.

║ Name

algFree() – determine the addresses of all memory buffers used by the al-gorithm

║ Synopsis

XDAS_Int32 algFree(IALG_Handle handle, IALG_MemRec memTab[]);

║ Arguments

IALG_Handle handle; /* handle to the algorithm instance */

API Reference

22

IALG_MemRec memTab[]; /* output array of memory records */

║ Return Value

XDAS_Int32; /* Number of buffers used by the algorithm */

║ Description

algFree() determines the addresses of all memory buffers used by the algo-rithm. The primary aim of doing so is to free up these memory regions after closing an instance of the algorithm.

The first argument to algFree() is a handle to the algorithm instance.

The second argument is a table of memory records that describe the base address, size, alignment, type, and memory space of all buffers previously al-located for the algorithm instance.

For more details, see TMS320 DSP Algorithm Standard API Reference (litera-ture number SPRU360).

║ See Also

algAlloc()

5-1

Chapter 5

Frequently Asked Questions

This chapter provides answers to few frequently asked questions related to using this decoder.

Table 5-1. FAQs for Deinterlacer Algorithm on C64x+.

Question Answer

How many DMA channels are using the Dein-terlacer algorithm?

4 DMA channels are used.

Does the algorithm support any format other than 422 input?

NO, Only supports 422 interlaced input.

What is the output format? YUV422 progressive frames

What are the resolutions supported by Deinter-lacer algorithm?

NTSC and PAL

Frequently Asked Questions

5-2


Appendix A

Revision History

This User guide revision history highlights the changes made to earlier re-lease.

Table A-1. Revision history for Deinterlacer Algorithm on C64x+.

Section Changes

Global Changes � Modified code generation tools version to 6.1.12. � Modified DSP/BIOS version to 5.33.02 � Modified Codec Engine (CE) version to 2.24 or above � Modified XDAIS version to 6.25

Section 1.3 Supported Services and Features Added following supported features � eXpressDSP Digital Media (XDM 1.0) complaint � Supports YUV422 interlaved frames � Outputs are available in YUV 422 progressive format � Supports DMA based framework � Supports use of C64x+

Section 2.2 Installing the Component � Modified top-level directory name

Section 2.5.1 Generic Configuration File � Modified sample Testvecs.cfg file

Section 2.5.2 Decoder Configuration File � Modified Testparams.cfg file

Section 4.1 Symbolic Constants and Enumerated Data Types IUNIVERSAL_InArgs Added following Symbolic Constants under IUNIVERSAL_InArgs Group or Enumeration Class � inObject

Revision History

5-2

Section Changes

Section 4.2.1.6 IUNIVERSAL_OutArgs

Added following Symbolic Constants under IUNIVERSAL_OutArgs Group or Enumeration Class � outObject

Chapter 5 Added new chapter Frequently Asked Questions

Revision History

A-3


Making xDM Compliant

5-4

Appendix B


This Appendix gives the details on xDAIS to xDM algorithm conversion using IUniversal interface.

xDM standard

The XDM standard requires the each algorithm to extend the XDAIS standard interface. I2P algorithm extends the standard XDM interface.

Follow these modifications for converting I2P algorithm from XDAIS compliant to XDM compliant algorithm. IUNIVERSAL is an XDM compliant interface.

A. Converting interface structures to IUNIVERSAL structures

B. Create an XDM wrapper to hold the control() and process() func-tions

C. Update the IALGFXNS and IUNIVERSAL_Fxns based on 1st and 2

nd

steps

D. Include the Codec Engine’s universal.h header file

E. Convert the header paths to full header paths.

F. Replace regular C types to XDAS types

G. Add “if TI_COMPILER” around code that won’t apply to ARM-only de-vices

A. Converting interface structures to IUNIVERSAL structures

Originally, this algorithm defined its “input” as an input array and its “output” as an output array. Since xDM provides structs to hold these, say, XDM1_BufDesc, we need to migrate our “algorithm-specific” objects to use these generic structs as seen in i2p_ti_xdm.c. Similarly, we need to determine if IUNIVERSAL has structs to hold the I2P params.

Extending params

Obviously, there are a number of “parameters” that the user should be able to set and the algorithm needs to know about, frame width, height etc., Since IUNIVERSAL_Params only contains a size field; we will need to extend it as done in ii2p_ti.h.

typedef struct II2P_Params {

XDAS_Int32 size;

XDAS_UInt16 width;


B-5

XDAS_UInt16 height;

II2P_VideoFormat_e videoFormat;

XDAS_UInt32 threshold;

II2P_Alg algSelect;

} II2P_Params;

Additional structs we need to be extend IUNIVERSAL_InArgs and IUNIVER-SAL_OutArgs are IDEINTER_InArgs and IDEINTER_OutArgs with corre-sponding Input and Output arguments of deinterlacer.

typedef struct IDEINTER_InArgs{

IUNIVERSAL_InArgs universalInArgs;

II2P_InputParams_t inObject;

}IDEINTER_InArgs;

typedef struct IDEINTER_OutArgs{

IUNIVERSAL_OutArgs universalOutArgs;

II2P_OutputParams_t outObject;

XDAS_UInt32 done;

}IDEINTER_OutArgs;

B. Create an xDM wrapper to hold the control() and process() functions

Instead of altering the I2P_TI_frameApply() to use the arguments of IUNIVERSAL_process(), we create a wrapper function, I2P_TI_process() that calls the I2P_TI_frameApply() function in i2p_ti_xdm.c file.

Int I2P_TI_process(IUNIVERSAL_Handle handle, XDM1_BufDesc *inBufs, XDM1_BufDesc *outBufs, XDM1_BufDesc *inOutBufs, IDEINTER_InArgs *inArgs, IDEINTER_OutArgs *outArgs)

{

........

}

In addition, we need to create an IUNIVERSAL_control() function that al-lows us to know the run time parameters changes if any. Again we use the wrapper notion to still use the original I2P_TI_control() call.

Int I2P_TI_xdmControl(IUNIVERSAL_Handle handle, IUNIVERSAL_Cmd id, IUNIVERSAL_DynamicParams *dynParams, IUNIVERSAL_Status *status)

{

......

}


5-6

C. Update the IALGFXNS and IUNIVERSAL_Fxns based on (1) and (2)

The IALGFXNS was modified to set the IALG control() (different from the IUNIVERSAL_control() call which is used to check the parameters) call to NULL since the original IALG control() call did not perform any real func-tion.

The IUNIVERSAL_Fxns that consist of the original IALGFXNS, plus the “xDM” functions process() and control() must be created. The IUNIVERSAL_Fxns expects the IUNIVERSAL_process() and IUNIVERSAL_control() calls to have the arguments and return types de-fined in universal.h. Since the algorithm returns ints instead of XDAS_Int32, we have needed to cast our I2P_TI_process() call to the type IUNIVERSAL_process().

IUNIVERSAL_Fxns I2P_TI_II2P = {

{IALGFXNS},

(XDAS_Int32(*)(IUNIVERSAL_Handle, XDM1_BufDesc *, XDM1_BufDesc *, XDM1_BufDesc *, IUNIVERSAL_InArgs *, IUNIVERSAL_OutArgs*))I2P_TI_process,

(XDAS_Int32(*)(IUNIVERSAL_Handle, IUNIVERSAL_Cmd, IUNIVERSAL_DynamicParams *, IUNIVERSAL_Status *))I2P_TI_xdmControl,

};

D. Include the xDAIS iuniversal.h header file

Only the xDAIS header file since the codec itself is not dependent upon Co-dec Engine.

E. Convert the header paths to full header paths

In the original project, headers from various sources were copied to an “in-clude” directory. Instead, simply reference the header files by providing a complete path, i.e. change “#include <ialg.h>” to “#include <ti/xdais/ialg.h>”.

F. Replace regular C types to XDAS types

Types like “Short” and “Int” – the risk in using these types is that they may not be defined for your particular chipset, or they may have different sizes on dif-ferent architectures. A safer way is to use XDAS types, such as XDAS_Int16, which is obviously of size 16. The example continues to use the regular C types where it can, but any of the IUNIVERSAL APIs expect variables in XDAS types.

Notice that the app uses XDAS types while the app uses regular C types, thus unexpected behavior could occur if the C types aren’t defined similar to the XDAS types for a particular platform. An easy fix to this is to convert the algo-rithm to use XDAS types, but in this case, we want to demonstrate only the minimum steps required to allow an algorithm use IUNIVERSAL.


B-7

G. Add “if TI_COMPILER” around code that won’t apply to ARM-only devices

There are two sections that need to be modified: one for #pragma (as this may result in an ARM compiler warning) and the other when setting the IALG and IMOD function tables (as .set may not be available in other compilers).

#ifdef __TI_COMPILER_VERSION__

#pragma CODE_SECTION(I2P_TI_frameApply, ".text:algActivate")

#endif

#ifdef __TI_COMPILER_VERSION__

asm("_I2P_TI_IALG .set _I2P_TI_II2P");

#else

IALG_Fxns I2P_TI_IALG = { IALGFXNS };

#endif

Date post:	28-Jun-2020
Category:	Documents
Upload:	others
View:	4 times
Download:	0 times

Deinterlacer Algorithm on C64x+downloads.isee.biz › pub › files ›...

Documents