Dirac - A Video Codec

Created by the British Broadcasting Corporation.


dirac_encoder.h File Reference

C interface to Dirac Encoder. More...

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_pts_offset (const dirac_encoder_t *encoder)
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

◆ dirac_encoder_presets_t

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

◆ dirac_mvprecision_t

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

◆ dirac_prefilter_t

Enumerated type that defines prefiltering types supported by the encoder.

Enumeration Type Documentation

◆ dirac_encoder_state_t

Enumerated type that defines encoder state

Enumerator
ENC_STATE_INVALID 
ENC_STATE_BUFFER 
ENC_STATE_AVAIL 
ENC_STATE_EOS 

Function Documentation

◆ dirac_encoder_close()

DllExport void dirac_encoder_close ( dirac_encoder_t * encoder)
extern

Free resources held by encoder

Parameters
encoderEncoder Handle

References DllExport.

◆ dirac_encoder_context_init()

DllExport void dirac_encoder_context_init ( dirac_encoder_context_t * enc_ctx,
dirac_encoder_presets_t preset )
extern

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.

References DllExport.

◆ dirac_encoder_end_sequence()

DllExport void dirac_encoder_end_sequence ( dirac_encoder_t * encoder)
extern

Request the encoder to end the sequence.

Parameters
encoderEncoder Handle

References DllExport.

◆ dirac_encoder_init()

DllExport dirac_encoder_t * dirac_encoder_init ( const dirac_encoder_context_t * enc_ctx,
int verbose )
extern

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

References DllExport.

◆ dirac_encoder_load()

DllExport int dirac_encoder_load ( dirac_encoder_t * encoder,
unsigned char * uncdata,
int uncdata_size )
extern

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.

References DllExport.

◆ dirac_encoder_output()

DllExport dirac_encoder_state_t dirac_encoder_output ( dirac_encoder_t * encoder)
extern

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

References DllExport.

◆ dirac_encoder_pts_offset()

DllExport int dirac_encoder_pts_offset ( const dirac_encoder_t * encoder)
extern

Query the encoder for the reordering depth.

Parameters
encoderEncoder Handle
Returns
encoder The number of pictures a realtime decoder must wait before outputting the first picture in display order; or -1 for failure.

References DllExport.


© 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.