documentation: fixed a heap o' typos
[platform/upstream/gstreamer.git] / gst-libs / gst / codecparsers / gstmpeg4parser.h
1 /*
2  * GStreamer
3  * Copyright (C) 2009 Carl-Anton Ingmarsson <ca.ingmarsson@gmail.com>
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Library General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Library General Public License for more details.
14  *
15  * You should have received a copy of the GNU Library General Public
16  * License along with this library; if not, write to the
17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
18  * Boston, MA 02110-1301, USA.
19  */
20
21 #ifndef __GST_MPEG4UTIL_H__
22 #define __GST_MPEG4UTIL_H__
23
24 #include <gst/gst.h>
25 #include <gst/codecparsers/codecparsers-prelude.h>
26
27 G_BEGIN_DECLS
28
29 typedef struct _GstMpeg4VisualObjectSequence    GstMpeg4VisualObjectSequence;
30 typedef struct _GstMpeg4VisualObject            GstMpeg4VisualObject;
31 typedef struct _GstMpeg4VideoObjectLayer        GstMpeg4VideoObjectLayer;
32 typedef struct _GstMpeg4GroupOfVOP              GstMpeg4GroupOfVOP;
33 typedef struct _GstMpeg4VideoObjectPlane        GstMpeg4VideoObjectPlane;
34 typedef struct _GstMpeg4VideoSignalType         GstMpeg4VideoSignalType;
35 typedef struct _GstMpeg4VideoPlaneShortHdr      GstMpeg4VideoPlaneShortHdr;
36 typedef struct _GstMpeg4VideoPacketHdr          GstMpeg4VideoPacketHdr;
37
38 typedef struct _GstMpeg4SpriteTrajectory        GstMpeg4SpriteTrajectory;
39
40 typedef struct _GstMpeg4Packet                  GstMpeg4Packet;
41
42 /**
43  * GstMpeg4StartCode:
44  *
45  * Defines the different startcodes present in the bitstream as
46  * defined in: Table 6-3 — Start code values
47  */
48 typedef enum
49 {
50   GST_MPEG4_VIDEO_OBJ_FIRST      = 0x00,
51   GST_MPEG4_VIDEO_OBJ_LAST       = 0x1f,
52   GST_MPEG4_VIDEO_LAYER_FIRST    = 0x20,
53   GST_MPEG4_VIDEO_LAYER_LAST     = 0x2f,
54   GST_MPEG4_VISUAL_OBJ_SEQ_START = 0xb0,
55   GST_MPEG4_VISUAL_OBJ_SEQ_END   = 0xb1,
56   GST_MPEG4_USER_DATA            = 0xb2,
57   GST_MPEG4_GROUP_OF_VOP         = 0xb3,
58   GST_MPEG4_VIDEO_SESSION_ERR    = 0xb4,
59   GST_MPEG4_VISUAL_OBJ           = 0xb5,
60   GST_MPEG4_VIDEO_OBJ_PLANE      = 0xb6,
61   GST_MPEG4_FBA                  = 0xba,
62   GST_MPEG4_FBA_PLAN             = 0xbb,
63   GST_MPEG4_MESH                 = 0xbc,
64   GST_MPEG4_MESH_PLAN            = 0xbd,
65   GST_MPEG4_STILL_TEXTURE_OBJ    = 0xbe,
66   GST_MPEG4_TEXTURE_SPATIAL      = 0xbf,
67   GST_MPEG4_TEXTURE_SNR_LAYER    = 0xc0,
68   GST_MPEG4_TEXTURE_TILE         = 0xc1,
69   GST_MPEG4_SHAPE_LAYER          = 0xc2,
70   GST_MPEG4_STUFFING             = 0xc3,
71   GST_MPEG4_SYSTEM_FIRST         = 0xc6,
72   GST_MPEG4_SYSTEM_LAST          = 0xff,
73   GST_MPEG4_RESYNC               = 0xfff
74 } GstMpeg4StartCode;
75
76 /**
77  * GstMpeg4VisualObjectType:
78  *
79  * Defines the different visual object types as
80  * defined in: Table 6-5 -- Meaning of visual object type
81  */
82 typedef enum {
83   GST_MPEG4_VIDEO_ID         = 0x01,
84   GST_MPEG4_STILL_TEXTURE_ID = 0x02,
85   GST_MPEG4_STILL_MESH_ID    = 0x03,
86   GST_MPEG4_STILL_FBA_ID     = 0x04,
87   GST_MPEG4_STILL_3D_MESH_ID = 0x05,
88   /*... reserved */
89
90 } GstMpeg4VisualObjectType;
91
92 /**
93  * GstMpeg4AspectRatioInfo:
94  * @GST_MPEG4_SQUARE: 1:1 square
95  * @GST_MPEG4_625_TYPE_4_3: 12:11 (625-type for 4:3 picture)
96  * @GST_MPEG4_525_TYPE_4_3: 10:11 (525-type for 4:3 picture)
97  * @GST_MPEG4_625_TYPE_16_9: 16:11 (625-type stretched for 16:9 picture)
98  * @GST_MPEG4_525_TYPE_16_9: 40:33 (525-type stretched for 16:9 picture)
99  * @GST_MPEG4_EXTENDED_PAR: Extended par
100  *
101  * Defines the different pixel aspect ratios as
102  * defined in: Table 6-12 -- Meaning of pixel aspect ratio
103  */
104 typedef enum {
105   GST_MPEG4_SQUARE        = 0x01,
106   GST_MPEG4_625_TYPE_4_3  = 0x02,
107   GST_MPEG4_525_TYPE_4_3  = 0x03,
108   GST_MPEG4_625_TYPE_16_9 = 0x04,
109   GST_MPEG4_525_TYPE_16_9 = 0x05,
110   GST_MPEG4_EXTENDED_PAR  = 0x0f,
111 } GstMpeg4AspectRatioInfo;
112
113 /**
114  * GstMpeg4ParseResult:
115  * @GST_MPEG4_PARSER_OK: The parsing went well
116  * @GST_MPEG4_PARSER_BROKEN_DATA: The bitstream was broken
117  * @GST_MPEG4_PARSER_NO_PACKET: There was no packet in the buffer
118  * @GST_MPEG4_PARSER_NO_PACKET_END: There was no packet end in the buffer
119  * @GST_MPEG4_PARSER_NO_PACKET_ERROR: An error accured durint the parsing
120  *
121  * Result type of any parsing function.
122  */
123 typedef enum {
124   GST_MPEG4_PARSER_OK,
125   GST_MPEG4_PARSER_BROKEN_DATA,
126   GST_MPEG4_PARSER_NO_PACKET,
127   GST_MPEG4_PARSER_NO_PACKET_END,
128   GST_MPEG4_PARSER_ERROR,
129 } GstMpeg4ParseResult;
130
131 /**
132  * GstMpeg4VideoObjectCodingType:
133  * @GST_MPEG4_I_VOP: intra-coded (I)
134  * @GST_MPEG4_P_VOP: predictive-coded (P)
135  * @GST_MPEG4_B_VOP: bidirectionally-predictive-coded (B)
136  * @GST_MPEG4_S_VOP: sprite (S)
137  *
138  * The vop coding types as defined in:
139  * Table 6-20 -- Meaning of vop_coding_type
140  */
141 typedef enum {
142   GST_MPEG4_I_VOP = 0x0,
143   GST_MPEG4_P_VOP = 0x1,
144   GST_MPEG4_B_VOP = 0x2,
145   GST_MPEG4_S_VOP = 0x3
146 } GstMpeg4VideoObjectCodingType;
147
148 /**
149  * GstMpeg4ChromaFormat:
150  *
151  * The chroma format in use as
152  * defined in: Table 6-13 -- Meaning of chroma_format
153  */
154 typedef enum {
155   /* Other value are reserved */
156   GST_MPEG4_CHROMA_4_2_0 = 0x01
157 } GstMpeg4ChromaFormat;
158
159 /**
160  * GstMpeg4VideoObjectLayerShape:
161  *
162  * The different video object layer shapes as defined in:
163  * Table 6-16 — Video Object Layer shape type
164  */
165 typedef enum {
166   GST_MPEG4_RECTANGULAR,
167   GST_MPEG4_BINARY,
168   GST_MPEG4_BINARY_ONLY,
169   GST_MPEG4_GRAYSCALE
170 } GstMpeg4VideoObjectLayerShape;
171
172 /**
173  * GstMpeg4SpriteEnable:
174  *
175  * Indicates the usage of static sprite coding
176  * or global motion compensation (GMC) as defined in:
177  * Table V2 - 2 -- Meaning of sprite_enable codewords
178  */
179 typedef enum {
180   GST_MPEG4_SPRITE_UNUSED,
181   GST_MPEG4_SPRITE_STATIC,
182   GST_MPEG4_SPRITE_GMG
183 } GstMpeg4SpriteEnable;
184
185 /**
186  * GstMpeg4Profile:
187  *
188  * Different defined profiles as defined in:
189  * 9- Profiles and levels
190  *
191  * It is computed using:
192  * Table G.1 — FLC table for profile_and_level_indication
193  */
194 typedef enum {
195   GST_MPEG4_PROFILE_CORE,
196   GST_MPEG4_PROFILE_MAIN,
197   GST_MPEG4_PROFILE_N_BIT,
198   GST_MPEG4_PROFILE_SIMPLE,
199   GST_MPEG4_PROFILE_HYBRID,
200   GST_MPEG4_PROFILE_RESERVED,
201   GST_MPEG4_PROFILE_SIMPLE_FBA,
202   GST_MPEG4_PROFILE_CORE_STUDIO,
203   GST_MPEG4_PROFILE_SIMPLE_STUDIO,
204   GST_MPEG4_PROFILE_CORE_SCALABLE,
205   GST_MPEG4_PROFILE_ADVANCED_CORE,
206   GST_MPEG4_PROFILE_ADVANCED_SIMPLE,
207   GST_MPEG4_PROFILE_SIMPLE_SCALABLE,
208   GST_MPEG4_PROFILE_SCALABLE_TEXTURE,
209   GST_MPEG4_PROFILE_SIMPLE_FACE_ANIMATION,
210   GST_MPEG4_PROFILE_BASIC_ANIMATED_TEXTURE,
211   GST_MPEG4_PROFILE_ADVANCED_REALTIME_SIMPLE,
212   GST_MPEG4_PROFILE_ADVANCED_SCALABLE_TEXTURE,
213   GST_MPEG4_PROFILE_FINE_GRANULARITY_SCALABLE,
214   GST_MPEG4_PROFILE_ADVANCED_CODING_EFFICIENCY
215 } GstMpeg4Profile;
216
217 /**
218  * GstMpeg4Level:
219  *
220  * Different levels as defined in:
221  * 9- Profiles and levels
222  *
223  * It is computed using:
224  * Table G.1 — FLC table for profile_and_level_indication
225  */
226 typedef enum {
227   GST_MPEG4_LEVEL0,
228   GST_MPEG4_LEVEL1,
229   GST_MPEG4_LEVEL2,
230   GST_MPEG4_LEVEL3,
231   GST_MPEG4_LEVEL3b,
232   GST_MPEG4_LEVEL4,
233   GST_MPEG4_LEVEL5,
234   GST_MPEG4_LEVEL_RESERVED
235 } GstMpeg4Level;
236
237 /**
238  * GstMpeg4VisualObjectSequence:
239  *
240  * The visual object sequence structure as defined in:
241  * 6.2.2 Visual Object Sequence and Visual Object
242  */
243 struct _GstMpeg4VisualObjectSequence {
244   guint8 profile_and_level_indication;
245
246   /* Computed according to:
247    * Table G.1 — FLC table for profile_and_level_indication */
248   GstMpeg4Level level;
249   GstMpeg4Profile profile;
250 };
251
252 /**
253  * GstMpeg4VisualObject:
254  *
255  * The visual object structure as defined in:
256  * 6.2.2 Visual Object Sequence and Visual Object
257  */
258 struct _GstMpeg4VisualObject {
259   guint8 is_identifier;
260   /* If is_identifier */
261   guint8 verid;
262   guint8 priority;
263
264   GstMpeg4VisualObjectType type;
265 };
266
267 /**
268  * GstMpeg4VideoSignalType:
269  *
270  * The video signal type structure as defined in:
271  * 6.2.2 Visual Object Sequence and Visual Object.
272  */
273 struct _GstMpeg4VideoSignalType {
274   guint8 type;
275
276   guint8 format;
277   guint8 range;
278   guint8 color_description;
279   guint8 color_primaries;
280   guint8 transfer_characteristics;
281   guint8 matrix_coefficients;
282 };
283
284 /**
285  * GstMpeg4VideoPlaneShortHdr:
286  *
287  * The video plane short header structure as defined in:
288  * 6.2.5.2 Video Plane with Short Header
289  */
290 struct _GstMpeg4VideoPlaneShortHdr {
291   guint8 temporal_reference;
292   guint8 split_screen_indicator;
293   guint8 document_camera_indicator;
294   guint8 full_picture_freeze_release;
295   guint8 source_format;
296   guint8 picture_coding_type;
297   guint8 vop_quant;
298   guint8 pei;
299   guint8 psupp;
300
301   /*  Gob layer specific fields */
302   guint8 gob_header_empty;
303   guint8 gob_number;
304   guint8 gob_frame_id;
305   guint8 quant_scale;
306
307   /* Computed
308    * If all the values are set to 0, then it is reserved
309    * Table 6-25 -- Parameters Defined by source_format Field
310    */
311   guint16 vop_width;
312   guint16 vop_height;
313   guint16 num_macroblocks_in_gob;
314   guint8 num_gobs_in_vop;
315
316   /* The size in bits */
317   guint size;
318 };
319
320 /**
321  * GstMpeg4VideoObjectLayer:
322  *
323  * The video object layer structure as defined in:
324  * 6.2.3 Video Object Layer
325  */
326 struct _GstMpeg4VideoObjectLayer {
327   guint8 random_accessible_vol;
328   guint8 video_object_type_indication;
329
330   guint8 is_object_layer_identifier;
331   /* if is_object_layer_identifier */
332   guint8 verid;
333   guint8 priority;
334
335   GstMpeg4AspectRatioInfo aspect_ratio_info;
336   guint8 par_width;
337   guint8 par_height;
338
339   guint8 control_parameters;
340   /* if control_parameters */
341   GstMpeg4ChromaFormat chroma_format;
342   guint8 low_delay;
343   guint8 vbv_parameters;
344   /* if vbv_parameters */
345   guint16 first_half_bitrate;
346   guint16 latter_half_bitrate;
347   guint16 first_half_vbv_buffer_size;
348   guint16 latter_half_vbv_buffer_size;
349   guint16 first_half_vbv_occupancy;
350   guint16 latter_half_vbv_occupancy;
351
352   /* Computed values */
353   guint32 bit_rate;
354   guint32 vbv_buffer_size;
355
356   GstMpeg4VideoObjectLayerShape shape;
357   /* if shape == GST_MPEG4_GRAYSCALE && verid =! 1 */
358   guint8 shape_extension;
359
360   guint16 vop_time_increment_resolution;
361   guint8 vop_time_increment_bits;
362   guint8 fixed_vop_rate;
363   /* if fixed_vop_rate */
364   guint16 fixed_vop_time_increment;
365
366   guint16 width;
367   guint16 height;
368   guint8 interlaced;
369   guint8 obmc_disable;
370
371   GstMpeg4SpriteEnable sprite_enable;
372   /* if vol->sprite_enable == SPRITE_GMG or SPRITE_STATIC*/
373   /* if vol->sprite_enable != GST_MPEG4_SPRITE_GMG */
374   guint16 sprite_width;
375   guint16 sprite_height;
376   guint16 sprite_left_coordinate;
377   guint16 sprite_top_coordinate;
378
379   guint8 no_of_sprite_warping_points;
380   guint8 sprite_warping_accuracy;
381   guint8 sprite_brightness_change;
382   /* if vol->sprite_enable != GST_MPEG4_SPRITE_GMG */
383   guint8 low_latency_sprite_enable;
384
385   /* if shape != GST_MPEG4_RECTANGULAR */
386   guint8 sadct_disable;
387
388   guint8 not_8_bit;
389
390   /* if no_8_bit */
391   guint8 quant_precision;
392   guint8 bits_per_pixel;
393
394   /* if shape == GRAYSCALE */
395   guint8 no_gray_quant_update;
396   guint8 composition_method;
397   guint8 linear_composition;
398
399   guint8 quant_type;
400   /* if quant_type */
401   guint8 load_intra_quant_mat;
402   guint8 intra_quant_mat[64];
403   guint8 load_non_intra_quant_mat;
404   guint8 non_intra_quant_mat[64];
405
406   guint8 quarter_sample;
407   guint8 complexity_estimation_disable;
408   guint8 resync_marker_disable;
409   guint8 data_partitioned;
410   guint8 reversible_vlc;
411   guint8 newpred_enable;
412   guint8 reduced_resolution_vop_enable;
413   guint8 scalability;
414   guint8 enhancement_type;
415
416   GstMpeg4VideoPlaneShortHdr short_hdr;
417 };
418
419 /**
420  * GstMpeg4SpriteTrajectory:
421  *
422  * The sprite trajectory structure as defined in:
423  * 7.8.4 Sprite reference point decoding and
424  * 6.2.5.4 Sprite coding
425  */
426 struct _GstMpeg4SpriteTrajectory {
427   guint16 vop_ref_points[63]; /* Defined as "du" in 6.2.5.4 */
428   guint16 sprite_ref_points[63]; /* Defined as "dv" in 6.2.5.4 */
429 };
430
431 /**
432  * GstMpeg4GroupOfVOP:
433  *
434  * The group of video object plane structure as defined in:
435  * 6.2.4 Group of Video Object Plane
436  */
437 struct _GstMpeg4GroupOfVOP {
438   guint8 hours;
439   guint8 minutes;
440   guint8 seconds;
441
442   guint8 closed;
443   guint8 broken_link;
444 };
445
446 /**
447  * GstMpeg4VideoObjectPlane:
448  *
449  * The Video object plane structure as defined in:
450  * 6.2.5 Video Object Plane and Video Plane with Short Header
451  */
452 struct _GstMpeg4VideoObjectPlane {
453   GstMpeg4VideoObjectCodingType coding_type;
454
455   guint8  modulo_time_base;
456   guint16 time_increment;
457
458   guint8  coded;
459   /* if newpred_enable */
460   guint16 id;
461   guint8  id_for_prediction_indication;
462   guint16 id_for_prediction;
463
464   guint16 width;
465   guint16 height;
466   guint16 horizontal_mc_spatial_ref;
467   guint16 vertical_mc_spatial_ref;
468
469   guint8  rounding_type;
470   /*if vol->shape != GST_MPEG4_RECTANGULAR */
471   guint8  background_composition;
472   guint8  change_conv_ratio_disable;
473   guint8  constant_alpha;
474   guint8  constant_alpha_value;
475   guint8  reduced_resolution;
476
477   guint8  intra_dc_vlc_thr;
478
479
480   guint8  top_field_first;
481   guint8  alternate_vertical_scan_flag;
482
483   guint16 quant;
484
485   guint8  fcode_forward;
486   guint8  fcode_backward;
487
488   guint8  shape_coding_type;
489   guint8  load_backward_shape;
490   guint8  ref_select_code;
491
492   /* Computed macroblock information */
493   guint16 mb_height;
494   guint16 mb_width;
495   guint mb_num;
496
497   /* The size of the header */
498   guint    size;
499 };
500
501 /**
502  * GstMpeg4VideoPacketHdr:
503  * @size: Size of the header in bit.
504  *
505  * The video packet header structure as defined in:
506  * 6.2.5.2 Video Plane with Short Header
507  */
508 struct _GstMpeg4VideoPacketHdr {
509   guint8  header_extension_code;
510   guint16 macroblock_number;
511   guint16 quant_scale;
512   guint   size;
513 };
514
515 /**
516  * GstMpeg4Packet:
517  * @type: the type of the packet that start at @offset
518  * @data: the data containing packet starting at @offset
519  * @offset: offset of the start of the packet (without the 3 bytes startcode), but
520  * including the #GstMpeg4StartCode byte.
521  * @size: The size in bytes of the packet or %G_MAXUINT if the end wasn't found.
522  * @marker_size: The size in bit of the resync marker.
523  *
524  * A structure that contains the type of a packet, its offset and its size
525  */
526 struct _GstMpeg4Packet
527 {
528   const guint8     *data;
529   guint             offset;
530   gsize             size;
531   guint             marker_size;
532
533   GstMpeg4StartCode type;
534 };
535
536 GST_CODEC_PARSERS_API
537 GstMpeg4ParseResult gst_h263_parse       (GstMpeg4Packet * packet,
538                                           const guint8 * data, guint offset,
539                                           gsize size);
540
541
542 GST_CODEC_PARSERS_API
543 GstMpeg4ParseResult gst_mpeg4_parse      (GstMpeg4Packet * packet,
544                                           gboolean skip_user_data,
545                                           GstMpeg4VideoObjectPlane *vop,
546                                           const guint8 * data, guint offset,
547                                           gsize size);
548 GST_CODEC_PARSERS_API
549 GstMpeg4ParseResult
550 gst_mpeg4_parse_video_object_plane       (GstMpeg4VideoObjectPlane *vop,
551                                           GstMpeg4SpriteTrajectory *sprite_trajectory,
552                                           GstMpeg4VideoObjectLayer *vol,
553                                           const guint8 * data,
554                                           gsize size);
555 GST_CODEC_PARSERS_API
556 GstMpeg4ParseResult
557 gst_mpeg4_parse_group_of_vop             (GstMpeg4GroupOfVOP *gov,
558                                           const guint8 * data, gsize size);
559 GST_CODEC_PARSERS_API
560 GstMpeg4ParseResult
561 gst_mpeg4_parse_video_object_layer       (GstMpeg4VideoObjectLayer *vol,
562                                           GstMpeg4VisualObject *vo,
563                                           const guint8 * data, gsize size);
564 GST_CODEC_PARSERS_API
565 GstMpeg4ParseResult
566 gst_mpeg4_parse_visual_object            (GstMpeg4VisualObject *vo,
567                                           GstMpeg4VideoSignalType *signal_type,
568                                           const guint8 * data, gsize size);
569 GST_CODEC_PARSERS_API
570 GstMpeg4ParseResult
571 gst_mpeg4_parse_visual_object_sequence   (GstMpeg4VisualObjectSequence *vos,
572                                           const guint8 * data, gsize size);
573 GST_CODEC_PARSERS_API
574 GstMpeg4ParseResult
575 gst_mpeg4_parse_video_plane_short_header (GstMpeg4VideoPlaneShortHdr * shorthdr,
576                                           const guint8 * data, gsize size);
577 GST_CODEC_PARSERS_API
578 GstMpeg4ParseResult
579 gst_mpeg4_parse_video_packet_header      (GstMpeg4VideoPacketHdr * videopackethdr,
580                                           GstMpeg4VideoObjectLayer * vol,
581                                           GstMpeg4VideoObjectPlane * vop,
582                                           GstMpeg4SpriteTrajectory * sprite_trajectory,
583                                           const guint8 * data, gsize size);
584
585 G_END_DECLS
586
587 #endif /* __GST_MPEG4UTIL_H__ */