mheg5_control.h File Reference

This file provides the control interface for MHEG5 engine. The use of this component MUST comply with the following sequence of events to ensure correct operation. More...

#include "techtype.h"
#include "dvblocator.h"
#include "mherrors.h"

Go to the source code of this file.

Classes
struct	S_MhegConfig

Macros
#define	SECTION_BUFFER_SIZE   (4 * 1024)
#define	MHEG5_MIN_SECTION_BUFFERS   (100)
#define	MHEG5_MIN_TASK_PRIORITY   (4)
#define	NVM_OVERHEAD_SIZE   (2 * 1024)
#define	NVM_STORE_SIZE_AU   (64 * 1024)
#define	NVM_STORE_SIZE_SA   (512 * 1024)
#define	AU_NVM_MINIMUM_SIZE   ((1024 * 1024 * 2) + NVM_STORE_SIZE_AU + NVM_OVERHEAD_SIZE)
#define	SA_NVM_MINIMUM_SIZE   ((1024 * 1024 * 32) + NVM_STORE_SIZE_SA + NVM_OVERHEAD_SIZE)
#define	ICS_DEFAULT_BUFFER_SIZE   (3 * 1024 * 1024)
#define	ICS_MINIMUM_BUFFER_SIZE   (768 * 1024)
#define	COLOUR_FORMAT_PALETTE   8
#define	COLOUR_FORMAT_ARGB4444   16
#define	COLOUR_FORMAT_ARGB7888   31 /* ST based platform */
#define	COLOUR_FORMAT_ARGB8888   32

Typedefs
typedef enum E_COUNTRY_PROFILE	E_MHEG_PROFILE

Enumerations
enum	E_COUNTRY_PROFILE {   CPROFILE_NONE, CPROFILE_UK = (1 << 0), CPROFILE_NZ = (1 << 1), CPROFILE_AU = (1 << 2),   CPROFILE_HK = (1 << 3), CPROFILE_SA = (1 << 4), CPROFILE_ALL = 0x1f, CPROFILE_FREESAT = (1 << 8) }
enum	E_MHEG5_CAPABILITES {   VC_DEFAULT = 0, VC_SUPPORT_MHEG_NATIVE_APP = (1 << 0), VC_SUPPORT_MHEG_UK_PVR = (1 << 0), VC_SUPPORT_MHEG_PVR = (1 << 1),   VC_SUPPORT_MHEG_NZ_PVR = (1 << 1), VC_SUPPORT_MHEG_AU_PVR = (1 << 2), VC_SUPPORT_MHEG_INTERACTION_CHANNEL = (1 << 3), VC_SUPPORT_MHEG_IC_STREAMING = (1 << 4),   VC_SUPPORT_NON_LINEAR_PLAYBACK_KEYS = (1 << 5), VC_SUPPORT_MHEG_IC_STREAMING_HD = (1 << 6), VC_SUPPORT_OIPF_BROWSER_PROFILE = (1 << 7), VC_HD_VIDEO_NOT_SUPPORTED = (1 << 17),   VC_SUBTITLES_NOT_SIMULTANEOUS = (1 << 18), VC_NO_VIDEO_OFF_SCREEN = (1 << 27), VC_NO_BITMAP_OFF_SCREEN = (1 << 28), VC_ONLY_SD_DOUBLE_SCALING = (1 << 29),   VC_ONLY_SD_STANDARD_SCALING = (1 << 30), VC_ONLY_SD_QUARTER_SCALING = (1 << 31) }
enum	E_ChannelStartMode { CHANNEL_START_NORMAL, CHANNEL_START_QUIETLY, CHANNEL_START_QUIET_SHOW_INFO }

Functions
E_MhegErr	MHEG5_Open (S_MhegConfig *pSetup)
	Initialise MHEG5 engine instance. The following will be performed as a result of a call to this function: More...
E_MhegErr	MHEG5_Close (void)
	Close MHEG engine. Free allocated MHEG5 engine memory region, and any other related resources. This is a synchronous blocking function. Must be called after MHEG5_Stop and normal use of MHEG5 engine has completed. More...
