## schroencoder

schroencoder

## Synopsis

                        SchroEncoder;
                        SchroEncoderFrame;
    enum                SchroEncoderFrameStateEnum;
    enum                SchroEncoderPerceptualEnum;
    enum                SchroQuantiserEngineEnum;
    enum                SchroStateEnum;
    enum                SchroEncoderGOPEnum;
    enum                SchroEncoderRateControlEnum;
                        SchroEncoderSetting;
    enum                SchroEncoderSettingTypeEnum;
    int                 (*SchroEngineIterateFunc)           (SchroEncoder *encoder);
    SchroEncoder *      schro_encoder_new                   (void);
    void                schro_encoder_free                  (SchroEncoder *encoder);
    SchroVideoFormat *  schro_encoder_get_video_format      (SchroEncoder *encoder);
    void                schro_encoder_set_video_format      (SchroEncoder *encoder,
                                                             SchroVideoFormat *video_format);
    void                schro_encoder_end_of_stream         (SchroEncoder *encoder);
    void                schro_encoder_push_frame            (SchroEncoder *encoder,
                                                             SchroFrame *frame);
    void                schro_encoder_encode_parse_info     (SchroPack *bits,
                                                             int parse_code);
    SchroBuffer *       schro_encoder_pull                  (SchroEncoder *encoder,
                                                             int *n_decodable_frames);
    void                schro_encoder_analyse_picture       (SchroAsyncStage *stage);
    void                schro_encoder_calculate_subband_weights
                                                            (SchroEncoder *encoder,
                                                             double (perceptual_weightdouble) ());
    void                schro_encoder_calculate_test_info   (SchroEncoderFrame *frame);
    void                schro_encoder_choose_quantisers     (SchroEncoderFrame *frame);
    void                schro_encoder_clean_up_transform    (SchroEncoderFrame *frame);
    SchroBuffer *       schro_encoder_encode_auxiliary_data (SchroEncoder *encoder,
                                                             SchroAuxiliaryDataID id,
                                                             const void *data,
                                                             int size);
    SchroBuffer *       schro_encoder_encode_end_of_stream  (SchroEncoder *encoder);
    void                schro_encoder_encode_lowdelay_transform_data
                                                            (SchroEncoderFrame *frame);
    void                schro_encoder_encode_picture        (SchroAsyncStage *stage);
    void                schro_encoder_encode_picture_header (SchroEncoderFrame *frame);
    void                schro_encoder_encode_subband        (SchroEncoderFrame *frame,
                                                             int component,
                                                             int index);
    void                schro_encoder_encode_subband_noarith
                                                            (SchroEncoderFrame *frame,
                                                             int component,
                                                             int index);
    int                 schro_encoder_engine_backref        (SchroEncoder *encoder);
    int                 schro_encoder_engine_backtest       (SchroEncoder *encoder);
    int                 schro_encoder_engine_intra_only     (SchroEncoder *encoder);
    int                 schro_encoder_engine_lossless       (SchroEncoder *encoder);
    int                 schro_encoder_engine_lowdelay       (SchroEncoder *encoder);
    int                 schro_encoder_engine_test_intra     (SchroEncoder *encoder);
    void                schro_encoder_estimate_entropy      (SchroEncoderFrame *frame);
    void                schro_encoder_frame_analyse         (SchroEncoderFrame *frame);
    void                schro_encoder_frame_downsample      (SchroEncoderFrame *frame);
    void                schro_encoder_frame_insert_buffer   (SchroEncoderFrame *frame,
                                                             SchroBuffer *buffer);
    SchroEncoderFrame * schro_encoder_frame_new             (SchroEncoder *encoder);
    SchroFrame *        schro_encoder_frame_queue_get       (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);
    void                schro_encoder_frame_queue_remove    (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);
    void                schro_encoder_frame_ref             (SchroEncoderFrame *frame);
    void                schro_encoder_frame_unref           (SchroEncoderFrame *frame);
    void                schro_encoder_init_subbands         (SchroEncoderFrame *frame);
    void                schro_encoder_insert_buffer         (SchroEncoder *encoder,
                                                             SchroBuffer *buffer);
    void                schro_encoder_output_push           (SchroEncoder *encoder,
                                                             SchroBuffer *buffer,
                                                             int slot,
                                                             int presentation_frame);
    double              schro_encoder_perceptual_weight_ccir959
                                                            (double cpd);
    double              schro_encoder_perceptual_weight_constant
                                                            (double cpd);
    double              schro_encoder_perceptual_weight_moo (double cpd);
    void                schro_encoder_postanalyse_picture   (SchroAsyncStage *stage);
    int                 schro_encoder_push_ready            (SchroEncoder *encoder);
    void                schro_encoder_recalculate_allocations
                                                            (SchroEncoder *encoder);
    void                schro_encoder_reconstruct_picture   (SchroAsyncStage *stage);
    SchroEncoderFrame * schro_encoder_reference_get         (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);
    void                schro_encoder_set_default_subband_weights
                                                            (SchroEncoder *encoder);
    void                schro_encoder_start                 (SchroEncoder *encoder);
    SchroStateEnum      schro_encoder_wait                  (SchroEncoder *encoder);
    int                 schro_encoder_get_n_settings        (void);
    const SchroEncoderSetting * schro_encoder_get_setting_info
                                                            (int i);
    void                schro_encoder_global_estimation     (SchroEncoderFrame *frame);
    void                schro_encoder_init_error_tables     (SchroEncoder *encoder);
    void                schro_encoder_phasecorr_estimation  (SchroPhaseCorr *pc);
    double              schro_encoder_setting_get_double    (SchroEncoder *encoder,
                                                             const char *name);
    void                schro_encoder_setting_set_double    (SchroEncoder *encoder,
                                                             const char *name,
                                                             double d);

