Version: 20 Mar 2024

ml_media_cea608_caption.h

Classes

	Name
struct	MLCea608CaptionStyleColor Cea608 caption style and color.
struct	MLCea608CaptionPAC Cea608 caption preamble address code.
struct	MLCea608CaptionLineEx Cea608 caption line structure.
struct	MLCea608CaptionSegmentEx Cea608 caption segment structure.

Types

	Name
typedef struct MLCea608CaptionStyleColor	MLCea608CaptionStyleColor Cea608 caption style and color.
typedef struct MLCea608CaptionPAC	MLCea608CaptionPAC Cea608 caption preamble address code.
typedef struct MLCea608CaptionLineEx	MLCea608CaptionLineEx Cea608 caption line structure.
typedef struct MLCea608CaptionSegmentEx	MLCea608CaptionSegmentEx Cea608 caption segment structure.
typedef void()(MLHandle cc_handle, const MLCea608CaptionSegmentEx cc_seg, void *data)	MLMediaCCParserDisplayChangedCallback Callback signature called when Cea608 displayable is changed.

Enums

	Name
enum	MLCea608CaptionDimension { MLCea608_CCMaxRows = 15, MLCea608_CCMaxCols = 32, MLCea608_CCMaxRowsPlus2 = 17, MLCea608_CCMaxColsPlus2 = 34, MLCea608_CCMaxRowsCols_Ensure32Bits = 0x7FFFFFFF } Cea608 Caption Dimension constants.
enum	MLCea608CaptionColor { MLCea608CaptionColor_White = 0, MLCea608CaptionColor_Green = 1, MLCea608CaptionColor_Blue = 2, MLCea608CaptionColor_Cyan = 3, MLCea608CaptionColor_Red = 4, MLCea608CaptionColor_Yellow = 5, MLCea608CaptionColor_Magenta = 6, MLCea608CaptionColor_Invalide = 7, MLCea608CaptionColor_Ensure32Bits = 0x7FFFFFFF } Cea608 caption color code.
enum	MLCea608CaptionStyle { MLCea608CaptionStyle_Italics = 0x00000001, MLCea608CaptionStyle_Underline = 0x00000002, MLCea608CaptionStyle_Ensure32Bits = 0x7FFFFFFF } Cea608 caption style code.
enum	Anonymous Enum 16 { MLCea608_TS = 0x00A0 }

Functions

	Name
MLResult	MLMediaCCParserCreate(MLHandle * out_handle) Create internal closed caption parser object.
MLResult	MLMediaCCParserGetDisplayableEx(MLHandle cc_handle, const uint8_t * subtitle_data, int32_t subtitle_data_size, const MLCea608CaptionSegmentEx ** out_cc_seg) Return closed caption for display.
MLResult	MLMediaCCParserDestroy(MLHandle cc_handle) Release internal CC parser object.
MLResult	MLMediaCCParserSetDisplayChangedCallback(MLHandle cc_handle, MLMediaCCParserDisplayChangedCallback on_display_changed_callback, void * data) Set callback to get notified when a caption displayable has changed.
MLResult	MLMediaCCParserParse(MLHandle cc_handle, const uint8_t * subtitle_data, uint32_t subtitle_data_size) Provide Cea608 parser with subtitle raw data for parsing. If the callback has been set by MLMediaCCParserSetDisplayChangedCallback, then its issued to notify the CC Data.

Enums Documentation

MLCea608CaptionDimension

Enumerator	Value	Description
MLCea608_CCMaxRows	15
MLCea608_CCMaxCols	32
MLCea608_CCMaxRowsPlus2	17
MLCea608_CCMaxColsPlus2	34
MLCea608_CCMaxRowsCols_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Cea608 Caption Dimension constants.

API Level:

MLCea608CaptionColor

Enumerator	Value	Description
MLCea608CaptionColor_White	0
MLCea608CaptionColor_Green	1
MLCea608CaptionColor_Blue	2
MLCea608CaptionColor_Cyan	3
MLCea608CaptionColor_Red	4
MLCea608CaptionColor_Yellow	5
MLCea608CaptionColor_Magenta	6
MLCea608CaptionColor_Invalide	7
MLCea608CaptionColor_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Cea608 caption color code.

API Level:

MLCea608CaptionStyle

Enumerator	Value	Description
MLCea608CaptionStyle_Italics	0x00000001
MLCea608CaptionStyle_Underline	0x00000002
MLCea608CaptionStyle_Ensure32Bits	0x7FFFFFFF

Cea608 caption style code.

API Level:

Anonymous Enum 16

Enumerator	Value	Description
MLCea608_TS	0x00A0	NO-BREAK SPACE.

Types Documentation

MLCea608CaptionStyleColor

typedef struct MLCea608CaptionStyleColor MLCea608CaptionStyleColor;

Cea608 caption style and color.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLCea608CaptionPAC

typedef struct MLCea608CaptionPAC MLCea608CaptionPAC;

