1 /* 2 * GPAC - Multimedia Framework C SDK 3 * 4 * Authors: Jean Le Feuvre 5 * Copyright (c) Telecom ParisTech 2000-2012 6 * All rights reserved 7 * 8 * This file is part of GPAC / modules interfaces 9 * 10 * GPAC is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU Lesser General Public License as published by 12 * the Free Software Foundation; either version 2, or (at your option) 13 * any later version. 14 * 15 * GPAC is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License for more details. 19 * 20 * You should have received a copy of the GNU Lesser General Public 21 * License along with this library; see the file COPYING. If not, write to 22 * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 23 * 24 */ 25 26 27 28 #ifndef _GF_MODULE_CODEC_H_ 29 #define _GF_MODULE_CODEC_H_ 30 31 32 #include <gpac/module.h> 33 #include <gpac/mpeg4_odf.h> 34 #include <gpac/color.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /*multimedia processing levels*/ 41 enum 42 { 43 /*normal, full processing*/ 44 GF_CODEC_LEVEL_NORMAL, 45 /*codec is late, should scale down processing*/ 46 GF_CODEC_LEVEL_LATE, 47 /*codec is very late, should turn off post-processing, even drop*/ 48 GF_CODEC_LEVEL_VERY_LATE, 49 /*input frames are already late before decoding*/ 50 GF_CODEC_LEVEL_DROP, 51 /*this is a special level indicating that a seek is happening (decode but no dispatch) 52 it is set dynamically*/ 53 GF_CODEC_LEVEL_SEEK 54 }; 55 56 57 /*codec resilience type*/ 58 enum 59 { 60 GF_CODEC_NOT_RESILIENT=0, 61 GF_CODEC_RESILIENT_ALWAYS=1, 62 GF_CODEC_RESILIENT_AFTER_FIRST_RAP=2 63 }; 64 65 /*Define codec matrix*/ 66 typedef struct __matrix GF_CodecMatrix; 67 68 /*the structure for capabilities*/ 69 typedef struct 70 { 71 /*cap code cf below*/ 72 u16 CapCode; 73 union { 74 u32 valueInt; 75 Float valueFloat; 76 Bool valueBool; 77 } cap; 78 } GF_CodecCapability; 79 80 81 /* 82 all codecs capabilities 83 */ 84 85 enum 86 { 87 /*size of a single composition unit */ 88 GF_CODEC_OUTPUT_SIZE = 0x01, 89 /*resilency: if packets are lost within an AU, resilience means the AU won't be discarded and the codec 90 will try to decode 91 0: not resilient 92 1: resilient 93 2: resilient after first rap 94 */ 95 GF_CODEC_RESILIENT, 96 /*critical level of composition memory - if below, media management for the object */ 97 GF_CODEC_BUFFER_MIN, 98 /*maximum size in CU of composition memory */ 99 GF_CODEC_BUFFER_MAX, 100 /*flags that all AUs should be discarded till next RAP (needed in case RAPs are not carried by the transport 101 protocol */ 102 GF_CODEC_WAIT_RAP, 103 /*number of padding bytes needed - if the decoder needs padding input cannot be pulled and data is duplicated*/ 104 GF_CODEC_PADDING_BYTES, 105 /*codecs can be threaded at will - by default a single thread is used for all decoders and priority is handled 106 by the app, but a codec can configure itself to run in a dedicated thread*/ 107 GF_CODEC_WANTS_THREAD, 108 109 /*video width and height and horizontal pitch (in YV12 we assume half Y pitch for U and V planes) */ 110 GF_CODEC_WIDTH, 111 GF_CODEC_HEIGHT, 112 GF_CODEC_STRIDE, 113 GF_CODEC_FPS, 114 GF_CODEC_FLIP, 115 /*Pixel Aspect Ratio, expressed as (par.num<<16) | par.den*/ 116 GF_CODEC_PAR, 117 /*video color mode - color modes are defined in constants.h*/ 118 GF_CODEC_PIXEL_FORMAT, 119 /*signal decoder performs frame re-ordering in temporal scalability*/ 120 GF_CODEC_REORDER, 121 /*signal decoder can safely handle CTS when outputing a picture. If not supported by the 122 decoder, the terminal will automatically handle CTS adjustments*/ 123 GF_CODEC_TRUSTED_CTS, 124 125 /*set cap only, indicate smax bpp of display*/ 126 GF_CODEC_DISPLAY_BPP, 127 128 /*Audio sample rate*/ 129 GF_CODEC_SAMPLERATE, 130 /*Audio num channels*/ 131 GF_CODEC_NB_CHAN, 132 /*Audio bps*/ 133 GF_CODEC_BITS_PER_SAMPLE, 134 /*audio frame format*/ 135 GF_CODEC_CHANNEL_CONFIG, 136 /*this is only used for audio in case transport mapping relies on sampleRate (RTP) 137 gets the CU duration in samplerate unit (type: int) */ 138 GF_CODEC_CU_DURATION, 139 /*queries whether data is RAW (directly dispatched to CompositionMemory) or not*/ 140 GF_CODEC_RAW_MEDIA, 141 /*queries or set support for usage of raw YUV from decoder memory - used for video codecs only, single frame pending*/ 142 GF_CODEC_RAW_MEMORY, 143 /*queries or set support for usage of decoded frame from decoder memory - used for video codecs only, multiple frames shall be supported*/ 144 GF_CODEC_FRAME_OUTPUT, 145 /*This is only called on scene decoders to signal that potential overlay scene should be 146 showed (cap.valueINT=1) or hidden (cap.valueINT=0). Currently only used with SetCap*/ 147 GF_CODEC_SHOW_SCENE, 148 /*This is only called on scene decoders, GetCap only. If the decoder may continue modifying the scene once the last AU is received, 149 it must set cap.valueINT to 1 (typically, text stream decoder will hold the scene for a given duration 150 after the last AU). Otherwise the decoder will be stopped and ask to remove any extra scene being displayed*/ 151 GF_CODEC_MEDIA_NOT_OVER, 152 153 /*switches up (1), max (2), down (0) or min (-1) media quality for scalable coding. */ 154 GF_CODEC_MEDIA_SWITCH_QUALITY, 155 GF_CODEC_MEDIA_LAYER_DETACH, 156 157 //notifies the codec all streams have been attached for the current time and that it may start init 158 //this is require for L-HEVC+AVC 159 GF_CODEC_CAN_INIT, 160 /*special cap indicating the codec should abort processing as soon as possible because it is about to be destroyed*/ 161 GF_CODEC_ABORT, 162 163 /*sets current hitpoint on the video texture. hitpoint is an integer (valueInt) containing: 164 the X coord in upper 16 bits, ranging from 0 to 0xFFFF 165 the Y coord in lower 16 bits, ranging from 0 to 0xFFFF 166 x,y are in normalized texture coordinates (0,0 bottom left, 1,1 top right) 167 return GF_NOT_SUPPORTED if your codec does'nt handle this 168 */ 169 GF_CODEC_INTERACT_COORDS, 170 GF_CODEC_NBVIEWS, 171 GF_CODEC_NBLAYERS, 172 GF_CODEC_FORCE_ANNEXB, 173 }; 174 175 176 enum 177 { 178 /*stream format is NOT supported by this codec*/ 179 GF_CODEC_NOT_SUPPORTED = 0, 180 /*stream type (eg audio, video) is supported by this codec*/ 181 GF_CODEC_STREAM_TYPE_SUPPORTED = 1, 182 GF_CODEC_PROFILE_NOT_SUPPORTED = 2, 183 /*stream format may be (partially) supported by this codec*/ 184 GF_CODEC_MAYBE_SUPPORTED = 127, 185 /*stream format is supported by this codec*/ 186 GF_CODEC_SUPPORTED = 255, 187 }; 188 189 /* Generic interface used by both media decoders and scene decoders 190 @AttachStream: 191 Add a Stream to the codec. If DependsOnESID is NULL, the stream is a base layer 192 UpStream means that the decoder should send feedback on this channel. 193 WARNING: Feedback format is not standardized by MPEG 194 the same API is used for both encoder and decoder (decSpecInfo is ignored 195 for an encoder) 196 @DetachStream: 197 Remove stream 198 @GetCapabilities: 199 Get the desired capability given its code 200 @SetCapabilities 201 Set the desired capability given its code if possible 202 if the codec does not support the request capability, return GF_NOT_SUPPORTED 203 @CanHandleStream 204 Can module handle this codec? Return one of GF_CODEC_NOT_SUPPORTED, GF_CODEC_MAYBE_SUPPORTED or GF_CODEC_SUPPORTED 205 esd is provided for more advanced inspection ( eg MPEG4 audio/visual where a bunch of codecs are defined with same objectType). If esd is NULL, only 206 decoder type is checked (audio or video), not codec type 207 @GetDecoderName 208 returns codec name - only called once the stream is successfully attached 209 @privateStack 210 user defined. 211 */ 212 213 #define GF_CODEC_BASE_INTERFACE(IFCE_NAME) \ 214 GF_DECL_MODULE_INTERFACE \ 215 GF_Err (*AttachStream)(IFCE_NAME, GF_ESD *esd);\ 216 GF_Err (*DetachStream)(IFCE_NAME, u16 ES_ID);\ 217 GF_Err (*GetCapabilities)(IFCE_NAME, GF_CodecCapability *capability);\ 218 GF_Err (*SetCapabilities)(IFCE_NAME, GF_CodecCapability capability);\ 219 u32 (*CanHandleStream)(IFCE_NAME, u32 StreamType, GF_ESD *esd, u8 ProfileLevelIndication);\ 220 const char *(*GetName)(IFCE_NAME);\ 221 void *privateStack; \ 222 223 224 typedef struct _basedecoder 225 { 226 GF_CODEC_BASE_INTERFACE(struct _basedecoder *) 227 } GF_BaseDecoder; 228 229 230 /*interface name and version for node decoder mainly used by AFX*/ 231 #define GF_NODE_DECODER_INTERFACE GF_4CC('G', 'N', 'D', '3') 232 233 typedef struct _base_node *LPNODE; 234 235 typedef struct _nodedecoder 236 { 237 GF_CODEC_BASE_INTERFACE(struct _basedecoder *) 238 239 /*Process the node data in inAU. 240 @inBuffer, inBufferLength: encoded input data (complete framing of encoded data) 241 @ES_ID: stream this data belongs too (scalable object) 242 @AU_Time: specifies the current AU time. This is usually unused, however is needed for decoder 243 handling the scene graph without input data (cf below). In this case the buffer passed is always NULL and the AU 244 time caries the time of the scene (or of the stream object attached to the scene decoder, cf below) 245 @mmlevel: speed indicator for the decoding - cf above for values*/ 246 GF_Err (*ProcessData)(struct _nodedecoder *, const char *inBuffer, u32 inBufferLength, 247 u16 ES_ID, u32 AU_Time, u32 mmlevel); 248 249 /*attaches node to the decoder - currently only one node is only attached to a single decoder*/ 250 GF_Err (*AttachNode)(struct _nodedecoder *, LPNODE node); 251 } GF_NodeDecoder; 252 253 254 255 /*interface name and version for scene decoder */ 256 #define GF_INPUT_DEVICE_INTERFACE GF_4CC('G', 'I', 'D', '1') 257 258 typedef struct __input_device 259 { 260 /* interface declaration*/ 261 GF_DECL_MODULE_INTERFACE 262 263 Bool (*RegisterDevice)(struct __input_device *, const char *urn, const char *dsi, u32 dsi_size, void (*AddField)(struct __input_device *_this, u32 fieldType, const char *name)); 264 void (*Start)(struct __input_device *); 265 void (*Stop)(struct __input_device *); 266 267 void *udta; 268 269 /*this is set upon loading and shall not be modified*/ 270 void *input_stream_context; 271 void (*DispatchFrame)(struct __input_device *, const u8 *data, u32 data_len); 272 } GF_InputSensorDevice; 273 274 275 276 /*interface name and version for media decoder */ 277 #define GF_MEDIA_DECODER_INTERFACE GF_4CC('G', 'M', 'D', '3') 278 279 typedef struct _mediadecoderframe 280 { 281 //release media frame 282 void (*Release)(struct _mediadecoderframe *frame); 283 //get media frame plane 284 // @plane_idx: plane index, 0: Y or full plane, 1: U or UV plane, 2: V plane 285 // @outPlane: adress of target color plane 286 // @outStride: stride in bytes of target color plane 287 GF_Err (*GetPlane)(struct _mediadecoderframe *frame, u32 plane_idx, const char **outPlane, u32 *outStride); 288 289 GF_Err (*GetGLTexture)(struct _mediadecoderframe *frame, u32 plane_idx, u32 *gl_tex_format, u32 *gl_tex_id, GF_CodecMatrix * texcoordmatrix); 290 291 //allocated space by the decoder 292 void *user_data; 293 } GF_MediaDecoderFrame; 294 295 /*the media module interface. A media module MUST be implemented in synchronous mode as time 296 and resources management is done by the terminal*/ 297 typedef struct _mediadecoder 298 { 299 GF_CODEC_BASE_INTERFACE(struct _basedecoder *) 300 301 /*Process the media data in inAU. 302 @inBuffer, inBufferLength: encoded input data (complete framing of encoded data) 303 @ES_ID: stream this data belongs too (scalable object) 304 @outBuffer, outBufferLength: allocated data for decoding - if outBufferLength is not enough 305 you must set the size in outBufferLength and GF_BUFFER_TOO_SMALL 306 307 @PaddingBits is the padding at the end of the buffer (some codecs need this info) 308 @mmlevel: speed indicator for the decoding - cf above for values*/ 309 GF_Err (*ProcessData)(struct _mediadecoder *, 310 char *inBuffer, u32 inBufferLength, 311 u16 ES_ID, u32 *CTS, 312 char *outBuffer, u32 *outBufferLength, 313 u8 PaddingBits, u32 mmlevel); 314 315 316 /*optional (may be null), retrievs internal output frame of decoder. this function is called only if the decoder returns GF_OK on a SetCapabilities GF_CODEC_RAW_MEMORY*/ 317 GF_Err (*GetOutputBuffer)(struct _mediadecoder *, u16 ES_ID, u8 **pY_or_RGB, u8 **pU, u8 **pV); 318 319 /*optional (may be null), retrievs internal output frame object of decoder. this function is called only if the decoder returns GF_OK on a SetCapabilities GF_CODEC_FRAME_OUTPUT*/ 320 GF_Err (*GetOutputFrame)(struct _mediadecoder *, u16 ES_ID, GF_MediaDecoderFrame **frame, Bool *needs_resize); 321 } GF_MediaDecoder; 322 323 324 #ifdef __cplusplus 325 } 326 #endif 327 328 #endif /*_GF_MODULE_CODEC_H_*/ 329 330