1 /* GStreamer 2 * Copyright (C) <2018> Edward Hervey <edward@centricular.com> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Library General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Library General Public License for more details. 13 * 14 * You should have received a copy of the GNU Library General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 #ifndef __GST_VIDEO_ANC_H__ 21 #define __GST_VIDEO_ANC_H__ 22 23 #include <gst/gst.h> 24 #include <gst/video/video-format.h> 25 #include <gst/video/video-info.h> 26 27 G_BEGIN_DECLS 28 29 typedef struct _GstVideoAncillary GstVideoAncillary; 30 31 /** 32 * GstVideoAncillary: 33 * @DID: The Data Identifier 34 * @SDID_block_number: The Secondary Data Identifier (if type 2) or the Data 35 * Block Number (if type 1) 36 * @data_count: The amount of data (in bytes) in @data (max 255 bytes) 37 * @data: (array length=data_count): The user data content of the Ancillary packet. 38 * Does not contain the ADF, DID, SDID nor CS. 39 * 40 * Video Ancillary data, according to SMPTE-291M specification. 41 * 42 * Note that the contents of the data are always stored as 8bit data (i.e. do not contain 43 * the parity check bits). 44 * 45 * Since: 1.16 46 */ 47 struct _GstVideoAncillary { 48 guint8 DID; 49 guint8 SDID_block_number; 50 guint8 data_count; 51 guint8 data[256]; 52 53 /*< private >*/ 54 /* Padding for future extension */ 55 gpointer _gst_reserved[GST_PADDING]; 56 }; 57 58 /** 59 * GstVideoAncillaryDID: 60 * 61 * Since: 1.16 62 */ 63 typedef enum { 64 GST_VIDEO_ANCILLARY_DID_UNDEFINED = 0x00, 65 GST_VIDEO_ANCILLARY_DID_DELETION = 0x80, 66 GST_VIDEO_ANCILLARY_DID_HANC_3G_AUDIO_DATA_FIRST = 0xa0, 67 GST_VIDEO_ANCILLARY_DID_HANC_3G_AUDIO_DATA_LAST = 0xa7, 68 GST_VIDEO_ANCILLARY_DID_HANC_HDTV_AUDIO_DATA_FIRST = 0xe0, 69 GST_VIDEO_ANCILLARY_DID_HANC_HDTV_AUDIO_DATA_LAST = 0xe7, 70 GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_1_FIRST = 0xec, 71 GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_1_LAST = 0xef, 72 GST_VIDEO_ANCILLARY_DID_CAMERA_POSITION = 0xf0, 73 GST_VIDEO_ANCILLARY_DID_HANC_ERROR_DETECTION = 0xf4, 74 GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_2_FIRST = 0xf8, 75 GST_VIDEO_ANCILLARY_DID_HANC_SDTV_AUDIO_DATA_2_LAST = 0xff, 76 } GstVideoAncillaryDID; 77 78 /** 79 * GST_VIDEO_ANCILLARY_DID16: 80 * @anc: a #GstVideoAncillary 81 * 82 * Returns the #GstVideoAncillaryDID16 of the ancillary data. 83 * 84 * Since: 1.16 85 * 86 * Returns: a #GstVideoAncillaryDID16 identifier 87 */ 88 #define GST_VIDEO_ANCILLARY_DID16(anc) ((guint16)((anc)->DID) << 8 | (guint16)((anc)->SDID_block_number)) 89 90 /** 91 * GstVideoAncillaryDID16: 92 * @GST_VIDEO_ANCILLARY_DID16_S334_EIA_708: CEA 708 Ancillary data according to SMPTE 334 93 * @GST_VIDEO_ANCILLARY_DID16_S334_EIA_608: CEA 608 Ancillary data according to SMPTE 334 94 * @GST_VIDEO_ANCILLARY_DID16_S2016_3_AFD_BAR: AFD/Bar Ancillary data according to SMPTE 2016-3 (Since: 1.18) 95 * 96 * Some know types of Ancillary Data identifiers. 97 * 98 * Since: 1.16 99 */ 100 typedef enum { 101 GST_VIDEO_ANCILLARY_DID16_S334_EIA_708 = 0x6101, 102 GST_VIDEO_ANCILLARY_DID16_S334_EIA_608 = 0x6102, 103 GST_VIDEO_ANCILLARY_DID16_S2016_3_AFD_BAR = 0x4105, 104 } GstVideoAncillaryDID16; 105 106 /** 107 * GstVideoAFDValue: 108 * @GST_VIDEO_AFD_UNAVAILABLE: Unavailable (see note 0 below). 109 * @GST_VIDEO_AFD_16_9_TOP_ALIGNED: For 4:3 coded frame, letterbox 16:9 image, 110 * at top of the coded frame. For 16:9 coded frame, full frame 16:9 image, 111 * the same as the coded frame. 112 * @GST_VIDEO_AFD_14_9_TOP_ALIGNED: For 4:3 coded frame, letterbox 14:9 image, 113 * at top of the coded frame. For 16:9 coded frame, pillarbox 14:9 image, 114 * horizontally centered in the coded frame. 115 * @GST_VIDEO_AFD_GREATER_THAN_16_9: For 4:3 coded frame, letterbox image with an aspect ratio 116 * greater than 16:9, vertically centered in the coded frame. For 16:9 coded frame, 117 * letterbox image with an aspect ratio greater than 16:9. 118 * @GST_VIDEO_AFD_4_3_FULL_16_9_FULL: For 4:3 coded frame, full frame 4:3 image, 119 * the same as the coded frame. For 16:9 coded frame, full frame 16:9 image, the same as 120 * the coded frame. 121 * @GST_VIDEO_AFD_4_3_FULL_4_3_PILLAR: For 4:3 coded frame, full frame 4:3 image, the same as 122 * the coded frame. For 16:9 coded frame, pillarbox 4:3 image, horizontally centered in the 123 * coded frame. 124 * @GST_VIDEO_AFD_16_9_LETTER_16_9_FULL: For 4:3 coded frame, letterbox 16:9 image, vertically centered in 125 * the coded frame with all image areas protected. For 16:9 coded frame, full frame 16:9 image, 126 * with all image areas protected. 127 * @GST_VIDEO_AFD_14_9_LETTER_14_9_PILLAR: For 4:3 coded frame, letterbox 14:9 image, vertically centered in 128 * the coded frame. For 16:9 coded frame, pillarbox 14:9 image, horizontally centered in the 129 * coded frame. 130 * @GST_VIDEO_AFD_4_3_FULL_14_9_CENTER: For 4:3 coded frame, full frame 4:3 image, with alternative 14:9 131 * center. For 16:9 coded frame, pillarbox 4:3 image, with alternative 14:9 center. 132 * @GST_VIDEO_AFD_16_9_LETTER_14_9_CENTER: For 4:3 coded frame, letterbox 16:9 image, with alternative 14:9 133 * center. For 16:9 coded frame, full frame 16:9 image, with alternative 14:9 center. 134 * @GST_VIDEO_AFD_16_9_LETTER_4_3_CENTER: For 4:3 coded frame, letterbox 16:9 image, with alternative 4:3 135 * center. For 16:9 coded frame, full frame 16:9 image, with alternative 4:3 center. 136 * 137 * Enumeration of the various values for Active Format Description (AFD) 138 * 139 * AFD should be included in video user data whenever the rectangular 140 * picture area containing useful information does not extend to the full height or width of the coded 141 * frame. AFD data may also be included in user data when the rectangular picture area containing 142 * useful information extends to the full height and width of the coded frame. 143 * 144 * For details, see Table 6.14 Active Format in: 145 * 146 * ATSC Digital Television Standard: 147 * Part 4 – MPEG-2 Video System Characteristics 148 * 149 * https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf 150 * 151 * and Active Format Description in Complete list of AFD codes 152 * 153 * https://en.wikipedia.org/wiki/Active_Format_Description#Complete_list_of_AFD_codes 154 * 155 * and SMPTE ST2016-1 156 * 157 * Notes: 158 * 159 * 1) AFD 0 is undefined for ATSC and SMPTE ST2016-1, indicating that AFD data is not available: 160 * If Bar Data is not present, AFD '0000' indicates that exact information 161 * is not available and the active image should be assumed to be the same as the coded frame. AFD '0000'. 162 * AFD '0000' accompanied by Bar Data signals that the active image’s aspect ratio is narrower than 16:9, 163 * but is not 4:3 or 14:9. As the exact aspect ratio cannot be conveyed by AFD alone, wherever possible, 164 * AFD ‘0000’ should be accompanied by Bar Data to define the exact vertical or horizontal extent 165 * of the active image. 166 * 2) AFD 0 is reserved for DVB/ETSI 167 * 3) values 1, 5, 6, 7, and 12 are reserved for both ATSC and DVB/ETSI 168 * 4) values 2 and 3 are not recommended for ATSC, but are valid for DVB/ETSI 169 * 170 * Since: 1.18 171 */ 172 typedef enum { 173 GST_VIDEO_AFD_UNAVAILABLE = 0, 174 GST_VIDEO_AFD_16_9_TOP_ALIGNED = 2, 175 GST_VIDEO_AFD_14_9_TOP_ALIGNED = 3, 176 GST_VIDEO_AFD_GREATER_THAN_16_9 = 4, 177 GST_VIDEO_AFD_4_3_FULL_16_9_FULL = 8, 178 GST_VIDEO_AFD_4_3_FULL_4_3_PILLAR = 9, 179 GST_VIDEO_AFD_16_9_LETTER_16_9_FULL = 10, 180 GST_VIDEO_AFD_14_9_LETTER_14_9_PILLAR = 11, 181 GST_VIDEO_AFD_4_3_FULL_14_9_CENTER = 13, 182 GST_VIDEO_AFD_16_9_LETTER_14_9_CENTER = 14, 183 GST_VIDEO_AFD_16_9_LETTER_4_3_CENTER = 15 184 } GstVideoAFDValue; 185 186 /** 187 * GstVideoAFDSpec: 188 * @GST_VIDEO_AFD_SPEC_DVB_ETSI: AFD value is from DVB/ETSI standard 189 * @GST_VIDEO_AFD_SPEC_ATSC_A53: AFD value is from ATSC A/53 standard 190 * @GST_VIDEO_AFD_SPEC_SMPT_ST2016_1 : AFD value is from SMPTE ST2016-1 standard 191 * 192 * Enumeration of the different standards that may apply to AFD data: 193 * 194 * 0) ETSI/DVB: 195 * https://www.etsi.org/deliver/etsi_ts/101100_101199/101154/02.01.01_60/ts_101154v020101p.pdf 196 * 197 * 1) ATSC A/53: 198 * https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf 199 * 200 * 2) SMPTE ST2016-1: 201 * 202 * Since: 1.18 203 */ 204 typedef enum { 205 GST_VIDEO_AFD_SPEC_DVB_ETSI, 206 GST_VIDEO_AFD_SPEC_ATSC_A53, 207 GST_VIDEO_AFD_SPEC_SMPTE_ST2016_1 208 } GstVideoAFDSpec; 209 210 /** 211 * GstVideoAFDMeta: 212 * @meta: parent #GstMeta 213 * @field: 0 for progressive or field 1 and 1 for field 2 214 * @spec: #GstVideoAFDSpec that applies to @afd 215 * @afd: #GstVideoAFDValue AFD value 216 * 217 * Active Format Description (AFD) 218 * 219 * For details, see Table 6.14 Active Format in: 220 * 221 * ATSC Digital Television Standard: 222 * Part 4 – MPEG-2 Video System Characteristics 223 * 224 * https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf 225 * 226 * and Active Format Description in Complete list of AFD codes 227 * 228 * https://en.wikipedia.org/wiki/Active_Format_Description#Complete_list_of_AFD_codes 229 * 230 * and SMPTE ST2016-1 231 * 232 * Since: 1.18 233 */ 234 typedef struct { 235 GstMeta meta; 236 237 guint8 field; 238 GstVideoAFDSpec spec; 239 GstVideoAFDValue afd; 240 } GstVideoAFDMeta; 241 242 GST_VIDEO_API GType gst_video_afd_meta_api_get_type (void); 243 #define GST_VIDEO_AFD_META_API_TYPE (gst_video_afd_meta_api_get_type()) 244 245 GST_VIDEO_API const GstMetaInfo *gst_video_afd_meta_get_info (void); 246 #define GST_VIDEO_AFD_META_INFO (gst_video_afd_meta_get_info()) 247 248 /** 249 * gst_buffer_get_video_afd_meta: 250 * @b: A #GstBuffer 251 * 252 * Gets the #GstVideoAFDMeta that might be present on @b. 253 * 254 * Note: there may be two #GstVideoAFDMeta structs for interlaced video. 255 * 256 * Since: 1.18 257 * 258 * Returns: The first #GstVideoAFDMeta present on @b, or %NULL if 259 * no #GstVideoAFDMeta are present 260 */ 261 #define gst_buffer_get_video_afd_meta(b) \ 262 ((GstVideoAFDMeta*)gst_buffer_get_meta((b),GST_VIDEO_AFD_META_API_TYPE)) 263 264 GST_VIDEO_API 265 GstVideoAFDMeta *gst_buffer_add_video_afd_meta (GstBuffer * buffer, guint8 field, 266 GstVideoAFDSpec spec, 267 GstVideoAFDValue afd); 268 /** 269 * GstVideoBarMeta: 270 * @meta: parent #GstMeta 271 * @field: 0 for progressive or field 1 and 1 for field 2 272 * @is_letterbox: if true then bar data specifies letterbox, otherwise pillarbox 273 * @bar_data1: If @is_letterbox is true, then the value specifies the 274 * last line of a horizontal letterbox bar area at top of reconstructed frame. 275 * Otherwise, it specifies the last horizontal luminance sample of a vertical pillarbox 276 * bar area at the left side of the reconstructed frame 277 * @bar_data2: If @is_letterbox is true, then the value specifies the 278 * first line of a horizontal letterbox bar area at bottom of reconstructed frame. 279 * Otherwise, it specifies the first horizontal 280 * luminance sample of a vertical pillarbox bar area at the right side of the reconstructed frame. 281 * 282 * Bar data should be included in video user data 283 * whenever the rectangular picture area containing useful information 284 * does not extend to the full height or width of the coded frame 285 * and AFD alone is insufficient to describe the extent of the image. 286 * 287 * Note: either vertical or horizontal bars are specified, but not both. 288 * 289 * For more details, see: 290 * 291 * https://www.atsc.org/wp-content/uploads/2015/03/a_53-Part-4-2009.pdf 292 * 293 * and SMPTE ST2016-1 294 * 295 * Since: 1.18 296 */ 297 typedef struct { 298 GstMeta meta; 299 300 guint8 field; 301 gboolean is_letterbox; 302 guint bar_data1; 303 guint bar_data2; 304 } GstVideoBarMeta; 305 306 GST_VIDEO_API GType gst_video_bar_meta_api_get_type (void); 307 #define GST_VIDEO_BAR_META_API_TYPE (gst_video_bar_meta_api_get_type()) 308 309 GST_VIDEO_API const GstMetaInfo *gst_video_bar_meta_get_info (void); 310 #define GST_VIDEO_BAR_META_INFO (gst_video_bar_meta_get_info()) 311 /** 312 * gst_buffer_get_video_bar_meta: 313 * @b: A #GstBuffer 314 * 315 * Gets the #GstVideoBarMeta that might be present on @b. 316 * 317 * Since: 1.18 318 * 319 * Returns: The first #GstVideoBarMeta present on @b, or %NULL if 320 * no #GstVideoBarMeta are present 321 */ 322 #define gst_buffer_get_video_bar_meta(b) \ 323 ((GstVideoBarMeta*)gst_buffer_get_meta((b),GST_VIDEO_BAR_META_API_TYPE)) 324 325 GST_VIDEO_API 326 GstVideoBarMeta *gst_buffer_add_video_bar_meta (GstBuffer * buffer, guint8 field, 327 gboolean is_letterbox, guint bar_data1, guint bar_data2); 328 329 /* Closed Caption support */ 330 /** 331 * GstVideoCaptionType: 332 * @GST_VIDEO_CAPTION_TYPE_UNKNOWN: Unknown type of CC 333 * @GST_VIDEO_CAPTION_TYPE_CEA608_RAW: CEA-608 as byte pairs. Note that 334 * this format is not recommended since is does not specify to 335 * which field the caption comes from and therefore assumes 336 * it comes from the first field (and that there is no information 337 * on the second field). Use @GST_VIDEO_CAPTION_TYPE_CEA708_RAW 338 * if you wish to store CEA-608 from two fields and prefix each byte pair 339 * with 0xFC for the first field and 0xFD for the second field. 340 * @GST_VIDEO_CAPTION_TYPE_CEA608_S334_1A: CEA-608 as byte triplets as defined 341 * in SMPTE S334-1 Annex A. The second and third byte of the byte triplet 342 * is the raw CEA608 data, the first byte is a bitfield: The top/7th bit is 343 * 0 for the second field, 1 for the first field, bit 6 and 5 are 0 and 344 * bits 4 to 0 are a 5 bit unsigned integer that represents the line 345 * offset relative to the base-line of the original image format (line 9 346 * for 525-line field 1, line 272 for 525-line field 2, line 5 for 347 * 625-line field 1 and line 318 for 625-line field 2). 348 * @GST_VIDEO_CAPTION_TYPE_CEA708_RAW: CEA-708 as cc_data byte triplets. They 349 * can also contain 608-in-708 and the first byte of each triplet has to 350 * be inspected for detecting the type. 351 * @GST_VIDEO_CAPTION_TYPE_CEA708_CDP: CEA-708 (and optionally CEA-608) in 352 * a CDP (Caption Distribution Packet) defined by SMPTE S-334-2. 353 * Contains the whole CDP (starting with 0x9669). 354 * 355 * The various known types of Closed Caption (CC). 356 * 357 * Since: 1.16 358 */ 359 typedef enum { 360 GST_VIDEO_CAPTION_TYPE_UNKNOWN = 0, 361 GST_VIDEO_CAPTION_TYPE_CEA608_RAW = 1, 362 GST_VIDEO_CAPTION_TYPE_CEA608_S334_1A = 2, 363 GST_VIDEO_CAPTION_TYPE_CEA708_RAW = 3, 364 GST_VIDEO_CAPTION_TYPE_CEA708_CDP = 4 365 } GstVideoCaptionType; 366 367 GST_VIDEO_API 368 GstVideoCaptionType 369 gst_video_caption_type_from_caps (const GstCaps *caps); 370 371 GST_VIDEO_API 372 GstCaps * 373 gst_video_caption_type_to_caps (GstVideoCaptionType type); 374 375 /** 376 * GstVideoCaptionMeta: 377 * @meta: parent #GstMeta 378 * @caption_type: The type of Closed Caption contained in the meta. 379 * @data: (array length=size): The Closed Caption data. 380 * @size: The size in bytes of @data 381 * 382 * Extra buffer metadata providing Closed Caption. 383 * 384 * Since: 1.16 385 */ 386 typedef struct { 387 GstMeta meta; 388 389 GstVideoCaptionType caption_type; 390 guint8 *data; 391 gsize size; 392 } GstVideoCaptionMeta; 393 394 GST_VIDEO_API 395 GType gst_video_caption_meta_api_get_type (void); 396 #define GST_VIDEO_CAPTION_META_API_TYPE (gst_video_caption_meta_api_get_type()) 397 398 GST_VIDEO_API 399 const GstMetaInfo *gst_video_caption_meta_get_info (void); 400 #define GST_VIDEO_CAPTION_META_INFO (gst_video_caption_meta_get_info()) 401 402 /** 403 * gst_buffer_get_video_caption_meta: 404 * @b: A #GstBuffer 405 * 406 * Gets the #GstVideoCaptionMeta that might be present on @b. 407 * 408 * Since: 1.16 409 * 410 * Returns: The first #GstVideoCaptionMeta present on @b, or %NULL if 411 * no #GstVideoCaptionMeta are present 412 */ 413 #define gst_buffer_get_video_caption_meta(b) \ 414 ((GstVideoCaptionMeta*)gst_buffer_get_meta((b),GST_VIDEO_CAPTION_META_API_TYPE)) 415 416 GST_VIDEO_API 417 GstVideoCaptionMeta *gst_buffer_add_video_caption_meta (GstBuffer * buffer, 418 GstVideoCaptionType caption_type, 419 const guint8 *data, 420 gsize size); 421 422 /** 423 * GstVideoVBIParser: 424 * 425 * A parser for detecting and extracting @GstVideoAncillary data from 426 * Vertical Blanking Interval lines of component signals. 427 * 428 * Since: 1.16 429 */ 430 431 typedef struct _GstVideoVBIParser GstVideoVBIParser; 432 433 GST_VIDEO_API 434 GType gst_video_vbi_parser_get_type (void); 435 436 /** 437 * GstVideoVBIParserResult: 438 * @GST_VIDEO_VBI_PARSER_RESULT_DONE: No line were provided, or no more Ancillary data was found. 439 * @GST_VIDEO_VBI_PARSER_RESULT_OK: A #GstVideoAncillary was found. 440 * @GST_VIDEO_VBI_PARSER_RESULT_ERROR: An error occurred 441 * 442 * Return values for #GstVideoVBIParser 443 * 444 * Since: 1.16 445 */ 446 typedef enum { 447 GST_VIDEO_VBI_PARSER_RESULT_DONE = 0, 448 GST_VIDEO_VBI_PARSER_RESULT_OK = 1, 449 GST_VIDEO_VBI_PARSER_RESULT_ERROR = 2 450 } GstVideoVBIParserResult; 451 452 GST_VIDEO_API 453 GstVideoVBIParserResult gst_video_vbi_parser_get_ancillary(GstVideoVBIParser *parser, 454 GstVideoAncillary *anc); 455 456 GST_VIDEO_API 457 GstVideoVBIParser *gst_video_vbi_parser_new (GstVideoFormat format, guint32 pixel_width); 458 459 GST_VIDEO_API 460 GstVideoVBIParser *gst_video_vbi_parser_copy (const GstVideoVBIParser *parser); 461 462 GST_VIDEO_API 463 void gst_video_vbi_parser_free (GstVideoVBIParser *parser); 464 465 GST_VIDEO_API 466 void gst_video_vbi_parser_add_line (GstVideoVBIParser *parser, const guint8 *data); 467 468 /** 469 * GstVideoVBIEncoder: 470 * 471 * An encoder for writing ancillary data to the 472 * Vertical Blanking Interval lines of component signals. 473 * 474 * Since: 1.16 475 */ 476 477 typedef struct _GstVideoVBIEncoder GstVideoVBIEncoder; 478 479 GST_VIDEO_API 480 GType gst_video_vbi_encoder_get_type (void); 481 482 GST_VIDEO_API 483 GstVideoVBIEncoder *gst_video_vbi_encoder_new (GstVideoFormat format, guint32 pixel_width); 484 485 GST_VIDEO_API 486 GstVideoVBIEncoder *gst_video_vbi_encoder_copy (const GstVideoVBIEncoder *encoder); 487 488 GST_VIDEO_API 489 void gst_video_vbi_encoder_free (GstVideoVBIEncoder *encoder); 490 491 GST_VIDEO_API 492 gboolean gst_video_vbi_encoder_add_ancillary (GstVideoVBIEncoder *encoder, 493 gboolean composite, 494 guint8 DID, 495 guint8 SDID_block_number, 496 const guint8 *data, 497 guint data_count); 498 499 GST_VIDEO_API 500 void gst_video_vbi_encoder_write_line (GstVideoVBIEncoder *encoder, guint8 *data); 501 502 G_END_DECLS 503 504 #endif /* __GST_VIDEO_ANC_H__ */ 505