DVBCore  22.3.0
Open Source DVB Engine
Classes | Macros | Typedefs | Enumerations | Functions
stbcc.c File Reference

Closed caption subtitle control, processing and rendering. More...

#include <string.h>
#include <stdio.h>
#include <ft2build.h>
#include <techtype.h>
#include <dbgfuncs.h>
#include "stbhwos.h"
#include "stbhwosd.h"
#include "stbhwav.h"
#include "stbheap.h"
#include "stbdpc.h"
#include "stbcc.h"

Classes

struct  S_CC_DATA
 
struct  s_cc_command_cw
 
struct  s_cc_command_clw
 
struct  s_cc_command_dsw
 
struct  s_cc_command_hdw
 
struct  s_cc_command_tgw
 
struct  s_cc_command_dlw
 
struct  s_cc_command_dly
 
struct  s_cc_command_spa
 
struct  s_cc_command_spc
 
struct  s_cc_command_spl
 
struct  s_cc_command_swa
 
struct  s_cc_command_df
 
struct  s_cc_command
 
struct  s_cc_data_state
 
struct  S_CC_STATUS
 
struct  S_CC_WINDOW_STATE
 
struct  S_CC_FONTS
 
struct  S_CC_PEN_STYLE
 

Macros

#define DBG_ERR(x, ...)   STB_SPDebugNoCnWrite("%s:%d " x, __FUNCTION__, __LINE__, ##__VA_ARGS__)
 
#define DBG_CC(x, ...)
 
#define DBG_PRE(x, ...)
 
#define DBG_PROC(x, ...)
 
#define DBG_608(x, ...)
 
#define DBG_708(x, ...)
 
#define DBG_RAW(x, ...)
 
#define DBG_CMD(x, ...)
 
#define CC_TASK_STACK_SIZE   1024 * 5
 
#define CC_TASK_PRIORITY   9
 
#define NTSC_CC_FIELD_1   0
 
#define NTSC_CC_FIELD_2   1
 
#define DTVCC_PACKET_DATA   2
 
#define DTVCC_PACKET_START   3
 
#define MIN(x, y)   (x < y? x : y)
 
#define CEA_MAX_ROWS   15
 
#define CEA_MAX_COLS   32
 
#define CEA_MAX_WINDOWS   8
 
#define CC_COLOUR_OFFSET   128 /* Offset in the colour palette to the start of the CC colours */
 
#define CC_COLOUR_TRANSLUCENT   0x7f /* Transparency value used when a translucent opacity is selected */
 
#define CC_COLOUR_BLACK   0x00
 
#define CC_COLOUR_RED3   0x30
 
#define CC_COLOUR_GREEN3   0x0c
 
#define CC_COLOUR_BLUE3   0x03
 
#define CC_COLOUR_CYAN3   0x0f
 
#define CC_COLOUR_YELLOW3   0x3c
 
#define CC_COLOUR_MAGENTA3   0x33
 
#define CC_COLOUR_WHITE2   0x2a
 
#define CC_COLOUR_WHITE3   0x3f
 
#define COMMAND_BUFFER_SIZE   70 /* Max bytes could be 3+63 for a variable length command */
 
#define INPUT_BUFFER_SIZE   272
 

Typedefs

typedef struct s_cc_command_cw S_CC_COMMAND_CW
 
typedef struct s_cc_command_clw S_CC_COMMAND_CLW
 
typedef struct s_cc_command_dsw S_CC_COMMAND_DSW
 
typedef struct s_cc_command_hdw S_CC_COMMAND_HDW
 
typedef struct s_cc_command_tgw S_CC_COMMAND_TGW
 
typedef struct s_cc_command_dlw S_CC_COMMAND_DLW
 
typedef struct s_cc_command_dly S_CC_COMMAND_DLY
 
typedef struct s_cc_command_spa S_CC_COMMAND_SPA
 
typedef struct s_cc_command_spc S_CC_COMMAND_SPC
 
typedef struct s_cc_command_spl S_CC_COMMAND_SPL
 
typedef struct s_cc_command_swa S_CC_COMMAND_SWA
 
typedef struct s_cc_command_df S_CC_COMMAND_DF
 
typedef struct s_cc_command S_CC_COMMAND
 
typedef struct s_cc_data_state S_DTVCC_PACKET_STATE
 

Enumerations

