1 /* ***** BEGIN LICENSE BLOCK ***** 2 * 3 * $Id: dirac_encoder.h,v 1.28 2008/11/18 23:25:54 asuraparaju Exp $ $Name: Dirac_1_0_2 $ 4 * 5 * Version: MPL 1.1/GPL 2.0/LGPL 2.1 6 * 7 * The contents of this file are subject to the Mozilla Public License 8 * Version 1.1 (the "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * http://www.mozilla.org/MPL/ 11 * 12 * Software distributed under the License is distributed on an "AS IS" basis, 13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for 14 * the specific language governing rights and limitations under the License. 15 * 16 * The Original Code is BBC Research and Development code. 17 * 18 * The Initial Developer of the Original Code is the British Broadcasting 19 * Corporation. 20 * Portions created by the Initial Developer are Copyright (C) 2004. 21 * All Rights Reserved. 22 * 23 * Contributor(s): Anuradha Suraparaju (Original Author) 24 * Andrew Kennedy, 25 * Thomas Davies 26 * Myo Tun (Brunel University, myo.tun@brunel.ac.uk) 27 * 28 * Alternatively, the contents of this file may be used under the terms of 29 * the GNU General Public License Version 2 (the "GPL"), or the GNU Lesser 30 * Public License Version 2.1 (the "LGPL"), in which case the provisions of 31 * the GPL or the LGPL are applicable instead of those above. If you wish to 32 * allow use of your version of this file only under the terms of the either 33 * the GPL or LGPL and not to allow others to use your version of this file 34 * under the MPL, indicate your decision by deleting the provisions above 35 * and replace them with the notice and other provisions required by the GPL 36 * or LGPL. If you do not delete the provisions above, a recipient may use 37 * your version of this file under the terms of any one of the MPL, the GPL 38 * or the LGPL. 39 * ***** END LICENSE BLOCK ***** */ 40 41 #ifndef DIRAC_ENCODER_H 42 #define DIRAC_ENCODER_H 43 44 #include <libdirac_common/dirac_inttypes.h> 45 #include <libdirac_common/dirac_types.h> 46 47 /*! \file 48 \brief C interface to Dirac Encoder. 49 50 A set of 'C' functions that define the public interface to the Dirac encoder. 51 Refer to the the reference encoder source code, encoder/encmain.cpp for 52 an example of how to use the "C" interface. The pseudocode below gives 53 a brief description of the "C" interface usage. 54 55 \verbatim 56 #include <libdirac_decoder/dirac_encoder.h> 57 58 #define ENCBUF_SIZE 1024*1024; 59 unsigned char *buffer, enc_buf[ENC_BUFSIZE]; 60 int buffer_size; 61 dirac_encoder_t *encoder; 62 dirac_encoder_context_t enc_ctx; 63 64 // Initialse the encoder context with the presets for SD576 - Standard 65 // Definition Digital 66 dirac_encoder_context_init (&enc_ctx, VIDEO_FORMAT_SD576I50); 67 68 // Override parameters if required 69 // interlace : 1 - interlaced; 0 - progressive 70 enc_ctx.seq_params.interlace = 0; 71 enc_ctx.seq_params.topfieldfirst = 0; 72 enc_ctx.enc_params.qf = 7.5; 73 // disable instrumentation flag 74 enc_ctx.instr_flag = 0; 75 // return locally decoded output 76 enc_ctx.decode_flag = 1; 77 78 // Initialise the encoder with the encoder context. 79 // Setting verbose output to false 80 encoder= dirac_encoder_init(&enc_ctx, false); 81 82 // Set the buffer size. For SD576 4:2:0 chroma 83 buffer_size = (720*576*3)/2; 84 buffer = (unsigned char *)malloc (buffer_size); 85 86 // Output buffer 87 88 dirac_encoder_state_t state; 89 int go = 1; 90 do 91 { 92 read uncompressed frame data into buffer 93 if (end of file) 94 { 95 // push end of sequence 96 dirac_encoder_end_sequence(encoder); 97 } 98 // load one frame of data into encoder 99 if (dirac_encoder_load(encoder, buffer, buffer_size) == 0) 100 { 101 // Retrieve encoded frames from encoder 102 do 103 { 104 encoder->enc_buf.buffer = enc_buf; 105 encoder->enc_buf.size = ENCBUF_SIZE; 106 state = dirac_encoder_output (encoder); 107 switch (state) 108 { 109 case ENC_STATE_AVAIL: 110 // Encoded frame available in encoder->enc_buf 111 // Encoded frame params available in enccoder->enc_fparams 112 // Encoded frame stats available in enccoder->enc_fstats 113 break; 114 case ENC_STATE_BUFFER: 115 break; 116 case ENC_STATE_EOS: 117 // Reached end of sequence 118 // End of sequence information is available in encoder->enc_buf 119 // Sequence statistics available in encoder->enc_seqstats; 120 go = 0; // exit from the encoding loop 121 break; 122 case ENC_STATE_INVALID: 123 default: 124 // Unrecoverable error encountered. Exit; 125 exit (exit code); 126 } 127 if (encoder->decoded_frame_avail) 128 { 129 //locally decoded frame is available in 130 //encoder->dec_buf 131 //locally decoded frame parameters available 132 //in encoder->dec_fparams 133 } 134 if (encoder->instr_data_avail) 135 { 136 //Instrumentation data (motion vectors etc.) 137 //available in encoder->instr 138 } 139 } while (state == ENC_STATE_AVAIL) 140 } 141 } while (go == 1); 142 143 // Free the encoder resources 144 dirac_encoder_close(encoder) 145 // Free the uncompressed data buffer 146 free (buffer); 147 148 \endverbatim 149 */ 150 151 #ifdef __cplusplus 152 extern "C" { 153 #endif 154 155 /*! Enumerated type that defines encoder state */ 156 typedef enum 157 { 158 ENC_STATE_INVALID = -1, 159 ENC_STATE_BUFFER, 160 ENC_STATE_AVAIL, 161 ENC_STATE_EOS 162 } dirac_encoder_state_t ; 163 164 /*! Enumerated type that defines prefiltering types supported by the 165 encoder. */ 166 typedef PrefilterType dirac_prefilter_t; 167 168 /*! Enumerated type that defines encoder presets that set the encoder and 169 sequence paramters. More presets may be added in future*/ 170 typedef VideoFormat dirac_encoder_presets_t; 171 172 /*! Enumerated type that defines motion vector precisions supported by the 173 encoder.*/ 174 typedef MVPrecisionType dirac_mvprecision_t; 175 /*! Structure that holds the encoder specific parameters */ 176 typedef struct 177 { 178 /*! Lossless coding */ 179 int lossless; 180 /*! Quality factor */ 181 float qf; 182 /*! Full-search motion estimation */ 183 int full_search; 184 /*! Combined component motion estimation */ 185 int combined_me; 186 /*! x-range for full search ME */ 187 int x_range_me; 188 /*! y-range for full search ME */ 189 int y_range_me; 190 /*! The separation between L1 frames */ 191 int L1_sep; 192 /*! The number of L1 frames before the next intra frame. Together 193 with L1_sep determines the GOP structure. 194 */ 195 int num_L1; 196 /*! Normalised viewing distance parameter, in cycles per degree */ 197 float cpd; 198 /*! The width of blocks used for motion compensation */ 199 int xblen; 200 /*! The height of blocks used for motion compensation */ 201 int yblen; 202 /*! The horizontal separation between blocks. Always <xblen */ 203 int xbsep; 204 /*! The vertical separation between blocks. Always <yblen */ 205 int ybsep; 206 /*! Video format preset */ 207 int video_format; 208 /*! Transform filter for intra frames*/ 209 dirac_wlt_filter_t intra_wlt_filter; 210 /*! Transform filter for inter frames*/ 211 dirac_wlt_filter_t inter_wlt_filter; 212 /*! Transform depth */ 213 unsigned int wlt_depth; 214 /*! Spatial partitioning flag */ 215 unsigned int spatial_partition; 216 /*! prefilter indicator */ 217 dirac_prefilter_t prefilter; 218 /*! prefilter strength*/ 219 unsigned int prefilter_strength; 220 /*! Multiple quantisers flag */ 221 unsigned int multi_quants; 222 /*! motion-vector pixel precision */ 223 dirac_mvprecision_t mv_precision; 224 /*! target bit rate in kbps */ 225 int trate; 226 /*! picture coding mode: 0 - frame coding; 1 - field coding */ 227 unsigned int picture_coding_mode; 228 /*! arithmetic coding flag: 0 - vlc coding; 1 - arithmetic coding */ 229 int using_ac; 230 } dirac_encparams_t; 231 232 /*! Structure that holds the parameters that set up the encoder context */ 233 typedef struct 234 { 235 /*! Source parameters */ 236 dirac_sourceparams_t src_params; 237 /*! Encoder parameters */ 238 dirac_encparams_t enc_params; 239 /*! Return diagnostics info 1-return mv data, 0-no diagnostics returned */ 240 int instr_flag; 241 /*! Return locally decoded frames 1-return locally decoded frames, 242 0-no decoded frames returned */ 243 int decode_flag; 244 } dirac_encoder_context_t; 245 246 /*! Function that creates an encoder context based on a preset value. The 247 values can then be overridden by the user by setting each field separately 248 \param enc_ctx pointer to Encoder context tp be initialised. 249 \param preset Preset to be used to initialise the encoder context 250 \verbatim 251 252 For a full list of video formats presets supported and the default values 253 of the source and encoder parameters. refer to Annex C of the Dirac 254 ByteStream Specification. 255 256 \endverbatim 257 */ 258 extern DllExport void dirac_encoder_context_init (dirac_encoder_context_t *enc_ctx, dirac_encoder_presets_t preset); 259 260 261 /*! Structure that holds the encoded data*/ 262 typedef struct 263 { 264 /*! Buffer to hold encoded. Allocated and managed by library user. */ 265 unsigned char *buffer; 266 /*! Buffer size */ 267 int size; 268 } dirac_enc_data_t; 269 270 /*! Structure that holds the statistics about the encoded picture */ 271 typedef struct 272 { 273 /*! Number of motion vector bits */ 274 unsigned int mv_bits; 275 /*! Number of used to encode y component */ 276 unsigned int ycomp_bits; 277 /*! Number of used to encode u component */ 278 unsigned int ucomp_bits; 279 /*! Number of used to encode v component */ 280 unsigned int vcomp_bits; 281 /*! Total number of bits used to encode picture */ 282 unsigned int pic_bits; 283 } dirac_enc_picstats_t; 284 285 /*! Structure that holds the statistics about the encoded sequence */ 286 typedef struct 287 { 288 /*! Number of motion vector bits */ 289 int64_t mv_bits; 290 /*! Total number of bits used to encode sequence */ 291 int64_t seq_bits; 292 /*! Number of used to encode y component */ 293 int64_t ycomp_bits; 294 /*! Number of used to encode u component */ 295 int64_t ucomp_bits; 296 /*! Number of used to encode v component */ 297 int64_t vcomp_bits; 298 /*! Average bit rate for the sequence */ 299 int64_t bit_rate; 300 } dirac_enc_seqstats_t; 301 302 /*! Structure that holds the motion vector information */ 303 typedef struct 304 { 305 /*! X component */ 306 int x; 307 /*! Y component */ 308 int y; 309 } dirac_mv_t; 310 311 /*! Structure that holds the motion vector cost information*/ 312 typedef struct 313 { 314 /*! The Sum of Absolute Differences */ 315 float SAD; 316 /*! The (Lagrangian-weighted) motion vector cost */ 317 float mvcost; 318 } dirac_mv_cost_t; 319 320 /*! Structure that diagnostics data returned by the encoder */ 321 typedef struct 322 { 323 /*! Frame type */ 324 dirac_picture_type_t ptype; 325 /*! Reference type */ 326 dirac_reference_type_t rtype; 327 /*! Picture number */ 328 int pnum; 329 /*! Number of reference pictures */ 330 int num_refs; 331 /*! Array of Reference picture numbers */ 332 int refs[2]; 333 /*! Block separation in X direction */ 334 int xbsep; 335 /*! Block separation in Y direction */ 336 int ybsep; 337 /*! MacroBlock length in X direction */ 338 int sb_xlen; 339 /*! MacroBlock length in Y direction */ 340 int sb_ylen; 341 /*! Motion Vector array length in X direction */ 342 int mv_xlen; 343 /*! Motion Vector array length in Y direction */ 344 int mv_ylen; 345 /*! Macro-block split mode array - sb_ylen*sb_xlen*/ 346 int *sb_split_mode; 347 /*! Macro-block costs array - sb_ylen*sb_xlen*/ 348 float *sb_costs; 349 /*! Block prediction mode - mv_xlen*mv_ylen */ 350 int *pred_mode; 351 /*! Block intrac costs - mv_xlen*mv_ylen */ 352 float *intra_costs; 353 /*! Bi prediction costs - mv_xlen*mv_ylen*2 */ 354 dirac_mv_cost_t *bipred_costs; 355 /*! DC values of y_comp */ 356 short *dc_ycomp; 357 /*! DC values of u_comp */ 358 short *dc_ucomp; 359 /*! DC values of v_comp */ 360 short *dc_vcomp; 361 /*! Motion vectors for Reference frames mv_ylen*mv_xlen */ 362 dirac_mv_t *mv[2]; 363 /*! Predictions costs for Reference frames mv_ylen*mv_xlen */ 364 dirac_mv_cost_t *pred_costs[2]; 365 } dirac_instr_t; 366 367 /*! Structure that holds the information returned by the encoder */ 368 typedef struct 369 { 370 /*! Encoder context */ 371 dirac_encoder_context_t enc_ctx; 372 373 /*! encoded picture available flag */ 374 int encoded_picture_avail; 375 376 /*! 377 encoded output. This buffer must be initialised by the user of the 378 library 379 */ 380 dirac_enc_data_t enc_buf; 381 382 /*! encoded picture params */ 383 dirac_picparams_t enc_pparams; 384 385 /*! encoded picture stats */ 386 dirac_enc_picstats_t enc_pstats; 387 388 /*! encoded sequence stats */ 389 dirac_enc_seqstats_t enc_seqstats; 390 391 /*! end of sequence */ 392 int end_of_sequence; 393 394 /* locally decoded frame (NB: not picture) available flag. 395 1 - locally decoded frame available in dec_buf. 396 0 - locally decoded frame not available. 397 */ 398 int decoded_frame_avail; 399 400 /*! 401 locally decoded output buffer. This buffer is allocated and managed by 402 the encoder library 403 */ 404 dirac_framebuf_t dec_buf; 405 406 /*! locally decoded picture params */ 407 dirac_picparams_t dec_pparams; 408 409 /*! 410 instrumentation data buffer. This buffer is allocated and managed by 411 the encoder library. */ 412 dirac_instr_t instr; 413 414 /*! instrumentation data available flag 415 1 - instrumentation data available in instr 416 0 - linstrumentation data not available. 417 */ 418 int instr_data_avail; 419 420 /*! void pointer to internal sequence compressor */ 421 const void *compressor; 422 } dirac_encoder_t; 423 424 /*! 425 Initialise encoder. Makes a copy of the enc_ctx passed to it. 426 \param enc_ctx Parameters to initialise encoder context 427 \param verbose boolean flag to set verbose output 428 \return encoder Handle to encoder if successful or NULL on failure 429 */ 430 extern DllExport dirac_encoder_t *dirac_encoder_init (const dirac_encoder_context_t *enc_ctx, int verbose); 431 432 #if DIRAC_RESEARCH_VERSION_ATLEAST(1,0,2) 433 /*! 434 Query the encoder for the reordering depth. 435 \param encoder Encoder Handle 436 \return encoder The number of pictures a realtime decoder must wait 437 before outputting the first picture in display order; 438 or -1 for failure. 439 */ 440 extern DllExport int dirac_encoder_pts_offset (const dirac_encoder_t *encoder); 441 #endif 442 443 /*! 444 Load uncompressed data into the encoder. Expects one full frame of data 445 \param encoder Encoder Handle 446 \param uncdata Uncompressed data buffer 447 \param uncdata_size boolean flag to set verbose output 448 \return return status. >0 - successful; -1 failed 449 Failure may be due to input data size not matching 450 the required frame size. 451 */ 452 extern DllExport int dirac_encoder_load (dirac_encoder_t *encoder, unsigned char *uncdata, int uncdata_size); 453 454 /*! 455 Retrieve an encoded frame from the encoder. Returns the state of the 456 encoder. The encoder buffer enc_buf in the encodermust be 457 set up with the buffer and buffer_size that will hold the encoded frame 458 \param encoder Encoder Handle 459 \return ENC_STATE_INVALID - unrecoverable error 460 ENC_STATE_BUFFER - load data into encoder 461 ENC_STATE_AVAIL - Encoded frame available 462 ENC_STATE_EOS - End of Sequence info available 463 */ 464 extern DllExport dirac_encoder_state_t dirac_encoder_output (dirac_encoder_t *encoder); 465 466 /*! 467 Request the encoder to end the sequence. 468 \param encoder Encoder Handle 469 */ 470 extern DllExport void dirac_encoder_end_sequence (dirac_encoder_t *encoder); 471 472 /*! 473 Free resources held by encoder 474 \param encoder Encoder Handle 475 */ 476 extern DllExport void dirac_encoder_close (dirac_encoder_t *encoder); 477 478 #endif 479 #ifdef __cplusplus 480 } 481 #endif 482