stbebutt.h File Reference

Header file - EBU Teletext driver. More...

#include "techtype.h"

Go to the source code of this file.

Data Structures
struct	s_ebutt_font

Typedefs
typedef enum e_ebutt_event	E_EBUTT_EVENT
typedef enum e_ebutt_caching_method	E_EBUTT_CACHING_METHOD
typedef enum e_ebutt_character_set_designation	E_EBUTT_CHARACTER_SET_DESIGNATION
typedef struct s_ebutt_font	S_EBUTT_FONT

Enumerations
enum	e_ebutt_event {   EBUTT_EVENT_QUICK_NAVIGATE_1, EBUTT_EVENT_QUICK_NAVIGATE_2, EBUTT_EVENT_QUICK_NAVIGATE_3, EBUTT_EVENT_QUICK_NAVIGATE_4,   EBUTT_EVENT_0, EBUTT_EVENT_1, EBUTT_EVENT_2, EBUTT_EVENT_3,   EBUTT_EVENT_4, EBUTT_EVENT_5, EBUTT_EVENT_6, EBUTT_EVENT_7,   EBUTT_EVENT_8, EBUTT_EVENT_9, EBUTT_EVENT_INDEXPAGE, EBUTT_EVENT_NEXTPAGE,   EBUTT_EVENT_PREVIOUSPAGE, EBUTT_EVENT_NEXTSUBPAGE, EBUTT_EVENT_PREVIOUSSUBPAGE, EBUTT_EVENT_BACKPAGE,   EBUTT_EVENT_FORWARDPAGE, EBUTT_EVENT_HOLD, EBUTT_EVENT_REVEAL, EBUTT_EVENT_CLEAR,   EBUTT_EVENT_MIX_VIDEO, EBUTT_EVENT_DOUBLE_HEIGHT, EBUTT_EVENT_DOUBLE_SCROLL_UP, EBUTT_EVENT_DOUBLE_SCROLL_DOWN,   EBUTT_EVENT_TIMER }
enum	e_ebutt_caching_method {   EBUTT_CACHING_METHOD_NONE = 0, EBUTT_CACHING_METHOD_PREVIOUS_NEXT, EBUTT_CACHING_METHOD_HISTORY, EBUTT_CACHING_METHOD_NAVIGATION,   EBUTT_CACHING_METHOD_NAVIGATION_TREE, EBUTT_CACHING_METHOD_ALL }
enum	e_ebutt_character_set_designation {   EBUTT_CHARACTER_SET_DESIGNATION_LATIN_DEFAULT = 0, EBUTT_CHARACTER_SET_DESIGNATION_LATIN_POLISH = 1, EBUTT_CHARACTER_SET_DESIGNATION_LATIN_TURKISH = 2, EBUTT_CHARACTER_SET_DESIGNATION_LATIN_SERBIAN_RUMANIAN = 3,   EBUTT_CHARACTER_SET_DESIGNATION_CYRILLIC = 4, EBUTT_CHARACTER_SET_DESIGNATION_GREEK_TURKISH = 6, EBUTT_CHARACTER_SET_DESIGNATION_LATIN_ARABIC = 8, EBUTT_CHARACTER_SET_DESIGNATION_HEBREW_ARABIC = 10 }

Functions
BOOLEAN	STB_EBUTT_Initialise (void)
	This must be called to invoke the EBU TeleText driver module before all other functionality can be accessed. This initiates the relevant resources used by the driver module. As a consequence of calling this function, no TeleText processing will occur until other functions are called. It is envisaged that this function may be called within the general initialisation of the STB layer. More...
void	STB_EBUTT_Kill (U8BIT path)
	This is the accompanying function to STB_EBUTT_Initialise( ), and is called to shut-down the EBU TeleText driver module and release the relevant resources used by the driver module. This may not be used in some implementations. More...
void	STB_EBUTT_Start (U8BIT path, U16BIT text_pid, U8BIT magazine, U8BIT page)
	These functions are called to control whether received TeleText data is processed. Using this functionality ensures that the process of collating page information can be halted when processing resources are a consideration. It is envisaged that some implementations may wish only to collate TeleText content only when the display is being shown, whilst other designs may which to cache significant page content as a background process. Abstracting this functionality from the initialisation routines gives the option to support both solution types. More...
