## schrodecoder

schrodecoder

## Synopsis

                        SchroDecoder;
    SchroDecoder *      schro_decoder_new                   (void);
    void                schro_decoder_free                  (SchroDecoder *decoder);
    void                schro_decoder_reset                 (SchroDecoder *decoder);
    SchroVideoFormat *  schro_decoder_get_video_format      (SchroDecoder *decoder);
    void                schro_decoder_add_output_picture    (SchroDecoder *decoder,
                                                             SchroFrame *frame);
    int                 schro_decoder_push_ready            (SchroDecoder *decoder);
    int                 schro_decoder_push                  (SchroDecoder *decoder,
                                                             SchroBuffer *buffer);
    int                 schro_decoder_push_end_of_stream    (SchroDecoder *decoder);
    SchroFrame *        schro_decoder_pull                  (SchroDecoder *decoder);
    int                 schro_decoder_wait                  (SchroDecoder *decoder);
    void                schro_decoder_set_earliest_frame    (SchroDecoder *decoder,
                                                             SchroPictureNumber earliest_frame);
    void                schro_decoder_set_skip_ratio        (SchroDecoder *decoder,
                                                             double ratio);
    SchroPictureNumber  schro_decoder_get_picture_number    (SchroDecoder *decoder);

    int                 schro_decoder_decode_parse_header   (SchroUnpack *unpack);
    void                schro_decoder_decode_transform_data (SchroPicture *picture);
    void                schro_decoder_decode_lowdelay_transform_data
                                                            (SchroPicture *picture);
    void                schro_decoder_subband_dc_predict    (SchroFrameData *fd);
    void                schro_decoder_decode_block_data     (SchroPicture *picture);
    void                schro_decoder_decode_macroblock     (SchroPicture *picture,
                                                             SchroArith **arith,
                                                             SchroUnpack *unpack,
                                                             int i,
                                                             int j);
    void                schro_decoder_decode_prediction_unit
                                                            (SchroPicture *picture,
                                                             SchroArith **arith,
                                                             SchroUnpack *unpack,
                                                             SchroMotionVector *motion_vectors,
                                                             int x,
                                                             int y);
    void                schro_decoder_init_subband_frame_data_interleaved
                                                            (SchroPicture *picture);
    int                 schro_decoder_iterate_picture       (SchroDecoderInstance *instance,
                                                             SchroBuffer *buffer,
                                                             SchroUnpack *unpack,
                                                             int parse_code);
    void                schro_decoder_parse_block_data      (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_lowdelay_transform_data
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_picture         (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_picture_header  (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_picture_prediction_parameters
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_transform_data  (SchroPicture *picture,
                                                             SchroUnpack *unpack);
    void                schro_decoder_parse_transform_parameters
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);
                        SchroPicture;
    SchroPicture *      schro_picture_new                   (SchroDecoderInstance *instance);
    SchroPicture *      schro_picture_ref                   (SchroPicture *picture);
    void                schro_picture_unref                 (SchroPicture *picture);

## Description

## Details

### SchroDecoder

    typedef struct {
    } SchroDecoder;

### schro_decoder_new ()

    SchroDecoder *      schro_decoder_new                   (void);

Creates a new decoder object. The decoder object should be freed using @`schro_decoder_free()` when it is no longer needed.

Returns : | a new decoder object

### schro_decoder_free ()

    void                schro_decoder_free                  (SchroDecoder *decoder);

Frees a decoder object.

`decoder` : | decoder object

### schro_decoder_reset ()

    void                schro_decoder_reset                 (SchroDecoder *decoder);

Resets the internal state of the decoder. This function should be called after a discontinuity of the stream, for example, as the result of a seek.

`decoder` : | a decoder object

### schro_decoder_get_video_format ()

    SchroVideoFormat *  schro_decoder_get_video_format      (SchroDecoder *decoder);

Returns a structure containing information on the video format being decoded by the decoder. This structure should be freed using `free()` when it is no longer needed.

`decoder` : | a decoder object
Returns : | a video format structure

### schro_decoder_add_output_picture ()

    void                schro_decoder_add_output_picture    (SchroDecoder *decoder,
                                                             SchroFrame *frame);

Adds a frame provided by the application to the picture queue. Frames in the picture queue will be used for decoding images, and are eventually returned to the application by `schro_decoder_pull()`.

The caller loses its reference to `frame` after calling this function.

`decoder` : | a decoder object
`frame` : | the frame to add to the picture queue

### schro_decoder_push_ready ()

    int                 schro_decoder_push_ready            (SchroDecoder *decoder);

This function is used by the application to determine if it should push more data to the decoder.

`decoder` : | a decoder object
Returns : | TRUE if the decoder is ready for more data

### schro_decoder_push ()

    int                 schro_decoder_push                  (SchroDecoder *decoder,
                                                             SchroBuffer *buffer);

`decoder` : |
`buffer` : |
Returns : |

### schro_decoder_push_end_of_stream ()

    int                 schro_decoder_push_end_of_stream    (SchroDecoder *decoder);

`decoder` : |
Returns : |

### schro_decoder_pull ()

    SchroFrame *        schro_decoder_pull                  (SchroDecoder *decoder);

Removes the next picture from the picture queue and returns a frame containing the image.

The application provides the frames that pictures are decoded into, and the same frames are returned from this function. However, the order of frames returned may be different than the order that the application provides the frames to the decoder.

An exception to this is that skipped frames are indicated by a frame having a height and width equal to 0. This frame is created using @`schro_frame_new()`, and is not one of the frames provided by the application.

Frames should be freed using @`schro_frame_unref()` when no longer needed. The frame must not be reused by the application, since it may contain a reference frame still in use by the decoder.

`decoder` : | a decoder object
Returns : | the next picture

### schro_decoder_wait ()

    int                 schro_decoder_wait                  (SchroDecoder *decoder);

Waits until the decoder requires the application to do something, e.g., push more data or remove a frame from the picture queue, and then returns the decoder status.

`decoder` : | a decoder object
Returns : | decoder status

### schro_decoder_set_earliest_frame ()

    void                schro_decoder_set_earliest_frame    (SchroDecoder *decoder,
                                                             SchroPictureNumber earliest_frame);

The application can tell the decoder the earliest frame it is interested in by calling this function. Subsequent calls to `schro_decoder_pull()` will only return pictures with picture numbers greater than or equal to this number. The decoder will avoid decoding pictures that will not be displayed or used as reference pictures.

This feature can be used for frame-accurate seeking.

This function can be called at any time during decoding. Calling this function with a picture number less than the current earliest frame setting is invalid.

`decoder` : | a decoder object
`earliest_frame` : | the earliest frame that the application is interested in

### schro_decoder_set_skip_ratio ()

    void                schro_decoder_set_skip_ratio        (SchroDecoder *decoder,
                                                             double ratio);

Sets the skip ratio of the decoder. The skip ratio is used by the decoder to skip decoding of some pictures. Reference pictures are always decoded.

A picture is skipped when the running average of the proportion of pictures skipped is less than the skip ratio. Reference frames are always decoded and contribute to the running average. Thus, the actual ratio of skipped pictures may be larger than the requested skip ratio.

The decoder indicates a skipped picture in the pictures returned by @`schro_decoder_pull()` by a frame that has a width and height of 0.

The default skip ratio is 1.0, indicating that all pictures should be decoded. A skip ratio of 0.0 indicates that no pictures should be decoded, although as mentioned above, some pictures will be decoded anyway. Values outside the range of 0.0 to 1.0 are quietly clamped to that range.

This function may be called at any time during decoding.

`decoder` : | a decoder object
`ratio` : | skip ratio.

### schro_decoder_get_picture_number ()

    SchroPictureNumber  schro_decoder_get_picture_number    (SchroDecoder *decoder);

Returns the picture number of the next picture that will be returned by @`schro_decoder_pull()`.

`decoder` : | a decoder object
Returns : | a picture number

### schro_decoder_decode_parse_header ()

    int                 schro_decoder_decode_parse_header   (SchroUnpack *unpack);

`unpack` : |
Returns : |

### schro_decoder_decode_transform_data ()

    void                schro_decoder_decode_transform_data (SchroPicture *picture);

`picture` : |

### schro_decoder_decode_lowdelay_transform_data ()

    void                schro_decoder_decode_lowdelay_transform_data
                                                            (SchroPicture *picture);

`picture` : |

### schro_decoder_subband_dc_predict ()

    void                schro_decoder_subband_dc_predict    (SchroFrameData *fd);

`fd` : |

### schro_decoder_decode_block_data ()

    void                schro_decoder_decode_block_data     (SchroPicture *picture);

`picture` : |

### schro_decoder_decode_macroblock ()

    void                schro_decoder_decode_macroblock     (SchroPicture *picture,
                                                             SchroArith **arith,
                                                             SchroUnpack *unpack,
                                                             int i,
                                                             int j);

`picture` : |
`arith` : |
`unpack` : |
`i` : |
`j` : |

### schro_decoder_decode_prediction_unit ()

    void                schro_decoder_decode_prediction_unit
                                                            (SchroPicture *picture,
                                                             SchroArith **arith,
                                                             SchroUnpack *unpack,
                                                             SchroMotionVector *motion_vectors,
                                                             int x,
                                                             int y);

`picture` : |
`arith` : |
`unpack` : |
`motion_vectors` : |
`x` : |
`y` : |

### schro_decoder_init_subband_frame_data_interleaved ()

    void                schro_decoder_init_subband_frame_data_interleaved
                                                            (SchroPicture *picture);

`picture` : |

### schro_decoder_iterate_picture ()

    int                 schro_decoder_iterate_picture       (SchroDecoderInstance *instance,
                                                             SchroBuffer *buffer,
                                                             SchroUnpack *unpack,
                                                             int parse_code);

`instance` : |
`buffer` : |
`unpack` : |
`parse_code` : |
Returns : |

### schro_decoder_parse_block_data ()

    void                schro_decoder_parse_block_data      (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_lowdelay_transform_data ()

    void                schro_decoder_parse_lowdelay_transform_data
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_picture ()

    void                schro_decoder_parse_picture         (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_picture_header ()

    void                schro_decoder_parse_picture_header  (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_picture_prediction_parameters ()

    void                schro_decoder_parse_picture_prediction_parameters
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_transform_data ()

    void                schro_decoder_parse_transform_data  (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### schro_decoder_parse_transform_parameters ()

    void                schro_decoder_parse_transform_parameters
                                                            (SchroPicture *picture,
                                                             SchroUnpack *unpack);

`picture` : |
`unpack` : |

### SchroPicture

    typedef struct {
      int refcount;

      SchroDecoderInstance *decoder_instance;

      int busy;
      int skip;
      int error;

      SchroBuffer *input_buffer;
      SchroParams params;
      SchroPictureNumber picture_number;
      SchroPictureNumber reference1;
      SchroPictureNumber reference2;
      SchroPictureNumber retired_picture_number;
      SchroPicture *ref0;
      SchroPicture *ref1;
      SchroFrame *planar_output_frame;

      SchroAsyncStage stages[9];

      int is_ref;

      int zero_residual;

      SchroFrame *transform_frame;
      SchroFrame *frame;
      SchroFrame *mc_tmp_frame;
      SchroMotion *motion;
      SchroFrame *output_picture;
      SchroUpsampledFrame *upsampled_frame;

      int subband_length[3][SCHRO_LIMIT_SUBBANDS];
      int subband_quant_index[3][SCHRO_LIMIT_SUBBANDS];
      SchroBuffer *subband_buffer[3][SCHRO_LIMIT_SUBBANDS];
      SchroFrameData subband_data[3][SCHRO_LIMIT_SUBBANDS];

      SchroBuffer *motion_buffers[9];

      SchroBuffer *lowdelay_buffer;

      int has_md5;
      uint8_t md5_checksum[32];

      /* private data that is associated with this picture */
      SchroTag *tag;
    } SchroPicture;

### schro_picture_new ()

    SchroPicture *      schro_picture_new                   (SchroDecoderInstance *instance);

Creates a new picture for `decoder`.

Internal API.

`instance` : |
Returns : | a new picture

### schro_picture_ref ()

    SchroPicture *      schro_picture_ref                   (SchroPicture *picture);

`picture` : |
Returns : |

### schro_picture_unref ()

    void                schro_picture_unref                 (SchroPicture *picture);

`picture` : |