1 /* GStreamer 2 * Copyright (C) 2019 Seungha Yang <seungha.yang@navercorp.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_H264_DECODER_H__ 21 #define __GST_H264_DECODER_H__ 22 23 #include <gst/codecs/codecs-prelude.h> 24 25 #include <gst/video/video.h> 26 #include <gst/codecparsers/gsth264parser.h> 27 #include <gst/codecs/gsth264picture.h> 28 29 G_BEGIN_DECLS 30 31 #define GST_TYPE_H264_DECODER (gst_h264_decoder_get_type()) 32 #define GST_H264_DECODER(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_H264_DECODER,GstH264Decoder)) 33 #define GST_H264_DECODER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_H264_DECODER,GstH264DecoderClass)) 34 #define GST_H264_DECODER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj),GST_TYPE_H264_DECODER,GstH264DecoderClass)) 35 #define GST_IS_H264_DECODER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_H264_DECODER)) 36 #define GST_IS_H264_DECODER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_H264_DECODER)) 37 #define GST_H264_DECODER_CAST(obj) ((GstH264Decoder*)obj) 38 39 /** 40 * GstH264DecoderCompliance: 41 * @GST_H264_DECODER_COMPLIANCE_AUTO: The decoder behavior is 42 * automatically choosen. 43 * @GST_H264_DECODER_COMPLIANCE_STRICT: The decoder behavior strictly 44 * conforms to the SPEC. All the decoder behaviors conform to the 45 * SPEC, not including any nonstandard behavior which is not 46 * mentioned in the SPEC. 47 * @GST_H264_DECODER_COMPLIANCE_NORMAL: The decoder behavior normally 48 * conforms to the SPEC. Most behaviors conform to the SPEC but 49 * including some nonstandard features which are widely used or 50 * often used in the industry practice. This meets the request of 51 * real streams and usages, but may not 100% conform to the 52 * SPEC. It has very low risk. E.g., we will output pictures 53 * without waiting DPB being full for the lower latency, which may 54 * cause B frame disorder when there are reference frames with 55 * smaller POC after it in decoder order. And the baseline profile 56 * may be mapped to the constrained-baseline profile, but it may 57 * have problems when a real baseline stream comes with FMO or 58 * ASO. 59 * @GST_H264_DECODER_COMPLIANCE_FLEXIBLE: The decoder behavior 60 * flexibly conforms to the SPEC. It uses the nonstandard features 61 * more aggressively in order to get better performance(for 62 * example, lower latency). It may change the result of the 63 * decoder and should be used carefully. Besides including all 64 * risks in *normal* mode, it has more risks, such as frames 65 * disorder when reference frames POC decrease in decoder order. 66 * 67 * Since: 1.20 68 */ 69 typedef enum 70 { 71 GST_H264_DECODER_COMPLIANCE_AUTO, 72 GST_H264_DECODER_COMPLIANCE_STRICT, 73 GST_H264_DECODER_COMPLIANCE_NORMAL, 74 GST_H264_DECODER_COMPLIANCE_FLEXIBLE 75 } GstH264DecoderCompliance; 76 77 #define GST_TYPE_H264_DECODER_COMPLIANCE (gst_h264_decoder_compliance_get_type()) 78 79 GST_CODECS_API 80 GType gst_h264_decoder_compliance_get_type (void); 81 82 typedef struct _GstH264Decoder GstH264Decoder; 83 typedef struct _GstH264DecoderClass GstH264DecoderClass; 84 typedef struct _GstH264DecoderPrivate GstH264DecoderPrivate; 85 86 /** 87 * GstH264Decoder: 88 * 89 * The opaque #GstH264Decoder data structure. 90 */ 91 struct _GstH264Decoder 92 { 93 /*< private >*/ 94 GstVideoDecoder parent; 95 96 /*< protected >*/ 97 GstVideoCodecState * input_state; 98 99 /*< private >*/ 100 GstH264DecoderPrivate *priv; 101 gpointer padding[GST_PADDING_LARGE]; 102 }; 103 104 /** 105 * GstH264DecoderClass: 106 * 107 * The opaque #GstH264DecoderClass data structure. 108 */ 109 struct _GstH264DecoderClass 110 { 111 /*< private >*/ 112 GstVideoDecoderClass parent_class; 113 114 /** 115 * GstH264DecoderClass::new_sequence: 116 * @decoder: a #GstH264Decoder 117 * @sps: a #GstH264SPS 118 * @max_dpb_size: the size of dpb including preferred output delay 119 * by subclass reported via get_preferred_output_delay method. 120 * 121 * Notifies subclass of SPS update 122 */ 123 GstFlowReturn (*new_sequence) (GstH264Decoder * decoder, 124 const GstH264SPS * sps, 125 gint max_dpb_size); 126 127 /** 128 * GstH264DecoderClass::new_picture: 129 * @decoder: a #GstH264Decoder 130 * @frame: (transfer none): a #GstVideoCodecFrame 131 * @picture: (transfer none): a #GstH264Picture 132 * 133 * Optional. Called whenever new #GstH264Picture is created. 134 * Subclass can set implementation specific user data 135 * on the #GstH264Picture via gst_h264_picture_set_user_data() 136 */ 137 GstFlowReturn (*new_picture) (GstH264Decoder * decoder, 138 GstVideoCodecFrame * frame, 139 GstH264Picture * picture); 140 141 /** 142 * GstH264DecoderClass::new_field_picture: 143 * @decoder: a #GstH264Decoder 144 * @first_field: (transfer none): the first field #GstH264Picture already decoded 145 * @second_field: (transfer none): a #GstH264Picture for the second field 146 * 147 * Called when a new field picture is created for interlaced field picture. 148 * Subclass can attach implementation specific user data on @second_field via 149 * gst_h264_picture_set_user_data() 150 * 151 * Since: 1.20 152 */ 153 GstFlowReturn (*new_field_picture) (GstH264Decoder * decoder, 154 const GstH264Picture * first_field, 155 GstH264Picture * second_field); 156 157 /** 158 * GstH264DecoderClass::start_picture: 159 * @decoder: a #GstH264Decoder 160 * @picture: (transfer none): a #GstH264Picture 161 * @slice: (transfer none): a #GstH264Slice 162 * @dpb: (transfer none): a #GstH264Dpb 163 * 164 * Optional. Called per one #GstH264Picture to notify subclass to prepare 165 * decoding process for the #GstH264Picture 166 */ 167 GstFlowReturn (*start_picture) (GstH264Decoder * decoder, 168 GstH264Picture * picture, 169 GstH264Slice * slice, 170 GstH264Dpb * dpb); 171 172 /** 173 * GstH264DecoderClass::decode_slice: 174 * @decoder: a #GstH264Decoder 175 * @picture: (transfer none): a #GstH264Picture 176 * @slice: (transfer none): a #GstH264Slice 177 * @ref_pic_list0: (element-type GstH264Picture) (transfer none): 178 * an array of #GstH264Picture pointers 179 * @ref_pic_list1: (element-type GstH264Picture) (transfer none): 180 * an array of #GstH264Picture pointers 181 * 182 * Provides per slice data with parsed slice header and required raw bitstream 183 * for subclass to decode it. If gst_h264_decoder_set_process_ref_pic_lists() 184 * is called with %TRUE by the subclass, @ref_pic_list0 and @ref_pic_list1 185 * are non-%NULL. 186 * In case of interlaced stream, @ref_pic_list0 and @ref_pic_list1 will 187 * contain only the first field of complementary reference field pair 188 * if currently being decoded picture is a frame picture. Subclasses might 189 * need to retrive the other field (i.e., the second field) of the picture 190 * if needed. 191 */ 192 GstFlowReturn (*decode_slice) (GstH264Decoder * decoder, 193 GstH264Picture * picture, 194 GstH264Slice * slice, 195 GArray * ref_pic_list0, 196 GArray * ref_pic_list1); 197 198 /** 199 * GstH264DecoderClass::end_picture: 200 * @decoder: a #GstH264Decoder 201 * @picture: (transfer none): a #GstH264Picture 202 * 203 * Optional. Called per one #GstH264Picture to notify subclass to finish 204 * decoding process for the #GstH264Picture 205 */ 206 GstFlowReturn (*end_picture) (GstH264Decoder * decoder, 207 GstH264Picture * picture); 208 209 /** 210 * GstH264DecoderClass::output_picture: 211 * @decoder: a #GstH264Decoder 212 * @frame: (transfer full): a #GstVideoCodecFrame 213 * @picture: (transfer full): a #GstH264Picture 214 * 215 * Called with a #GstH264Picture which is required to be outputted. 216 * The #GstVideoCodecFrame must be consumed by subclass. 217 */ 218 GstFlowReturn (*output_picture) (GstH264Decoder * decoder, 219 GstVideoCodecFrame * frame, 220 GstH264Picture * picture); 221 222 /** 223 * GstH264DecoderClass::get_preferred_output_delay: 224 * @decoder: a #GstH264Decoder 225 * @live: whether upstream is live or not 226 * 227 * Optional. Called by baseclass to query whether delaying output is 228 * preferred by subclass or not. 229 * 230 * Returns: the number of perferred delayed output frame 231 * 232 * Since: 1.20 233 */ 234 guint (*get_preferred_output_delay) (GstH264Decoder * decoder, 235 gboolean live); 236 237 /*< private >*/ 238 gpointer padding[GST_PADDING_LARGE]; 239 }; 240 241 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstH264Decoder, gst_object_unref) 242 243 GST_CODECS_API 244 GType gst_h264_decoder_get_type (void); 245 246 GST_CODECS_API 247 void gst_h264_decoder_set_process_ref_pic_lists (GstH264Decoder * decoder, 248 gboolean process); 249 250 GST_CODECS_API 251 GstH264Picture * gst_h264_decoder_get_picture (GstH264Decoder * decoder, 252 guint32 system_frame_number); 253 254 G_END_DECLS 255 256 #endif /* __GST_H264_DECODER_H__ */ 257