enum  E_CC_CODE {
  CC_CODE_UNKNOWN, CC_CODE_FIXED_LEN, CC_CODE_VAR_LEN, CC_CODE_C0_ETX,
  CC_CODE_C0_BS, CC_CODE_C0_FF, CC_CODE_C0_CR, CC_CODE_C0_HCR,
  CC_CODE_C0_EXT1_C2, CC_CODE_C0_EXT1_G2, CC_CODE_C0_EXT1_C3, CC_CODE_C0_EXT1_C3_VAR_LENGTH,
  CC_CODE_C0_EXT1_G3, CC_CODE_C0_P16, CC_CODE_G0, CC_CODE_C1_CW,
  CC_CODE_C1_CLW, CC_CODE_C1_DSW, CC_CODE_C1_HDW, CC_CODE_C1_TGW,
  CC_CODE_C1_DLW, CC_CODE_C1_DLY, CC_CODE_C1_RST, CC_CODE_C1_DLC,
  CC_CODE_C1_SPA, CC_CODE_C1_SPC, CC_CODE_C1_SPL, CC_CODE_C1_SWA,
  CC_CODE_C1_DF, CC_CODE_G1
}
 
enum  E_CC_TEXT_TAG {
  CC_TEXT_TAG_DIALOG = 0, CC_TEXT_TAG_SOURCE_ID = 1, CC_TEXT_TAG_ELECTRONIC_VOICE = 2, CC_TEXT_TAG_FOREIGN_DIALOG = 3,
  CC_TEXT_TAG_VOICEOVER = 4, CC_TEXT_TAG_AUDIBLE_TRANSLATION = 5, CC_TEXT_TAG_SUBTITLE_TRANSLATION = 6, CC_TEXT_TAG_VOICE_QUALITY = 7,
  CC_TEXT_TAG_SONG_LYRICS = 8, CC_TEXT_TAG_SOUND_EFFECT = 9, CC_TEXT_TAG_MUSICAL_SCORE = 10, CC_TEXT_TAG_EXPLETIVE = 11,
  CC_TEXT_TAG_UNDEFINED_12 = 12, CC_TEXT_TAG_UNDEFINED_13 = 13, CC_TEXT_TAG_UNDEFINED_14 = 14, CC_TEXT_TAG_NO_DISPLAY = 15
}
 
enum  E_CC_OFFSET { CC_OFFSET_SUBSCRIPT = 0, CC_OFFSET_NORMAL = 1, CC_OFFSET_SUPERSCRIPT = 2, CC_OFFSET_UNDEFINED_3 = 3 }
 
enum  E_CC_PEN_SIZE { CC_PEN_SIZE_SMALL = 0, CC_PEN_SIZE_STANDARD = 1, CC_PEN_SIZE_LARGE = 2, CC_PEN_SIZE_UNDEFINED_3 = 3 }
 
enum  E_CC_BORDER {
  CC_BORDER_NONE = 0, CC_BORDER_RAISED = 1, CC_BORDER_DEPRESSED = 2, CC_BORDER_UNIFORM = 3,
  CC_BORDER_SHADOW_LEFT = 4, CC_BORDER_SHADOW_RIGHT = 5, CC_BORDER_UNDEFINED_6 = 6, CC_BORDER_UNDEFINED_7 = 7
}
 
enum  E_CC_OPACITY { CC_OPACITY_SOLID = 0, CC_OPACITY_FLASH = 1, CC_OPACITY_TRANSLUCENT = 2, CC_OPACITY_TRANSPARENT = 3 }
 
enum  E_CC_DIRECTION { CC_DIRECTION_LEFT_TO_RIGHT = 0, CC_DIRECTION_RIGHT_TO_LEFT = 1, CC_DIRECTION_TOP_TO_BOTTOM = 2, CC_DIRECTION_BOTTOM_TO_TOP = 3 }
 
enum  E_CC_JUSTIFY { CC_JUSTIFY_LEFT = 0, CC_JUSTIFY_RIGHT = 1, CC_JUSTIFY_CENTER = 2, CC_JUSTIFY_FULL = 3 }
 
enum  E_CC_DISPLAY_EFFECT { CC_DISPLAY_EFFECT_SNAP = 0, CC_DISPLAY_EFFECT_FADE = 1, CC_DISPLAY_EFFECT_WIPE = 2, CC_DISPLAY_EFFECT_UNDEFINED_3 = 3 }
 
enum  E_CC_DATA_STATE {
  CC_DATA_STATE_START, CC_DATA_STATE_608_SEGMENT, CC_DATA_STATE_CCP_START, CC_DATA_STATE_CCP_CONT,
  CC_DATA_STATE_PADDING, CC_DATA_STATE_INVALID
}
 

Functions

void STB_CCInitialise (void)
 Initialises closed caption subtitling control.
 
void STB_CCSetDisplayInfo (E_STB_AV_ASPECT_RATIO tv_aspect_ratio, U16BIT screen_width, U16BIT screen_height)
 The TV aspect ratio and size in pixels are needed for closed captions so the safe area can be determined, as well as the number of rows and columns. This information should be provided before closed captions are started and whenever the display changes. More...
 
void STB_CCSetFont (E_CC_FONT_STYLE font_style, U8BIT *font_data, U32BIT font_size)
 Closed captions can use a number of defined font styles: monospaced serif, proportional serif, monospace sans serif, proportional sans serif, casual, cursive, small capitals, and a default font. The font data for each of these needs to be provided and the CC renderer will use whichever ones are provided. More...
 
