Scribd
Upload
14 views15 pages

EMMA2 Teletext API User Manual

The document is a user manual for the EMMA2 API, specifically detailing the Teletext subsystem. It includes an introduction to the API functions, function prototypes, data structures, and example usage for initializing and processing teletext data. Additionally, it outlines the result codes for various operations and configurable options for the Teletext API.

Uploaded by

gwoodstccd
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
14 views15 pages

EMMA2 Teletext API User Manual

The document is a user manual for the EMMA2 API, specifically detailing the Teletext subsystem. It includes an introduction to the API functions, function prototypes, data structures, and example usage for initializing and processing teletext data. Additionally, it outlines the result codes for various operations and configurable options for the Teletext API.

Uploaded by

gwoodstccd
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

User’s Manual

EMMA2 API

Teletext

CONTENTS

1 Introduction ....................................................................................................................... 2
1.1 Example of TELETEXT API Use .......................................................................... 3
2 Function Prototypes .......................................................................................................... 9
MMAC_TELETEXT_Initialise........................................................................................9
MMAC_TELETEXT_Open ..........................................................................................10
MMAC_TELETEXT_Close..........................................................................................11
MMAC_TELETEXT_SetTeletext.................................................................................12
MMAC_TELETEXT_ProcessTeletext.........................................................................13
3 Data Structures ............................................................................................................... 14
4 Revision History .............................................................................................................. 15

Book No: S16753EE1V0UM00 Doc No: MMAC0039, Issue: 1.1


© NEC Electronics Corporation 2002, 2003 Date: 2003-06-27
The information is this document is subject to change without notice – it is
the reader’s responsibility to check that this is the latest available version.

This document includes company confidential information. It should only be


released to third parties under a Non-Disclosure Agreemant.
1 Introduction
This section defines the API for the MMAC teletext driver. Prior to using any of the functions of this
section it is necessary to initialise the other parts of the MMAC API that this code depends on by calling:
MMAC_RTOS_Initialise()
MMAC_DEMUX_Initialise()
MMAC_VIDENC_Initialise()
MMAC_VIDEO_Initialise()

The Teletext driver is responsible for inserting acquired teletext packets into the Vertical Blanking Interval
(VBI) by setting the appropriate registers of the Video Encoder hardware.
Before using any other functions within the Teletext subsystem, the function
MMAC_TELETEXT_Initialise() should be called. This allocates the system resources necessary for the
subsystem.
Once initialised, the subsystem may then be ‘opened’ for use, by calling MMAC_TELETEXT_Open().
The teletext driver may be configured to insert only subtitle teletext information into the VBI if required.
This is achieved by calling MMAC_TELETEXT_SetTeletext(). By default, the teletext drive will insert
data for both normal teletext pages and subtitles.
It is the responsibility of the application to configure a Demux PID filter using the Demux API in order to
acquire the teletext data. The filter should acquire the complete Transport Packet, including the Transport
Stream header, as the Teletext driver will expect this to be present.
When the Demux notifies the application of the arrival of new data for this filter, the application should
call MMAC_TELETEXT_ProcessTeletext(). The teletext driver will then make this data available to the
Video Encoder, for insertion into the VBI.
When VBI insertion of teletext data is no longer required, the function MMAC_TELETEXT_Close()
should be called. This disables the VBI insertion of teletext. It is the responsibility of the application to
disable the PID filter set up to acquire the teletext data, as the teletext API is not responsible for this.

Functions
The Teletext API provides the following functions:
Function Name Description
MMAC_TELETEXT_Initialise Used to initialise the teletext subsystem and allocate
resources required for using the API.
MMAC_TELETEXT_Open Used to open the teletext subsystem, resetting all
teletext acquisition buffers.
MMAC_TELETEXT_Close Used to close down the teletext subsystem.
MMAC_TELETEXT_SetTeletext Can be used to restrict the type of teletext data
inserted into the VBI to just subtitle information.
MMAC_TELETEXT_ProcessTeletext Used to process the teletext data once it has been
acquired.

Result Codes
The meanings of the various result codes returned by the driver are described in the following table:
Result Code Description
MMAC_TELETEXT_OK A TELETEXT operation has successfully
completed.