Cea608 caption preamble address code.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLCea608CaptionLineEx

typedef struct MLCea608CaptionLineEx MLCea608CaptionLineEx;

Cea608 caption line structure.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLCea608CaptionSegmentEx

typedef struct MLCea608CaptionSegmentEx MLCea608CaptionSegmentEx;

Cea608 caption segment structure.

More Info

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCCParserDisplayChangedCallback

typedef void(* MLMediaCCParserDisplayChangedCallback) (MLHandle cc_handle, const MLCea608CaptionSegmentEx *cc_seg, void *data);

Callback signature called when Cea608 displayable is changed.

Parameters


	cc_handle	MLHandle is a CC Parser instance for which callback was called.
	cc_seg	MLCea608CaptionSegmentEx conveys caption displayble to be rendered.
	data	Custom data to be returned when callback is fired.

API Level:

Functions Documentation

MLMediaCCParserCreate

MLResult MLMediaCCParserCreate(
    MLHandle * out_handle
)

Create internal closed caption parser object.

Parameters


MLHandle *	out_handle	A pointer to an MLHandle which will contain the handle to the CC parser. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns


MLResult	MLResult_Ok	Internal closed caption parser object was created successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCCParserGetDisplayableEx

MLResult MLMediaCCParserGetDisplayableEx(
    MLHandle cc_handle,
    const uint8_t * subtitle_data,
    int32_t subtitle_data_size,
    const MLCea608CaptionSegmentEx ** out_cc_seg
)

Return closed caption for display.

Parameters


MLHandle	cc_handle	A handle to a CC parser.
const uint8_t *	subtitle_data	Subtitle data of MLMediaPlayerSubtitleData structure returned from MLMediaPlayerGetSubtitleEx function.
int32_t	subtitle_data_size	Subtitle data size of MLMediaPlayerSubtitleData structure returned from MLMediaPlayerGetSubtitleEx function.
const MLCea608CaptionSegmentEx **	out_cc_seg	The returned MLCea608CaptionSegmentEx pointer for CC display. NOTE that user doesn't own this memory.

Returns


MLResult	MLResult_InvalidParam	one of the arguements is incorrect.
MLResult	MLResult_Ok	CC is ready to display and content is stored in out_ccSeg.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.
MLResult	MLMediaGenericResult_NoInit	CC parser was not properly built or initialized.
MLResult	MLMediaGenericResult_NotEnoughData	more data is required and no displayable CC for now.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCCParserDestroy

MLResult MLMediaCCParserDestroy(
    MLHandle cc_handle
)

Release internal CC parser object.

Parameters


MLHandle	cc_handle	A handle to a CC parser.

Returns


MLResult	MLResult_Ok	internal CC parser object was released successfully.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCCParserSetDisplayChangedCallback

MLResult MLMediaCCParserSetDisplayChangedCallback(
    MLHandle cc_handle,
    MLMediaCCParserDisplayChangedCallback on_display_changed_callback,
    void * data
)

Set callback to get notified when a caption displayable has changed.

Parameters


MLHandle	cc_handle	A handle to a CC parser.
MLMediaCCParserDisplayChangedCallback	on_display_changed_callback	Function pointer for display changed callback. See MLMediaCCParserDisplayChangedCallback() callback typedef declaration and comments for explanation on expected callback parameters. This can be 'NULL' to unset the callback.
void *	data	Custom data to be returned when callback is fired.

Returns


MLResult	MLResult_InvalidParam	Passed `cc_handle` handle was not found.
MLResult	MLResult_Ok	Callback was successfully set.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

Setting this callback saves application from handling raw subtitle data. Caption will be delivered in this callback at displayable time.

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

MLMediaCCParserParse

MLResult MLMediaCCParserParse(
    MLHandle cc_handle,
    const uint8_t * subtitle_data,
    uint32_t subtitle_data_size
)

Provide Cea608 parser with subtitle raw data for parsing. If the callback has been set by MLMediaCCParserSetDisplayChangedCallback, then its issued to notify the CC Data.

Parameters


MLHandle	cc_handle	A handle to a Cea608 parser.
const uint8_t *	subtitle_data	Subtitle data of MLMediaPlayerSubtitleData.
uint32_t	subtitle_data_size	Subtitle data size of MLMediaPlayerSubtitleData.

Returns


MLResult	MLResult_InvalidParam	the input parameter(s) is(are) wrong.
MLResult	MLResult_Ok	the operation was successful.
MLResult	MLMediaGenericResult_NoInit	Cea708 parser was not properly built or initialized.

Required Permissions:

None

Deprecated

Deprecated since 1.4.0. Scheduled for removal.

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"
#include "ml_types.h"

ML_EXTERN_C_BEGIN

typedef enum MLCea608CaptionDimension {
  MLCea608_CCMaxRows = 15,
  MLCea608_CCMaxCols = 32,
  MLCea608_CCMaxRowsPlus2 = 17,
  MLCea608_CCMaxColsPlus2 = 34,
  MLCea608_CCMaxRowsCols_Ensure32Bits = 0x7FFFFFFF
} MLCea608CaptionDimension;

