Dirac - A Video Codec

Created by the British Broadcasting Corporation.


dirac_encoder.h File Reference

C interface to Dirac Encoder. More...

#include <libdirac_common/dirac_types.h>

Go to the source code of this file.

Classes

Enumerations

Functions


Detailed Description

A set of 'C' functions that define the public interface to the Dirac encoder. Refer to the the reference encoder source code, encoder/encmain.cpp for an example of how to use the "C" interface. The pseudocode below gives a brief description of the "C" interface usage.

#include <libdirac_decoder/dirac_encoder.h> #define ENCBUF_SIZE 1024*1024; unsigned char *buffer, enc_buf[ENC_BUFSIZE]; int buffer_size; dirac_encoder_t *encoder; dirac_encoder_context_t enc_ctx; // Initialse the encoder context with the presets for SD576 - Standard // Definition Digital dirac_encoder_context_init (&enc_ctx, SD576); // Override parameters if required // interlace : 1 - interlaced; 0 - progressive enc_ctx.seq_params.interlace = 0; enc_ctx.seq_params.topfieldfirst = 0; enc_ctx.enc_params.qf = 7.5; // disable instrumentation flag enc_ctx.instr_flag = 0; // return locally decoded output enc_ctx.decode_flag = 1; // Initialise the encoder with the encoder context. // Setting verbose output to false encoder= dirac_encoder_init(&enc_ctx, false); // Set the buffer size. For SD576 4:2:0 chroma buffer_size = (720*576*3)/2; buffer = (unsigned char *)malloc (buffer_size); // Output buffer dirac_encoder_state_t state; while (read uncompressed frame data into buffer) { // load one frame of data into encoder if (dirac_encoder_load(encoder, buffer, buffer_size) == 0) { // Retrieve encoded frames from encoder do { encoder->enc_buf.buffer = enc_buf; encoder->enc_buf.size = ENCBUF_SIZE; state = dirac_encoder_output (encoder); switch (state) { case ENC_STATE_AVAIL: // Encoded frame available in encoder->enc_buf // Encoded frame params available in enccoder->enc_fparams // Encoded frame stats available in enccoder->enc_fstats break; case ENC_STATE_BUFFER: break; case ENC_STATE_INVALID: default: // Unrecoverable error encountered. Exit; exit (exit code); } if (encoder->decoded_frame_avail) { //locally decoded frame is available in //encoder->dec_buf //locally decoded frame parameters available //in encoder->dec_fparams } if (encoder->instr_data_avail) { //Instrumentation data (motion vectors etc.) //available in encoder->instr } } while (state == ENC_STATE_AVAIL) } } // Retrieve end of sequence info encoder->enc_buf.buffer = video_buf; encoder->enc_buf.size = VIDEO_BUFFER_SIZE; dirac_encoder_end_sequence( encoder ); // End of sequence info is availale in encoder->enc_buf // Sequence statistics available in encoder->enc_seqstats; // Free the encoder resources dirac_encoder_close(encoder) // Free the uncompressed data buffer free (buffer);

Enumeration Type Documentation

enum dirac_encoder_presets_t
 

Enumerated type that defines encoder presets that set the encoder and sequence paramters. More presets may be added in future

Enumeration values:
CIF 
SD576 
HD720 
HD1080 

enum dirac_encoder_state_t
 

Enumerated type that defines encoder state

Enumeration values:
ENC_STATE_INVALID 
ENC_STATE_BUFFER 
ENC_STATE_AVAIL 


Function Documentation

DllExport void dirac_encoder_close dirac_encoder_t encoder  ) 
 

Free resources held by encoder

Parameters:
encoder Encoder Handle

DllExport void dirac_encoder_context_init dirac_encoder_context_t enc_ctx,
dirac_encoder_presets_t  preset
 

Function that creates an encoder context based on a preset value. The values can then be overridden by the user by setting each field separately

Parameters:
enc_ctx pointer to Encoder context tp be initialised.
preset Preset to be used to initialise the encoder context
The sequence parameters and encoder parameters are initialised as follows Sequence Parameters: Preset Field Value CIF width 352 height 288 chroma Planar YUV 4:2:0 chroma_width calculated from width and chroma chroma_height calculated from height and chroma frame_rate 13/1 interlace 0 (progressive) topfieldfirst 0 SD576 width 720 height 576 chroma Planar YUV 4:2:0 chroma_width calculated from width and chroma chroma_height calculated from height and chroma frame_rate 25/1 interlace 1 (interlaced) topfieldfirst 1 HD720 width 1280 height 720 chroma Planar YUV 4:2:0 chroma_width calculated from width and chroma chroma_height calculated from height and chroma frame_rate 50/1 interlace 0 (progressive) topfieldfirst 0 HD1080 width 1920 height 1080 chroma Planar YUV 4:2:0 chroma_width calculated from width and chroma chroma_height calculated from height and chroma frame_rate 25/1 interlace 1 (interlaced) topfieldfirst 1 Encoder params: Preset Field Value CIF qf 7 L1_sep 3 num_L1 11 cpd 20.0 xblen 12 yblen 12 xbsep 8 ybsep 8 SD576 qf 7 L1_sep 3 num_L1 3 cpd 32.0 xblen 12 yblen 12 xbsep 8 ybsep 8 HD720 qf 7 L1_sep 3 num_L1 7 cpd 20.0 xblen 16 yblen 16 xbsep 10 ybsep 12 HD1080 qf 7 L1_sep 3 num_L1 3 cpd 32.0 xblen 20 yblen 20 xbsep 16 ybsep 16

DllExport int dirac_encoder_end_sequence dirac_encoder_t encoder  ) 
 

Retrieve end of sequence information from the encoder. The encoder buffer, enc_buf, in the encodermust be set up with the buffer and buffer_size that will hold the end of sequence information.

Parameters:
encoder Encoder Handle
Returns:
return status. >=0 - successful; -1 failed

DllExport dirac_encoder_t* dirac_encoder_init const dirac_encoder_context_t enc_ctx,
int  verbose
 

Initialise encoder. Makes a copy of the enc_ctx passed to it.

Parameters:
enc_ctx Parameters to initialise encoder context
verbose boolean flag to set verbose output
Returns:
encoder Handle to encoder if successful or NULL on failure

DllExport int dirac_encoder_load dirac_encoder_t encoder,
unsigned char *  uncdata,
int  uncdata_size
 

Load uncompressed data into the encoder. Expects one full frame of data

Parameters:
encoder Encoder Handle
uncdata Uncompressed data buffer
uncdata_size boolean flag to set verbose output
Returns:
return status. >0 - successful; -1 failed Failure may be due to input data size not matching the required frame size.

DllExport dirac_encoder_state_t dirac_encoder_output dirac_encoder_t encoder  ) 
 

Retrieve an encoded frame from the encoder. Returns the state of the encoder. The encoder buffer enc_buf in the encodermust be set up with the buffer and buffer_size that will hold the encoded frame

Parameters:
encoder Encoder Handle
Returns:
ENC_STATE_INVALID - unrecoverable error ENC_STATE_BUFFER - load data into encoder ENC_STATE_AVAIL - Encoded frame available


© 2004 British Broadcasting Corporation. Dirac code licensed under the Mozilla Public License (MPL) Version 1.1.
HTML documentation generated by Dimitri van Heesch's excellent Doxygen tool.