2
Result Code Description
MMAC_TELETEXT_FAILED The TELETEXT driver has failed to allocate
sufficient memory for its internal teletext frame
buffers.
MMAC_TELETEXT_ALREADY_INITIALISED The TELETEXT driver has already been initialised.
MMAC_TELETEXT_NOT_INITIALISED The TELETEXT driver has not been initialised.
MMAC_TELETEXT_ALREADY_OPENED The TELETEXT driver has already been opened.
MMAC_TELETEXT_NOT_OPENED The TELETEXT driver has not yet been opened.
MMAC_TELETEXT_INVALID_PARAM The TELETEXT driver has been passed an invalid
parameter.

API Configuration
A number of configurable options, in the form of “#define”s are defined in the Teletext section of the
mmac_config.h source file clearly marked by the comment:

/****************************************************************/
/* */
/* MMAC TELETEXT SETUP */
/* */
/****************************************************************/

These options are:


Define Default Meaning
MMAC_TELETEXT_ MMAC_NO Determines whether or not the Teletext API will
PARAMETER_CHECKING perform any checks on the parameters passed when
called. This should be set to MMAC_YES during
application development and testing, but may be set to
MMAC_NO to improve performance once application
code has been verified.

1.1 Example of TELETEXT API Use

/* Declare variables */
MMAC_DEMUX_DEVICE_HANDLE demuxDevice;
MMAC_DEMUX_RESULT_CODE demuxResult;
MMAC_TELETEXT_RESULT_CODE ttxtResult;

/* Initialise the demux subsystem */


demuxResult = MMAC_DEMUX_Initialise();

/* Open a demux device */


demuxResult = MMAC_DEMUX_OpenDevice( MMAC_DEMUX_TYPE_MPEG2_TS,
&demuxDevice);

/* Set demux device input source */


demuxResult = MMAC_DEMUX_SetDeviceInputSource( demuxDevice,
MMAC_DEMUX_SOURCE_ID_PARALLEL0);

/* Set up demodulator... */
setupDemod();

3
/* Allocate a PID filter for Video acquisition */
demuxResult = MMAC_DEMUX_AllocateAvPidFilter(
MMAC_DEMUX_PID_FILTER_VIDEO_TYPE,
MMAC_DEMUX_CHANNEL_ONE,
MMAC_FALSE,
demuxDevice,
&avPidFilter
);
demuxResult = MMAC_DEMUX_SetPidFilterBuffer(
avPidFilter,
avBufferPointer,
avBufferSize,
&avBuffPointers
);

/* Allocate a PID filter for teletext acquisition */


[Link] = MMAC_FALSE;
[Link] = MMAC_FALSE;
[Link] = MMAC_FALSE;
demuxResult = MMAC_DEMUX_AllocatePesPidFilter(
&pesFilterCtrl,
demuxDevice,
&ttxtPidFilter
);
demuxResult = MMAC_DEMUX_SetPidFilterBuffer(
ttxtPidFilter,
ttxtBufferPointer,
ttxtBufferSize,
&ttxtBuffPointers
);

/* Assign PID values to the PID filters */


demuxResult = MMAC_DEMUX_SetPid( avPidFilter, videoPid );
demuxResult = MMAC_DEMUX_SetPid( ttxtPidFilter, teletextPid );

/* Enable the AV PID filter */


demuxResult = MMAC_DEMUX_EnablePidFilter(
avPidFilter,
MMAC_DEMUX_PID_ENABLE_MODE_PAYLOAD
);

/* Initialise the Video Encoder Hardware */


[Link] = MMAC_VIDENC_FORMAT_PAL;
[Link] = MMAC_VIDENC_MODE_COMPOSITE;
MMAC_VIDENC_Initialise( &vencCfg );

/* Initialise the APIs needed to display video */


MMAC_PAS_Initialise();
MMAC_SCALER_Initialise();
MMAC_DISP_Initialise();

/* Define window for Video on SCALER 1 plane */


[Link] = 0;
[Link] = 719;
[Link] = 0;
[Link] = 575;

/* Initialise the Video API */