E_MhegErr	MHEG5_Start (S32BIT serviceIndex, E_ChannelStartMode *quietMode)
	This function starts MHEG5 engine on the current broadcast service. It will cause MHEG5 engine to start retrieving the associated service information (i.e. PMT) and launch an appropriate broadcast application. This should mean MHEG5 engine will mount an associated DSM-CC carousel for this application. If this should fail, MHEG5 engine will periodically try to mount the DSM-CC boot carousel in order to launch the default MHEG-5 auto boot application. This is a non-blocking function, which may return before completion. It should be called whenever a tuning process has completed and the external application is aware of a new broadcast service. More...
E_MhegErr	MHEG5_Stop (void)
	Tells MHEG5 engine to enter stop state (i.e. no broadcast service). This function should kill any currently running MHEG5 broadcast application, and release allocated memory and resources. This is a synchronous blocking function. More...
E_MhegErr	MHEG5_Suspend (void)
	Suspend MHEG5 engine (while there is no valid broadcast service). When the external application is performing a tune as requested by MHEG5, this function should be called as an alternative to MHEG5_Stop. This may or may not kill the running MHEG application. This suspend state will remain in effect until MHEG5_Start or MHEG5_Stop is called. This is a synchronous blocking function. More...
E_MhegErr	MHEG5_StopWithoutKilling (void)
	Suspend MHEG5 engine (while there is no valid broadcast service). This function should be called as an alternative to MHEG5_Stop, in cases when the CI+ host control module requests a tune and the keep_app_running flag is set to 1. In cases when keep_app_running is set to 0, or if the implemented version of host control doesn't have the keep_app_running flag, use MHEG5_Stop. This will not kill the running MHEG application. This suspend state will remain in effect until MHEG5_Start or MHEG5_Stop is called. This is a synchronous blocking function. More...
E_MhegErr	MHEG5_Pause (void)
	This allows MHEG5 engine to be paused whilst another application has display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine. More...
E_MhegErr	MHEG5_Resume (void)
	This allows Voyageer to be resumed after another application has had display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine. More...
E_MhegErr	MHEG5_SetScreenResolution (U16BIT screenWidth, U16BIT screenHeight)
	Sets the screen resolution to new size. This function is required when the external application wishes to change the screen resolution. This is a synchronous blocking function. It will return when MHEG5 engine has finished using the previous resolution. After returning from this function, MHEG5 engine will NOT refresh the OSD or AV until MHEG5_RestoreScreen() is called. More...
E_MhegErr	MHEG5_SetSurfaceThreshold (S32BIT pixels)
	Set the minimum number of pixels that force the MHEG-5 engine to release a surface immediately after it's been used (or blitted). When threshold is not applied, a surface remains until the MHEG-5 application unloads them (either directly or as part of scene/application tear-down). This function is only included in the compiled library when environment variable DTVKIT_MHEG5_SURFACE_THRESHOLD is not zero. More...
void	MHEG5_RestoreScreen (void)
	Refresh screen after resolution change with MHEG5_SetScreenResolution() This is a non-blocking function. More...
void *	MHEG5_DsmccInstance (void)
	Get the DSMCC instance handle. More...
E_ChannelStartMode	MHEG5_GetTuningInfoMode (S32BIT serviceIndex)
	Get the current tuning mode for the target service. This is only relevant when MHEG5 has requested a tune, and DVB has not yet tuned to that service. The return value will be the same as that given back by next call to MHEG5_Start(). More...

Detailed Description

This file provides the control interface for MHEG5 engine. The use of this component MUST comply with the following sequence of events to ensure correct operation.

1. MHEG5_Open() - Initialise MHEG5 engine.

   2. MHEG5_Start() - Start MHEG5 engine for a DVB service

3. Normal Operation - MHEG5 component interaction.

1. MHEG5_Stop() - Stop MHEG5 engine running on DVB service.
2. MHEG5_Close() - Release all instance memory and resources. Generally provided functions are non-blocking (i.e. they will perform quickly). Functions without a post condition (no returned values), will either perform quickly, or copy passed data and return. Functions with a post condition (synchronously returned values) will perform quickly. Other functions that cannot perform quickly will copy passed data and return asynchronously through the specified asynchronous return path. References: [1] DTG UK D-Book 7 part A. [2] ISO/IEC 13818-1:2000 - Information technology – Generic coding of moving pictures and associated audio information: Systems [3] ISO/IEC 13818-6:1998 - Information technology – Generic coding of moving pictures and associated audio information – Part 6: Extensions for DSM-CC