void STB_CCSetUserFontStyle (E_CC_FONT_STYLE font_style)
 Sets the user defined font style that will be used to display caption text, overriding the style defined by the broadcast. Set as CC_FONT_STYLE_BROADCAST to revert back to having caption text rendered using the broadcast defined font style. More...
 
E_CC_FONT_STYLE STB_CCGetUserFontStyle (void)
 Returns the user defined font style for rendering caption text. More...
 
void STB_CCSetUserTextSize (E_CC_TEXT_SIZE text_size)
 Sets the user defined text size of the caption text, overriding the broadcast text size. Use CC_TEXT_SIZE_BROADCAST to revert to using the broadcast size. Note that this may not take effect if it results in the caption window being too large to be displayed, in which case the next size down will be used. More...
 
E_CC_TEXT_SIZE STB_CCGetUserTextSize (void)
 Returns the user defined text size for rendering caption text. More...
 
BOOLEAN STB_CCStart (U8BIT path, BOOLEAN digital_cc, U8BIT caption_service_number)
 Starts processing closed caption subtitling. More...
 
void STB_CCEnable (BOOLEAN enable)
 Enables or disables display of CC subtitles. If the CC service to be used hasn't been set then service 1 will be selected by default. More...
 
void STB_CCStop (U8BIT path)
 Stops subtitling display. More...
 
void STB_CCStatus (BOOLEAN *started, BOOLEAN *enabled)
 Returns the current status of CC subtitling. More...
 

Detailed Description

Closed caption subtitle control, processing and rendering.

Date
October 2020

Function Documentation

void STB_CCEnable ( BOOLEAN  enable)

Enables or disables display of CC subtitles. If the CC service to be used hasn't been set then service 1 will be selected by default.

Parameters
enableTRUE to enable display of closed captions, FALSE to disable
E_CC_FONT_STYLE STB_CCGetUserFontStyle ( void  )

Returns the user defined font style for rendering caption text.

Returns
User defined font style
E_CC_TEXT_SIZE STB_CCGetUserTextSize ( void  )

Returns the user defined text size for rendering caption text.

Returns
User defined text size
void STB_CCSetDisplayInfo ( E_STB_AV_ASPECT_RATIO  tv_aspect_ratio,
U16BIT  screen_width,
U16BIT  screen_height 
)

The TV aspect ratio and size in pixels are needed for closed captions so the safe area can be determined, as well as the number of rows and columns. This information should be provided before closed captions are started and whenever the display changes.

Parameters
tv_aspect_ratioAspect ratio of the screen, either 4:3 or 16:9
screen_widthWidth of the screen in pixels
screen_heightHeight of the screen in pixels
void STB_CCSetFont ( E_CC_FONT_STYLE  font_style,
U8BIT *  font_data,
U32BIT  font_size 
)

Closed captions can use a number of defined font styles: monospaced serif, proportional serif, monospace sans serif, proportional sans serif, casual, cursive, small capitals, and a default font. The font data for each of these needs to be provided and the CC renderer will use whichever ones are provided.

Parameters
font_styleThe font style of the font data being set (not CC_FONT_STYLE_BROADCAST)
font_dataData for the font. This is not copied and so must remain in memory
font_sizeNumber of bytes in the font data
void STB_CCSetUserFontStyle ( E_CC_FONT_STYLE  font_style)

Sets the user defined font style that will be used to display caption text, overriding the style defined by the broadcast. Set as CC_FONT_STYLE_BROADCAST to revert back to having caption text rendered using the broadcast defined font style.

Parameters
font_styleFont style to be used to render caption text
void STB_CCSetUserTextSize ( E_CC_TEXT_SIZE  text_size)

Sets the user defined text size of the caption text, overriding the broadcast text size. Use CC_TEXT_SIZE_BROADCAST to revert to using the broadcast size. Note that this may not take effect if it results in the caption window being too large to be displayed, in which case the next size down will be used.

Parameters
text_sizeSize to be used to render the caption text.
BOOLEAN STB_CCStart ( U8BIT  path,
BOOLEAN  digital_cc,
U8BIT  caption_service_number 
)

Starts processing closed caption subtitling.

Parameters
pathDecode path
digital_ccTRUE if 708 captions are to be decoded, FALSE for 608
caption_service_numberservice number to be decoded if digital (708) captions are selected
Returns
TRUE if closed caption processing is started, FALSE otherwise
void STB_CCStatus ( BOOLEAN *  started,
BOOLEAN *  enabled 
)

Returns the current status of CC subtitling.

Parameters
startedReturns the started state
enabledReturns the enabled state
void STB_CCStop ( U8BIT  path)

Stops subtitling display.

Parameters
pathDecode path