MMAC_VIDEO_Initialise();
[Link] = MMAC_VIDEO_PTS;
[Link] = MMAC_VIDEO_ASPECT_4x3;
[Link] = MMAC_VIDEO_ASPECT_4x3;
[Link] = MMAC_VIDEO_LETTERBOX;
[Link] = MMAC_VIDEO_AUTO_ALL;

4
[Link] = MMAC_VIDEO_NO_SOFTNESS;
[Link] = MMAC_VIDEO_NO_COMPRESS;
[Link] = MMAC_VIDEO_PAL;
[Link] = MMAC_FALSE;
[Link] = MMAC_VIDEO_DVB;
[Link] = MMAC_VIDEO_SCAN_ALL;
[Link] = MMAC_VIDEO_FREEZE_ANY;
[Link] = (UI8*)avBufferPointer;
[Link] = avBufferSize;

/* Begin video decode */


MAC_VIDEO_Open( MMAC_VIDEO_CHANNEL1, MMAC_VIDEO_TYPE_STREAM, &vidHandle);
MMAC_VIDEO_SetConfiguration( vidHandle, &vidCfg );

/* Define window configuration for SCALER video window */


[Link] = MMAC_SCALER_422_FORMAT;
[Link] = MMAC_FALSE;
[Link] = MMAC_SCALER_VIDEO;
[Link] = vidHandle;
MMAC_SCALER_CreateWindow( MMAC_SCALER_PLANE1,
&sc1Window,
&sc1WindowHandle,
&sclCreateConfig
);
MMAC_SCALER_ControlWindow( sc1WindowHandle, MMAC_SCALER_WINDOW_DISPLAY );
MMAC_DISP_Display( MMAC_DISP_SCALER1, MMAC_TRUE );

/* Play the video (1000 = normal speed) */


MMAC_VIDEO_Play( vidHandle, 1000 );

/* Initialise and open the teletext driver */


ttxtResult = MMAC_TELETEXT_Initialise();
ttxtResult = MMAC_TELETEXT_Open();

/* Enable the teletext PID filter */


demuxResult = MMAC_DEMUX_EnablePidFilter(
ttxtPidFilter,
MMAC_DEMUX_PID_ENABLE_MODE_ALL
);
nfPointerOffset = ttxtPointerBuffers->nearlyFullOffset;
readPointerOffset = 0;

/* Wait for teletext data to arrive – there would normally


be a task which would be responsible for handling the
notificaton of PID filter data arrival... */

while (1)
{
MMAC_RTOS_EventRetrieve( [Link],
MMAC_RTOS_SUSPEND,
MMAC_DEMUS_TS_DETECT_EVENT |
MMAC_DEMUX_NEARLY_FULL_EVENT,
&rtosRetrievedEvents,
MMAC_RTOS_EVENT_OP_OR );

if( rtosRetrievedEvents & MMAC_DEMUX_TS_DETECT_EVENT )


{
/* Check the TS Detect event is for our teletext PID filter… */
if((ttxtPidFilter & EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)>63 )
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_THREE]
& (1 << ((ttxtPidFilter &

5
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-64))) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_THREE]
&= ~(1<<((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-64));
}
}
if((ttxtPidFilter & EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)>31)
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_TWO]
& (1 << ((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-32))) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_TWO]
&= ~(1<<((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-32));
}
}
else
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_ONE]
& (1<<(ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK))) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_ONE]
&= ~(1<<(ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK));
}
}

while( eventStatus == MMAC_TRUE )


{
/* Calculate number of TS packets in buffer */
/* ( 188 bytes in a TS packet ) */
if( ttxtBuffPointers->writePointerOffset >
readPointerOffset )
{
numPackets =
(ttxtBuffPointers->writePointerOffset –
readPointerOffset) / 188;
}
else
{
numPackets =
(ttxtBuffPointers->endOfBufferOffset –
readPointerOffset) / 188;
numPackets +=
(ttxtBuffPointers->writePointerOffset –

6
readPointerOffset) / 188;
}

tRes = MMAC_TELETEXT_ProcessTeletext(
ttxtBuffPointers->startPointer,
readPointerOffset,
numPackets );

/* Advance our readPointerOffset and the nearlyFull


ptr (checking for buffer wrap) */
readPointerOffset += (numPackets * 188);
if( readPointerOffset >
ttxtBufferPointers->endOfBufferOffset )
{
readPointerOffset -=
(ttxtBufferPointers->enfOfBufferOffset+1);
}
nfPointerOffset += (numPackets * 188);
if( nfPointerOffset >
ttxtBufferPointers->endOfBufferOffset )
{
nfPointerOffset -=
(ttxtBufferPointers->enfOfBufferOffset+1);
}
ttxtBufferPointers->nearlyFullOffset =
nfPointerOffset;

/* Check to see if more data has arrived while


we were processing the previous lot */
if((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK) > 63 )
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_
THREE]
& (1 << ((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-64)
)) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_
THREE]
&= ~(1<<((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-64));
}
}
if((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK) > 31)
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_TWO]
& (1 << ((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-32)
)) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]