void	STB_EBUTT_Stop (U8BIT path, BOOLEAN reset_cache)
BOOLEAN	STB_EBUTT_InjectData (U8BIT *data_ptr, U32BIT data_length)
	Allows teletext PES data packets to be injected by an external module, which will be decoded and displayed. More...
BOOLEAN	STB_EBUTT_Show (E_EBUTT_CHARACTER_SET_DESIGNATION character_set_designation, BOOLEAN navigate_to_index_page, BOOLEAN show_header)
	Called to initiate continuous display of TeleText page content. This will result in either the index page defined in the service data stream being selected, or the previously displayed page (prior to a call to STB_EBUTT_Hide( ) being made) from being reinstated. This function can be called irrespective of the use of the STB_EBUTT_Start( ) / STB_EBUTT_Stop( ) functions, but of course may result in no TeleText data being displayed if none already exists within the cache. The return value indicates whether initialisation of the display mechanism has been successful or not. More...
void	STB_EBUTT_Hide (void)
	Called to halt the continuous display of TeleText page content, and to clear the relevant area of the application display.
void	STB_EBUTT_SetCacheMethod (E_EBUTT_CACHING_METHOD ebutt_caching_method)
	Called to define the strategy used to determine what page content is to be displayed form the TeleText carousel content. More...
void	STB_EBUTT_NotifyEvent (E_EBUTT_EVENT event_type)
	Called whenever a TeleText-specific event being invoked. This is used to pass relevant user input to the driver, and the enumerate type supplied is defined independently of any IR handset / keypad. More...
void	STB_EBUTT_NotifyServiceChange (void)
	Called whenever the application permits a TV/Radio service change during a TeleText display session. This is provided because an update of the display to new page content is required.
void	STB_EBUTT_SetDisplayBrightness (U8BIT gun_intensity)
	Called to adjust the display brightness (colour intensity) of the Teletext pages. More...
void	STB_EBUTT_IncreaseDisplayBrightness (void)
	Called to adjust the display brightness (colour intensity) of the Teletext pages.
void	STB_EBUTT_DecreaseDisplayBrightness (void)
void	STB_EBUTT_SetDisplayAntiAliasing (U8BIT antialias_level)
	Called to adjust the display anti-aliasing level of the Teletext pages. This is used to control 'flicker' on TV displays. More...
void	STB_EBUTT_IncreaseDisplayAntiAliasing (void)
	Called to adjust the display anti-aliasing level of the Teletext pages.
void	STB_EBUTT_DecreaseDisplayAntiAliasing (void)
void	STB_EBUTT_SetDisplayMixTransparency (U8BIT transparency_level)
	Called to adjust the display video-mix transparency level of the Teletext pages. More...
void	STB_EBUTT_IncreaseDisplayMixTransparency (void)
	Called to adjust the display video-mix transparency level of the Teletext pages.
void	STB_EBUTT_DecreaseDisplayMixTransparency (void)
BOOLEAN	STB_EBUTT_IsDisplayHeld (void)
	Called to ascertain whether the present page is in 'hold' mode or not. Thus function is useful when allocating handet keys to events on the basis of the current functional state of the Teletext driver. More...
BOOLEAN	STB_EBUTT_IsDisplayDoubleHeight (void)
	Called to ascertain whether the present page is in 'double height' mode or not. Thus function is useful when allocating handet keys to events on the basis of the current functional state of the Teletext driver. More...

Variables
const S_EBUTT_FONT *const	ebutt_font_ptr

Detailed Description

Header file - EBU Teletext driver.

Date

04/02/2004

Author

Ocean Blue

Function Documentation

BOOLEAN STB_EBUTT_Initialise

(

void

)

This must be called to invoke the EBU TeleText driver module before all other functionality can be accessed. This initiates the relevant resources used by the driver module. As a consequence of calling this function, no TeleText processing will occur until other functions are called. It is envisaged that this function may be called within the general initialisation of the STB layer.

Returns

TRUE if initialisation was successful, FALSE otherwise.

BOOLEAN STB_EBUTT_InjectData	(	U8BIT *	data_ptr,
		U32BIT	data_length
	)

Allows teletext PES data packets to be injected by an external module, which will be decoded and displayed.

---

Parameters

data_ptr	- pointer to first whole PES packet data
data_length	- number of bytes of data provided

Returns

TRUE if the data is valid EBU teletext PES data, FALSE otherwise