typedef enum MLCea608CaptionColor {
  MLCea608CaptionColor_White        = 0,
  MLCea608CaptionColor_Green        = 1,
  MLCea608CaptionColor_Blue         = 2,
  MLCea608CaptionColor_Cyan         = 3,
  MLCea608CaptionColor_Red          = 4,
  MLCea608CaptionColor_Yellow       = 5,
  MLCea608CaptionColor_Magenta      = 6,
  MLCea608CaptionColor_Invalide     = 7,
  MLCea608CaptionColor_Ensure32Bits = 0x7FFFFFFF
} MLCea608CaptionColor;

typedef enum MLCea608CaptionStyle {
  MLCea608CaptionStyle_Italics      = 0x00000001,
  MLCea608CaptionStyle_Underline    = 0x00000002,
  MLCea608CaptionStyle_Ensure32Bits = 0x7FFFFFFF
} MLCea608CaptionStyle;

typedef ML_DEPRECATED_MSG("Use standard Android SDK APIs.") struct MLCea608CaptionStyleColor {
  uint32_t style;
  uint32_t color;
} MLCea608CaptionStyleColor;

typedef ML_DEPRECATED_MSG("Use standard Android SDK APIs.") struct MLCea608CaptionPAC {
  MLCea608CaptionStyleColor styleColor;
  uint32_t row;
  uint32_t col;
} MLCea608CaptionPAC;

enum {
  MLCea608_TS = 0x00A0
};

typedef ML_DEPRECATED_MSG("Use standard Android SDK APIs.") struct MLCea608CaptionLineEx {
  uint16_t display_chars[2 * MLCea608_CCMaxColsPlus2];
  MLCea608CaptionStyleColor *mid_row_styles[MLCea608_CCMaxColsPlus2];
  MLCea608CaptionPAC *pac_styles[MLCea608_CCMaxColsPlus2];
} MLCea608CaptionLineEx;

typedef ML_DEPRECATED_MSG("Use standard Android SDK APIs.") struct MLCea608CaptionSegmentEx {
  uint32_t version;
  MLCea608CaptionLineEx *cc_line[MLCea608_CCMaxRowsPlus2];
} MLCea608CaptionSegmentEx;

ML_DEPRECATED_MSG("Use standard Android SDK APIs.")
ML_API MLResult ML_CALL MLMediaCCParserCreate(MLHandle *out_handle);

ML_DEPRECATED_MSG("Use standard Android SDK APIs.")
ML_API MLResult ML_CALL MLMediaCCParserGetDisplayableEx(MLHandle cc_handle, const uint8_t *subtitle_data, int32_t subtitle_data_size, const MLCea608CaptionSegmentEx **out_cc_seg);

ML_DEPRECATED_MSG("Use standard Android SDK APIs.")
ML_API MLResult ML_CALL MLMediaCCParserDestroy(MLHandle cc_handle);

typedef void(*MLMediaCCParserDisplayChangedCallback)(MLHandle cc_handle, const MLCea608CaptionSegmentEx *cc_seg, void *data);

ML_DEPRECATED_MSG("Use standard Android SDK APIs.")
ML_API MLResult ML_CALL MLMediaCCParserSetDisplayChangedCallback(MLHandle cc_handle, MLMediaCCParserDisplayChangedCallback on_display_changed_callback, void *data);

ML_DEPRECATED_MSG("Use standard Android SDK APIs.")
ML_API MLResult ML_CALL MLMediaCCParserParse(MLHandle cc_handle, const uint8_t *subtitle_data, uint32_t subtitle_data_size);

ML_EXTERN_C_END

ml_media_cea608_caption.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLCea608CaptionDimension​

MLCea608CaptionColor​

MLCea608CaptionStyle​

Anonymous Enum 16​

Types Documentation​

MLCea608CaptionStyleColor​

MLCea608CaptionPAC​

MLCea608CaptionLineEx​

MLCea608CaptionSegmentEx​

MLMediaCCParserDisplayChangedCallback​

Functions Documentation​

MLMediaCCParserCreate​

MLMediaCCParserGetDisplayableEx​

MLMediaCCParserDestroy​

MLMediaCCParserSetDisplayChangedCallback​

MLMediaCCParserParse​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLCea608CaptionDimension

MLCea608CaptionColor

MLCea608CaptionStyle

Anonymous Enum 16

Types Documentation

MLCea608CaptionStyleColor

MLCea608CaptionPAC

MLCea608CaptionLineEx

MLCea608CaptionSegmentEx

MLMediaCCParserDisplayChangedCallback

Functions Documentation

MLMediaCCParserCreate

MLMediaCCParserGetDisplayableEx

MLMediaCCParserDestroy

MLMediaCCParserSetDisplayChangedCallback

MLMediaCCParserParse

Source code