## Description

## Details

### SchroEncoder

    typedef struct {
    } SchroEncoder;

### SchroEncoderFrame

    typedef struct {
    } SchroEncoderFrame;

### enum SchroEncoderFrameStateEnum

    typedef enum {
      SCHRO_ENCODER_FRAME_STAGE_NEW = 0,
      SCHRO_ENCODER_FRAME_STAGE_ANALYSE,
      SCHRO_ENCODER_FRAME_STAGE_SC_DETECT_1,
      SCHRO_ENCODER_FRAME_STAGE_SC_DETECT_2,
      SCHRO_ENCODER_FRAME_STAGE_HAVE_GOP,
      SCHRO_ENCODER_FRAME_STAGE_HAVE_PARAMS,
      SCHRO_ENCODER_FRAME_STAGE_PREDICT_ROUGH,
      SCHRO_ENCODER_FRAME_STAGE_PREDICT_PEL,
      SCHRO_ENCODER_FRAME_STAGE_PREDICT_SUBPEL,
      SCHRO_ENCODER_FRAME_STAGE_MODE_DECISION,
      SCHRO_ENCODER_FRAME_STAGE_HAVE_REFS,
      SCHRO_ENCODER_FRAME_STAGE_HAVE_QUANTS,
      SCHRO_ENCODER_FRAME_STAGE_ENCODING,
      SCHRO_ENCODER_FRAME_STAGE_RECONSTRUCT,
      SCHRO_ENCODER_FRAME_STAGE_POSTANALYSE,
      SCHRO_ENCODER_FRAME_STAGE_DONE,
      SCHRO_ENCODER_FRAME_STAGE_FREE,
      SCHRO_ENCODER_FRAME_STAGE_LAST /* this should be last */
    } SchroEncoderFrameStateEnum;

### enum SchroEncoderPerceptualEnum

    typedef enum {
      SCHRO_ENCODER_PERCEPTUAL_CONSTANT,
      SCHRO_ENCODER_PERCEPTUAL_CCIR959,
      SCHRO_ENCODER_PERCEPTUAL_MOO,
      SCHRO_ENCODER_PERCEPTUAL_MANOS_SAKRISON
    } SchroEncoderPerceptualEnum;

### enum SchroQuantiserEngineEnum

    typedef enum {
      SCHRO_QUANTISER_ENGINE_SIMPLE,
      SCHRO_QUANTISER_ENGINE_RDO_BIT_ALLOCATION,
      SCHRO_QUANTISER_ENGINE_CBR,
      SCHRO_QUANTISER_ENGINE_LOSSLESS,
      SCHRO_QUANTISER_ENGINE_LOWDELAY,
      SCHRO_QUANTISER_ENGINE_RDO_LAMBDA,
      SCHRO_QUANTISER_ENGINE_CONSTANT_ERROR
    } SchroQuantiserEngineEnum;