Date

20/12/2012

Author

Adam Sturtridge

Definition in file mheg5_control.h.

Macro Definition Documentation

#define AU_NVM_MINIMUM_SIZE   ((1024 * 1024 * 2) + NVM_STORE_SIZE_AU + NVM_OVERHEAD_SIZE)

Definition at line 71 of file mheg5_control.h.

#define COLOUR_FORMAT_ARGB4444   16

Definition at line 80 of file mheg5_control.h.

#define COLOUR_FORMAT_ARGB7888   31 /* ST based platform */

Definition at line 81 of file mheg5_control.h.

#define COLOUR_FORMAT_ARGB8888   32

Definition at line 82 of file mheg5_control.h.

#define COLOUR_FORMAT_PALETTE   8

Definition at line 79 of file mheg5_control.h.

#define ICS_DEFAULT_BUFFER_SIZE   (3 * 1024 * 1024)

Definition at line 75 of file mheg5_control.h.

#define ICS_MINIMUM_BUFFER_SIZE   (768 * 1024)

Definition at line 76 of file mheg5_control.h.

#define MHEG5_MIN_SECTION_BUFFERS   (100)

Definition at line 63 of file mheg5_control.h.

#define MHEG5_MIN_TASK_PRIORITY   (4)

Definition at line 66 of file mheg5_control.h.

#define NVM_OVERHEAD_SIZE   (2 * 1024)

Definition at line 68 of file mheg5_control.h.

#define NVM_STORE_SIZE_AU   (64 * 1024)

Definition at line 69 of file mheg5_control.h.

#define NVM_STORE_SIZE_SA   (512 * 1024)

Definition at line 70 of file mheg5_control.h.

#define SA_NVM_MINIMUM_SIZE   ((1024 * 1024 * 32) + NVM_STORE_SIZE_SA + NVM_OVERHEAD_SIZE)

Definition at line 72 of file mheg5_control.h.

#define SECTION_BUFFER_SIZE   (4 * 1024)

Definition at line 60 of file mheg5_control.h.

Typedef Documentation

typedef enum E_COUNTRY_PROFILE E_MHEG_PROFILE

Enumeration Type Documentation

enum E_ChannelStartMode

Enumerator
CHANNEL_START_NORMAL
CHANNEL_START_QUIETLY
CHANNEL_START_QUIET_SHOW_INFO

Definition at line 137 of file mheg5_control.h.

enum E_COUNTRY_PROFILE

Enumerator
CPROFILE_NONE
CPROFILE_UK
CPROFILE_NZ
CPROFILE_AU
CPROFILE_HK
CPROFILE_SA
CPROFILE_ALL
CPROFILE_FREESAT

Definition at line 86 of file mheg5_control.h.

enum E_MHEG5_CAPABILITES

Enumerator
VC_DEFAULT
VC_SUPPORT_MHEG_NATIVE_APP
VC_SUPPORT_MHEG_UK_PVR
VC_SUPPORT_MHEG_PVR
VC_SUPPORT_MHEG_NZ_PVR
VC_SUPPORT_MHEG_AU_PVR
VC_SUPPORT_MHEG_INTERACTION_CHANNEL
VC_SUPPORT_MHEG_IC_STREAMING
VC_SUPPORT_NON_LINEAR_PLAYBACK_KEYS
VC_SUPPORT_MHEG_IC_STREAMING_HD
VC_SUPPORT_OIPF_BROWSER_PROFILE
VC_HD_VIDEO_NOT_SUPPORTED
VC_SUBTITLES_NOT_SIMULTANEOUS
VC_NO_VIDEO_OFF_SCREEN
VC_NO_BITMAP_OFF_SCREEN
VC_ONLY_SD_DOUBLE_SCALING
VC_ONLY_SD_STANDARD_SCALING
VC_ONLY_SD_QUARTER_SCALING

Definition at line 102 of file mheg5_control.h.

Function Documentation

E_MhegErr MHEG5_Close

(

void

)

Close MHEG engine. Free allocated MHEG5 engine memory region, and any other related resources. This is a synchronous blocking function. Must be called after MHEG5_Stop and normal use of MHEG5 engine has completed.

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not ready to close.

