mheg5_control.h

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2012 Ocean Blue Software Ltd
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 *
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 *
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
#ifndef _MHEG5_CONTROL_H
#define _MHEG5_CONTROL_H

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

/*---Constant and macro definitions for public use-----------------------------*/

/* Section buffer, buffer size (bytes) */
#define SECTION_BUFFER_SIZE               (4 * 1024)

/* Minimum section buffers */
#define MHEG5_MIN_SECTION_BUFFERS           (100)

/* Minimum task priority */
#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)

/* Interaction Channel Streamer: buffer sizes (bytes) */
#define ICS_DEFAULT_BUFFER_SIZE            (3 * 1024 * 1024)
#define ICS_MINIMUM_BUFFER_SIZE            (768 * 1024)

/* Values for colourDepth */
#define COLOUR_FORMAT_PALETTE    8
#define COLOUR_FORMAT_ARGB4444   16
#define COLOUR_FORMAT_ARGB7888   31 /* ST based platform */
#define COLOUR_FORMAT_ARGB8888   32

/*---Enumerations for public use-----------------------------------------------*/

typedef enum
{
   CPROFILE_NONE,

   CPROFILE_UK = (1 << 0),     /* United Kingdom only */
   CPROFILE_NZ = (1 << 1),     /* New Zealand only */
   CPROFILE_AU = (1 << 2),     /* Australia only */
   CPROFILE_HK = (1 << 3),     /* Hong Kong only */
   CPROFILE_SA = (1 << 4),     /* South Africa only */
   CPROFILE_ALL = 0x1f,        /* all countries above (but not FreeSat) */
   CPROFILE_FREESAT = (1 << 8)   /* FreeSat profile only */
} E_COUNTRY_PROFILE, E_MHEG_PROFILE;

/*
 * Receiver Capabilities
 */
typedef enum
{
   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),

/* Unless VC_HD_VIDEO_NOT_SUPPORTED is set, it is assumed that the receiver
 * can and must support decoding of:
 *    1.  H.264 video/iframes
 *    2.  HE-AAC audio
 *    3.  E-AC3 audio. */
   VC_HD_VIDEO_NOT_SUPPORTED = (1 << 17),

/* Unless VC_SUBT_NOT_SIMULTANEOUS is set, it is assumed the receiver can present
 * DVB subtitles and presentation engine Visibles simultaneously,
 * without restriction (see [1] 16.5.1.1) */
   VC_SUBTITLES_NOT_SIMULTANEOUS = (1 << 18),

   /* The following MHEG SD scalings are unlikely to be specified, but are here for completeness */
   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)
} E_MHEG5_CAPABILITES;

typedef enum
{
   /* Display banner and new channel info to user to indicate that channel has changed */
   CHANNEL_START_NORMAL,

   /* No banner displayed, act to user as though on original channel */
   CHANNEL_START_QUIETLY,

   /* No banner displayed, but still show new channel info to user */
   CHANNEL_START_QUIET_SHOW_INFO,
} E_ChannelStartMode;

/*---Global type defs for public use-------------------------------------------*/

/* MHEG5 engine setup structure */
typedef struct
{
   /* MHEG5 engine task priority value - passed to STB_OSCreateTask
    * The specified task priority value is used by the main task for MHEG5 engine
    * MHEG5 engine's timer task is 2 levels ABOVE this
    */
   U32BIT taskPriority;

   /*
    * Receiver Capabilities - as given by E_MHEG5_CONFIG above
    */
   E_MHEG5_CAPABILITES capabilities;

   /*
    * Screen resolution parameters - required by MHEG5 engine graphics
    */
   U16BIT screenWidth;
   U16BIT screenHeight;
   U8BIT colourDepth;

   /* Manufacturer string (passed to MHEG) indicating hardware and software specific
    * support.
    * Format: mmmcccvvv
    *      Where:
    *          mmm = unique manufacturer name
    *          ccc = unique model code
    *          vvv = principal version
    */
   U8BIT *manufacturerString;

   /*
    * Country profile support required
    * Set to CPROFILE_NONE if only require HbbTv support
    */
   E_COUNTRY_PROFILE countryProfile;

   /* Size of Non-Volitile Memory file system for caching broadcast data
    * MHEG5 Australia profile requires a minimum of 2MB plus 64K.
    * MHEG5 South Africa profile requires minimum of 32MB plus 512K.
    * MHEG5 engine monitors the size of the cached data and ensures that the limit
    * is not exceeded.
    */
   U32BIT nvmSize;

   /* IP streamer buffer
    *
    * Streaming content from IP connection requires a buffer. The size is
    * not specified, but the MHEG-5 component is not allowed to buffer more
    * than 3 Megabytes.
    *
    * The size affects the ability of the receiver to deal with jitter and
    * variable bitrate. Minimum size is 768 Kbytes.
    * Less than minimum size, or NULL will disable IP streaming.
    */
   void *streamerBuffer;
   U32BIT streamerBufferSize;

   /*
    * Pointer to version string as defined by macro "MHEG5_VER_STRING"
    */
   const char *version_string;

   /* MHEG5 engine task stack size - passed to STB_OSCreateTask.
    * The minimum stack size is 32KB, and the maximum size is 1MB. Any
    * value outside this range will be ignored, and 32KB will be used.
    */
   U32BIT engineStackSize;

} S_MhegConfig;

/*---Global Function prototypes for public use---------------------------------*/

E_MhegErr MHEG5_Open( S_MhegConfig *pSetup );

E_MhegErr MHEG5_Close(void);

E_MhegErr MHEG5_Start( S32BIT serviceIndex, E_ChannelStartMode *quietMode );

E_MhegErr MHEG5_Stop( void );

E_MhegErr MHEG5_Suspend( void );

E_MhegErr MHEG5_StopWithoutKilling( void );

E_MhegErr MHEG5_Pause(void);

E_MhegErr MHEG5_Resume(void);

E_MhegErr MHEG5_SetScreenResolution( U16BIT screenWidth, U16BIT screenHeight );

E_MhegErr MHEG5_SetSurfaceThreshold(S32BIT pixels);

void MHEG5_RestoreScreen(void);

void* MHEG5_DsmccInstance(void);

E_ChannelStartMode MHEG5_GetTuningInfoMode( S32BIT serviceIndex );

#endif /* _PM_CONTROL_H */