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>

Include dependency graph for dirac_encoder.h:

Go to the source code of this file.

Classes

Typedefs

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

 

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 defined motion vector precisions supported by the encoder. More mv precisions may be added in future.


Enumeration Type Documentation

Enumerated type that defines encoder state

Enumerator:
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              lossless       false
                      qf             7
                      L1_sep         3
                      num_L1         11
                      cpd            20.0
                      xblen          12
                      yblen          12
                      xbsep          8
                      ybsep          8

     SD576            lossless       false
                      qf             7
                      L1_sep         3
                      num_L1         3
                      cpd            32.0
                      xblen          12
                      yblen          12
                      xbsep          8
                      ybsep          8

     HD720            lossless       false
                      qf             7
                      L1_sep         3
                      num_L1         7
                      cpd            20.0
                      xblen          16
                      yblen          16
                      xbsep          10
                      ybsep          12

     HD1080           lossless       false
                      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.