Close MHEG engine. Free allocated MHEG5 engine memory region, and any other related resources. This is a synchronous blocking function. Must be called after MHEG5_Stop and normal use of MHEG5 engine has completed.

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not ready to close.

Definition at line 541 of file glue_main.c.

void* MHEG5_DsmccInstance

(

void

)

Get the DSMCC instance handle.

Returns

dsmcc instance

Definition at line 778 of file glue_dsmcc.c.

E_ChannelStartMode MHEG5_GetTuningInfoMode

(

S32BIT

serviceIndex

)

Get the current tuning mode for the target service. This is only relevant when MHEG5 has requested a tune, and DVB has not yet tuned to that service. The return value will be the same as that given back by next call to MHEG5_Start().

Parameters

serviceIndex

"Service Index" for the new service

Returns

E_ChannelStartMode

Get the current tuning mode for the target service. This is only relevant when MHEG5 has requested a tune, and DVB has not yet tuned to that service. The return value will be the same as that given back by next call to MHEG5_Start().

Parameters

serviceIndex

"Service Index" for the new service

Returns

E_ChannelStartMode

Definition at line 934 of file mh5control.c.

E_MhegErr MHEG5_Open

(

S_MhegConfig *

pSetup

)

Initialise MHEG5 engine instance. The following will be performed as a result of a call to this function:

• The component memory region will be allocated
• MHEG5 engine will be initialised using the setup values provided.
• allocates and initialises memory for the sub-components. This function may return MHERR_BAD_PARAMETER if the specified values of the component setup are outside the required range. This is a synchronous blocking function. This function must be called before MHEG5_Start and before normal use

  Parameters

  pSetup

  Pointer configuration parameters. This defines many configuration options for MHEG5 engine

  Returns

  MHERR_OK - Success MHERR_COMP_ALREADY_OPEN - Component already opened. MHERR_BAD_PARAMETER - Invalid parameter. MHERR_VERSION_MISMATCH - Setup version does not match library MHERR_BAD_TASK_PRIORITY MHERR_ALLOCATING_MEMORY_REGION MHERR_SYSTEM_RESOURCE_...

  Initialise MHEG5 engine instance. The following will be performed as a result of a call to this function:
• The component memory region will be allocated
• MHEG5 will be initialised using the setup values provided.
• allocates and initialises memory for the sub-components. This function may return MHERR_BAD_PARAMETER if the specified values of the component setup are outside the required range. This is a synchronous blocking function. This function must be called before VFX_Start and before normal use

  Parameters

  pSetup

  Pointer configuration parameters. This defines many configuration options for MHEG5

  Returns

  MHERR_OK - Success MHERR_COMP_ALREADY_OPEN - Component already opened. MHERR_BAD_PARAMETER - Invalid parameter. MHERR_VERSION_MISMATCH - Setup version does not match library MHERR_BAD_TASK_PRIORITY MHERR_ALLOCATING_MEMORY_REGION MHERR_SYSTEM_RESOURCE_...

Definition at line 361 of file glue_main.c.

E_MhegErr MHEG5_Pause

(

void

)

This allows MHEG5 engine to be paused whilst another application has display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine.

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not initialised.

This allows MHEG5 engine to be paused whilst another application has display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine.

Parameters

None.

Returns

None.

Definition at line 1035 of file glue_main.c.

void MHEG5_RestoreScreen

(

void

)

Refresh screen after resolution change with MHEG5_SetScreenResolution() This is a non-blocking function.

Returns

void

Refresh screen after resolution change with MHEG5_SetScreenResolution() This is a non-blocking function.

Parameters

None.

Returns

None.

Definition at line 1159 of file glue_main.c.

E_MhegErr MHEG5_Resume

(

void

)

This allows Voyageer to be resumed after another application has had display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine.

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not initialised.

This allows Voyageer to be resumed after another application has had display focus (such as an EPG). This is a synchronous blocking function. Section 16.9 of reference [1] discusses the behaviour for pausing the engine. This implementation is "Non-transparent". This may be called independently of start/stop of engine.

Parameters

None.

Returns

None.

Definition at line 1070 of file glue_main.c.

E_MhegErr MHEG5_SetScreenResolution	(	U16BIT	screenWidth,
		U16BIT	screenHeight
	)