BOOLEAN STB_EBUTT_IsDisplayDoubleHeight

(

void

)

Called to ascertain whether the present page is in 'double height' mode or not. Thus function is useful when allocating handet keys to events on the basis of the current functional state of the Teletext driver.

Returns

TRUE if the displayed page is double height, FALSE otherwise.

BOOLEAN STB_EBUTT_IsDisplayHeld

(

void

)

Called to ascertain whether the present page is in 'hold' mode or not. Thus function is useful when allocating handet keys to events on the basis of the current functional state of the Teletext driver.

Returns

TRUE if the displayed page is held, FALSE otherwise.

void STB_EBUTT_Kill

(

U8BIT

path

)

This is the accompanying function to STB_EBUTT_Initialise( ), and is called to shut-down the EBU TeleText driver module and release the relevant resources used by the driver module. This may not be used in some implementations.

Parameters

U8BIT

path - the path of where to kill teletext.

void STB_EBUTT_NotifyEvent

(

E_EBUTT_EVENT

event_type

)

Called whenever a TeleText-specific event being invoked. This is used to pass relevant user input to the driver, and the enumerate type supplied is defined independently of any IR handset / keypad.

Parameters

E_EBUTT_EVENT

event_type -

void STB_EBUTT_SetCacheMethod

(

E_EBUTT_CACHING_METHOD

ebutt_caching_method

)

Called to define the strategy used to determine what page content is to be displayed form the TeleText carousel content.

Parameters

E_EBUTT_CACHING_METHOD

ebutt_caching_method -

void STB_EBUTT_SetDisplayAntiAliasing

(

U8BIT

antialias_level

)

Called to adjust the display anti-aliasing level of the Teletext pages. This is used to control 'flicker' on TV displays.

Parameters

U8BIT	antialias_level - a factor between zero (no anti-alaising) to 8 (full anti-aliasing
U8BIT	antialias_level - a factor between zero (no anti-alaising) to 8 (full anti-aliasing)

void STB_EBUTT_SetDisplayBrightness

(

U8BIT

gun_intensity

)

Called to adjust the display brightness (colour intensity) of the Teletext pages.

Parameters

U8BIT

gun_intensity - a RGB gun intensity, ranging from 255 (brightest) to 127 (darkest)

void STB_EBUTT_SetDisplayMixTransparency

(

U8BIT

transparency_level

)

Called to adjust the display video-mix transparency level of the Teletext pages.

Parameters

U8BIT

transparency_level - a factor between zero (no transparency) to 255 (full transparency)

BOOLEAN STB_EBUTT_Show	(	E_EBUTT_CHARACTER_SET_DESIGNATION	character_set_designation,
		BOOLEAN	navigate_to_index_page,
		BOOLEAN	show_header
	)

Called to initiate continuous display of TeleText page content. This will result in either the index page defined in the service data stream being selected, or the previously displayed page (prior to a call to STB_EBUTT_Hide( ) being made) from being reinstated. This function can be called irrespective of the use of the STB_EBUTT_Start( ) / STB_EBUTT_Stop( ) functions, but of course may result in no TeleText data being displayed if none already exists within the cache. The return value indicates whether initialisation of the display mechanism has been successful or not.

Parameters

E_STB_EBUTT_CHARACTER_SET_DESIGNATION	character_set_designation - used to specifiy the default character set designation for a level 1.0 Teletext broadcast. This is useful to configure the implementation to work correctly when used with regionalised broadcasts.
BOOLEAN	navigate_to_index_page - set it TRUE if the index page defined within the Teletext service is used, or the last visited page is re-displayed.

Returns

TRUE if initialisation of diaply mechanism was successful, FALSE otherwise.

void STB_EBUTT_Start	(	U8BIT	path,
		U16BIT	text_pid,
		U8BIT	magazine,
		U8BIT	page
	)

These functions are called to control whether received TeleText data is processed. Using this functionality ensures that the process of collating page information can be halted when processing resources are a consideration. It is envisaged that some implementations may wish only to collate TeleText content only when the display is being shown, whilst other designs may which to cache significant page content as a background process. Abstracting this functionality from the initialisation routines gives the option to support both solution types.

Parameters

BOOLEAN	reset_cache - clears all pages from the cache if set to TRUE, saving memory resources.
magazine	- initial magazine to be loaded page - initial page to show from the magazine