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
27G_BEGIN_DECLS
28
29typedef 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 */
47struct _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 */
63typedef 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 */
100typedef 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 */
172typedef 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 */
204typedef 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 */
234typedef struct {
235 GstMeta meta;
236
237 guint8 field;
238 GstVideoAFDSpec spec;
239 GstVideoAFDValue afd;
240} GstVideoAFDMeta;
241
242GST_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
245GST_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
264GST_VIDEO_API
265GstVideoAFDMeta *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 */
297typedef struct {
298 GstMeta meta;
299
300 guint8 field;
301 gboolean is_letterbox;
302 guint bar_data1;
303 guint bar_data2;
304} GstVideoBarMeta;
305
306GST_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
309GST_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
325GST_VIDEO_API
326GstVideoBarMeta *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 */
359typedef 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
367GST_VIDEO_API
368GstVideoCaptionType
369gst_video_caption_type_from_caps (const GstCaps *caps);
370
371GST_VIDEO_API
372GstCaps *
373gst_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 */
386typedef struct {
387 GstMeta meta;
388
389 GstVideoCaptionType caption_type;
390 guint8 *data;
391 gsize size;
392} GstVideoCaptionMeta;
393
394GST_VIDEO_API
395GType gst_video_caption_meta_api_get_type (void);
396#define GST_VIDEO_CAPTION_META_API_TYPE (gst_video_caption_meta_api_get_type())
397
398GST_VIDEO_API
399const 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
416GST_VIDEO_API
417GstVideoCaptionMeta *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
431typedef struct _GstVideoVBIParser GstVideoVBIParser;
432
433GST_VIDEO_API
434GType 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 */
446typedef 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
452GST_VIDEO_API
453GstVideoVBIParserResult gst_video_vbi_parser_get_ancillary(GstVideoVBIParser *parser,
454 GstVideoAncillary *anc);
455
456GST_VIDEO_API
457GstVideoVBIParser *gst_video_vbi_parser_new (GstVideoFormat format, guint32 pixel_width);
458
459GST_VIDEO_API
460GstVideoVBIParser *gst_video_vbi_parser_copy (const GstVideoVBIParser *parser);
461
462GST_VIDEO_API
463void gst_video_vbi_parser_free (GstVideoVBIParser *parser);
464
465GST_VIDEO_API
466void 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
477typedef struct _GstVideoVBIEncoder GstVideoVBIEncoder;
478
479GST_VIDEO_API
480GType gst_video_vbi_encoder_get_type (void);
481
482GST_VIDEO_API
483GstVideoVBIEncoder *gst_video_vbi_encoder_new (GstVideoFormat format, guint32 pixel_width);
484
485GST_VIDEO_API
486GstVideoVBIEncoder *gst_video_vbi_encoder_copy (const GstVideoVBIEncoder *encoder);
487
488GST_VIDEO_API
489void gst_video_vbi_encoder_free (GstVideoVBIEncoder *encoder);
490
491GST_VIDEO_API
492gboolean 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
499GST_VIDEO_API
500void gst_video_vbi_encoder_write_line (GstVideoVBIEncoder *encoder, guint8 *data);
501
502G_END_DECLS
503
504#endif /* __GST_VIDEO_ANC_H__ */
505

source code of include/gstreamer-1.0/gst/video/video-anc.h