Sets the screen resolution to new size. This function is required when the external application wishes to change the screen resolution. This is a synchronous blocking function. It will return when MHEG5 engine has finished using the previous resolution. After returning from this function, MHEG5 engine will NOT refresh the OSD or AV until MHEG5_RestoreScreen() is called.

Parameters

screenWidth	New screen width
sreeenHeight	New screen height

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not ready to start. MHERR_BAD_PARAMETER - Invalid parameter.

Sets the screen resolution to new size. This function is required when the external application wishes to change the screen resolution. This is a synchronous blocking function. It will return when MHEG5 engine has finished using the previous resolution. After returning from this function, MHEG5 engine will NOT refresh the OSD or AV until MHEG5_RestoreScreen() is called.

Parameters

None.

Returns

None.

Definition at line 1115 of file glue_main.c.

E_MhegErr MHEG5_SetSurfaceThreshold

(

S32BIT

pixels

)

Set the minimum number of pixels that force the MHEG-5 engine to release a surface immediately after it's been used (or blitted). When threshold is not applied, a surface remains until the MHEG-5 application unloads them (either directly or as part of scene/application tear-down). This function is only included in the compiled library when environment variable DTVKIT_MHEG5_SURFACE_THRESHOLD is not zero.

Parameters

pixels

Number of pixels to be used as a threshold. Zero or negative number disables automatic destruction

Returns

MHERR_OK - Success MHERR_COMP_NOT_STARTED - Component not started.

E_MhegErr MHEG5_Start	(	S32BIT	serviceIndex,
		E_ChannelStartMode *	quietMode
	)

This function starts MHEG5 engine on the current broadcast service. It will cause MHEG5 engine to start retrieving the associated service information (i.e. PMT) and launch an appropriate broadcast application. This should mean MHEG5 engine will mount an associated DSM-CC carousel for this application. If this should fail, MHEG5 engine will periodically try to mount the DSM-CC boot carousel in order to launch the default MHEG-5 auto boot application. This is a non-blocking function, which may return before completion. It should be called whenever a tuning process has completed and the external application is aware of a new broadcast service.

Parameters

serviceIndex	"Service Index" for the new service
quietMode	pointer to return channel change mode that MHEG5 requires of the external application. Can be NULL, if not interested in mode.

Returns

MHERR_OK - Success MHERR_COMP_NOT_OPEN - Component not ready to start. MHERR_COMP_ALREADY_STARTED - Component has already been started. MHERR_BAD_PARAMETER - Invalid parameter.

Definition at line 659 of file glue_main.c.

E_MhegErr MHEG5_Stop

(

void

)

Tells MHEG5 engine to enter stop state (i.e. no broadcast service). This function should kill any currently running MHEG5 broadcast application, and release allocated memory and resources. This is a synchronous blocking function.

Returns

MHERR_OK - Success MHERR_COMP_NOT_STARTED - Component not ready to stop.

Definition at line 764 of file glue_main.c.

E_MhegErr MHEG5_StopWithoutKilling

(

void

)

Suspend MHEG5 engine (while there is no valid broadcast service). This function should be called as an alternative to MHEG5_Stop, in cases when the CI+ host control module requests a tune and the keep_app_running flag is set to 1. In cases when keep_app_running is set to 0, or if the implemented version of host control doesn't have the keep_app_running flag, use MHEG5_Stop. This will not kill the running MHEG application. This suspend state will remain in effect until MHEG5_Start or MHEG5_Stop is called. This is a synchronous blocking function.

Returns

MHERR_OK - Success MHERR_REQUEST_IGNORED - Already suspended MHERR_COMP_NOT_STARTED - Component not ready to stop.

Definition at line 825 of file glue_main.c.

E_MhegErr MHEG5_Suspend

(

void

)

Suspend MHEG5 engine (while there is no valid broadcast service). When the external application is performing a tune as requested by MHEG5, this function should be called as an alternative to MHEG5_Stop. This may or may not kill the running MHEG application. This suspend state will remain in effect until MHEG5_Start or MHEG5_Stop is called. This is a synchronous blocking function.

Returns

MHERR_OK - Success MHERR_REQUEST_IGNORED - Already suspended MHERR_COMP_NOT_STARTED - Component not ready to stop.

Definition at line 887 of file glue_main.c.