- Main Page
- Namespaces
- Classes
- Files
- Directories

- File List
- File Members

# 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
struct | dirac_encparams_t
struct | dirac_encoder_context_t
struct | dirac_enc_data_t
struct | dirac_enc_framestats_t
struct | dirac_enc_seqstats_t
struct | dirac_mv_t
struct | dirac_mv_cost_t
struct | dirac_instr_t
struct | dirac_encoder_t
## Enumerations
enum | dirac_encoder_state_t
enum | dirac_encoder_presets_t
## Functions
DllExport void | dirac_encoder_context_init (dirac_encoder_context_t *enc_ctx, dirac_encoder_presets_t preset)
DllExport dirac_encoder_t * | dirac_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 int | dirac_encoder_end_sequence (dirac_encoder_t *encoder)
DllExport void | dirac_encoder_close (dirac_encoder_t *encoder)

## Detailed Description

C interface to Dirac Encoder.

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

Definition in file dirac_encoder.h.

## 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 Definition at line 155 of file dirac_encoder.h.

enum dirac_encoder_state_t

| Enumerated type that defines encoder state Definition at line 146 of file dirac_encoder.h.

## Function Documentation

DllExport void dirac_encoder_close | ( | dirac_encoder_t * | encoder | ) |

  | Free resources held by encoder Parameters:
  | encoder | Encoder Handle
Definition at line 925 of file dirac_encoder.cpp.

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
Definition at line 804 of file dirac_encoder.cpp.

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 Definition at line 895 of file dirac_encoder.cpp. References DiracEncoder::GetDecodedData(), and DiracEncoder::GetSequenceEnd().

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 Definition at line 812 of file dirac_encoder.cpp. References dirac_encoder_t::decoded_frame_avail, dirac_encoder_t::encoded_frame_avail, and dirac_encoder_t::instr_data_avail.

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. Definition at line 833 of file dirac_encoder.cpp. References dirac_encoder_t::compressor, DiracEncoder::GetEncParams(), DiracEncoder::LoadNextFrame(), and dirac::CodecParams::Verbose().

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 Definition at line 856 of file dirac_encoder.cpp. References DiracEncoder::CompressNextFrame(), DiracEncoder::GetDecodedData(), and DiracEncoder::GetEncodedData().