MMAC
Software Group
API – Timecode
EMMA2 Software User’s Manual
CONTENTS
1 Introduction .....................................................................................................................................2
2 Function Prototypes ........................................................................................................................3
MMAC_TIMECODE_Initialise...............................................................................................3
MMAC_TIMECODE_Set ......................................................................................................4
MMAC_TIMECODE_Get......................................................................................................6
MMAC_TIMECODE_Cancel ................................................................................................7
MMAC_TIMECODE_Notify ..................................................................................................8
MMAC_TIMECODE_UpdateAndCheck ...............................................................................9
3 Data Structures .............................................................................................................................10
4 Revision History ............................................................................................................................12
Book No: S16753EE1V0UM00 Doc No: MMAC040, Issue: 1.2
© NEC Electronics Corporation 2003, 2004 Date: 2004-02-18
The information is this document is subject to change without notice – it is the reader’s responsibility to check that this is the current version.
This document includes company confidential information. It should only be released to third parties under a Non-Disclosure Agreement.
1 Introduction
This unit deals with operations related to the timing information of the MPEG stream. This allows the
application to set the driver to report when a specified timecode has been received, or to freeze the
frame on a specified timecode and notify the application that this has occurred. The driver will only
handle one report event and one freeze frame event at any one time.
Prior to using any of the functions of this section, it is necessary to initialise the other parts of the API
that this code depends on by calling
MMAC_RTOS_Initialise( )
MMAC_VIDENC_Initialise( )
MMAC_VIDEO_Initialise( )
The driver function MMAC_TIMECODE_Initialise( ) should then be called.
Functions
The timecode API provides the following functions:
Function Name Description
MMAC_TIMECODE_Initialise( ) This function initialises the timecode subsystem.
MMAC_TIMECODE_Set( ) This function sets the timecode and mode.
MMAC_TIMECODE_Get( ) This function returns the current timecode from the
MPEG stream.
MMAC_TIMECODE_Cancel( ) This function cancels the timecode specified by
mode.
MMAC_TIMECODE_Notify( ) This function installs a callback function which will
be called when the condition is met.
MMAC_TIMECODE_UpdateAndCheck( ) This function check and update frame, sec and minute
couter.
Return Codes
The meaning of the various return codes returned by the driver are described in the following table:
Return Code Description
MMAC_TIMECODE_OK A TIMECODE operation has successfully
completed.
MMAC_TIMECODE_ERROR MMAC_TIMECODE_Get( ) has been called
with a NULL timecode pointer, or no MPEG
stream has been received.
MMAC_TIMECODE_ALREADY_INITIALISED The TIMECODE driver has already been
initialised.
MMAC_TIMECODE_NOT_INITIALISED The TIMECODE driver has not been initialised.
MMAC_TIMECODE_INVALID_MODE The TIMECODE driver has been passed an
unrecognised value in the timecode mode
parameter.
MMAC_TIMECODE_INVALID_CHANNEL The TIMECODE driver has been passed an
unrecognised channel.
2 / 12
2 Function Prototypes
MMAC_TIMECODE_Initialise
Function Prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_Initialise(void);
Includes
#include “mmac/timecode.h”
Inputs
None.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
MMAC_TIMECODE_ALREADY_INITIALISED
Description
This function initialises the timecode subsystem and must be called once prior to using any of the
other timecode API functions. On this function being called the initialisation state will be checked, if
already initialised it will return MMAC_TIMECODE_ALREADY_INITIALISED without performing
any actions.
See Also
MMAC_VIDEO_Initialise( )
Sample Code
< tba >
3 / 12
MMAC_TIMECODE_Set
Function prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_Set(
MMAC_TIMECODE_CHANNEL channel,
MMAC_TIMECODE_DESC timecode,
MMAC_TIMECODE_MODE mode
);
Includes
#include “mmac/timecode.h”
Inputs
channel
Channel to set the mode and timecode.
timecode
Sets the timecode for the action.
mode
Sets the report or freeze mode.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
MMAC_TIMECODE_INVALID_MODE
MMAC_TIMECODE_NOT_INITIALISED
MMAC_TIMECODE_INVALID_CHANNEL
Description
This function sets mode depending on the value of mode, on the specified timecode.
The function MMAC_TIMECODE_Initialise( ) must be called first, otherwise
MMAC_TIMECODE_ NOT_INITIALISED will be returned.
The value MMAC_TIMECODE_INVALID_MODE will be returned if the mode parameter is not a
valid enum member.
The value MMAC_TIMECODE_INVALID_CHANNEL will be returned if the channel is not a valid
enum member.
The driver will call the callback function installed by using MMAC_TIMECODE_Notify( ),
therefore the callback should be installed first.
See Also
MMAC_TIMECODE_Initialise
MMAC_TIMECODE_Get
MMAC_TIMECODE_Notify
4 / 12
Sample Code
< tba >
5 / 12
MMAC_TIMECODE_Get
Function prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_Get(
MMAC_TIMECODE_CHANNEL channel,
MMAC_TIMECODE_DESC *timecode
);
Includes
#include “mmac/timecode.h”
Inputs
None.
Outputs
channel
Channel to get the timecode from MPEG stream.
timecode
Returns the current timecode.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
MMAC_TIMECODE_ERROR
MMAC_TIMECODE_NOT_INITIALISED
MMAC_TIMECODE_INVALID_CHANNEL
Description
This function returns the current timecode from the MPEG stream, and then returns MMAC_
TIMECODE_OK.
The function MMAC_TIMECODE_Initialise( ) must be called first, otherwise MMAC_
TIMECODE_ NOT_INITIALISED will be returned.
Except if the timecode pointer is NULL or there has been no MPEG stream received, then MMAC_
TIMECODE_ERROR is returned.
The value MMAC_TIMECODE_INVALID_CHANNEL will be returned if the channel is not a valid
enum member.
See Also
MMAC_TIMECODE_Initialise( )
MMAC_TIMECODE_Set( )
Sample Code
< tba >
6 / 12
MMAC_TIMECODE_Cancel
Function prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_Cancel(
MMAC_TIMECODE_CHANNEL channel,
MMAC_TIMECODE_MODE mode
);
Includes
#include “mmac/timecode.h”
Inputs
channel
Specifies the channel to cancel.
mode
Specifies the timecode type to cancel.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
MMAC_TIMECODE_NOT_INITIALISED
MMAC_TIMECODE_INVALID_MODE
MMAC_TIMECODE_INVALID_CHANNEL
Description
The function cancels the timecode specified by channel and mode that was previously set by a call to
MMAC_TIMECODE_Set( ) with the same channel and mode.
The function MMAC_TIMECODE_Initialise( ) must be called first otherwise. MMAC_
TIMECODE_NOT_INITIALISED will be returned.
Returns MMAC_TIMECODE_INVALID_MODE if no timecode has been set.
The value MMAC_TIMECODE_INVALID_CHANNEL will be returned if the channel is not a valid
enum member.
See Also
MMAC_TIMECODE_Initialise( )
MMAC_TIMECODE_Set( )
Sample Code
< tba >
7 / 12
MMAC_TIMECODE_Notify
Function prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_Notify(
MMAC_TIMECODE_CALLBACK function
);
Includes
#include “mmac/timecode.h”
Inputs
function
Pointer to callback function.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
MMAC_TIMECODE_NOT_INIITIALISED
Description
This function installs a callback function specified by function, which will be called when the
condition is met.
The function MMAC_TIMECODE_Initialise( ) must be called first otherwise MMAC_
TIMECODE_NOT_INITIALISED will be returned.
This function should be called prior to setting any active condition with MMAC_TIMECODE_
Set( ). Since it is possible to have multiple conditions set which may cause the callback the callback
function is NOT automatically uninstalled after a callback event occurs. The conditions which cause
this function to be called are set using MMAC_TIMECODE_Set( ), when the requested condition
occurs this notification will happen immediately. This callback must be explicitly removed by calling
this function with a NULL pointer as the argument.
See Also
MMAC_TIMECODE_Initialise( )
MMAC_TIMECODE_Set( )
Sample Code
< tba >
8 / 12
MMAC_TIMECODE_UpdateAndCheck
Function prototype
MMAC_TIMECODE_RESULT_CODE MMAC_TIMECODE_UpdateAndCheck(
MMAC_TIMECODE_CHANNEL channel,
UI32 framePerSec
);
Includes
#include “mmac/timecode.h”
Inputs
channel
Channel to set the mode and timecode.
framePerSec
frame per sec.
Outputs
None.
Event Notification
N/A
Return Codes
MMAC_TIMECODE_OK
Description
This function is called from the av_isr interrupt once every 2 I_VFIP interrupts (or each time the
display frame is updated). The frame count is incremented, and checked if it is > number of frame/sec,
if so the secs section is incremented and so on. This format is a 25 bit integer within the 32 bits with
the following meaning.
See Also
None.
Sample Code
< tba >
9 / 12
3 Data Structures
Includes
#include “mmac/timecode.h”
MMAC_TIMECODE_RESULT_CODE
Enumeration defining possible return codes for the timecode functions.
typedef enum
{
MMAC_TIMECODE_OK = 0,
MMAC_TIMECODE_ERROR,
MMAC_TIMECODE_NOT_INITIALISED,
MMAC_TIMECODE_INVALID_MODE,
MMAC_TIMECODE_ALREADY_INITIALISED,
MMAC_TIMECODE_INVALID_CHANNEL
} MMAC_TIMECODE_RESULT_CODE;
MMAC_TIMECODE_MODE
Enumeration defining possible timecode modes.
typedef enum
{
MMAC_TIMECODE_NO_ACTION,
MMAC_TIMECODE_DONE,
MMAC_TIMECODE_REPORT,
MMAC_TIMECODE_FREEZE_FRAME
} MMAC_TIMECODE_MODE;
MMAC_TIMECODE_DESC
Structure defining a timecode.
typedef struct
{
UI32 frames;
UI32 secs;
UI32 mins;
UI32 hrs;
UI32 marker;
UI32 drop
MMAC_BOOL valid;
} MMAC_TIMECODE_DESC;
MMAC_TIMECODE_CHANNEL
Structure defining a channel.
typedef enum
{
MMAC_TIMECODE_CHANNEL1 = 0,
MMAC_TIMECODE_CHANNEL2 = 1,
} MMAC_TIMECODE_CHANNEL;
10 / 12
Callback
The following type defines an MMAC_TIMECODE_CALLBACK.
typedef void(*MMAC_TIMECODE_CALLBACK)(MMAC_TIMECODE_CHANNEL channel,
MMAC_TIMECODE_MODE mode);
11 / 12
4 Revision History
Title: API – Timecode
Ref: API_Timecode.doc
Date Doc Details of change Ref.
Ver.
0.01 Initial Revision J-HN
0.02 EMMA2_xxx_ functions were renamed to MMAC_xxx and
existing MMAC_xxx functions were deleted.
2001-05-28 0.03 Mode specified by struct MMAC_TIMECODE_DESC, not UI32.
Return code changed from MMAC_TIMECODE_NO_CHANNEL
to MMAC_TIMECODE_INVALID_CHANNEL.
2002-08-12 0.04 Doc reformatted M-RI
2002-12-09 1.0 For release – same as v0.04 M-RI
2003-06-27 1.1 Doc number added. M-RJI
2004-02-12 1.2 Added function MMAC_TIMECODE_UpdateAndCheck( ). M-HG
2004-02-18 1.21 Format update. M-RJI
12 / 12