7
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_TWO]
&= ~(1<<((ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK)-32));
}
}
else
{
if(([Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_ONE]
& (1<<(ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK))) != 0 )
{
eventStatus = MMAC_TRUE;

[Link]
[MMAC_DEMUX_TS_DETECT_EVENT_ARRAY]
[MMAC_DEMUX_GENERAL_EVENT_STATUS_REGISTER_ONE]
&= ~(1<<(ttxtPidFilter &
EMMA_BIOS_DEMUX_PID_HANDLE_INDEX_MASK));
}
}
}
}
}

8
2 Function Prototypes

MMAC_TELETEXT_Initialise

Function Prototype
MMAC_TELETEXT_RESULT_CODE MMAC_TELETEXT_Initialise (void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_TELETEXT_OK
MMAC_TELETEXT_ALREADY_INITIALISED
MMAC_TELETEXT_FAILED

Description
This function initialises the teletext subsystem and must be called once prior to using any of the other
Teletext API functions. On this function being called the initialisation state will be checked if already
initialised it will return MMAC_TELETEXT_ALREADY_INITIALISED without performing any actions.
If the function is unable to allocate the memory required to hold the teletext data for VBI insertion, the
code MMAC_TELETEXT_FAILED is returned and the subsystem is left uninitialised.
The function resets all teletext frame buffers, configures the embedded Video Encoder for teletext
operation and flags the Teletext subsystem as being initialised. It then returns the code
MMAC_TELETEXT_OK.

See Also
MMAC_TELETEXT_Open
MMAC_TELETEXT_Close

Sample Code
< tba >

9
MMAC_TELETEXT_Open

Function Prototype
MMAC_TELETEXT_RESULT_CODE MMAC_TELETEXT_Open (void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_TELETEXT_OK
MMAC_TELETEXT_NOT_INITIALISED
MMAC_TELETEXT_ALREADY_OPENED

Description
This function opens the teletext subsystem for use, and must be called after calling
MMAC_TELETEXT_Initialise(), and prior to using any of the other Teletext API functions.
If this function is called before the subsystem has been initialised, the function will return the value
MMAC_TELETEXT_NOT_INITIALISED without performing any further action.
If the function is called when the subsystem has already been opened, the function will return
MMAC_TELETEXT_ALREADY_OPENED without performing any actions.
If not already open, teletext buffers are reset and the subsystem is marked as now being open.

See Also
MMAC_TELETEXT_Initialise
MMAC_TELETEXT_Close

Sample Code
< tba >

10
MMAC_TELETEXT_Close

Function Prototype
MMAC_TELETEXT_RESULT_CODE MMAC_TELETEXT_Close (void);

Inputs
None.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_TELETEXT_OK
MMAC_TELETEXT_NOT_OPENED

Description
This function disables the VBI insertion of teletext data.
If the teletext subsystem is not open, the function will return the value MMAC_TELETEXT_NOT_
OPENED.
Otherwise, the teletext buffers are reset, the teletext lines to be displayed by the embedded Video Encoder
are disabled (such that the embedded Video Encoder inserts no lines into the VBI) and the code MMAC_
TELETEXT_OK is returned.
This function does not free the memory used by the Teletext subsystem for storing teletext data.

See Also
MMAC_TELETEXT_Open

Sample Code
< tba >

11
MMAC_TELETEXT_SetTeletext

Function Prototype
MMAC_TELETEXT_RESULT_CODE MMAC_TELETEXT_SetTeletext (
MMAC_BOOL type,

Inputs
type Determines whether only teletext subtitle information or all teletext information
is copied into the teletext buffers for VBI insertion.
If MMAC_TRUE, then the Teletext API will copy all teletext packets into the
teletext line buffers for VBI insertion.
If MMAC_FALSE, the Teletext API will only copy teletext subtitle packets into
the teletext line buffers for VBI insertion.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_TELETEXT_OK
MMAC_TELETEXT_NOT_OPENED

Description
Determines whether all teletext data is VBI inserted or only subtitle teletext data is inserted.
The teletext driver must have been previously initialised with MMAC_TELETEXT_Open(),otherwise
the value MMAC_TELETEXT_NOT_OPENED is returned.

See Also
MMAC_TELETEXT_Open

Sample Code
< tba >

12
MMAC_TELETEXT_ProcessTeletext

Function Prototype
MMAC_TELETEXT_RESULT_CODE MMAC_TELETEXT_ProcessTeletext (
UI8 *startOfBuffer,
UI32 readPtrOffset,
UI32 numPackets
);

Inputs
startOfBuffer Pointer to the start of the PID filter buffer containing the acquired Transport
Stream packets which in turn contain the teletext data to be copied.
readPtrOffset A byte offset into the PID filter buffer pointed to by startOfBuffer, which will be
used to determine the point at which to begin processing the packets.
numPackets The number of Transport Stream packets to be processed.

Outputs
None.

Event Notification
N/A

Return Codes
MMAC_TELETEXT_OK
MMAC_TELETEXT_NOT_OPENED
MMAC_TELETEXT_INVALID_PARAM

Description
This function copies the Teletext data from the Demux PID filter buffer (where it is contained within
Transport Stream packets) into the appropriate place in the Teletext frame buffer.
If this function is called before the Teletext subsystem has been opened, it will return the value
MMAC_TELETEXT_NOT_OPENED without performing any actions.
If this function is called with startOfBuffer set to NULL, it will return the value
MMAC_TELETEXT_INVALID_PARAM without performing any actions.
Otherwise, the function copies the data into the appropriate teletext frame buffer, and returns the code
MMAC_TELETEXT_OK.

See Also
MMAC_TELETEXT_Open
MMAC_TELETEXT_SetTeletext

Sample Code
< tba >

13
3 Data Structures

Result Codes
The following result codes are defined for the Teletext driver. The result code zero is reserved for
indication of a successful operation.

typedef enum
{
MMAC_TELETEXT_OK = 0,
MMAC_TELETEXT_ALREADY_INITIALISED,
MMAC_TELETEXT_NOT_INITIALISED,
MMAC_TELETEXT_NOT_OPENED,
MMAC_TELETEXT_ALREADY_OPENED,
MMAC_TELETEXT_FAILED,
MMAC_TELETEXT_INVALID_PARAM
}MMAC_TELETEXT_RESULT_CODE;

14
4 Revision History
Title: API Specification: Teletext
Ref: API_Teletext.doc

Date Doc API Details of change Ref.


Ver. Ver.
0.01 Initial Revision – from V3.0 EMMA 1 API. M-RV
0.02 Added code example. M-RV
0.03 Added Closed Caption support to subsystem M-RV
0.04 Updated following changes to hardware register M-RV
descriptions –removed Closed Captioning functionality as
this will be provided by a separate Closed Caption API.
0.05 Added semaphore protection to hardware registers. M-RV
0.06 API changed – PID filter is now not set up by Teletext API, M-RV
but must be set up the application by using Demux API.
Replaced example code with new example code.
Semaphore protection is not required by the driver.
0.07 Added result code MMAC_TELETEXT_INVALID_PARAM M-RV
and updated the description of function
MMAC_TELETEXT_ProcessTeletext() which returns it.
0.08 Updated example code following changes to the Video and M-RV
Demux APIs.
2001-09-25 0.09 Updated example code following further changes to the M-RV
Video API.
2002-08-12 0.10 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.10 M-RI
2003-06-27 1.1 Doc number added. M-RJI

15

Common questions

Powered by AI

The teletext API employs an error-handling mechanism using specific return codes for the initialization and opening functions. During initialization with MMAC_TELETEXT_Initialise, error codes like MMAC_TELETEXT_ALREADY_INITIALISED and MMAC_TELETEXT_FAILED signal if the subsystem was already initialized or if memory allocation failed. For opening the subsystem with MMAC_TELETEXT_Open, MMAC_TELETEXT_NOT_INITIALISED and MMAC_TELETEXT_ALREADY_OPENED indicate if the subsystem hasn’t been initialized or is already open, preventing redundant or out-of-order operations .

The MMAC_TELETEXT_Close function does not free the memory used by the Teletext subsystem for storing data. This means that while the function disables teletext VBI insertion by resetting buffers and disabling lines, the allocated memory persists. Management of this memory is left to the application, implying the need for explicit handling and deallocation of this memory space once it is confirmed that teletext resources are no longer required .

The MMAC_TELETEXT_ProcessTeletext function returns MMAC_TELETEXT_INVALID_PARAM if the startOfBuffer pointer is NULL, indicating an invalid parameter was passed, and thus avoids processing. If the subsystem is not open, it returns MMAC_TELETEXT_NOT_OPENED without processing any data. This function is conditional on the teletext subsystem being properly initialized and open to ensure the data can be appropriately transferred to the Teletext frame buffer from the PID filter buffer .

The MMAC_TELETEXT_Initialise function is responsible for initializing the teletext subsystem by allocating necessary system resources and configuring the embedded Video Encoder for teletext operation. It must be called once before any other teletext functions are used. When invoked, it checks if the subsystem has already been initialized. If it has, the function returns MMAC_TELETEXT_ALREADY_INITIALISED without any action. If the memory allocation for teletext data fails, it returns MMAC_TELETEXT_FAILED, leaving the subsystem uninitialized. Upon successful initialization, it returns MMAC_TELETEXT_OK .

The MMAC_TELETEXT_Open function manages the teletext acquisition buffers by resetting them upon execution. It must be called after the subsystem has been initialized with MMAC_TELETEXT_Initialise(). The buffer reset prepares the subsystem by ensuring a clean state for teletext data acquisition. If the function is called when the subsystem isn't initialized or is already open, it returns corresponding error codes without further action. Successfully opening the subsystem marks it as ready for teletext operations .

The teletext API provides configuration options via #define directives in the mmac_config.h file, clearly marked for setup purposes. One significant option is MMAC_TELETEXT_PARAMETER_CHECKING, which determines whether the Teletext API should perform parameter checks when called. This is set to MMAC_YES during development for validation but can be changed to MMAC_NO to enhance performance once the code is verified. These directives help tailor the API's behavior to suit different stages of the application's lifecycle .

The teletext subsystem determines the type of data to insert into the VBI based on the configuration set by the MMAC_TELETEXT_SetTeletext function. By default, it inserts both normal teletext pages and subtitles. However, it can be configured to insert only subtitle information or all teletext packets, depending on the Boolean parameter passed to this function. If MMAC_TRUE is passed, all teletext packets are copied; if MMAC_FALSE, only subtitles are processed .

Configuring the Demux PID filter is crucial because the teletext driver relies on acquiring the complete Transport Packet, including the header, for correct processing. This configuration involves setting up the PID filter to capture teletext data packets and notifying the application upon new data arrival. The application must assign PID values appropriately and handle incoming data notifications. Failure to configure this filter properly may result in incomplete data retrieval and hinder teletext processing capabilities .

The MMAC_TELETEXT_SetTeletext function would return MMAC_TELETEXT_NOT_OPENED if it is called before the teletext subsystem has been opened with MMAC_TELETEXT_Open(). This signifies that the teletext subsystem must be initialized and opened before any configurations, such as setting teletext data for VBI insertion, can be made .

Once teletext data is received via a Demux PID filter, the application should process this data using the MMAC_TELETEXT_ProcessTeletext function. The function copies the data from the Demux PID filter buffer, contained within Transport Stream packets, into the Teletext frame buffer for video insertion. The application is responsible for maintaining pointer offsets and handling buffer wraps while processing; it must update the readPointerOffset and check for additional data post-processing .

You might also like