### enum SchroStateEnum

    typedef enum {
      SCHRO_STATE_NEED_FRAME,
      SCHRO_STATE_HAVE_BUFFER,
      SCHRO_STATE_AGAIN,
      SCHRO_STATE_END_OF_STREAM
    } SchroStateEnum;

### enum SchroEncoderGOPEnum

    typedef enum {
      SCHRO_ENCODER_GOP_ADAPTIVE,
      SCHRO_ENCODER_GOP_INTRA_ONLY,
      SCHRO_ENCODER_GOP_BACKREF,
      SCHRO_ENCODER_GOP_CHAINED_BACKREF,
      SCHRO_ENCODER_GOP_BIREF,
      SCHRO_ENCODER_GOP_CHAINED_BIREF,
    } SchroEncoderGOPEnum;

### enum SchroEncoderRateControlEnum

    typedef enum {
      SCHRO_ENCODER_RATE_CONTROL_CONSTANT_NOISE_THRESHOLD,
      SCHRO_ENCODER_RATE_CONTROL_CONSTANT_BITRATE,
      SCHRO_ENCODER_RATE_CONTROL_LOW_DELAY,
      SCHRO_ENCODER_RATE_CONTROL_LOSSLESS,
      SCHRO_ENCODER_RATE_CONTROL_CONSTANT_LAMBDA,
      SCHRO_ENCODER_RATE_CONTROL_CONSTANT_ERROR,
      SCHRO_ENCODER_RATE_CONTROL_CONSTANT_QUALITY
    } SchroEncoderRateControlEnum;

### SchroEncoderSetting

    typedef struct {
      const char *name;
      SchroEncoderSettingTypeEnum type;

      double min;
      double max;
      double default_value;

      const char **enum_list;
    } SchroEncoderSetting;

### enum SchroEncoderSettingTypeEnum

    typedef enum {
      SCHRO_ENCODER_SETTING_TYPE_BOOLEAN,
      SCHRO_ENCODER_SETTING_TYPE_INT,
      SCHRO_ENCODER_SETTING_TYPE_ENUM,
      SCHRO_ENCODER_SETTING_TYPE_DOUBLE,
      SCHRO_ENCODER_SETTING_TYPE_LAST
    } SchroEncoderSettingTypeEnum;

