Dirac - A Video Codec

Created by the British Broadcasting Corporation.


Classes | Typedefs | Enumerations | Functions
dirac_encoder.h File Reference

C interface to Dirac Encoder. More...

#include <libdirac_common/dirac_inttypes.h>
#include <libdirac_common/dirac_types.h>
Include dependency graph for dirac_encoder.h:

Go to the source code of this file.

Classes

struct  dirac_encparams_t
struct  dirac_encoder_context_t
struct  dirac_enc_data_t
struct  dirac_enc_picstats_t
struct  dirac_enc_seqstats_t
struct  dirac_mv_t
struct  dirac_mv_cost_t
struct  dirac_instr_t
struct  dirac_encoder_t

Typedefs

typedef PrefilterType dirac_prefilter_t
typedef VideoFormat dirac_encoder_presets_t
typedef MVPrecisionType dirac_mvprecision_t

Enumerations

enum  dirac_encoder_state_t { ENC_STATE_INVALID = -1, ENC_STATE_BUFFER, ENC_STATE_AVAIL, ENC_STATE_EOS }

Functions

DllExport void dirac_encoder_context_init (dirac_encoder_context_t *enc_ctx, dirac_encoder_presets_t preset)
DllExport dirac_encoder_tdirac_encoder_init (const dirac_encoder_context_t *enc_ctx, int verbose)
DllExport int dirac_encoder_load (dirac_encoder_t *encoder, unsigned char *uncdata, int uncdata_size)
DllExport dirac_encoder_state_t dirac_encoder_output (dirac_encoder_t *encoder)
DllExport void dirac_encoder_end_sequence (dirac_encoder_t *encoder)
DllExport void dirac_encoder_close (dirac_encoder_t *encoder)

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, VIDEO_FORMAT_SD576I50);

 // 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;
 int go = 1;
 do
 {
    read uncompressed frame data into buffer
    if (end of file)
    {
        // push end of sequence
        dirac_encoder_end_sequence(encoder);
    }
    // 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_EOS:
                // Reached end of sequence
                // End of sequence information is available in encoder->enc_buf
                // Sequence statistics available in encoder->enc_seqstats;
                go = 0; // exit from the encoding loop
                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)
    }
 } while (go == 1);

 // Free the encoder resources
 dirac_encoder_close(encoder)
 // Free the uncompressed data buffer
 free (buffer);

Typedef Documentation

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

Enumerated type that defines motion vector precisions supported by the encoder.

Enumerated type that defines prefiltering types supported by the encoder.


Enumeration Type Documentation

Enumerated type that defines encoder state

Enumerator:
ENC_STATE_INVALID 
ENC_STATE_BUFFER 
ENC_STATE_AVAIL 
ENC_STATE_EOS 

Function Documentation

DllExport void dirac_encoder_close ( dirac_encoder_t encoder)

Free resources held by encoder

Parameters:
encoderEncoder 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_ctxpointer to Encoder context tp be initialised.
presetPreset to be used to initialise the encoder context
    For a full list of video formats presets supported and the default values
    of the source and encoder parameters. refer to Annex C of the Dirac
    ByteStream Specification.
DllExport void dirac_encoder_end_sequence ( dirac_encoder_t encoder)

Request the encoder to end the sequence.

Parameters:
encoderEncoder Handle
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_ctxParameters to initialise encoder context
verboseboolean 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:
encoderEncoder Handle
uncdataUncompressed data buffer
uncdata_sizeboolean 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:
encoderEncoder Handle
Returns:
ENC_STATE_INVALID - unrecoverable error ENC_STATE_BUFFER - load data into encoder ENC_STATE_AVAIL - Encoded frame available ENC_STATE_EOS - End of Sequence info 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.