### SchroEngineIterateFunc ()

    int                 (*SchroEngineIterateFunc)           (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_new ()

    SchroEncoder *      schro_encoder_new                   (void);

Create a new encoder object.

Returns : | a new encoder object

### schro_encoder_free ()

    void                schro_encoder_free                  (SchroEncoder *encoder);

Frees an encoder object and all its resources.

`encoder` : | an encoder object

### schro_encoder_get_video_format ()

    SchroVideoFormat *  schro_encoder_get_video_format      (SchroEncoder *encoder);

Creates a new SchroVideoFormat structure and copies the video format information of `decoder` into it.

When no longer needed, the returned pointer should be freed using `free()`.

`encoder` : | an encoder object
Returns : | a pointer to a SchroVideoFormat structure

### schro_encoder_set_video_format ()

    void                schro_encoder_set_video_format      (SchroEncoder *encoder,
                                                             SchroVideoFormat *video_format);

Sets the video format used by `encoder` to the values specified in `format`. This function may only be called before `schro_encoder_start()` is called on the encoder.

`encoder` : | an encoder object
`video_format` : |

### schro_encoder_end_of_stream ()

    void                schro_encoder_end_of_stream         (SchroEncoder *encoder);

Tells the encoder that the end of the stream has been reached, and no more frames are available to encode. The encoder will then finish encoding.

`encoder` : | an encoder object

### schro_encoder_push_frame ()

    void                schro_encoder_push_frame            (SchroEncoder *encoder,
                                                             SchroFrame *frame);

Provides a frame to the encoder to encode.

`encoder` : | an encoder object
`frame` : | a frame to encode

### schro_encoder_encode_parse_info ()

    void                schro_encoder_encode_parse_info     (SchroPack *bits,
                                                             int parse_code);

`bits` : |
`parse_code` : |

### schro_encoder_pull ()

    SchroBuffer *       schro_encoder_pull                  (SchroEncoder *encoder,
                                                             int *n_decodable_frames);

Pulls a buffer of compressed video from the encoder. If `presentation_frame` is not NULL, the frame number of the latest decodable frame is returned.

`encoder` : | an encoder object
`n_decodable_frames` : |
Returns : | a buffer containing compressed video

### schro_encoder_analyse_picture ()

    void                schro_encoder_analyse_picture       (SchroAsyncStage *stage);

`stage` : |

### schro_encoder_calculate_subband_weights ()

    void                schro_encoder_calculate_subband_weights
                                                            (SchroEncoder *encoder,
                                                             double (perceptual_weightdouble) ());

`encoder` : |
`perceptual_weight` : |

### schro_encoder_calculate_test_info ()

    void                schro_encoder_calculate_test_info   (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_choose_quantisers ()

    void                schro_encoder_choose_quantisers     (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_clean_up_transform ()

    void                schro_encoder_clean_up_transform    (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_encode_auxiliary_data ()

    SchroBuffer *       schro_encoder_encode_auxiliary_data (SchroEncoder *encoder,
                                                             SchroAuxiliaryDataID id,
                                                             const void *data,
                                                             int size);

Packs data into a Dirac auxiliary data packet.

`encoder` : |
`id` : |
`data` : |
`size` : |
Returns : | a buffer

### schro_encoder_encode_end_of_stream ()

    SchroBuffer *       schro_encoder_encode_end_of_stream  (SchroEncoder *encoder);

Creates an end-of-stream packet.

`encoder` : |
Returns : | a buffer

### schro_encoder_encode_lowdelay_transform_data ()

    void                schro_encoder_encode_lowdelay_transform_data
                                                            (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_encode_picture ()

    void                schro_encoder_encode_picture        (SchroAsyncStage *stage);

`stage` : |

### schro_encoder_encode_picture_header ()

    void                schro_encoder_encode_picture_header (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_encode_subband ()

    void                schro_encoder_encode_subband        (SchroEncoderFrame *frame,
                                                             int component,
                                                             int index);

`frame` : |
`component` : |
`index` : |

### schro_encoder_encode_subband_noarith ()

    void                schro_encoder_encode_subband_noarith
                                                            (SchroEncoderFrame *frame,
                                                             int component,
                                                             int index);

`frame` : |
`component` : |
`index` : |

### schro_encoder_engine_backref ()

    int                 schro_encoder_engine_backref        (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_engine_backtest ()

    int                 schro_encoder_engine_backtest       (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_engine_intra_only ()

    int                 schro_encoder_engine_intra_only     (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_engine_lossless ()

    int                 schro_encoder_engine_lossless       (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_engine_lowdelay ()

    int                 schro_encoder_engine_lowdelay       (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_engine_test_intra ()

    int                 schro_encoder_engine_test_intra     (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_estimate_entropy ()

    void                schro_encoder_estimate_entropy      (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_frame_analyse ()

    void                schro_encoder_frame_analyse         (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_frame_downsample ()

    void                schro_encoder_frame_downsample      (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_frame_insert_buffer ()

    void                schro_encoder_frame_insert_buffer   (SchroEncoderFrame *frame,
                                                             SchroBuffer *buffer);

Inserts a buffer into an encoder frame.

`frame` : | an encoder frame
`buffer` : | a buffer

### schro_encoder_frame_new ()

    SchroEncoderFrame * schro_encoder_frame_new             (SchroEncoder *encoder);

`encoder` : |
Returns : |

### schro_encoder_frame_queue_get ()

    SchroFrame *        schro_encoder_frame_queue_get       (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);

`encoder` : |
`frame_number` : |
Returns : |

### schro_encoder_frame_queue_remove ()

    void                schro_encoder_frame_queue_remove    (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);

`encoder` : |
`frame_number` : |

### schro_encoder_frame_ref ()

    void                schro_encoder_frame_ref             (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_frame_unref ()

    void                schro_encoder_frame_unref           (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_init_subbands ()

    void                schro_encoder_init_subbands         (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_insert_buffer ()

    void                schro_encoder_insert_buffer         (SchroEncoder *encoder,
                                                             SchroBuffer *buffer);

Inserts an application-provided buffer into the encoded video stream with the next frame that is pushed.

`encoder` : | an encoder object
`buffer` : | a buffer

### schro_encoder_output_push ()

    void                schro_encoder_output_push           (SchroEncoder *encoder,
                                                             SchroBuffer *buffer,
                                                             int slot,
                                                             int presentation_frame);

`encoder` : |
`buffer` : |
`slot` : |
`presentation_frame` : |

### schro_encoder_perceptual_weight_ccir959 ()

    double              schro_encoder_perceptual_weight_ccir959
                                                            (double cpd);

`cpd` : |
Returns : |

### schro_encoder_perceptual_weight_constant ()

    double              schro_encoder_perceptual_weight_constant
                                                            (double cpd);

`cpd` : |
Returns : |

### schro_encoder_perceptual_weight_moo ()

    double              schro_encoder_perceptual_weight_moo (double cpd);

`cpd` : |
Returns : |

### schro_encoder_postanalyse_picture ()

    void                schro_encoder_postanalyse_picture   (SchroAsyncStage *stage);

`stage` : |

### schro_encoder_push_ready ()

    int                 schro_encoder_push_ready            (SchroEncoder *encoder);

Returns true if the encoder has available space for additional video frames.

`encoder` : | an encoder object
Returns : | TRUE if the encoder is ready for another video frame to be pushed.

### schro_encoder_recalculate_allocations ()

    void                schro_encoder_recalculate_allocations
                                                            (SchroEncoder *encoder);

`encoder` : |

### schro_encoder_reconstruct_picture ()

    void                schro_encoder_reconstruct_picture   (SchroAsyncStage *stage);

`stage` : |

### schro_encoder_reference_get ()

    SchroEncoderFrame * schro_encoder_reference_get         (SchroEncoder *encoder,
                                                             SchroPictureNumber frame_number);

`encoder` : |
`frame_number` : |
Returns : |

### schro_encoder_set_default_subband_weights ()

    void                schro_encoder_set_default_subband_weights
                                                            (SchroEncoder *encoder);

`encoder` : |

### schro_encoder_start ()

    void                schro_encoder_start                 (SchroEncoder *encoder);

Locks in encoder configuration and causes the encoder to start encoding pictures. At this point, the encoder will start worker threads to do the actual encoding.

`encoder` : | an encoder object

### schro_encoder_wait ()

    SchroStateEnum      schro_encoder_wait                  (SchroEncoder *encoder);

Checks the state of the encoder. If the encoder requires the application to do something, an appropriate state code is returned. Otherwise, this function waits until the encoder requires the application to do something.

`encoder` : | an encoder object
Returns : | a state code

### schro_encoder_get_n_settings ()

    int                 schro_encoder_get_n_settings        (void);

Returns : |

### schro_encoder_get_setting_info ()

    const SchroEncoderSetting * schro_encoder_get_setting_info
                                                            (int i);

`i` : |
Returns : |

### schro_encoder_global_estimation ()

    void                schro_encoder_global_estimation     (SchroEncoderFrame *frame);

`frame` : |

### schro_encoder_init_error_tables ()

    void                schro_encoder_init_error_tables     (SchroEncoder *encoder);

`encoder` : |

### schro_encoder_phasecorr_estimation ()

    void                schro_encoder_phasecorr_estimation  (SchroPhaseCorr *pc);

`pc` : |

### schro_encoder_setting_get_double ()

    double              schro_encoder_setting_get_double    (SchroEncoder *encoder,
                                                             const char *name);

`encoder` : | an encoder object
`name` : |
Returns : | the current value of an encoder option given by `name`

### schro_encoder_setting_set_double ()

    void                schro_encoder_setting_set_double    (SchroEncoder *encoder,
                                                             const char *name,
                                                             double d);

set the encoder option given by `name` to `value`.

`encoder` : | an encoder object
`name` : |
`d` : |