## schroframe

schroframe

## Synopsis

                        SchroFrame;
                        SchroFrameData;
    void                (*SchroFrameFreeFunc)               (SchroFrame *frame,
                                                             void *priv);
    enum                SchroFrameFormat;
                        SchroUpsampledFrame;
    #define             SCHRO_FRAME_FORMAT_DEPTH            (format)
    #define             SCHRO_FRAME_FORMAT_DEPTH_S16
    #define             SCHRO_FRAME_FORMAT_DEPTH_S32
    #define             SCHRO_FRAME_FORMAT_DEPTH_U8
    #define             SCHRO_FRAME_FORMAT_H_SHIFT          (format)
    #define             SCHRO_FRAME_FORMAT_V_SHIFT          (format)
    #define             SCHRO_FRAME_IS_PACKED               (format)
    #define             SCHRO_FRAME_DATA_GET_LINE           (fd,i)
    #define             SCHRO_FRAME_DATA_GET_PIXEL_S16      (fd,i,j)
    #define             SCHRO_FRAME_DATA_GET_PIXEL_U8       (fd,i,j)
    SchroFrame *        schro_frame_new                     (void);
    SchroFrame *        schro_frame_new_and_alloc           (SchroMemoryDomain *domain,
                                                             SchroFrameFormat format,
                                                             int width,
                                                             int height);
    SchroFrame *        schro_frame_new_from_data_AYUV      (void *data,
                                                             int width,
                                                             int height);
    SchroFrame *        schro_frame_new_from_data_I420      (void *data,
                                                             int width,
                                                             int height);
    SchroFrame *        schro_frame_new_from_data_YUY2      (void *data,
                                                             int width,
                                                             int height);
    SchroFrame *        schro_frame_dup                     (SchroFrame *frame);
    SchroFrame *        schro_frame_ref                     (SchroFrame *frame);
    void                schro_frame_unref                   (SchroFrame *frame);
    void                schro_frame_set_free_callback       (SchroFrame *frame,
                                                             SchroFrameFreeFunc free_func,
                                                             void *priv);
    SchroFrame *        schro_frame_clone                   (SchroMemoryDomain *domain,
                                                             SchroFrame *frame);
    void                schro_frame_data_get_codeblock      (SchroFrameData *dest,
                                                             SchroFrameData *src,
                                                             int x,
                                                             int y,
                                                             int horiz_codeblocks,
                                                             int vert_codeblocks);
    int                 schro_frame_get_metric              (SchroFrame *frame1,
                                                             int x1,
                                                             int y1,
                                                             SchroFrame *frame2,
                                                             int x2,
                                                             int y2);
    void                schro_frame_get_subdata             (SchroFrame *frame,
                                                             SchroFrameData *fd,
                                                             int comp,
                                                             int x,
                                                             int y);
    void                schro_frame_inverse_iwt_transform_cuda
                                                            (SchroFrame *frame,
                                                             SchroFrame *transform_frame,
                                                             SchroParams *params);
    SchroFrame *        schro_frame_new_from_data_UYVY      (void *data,
                                                             int width,
                                                             int height);
    SchroFrame *        schro_frame_new_from_data_YV12      (void *data,
                                                             int width,
                                                             int height);

    void                schro_frame_convert                 (SchroFrame *dest,
                                                             SchroFrame *src);
    SchroFrame *        schro_frame_convert_to_444          (SchroFrame *frame);
    void                schro_frame_add                     (SchroFrame *dest,
                                                             SchroFrame *src);
    void                schro_frame_subtract                (SchroFrame *dest,
                                                             SchroFrame *src);
    void                schro_frame_shift_left              (SchroFrame *frame,
                                                             int shift);
    void                schro_frame_shift_right             (SchroFrame *frame,
                                                             int shift);
    void                schro_frame_edge_extend             (SchroFrame *frame,
                                                             int width,
                                                             int height);
    void                schro_frame_zero_extend             (SchroFrame *frame,
                                                             int width,
                                                             int height);
    void                schro_frame_iwt_transform           (SchroFrame *frame,
                                                             SchroParams *params);
    void                schro_frame_inverse_iwt_transform   (SchroFrame *frame,
                                                             SchroParams *params);
    void                schro_frame_downsample              (SchroFrame *dest,
                                                             SchroFrame *src);
    void                schro_frame_mark                    (SchroFrame *frame,
                                                             int value);
    void                schro_frame_upsample_horiz          (SchroFrame *dest,
                                                             SchroFrame *src);
    void                schro_frame_upsample_vert           (SchroFrame *dest,
                                                             SchroFrame *src);

    double              schro_frame_ssim                    (SchroFrame *a,
                                                             SchroFrame *b);
    void                schro_frame_mean_squared_error      (SchroFrame *a,
                                                             SchroFrame *b,
                                                             double *mse);
    void                schro_frame_md5                     (SchroFrame *frame,
                                                             uint32_t *state);
    double              schro_frame_calculate_average_luma  (SchroFrame *frame);

    void                schro_upsampled_frame_free          (SchroUpsampledFrame *df);
    SchroUpsampledFrame * schro_upsampled_frame_new         (SchroFrame *frame);
    void                schro_upsampled_frame_upsample      (SchroUpsampledFrame *df);
    void                schro_upsampled_frame_get_block_fast_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int prec,
                                                             SchroFrameData *dest,
                                                             SchroFrameData *fd);
    void                schro_upsampled_frame_get_block_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int prec,
                                                             SchroFrameData *dest);
    int                 schro_upsampled_frame_get_pixel_prec0
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);
    int                 schro_upsampled_frame_get_pixel_prec1
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);
    int                 schro_upsampled_frame_get_pixel_prec3
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);
    int                 schro_upsampled_frame_get_pixel_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int mv_precision);

## Description

## Details

### SchroFrame

    typedef struct {
      int refcount;
      SchroFrameFreeFunc free;
      SchroMemoryDomain *domain;
      void *regions[3];
      void *priv;

      SchroFrameFormat format;
      int width;
      int height;

      SchroFrameData components[3];

      int is_virtual;
      int cached_lines[3][SCHRO_FRAME_CACHE_SIZE];
      SchroFrame *virt_frame1;
      SchroFrame *virt_frame2;
      void (*render_line) (SchroFrame *frame, void *dest, int component, int i);
      void *virt_priv;
      void *virt_priv2;

      int extension;
    } SchroFrame;

### SchroFrameData

    typedef struct {
      SchroFrameFormat format;
      void *data;
      int stride;
      int width;
      int height;
      int length;
      int h_shift;
      int v_shift;
    } SchroFrameData;

### SchroFrameFreeFunc ()

    void                (*SchroFrameFreeFunc)               (SchroFrame *frame,
                                                             void *priv);

`frame` : |
`priv` : |

### enum SchroFrameFormat

    typedef enum _SchroFrameFormat {
      SCHRO_FRAME_FORMAT_U8_444 = 0x00,
      SCHRO_FRAME_FORMAT_U8_422 = 0x01,
      SCHRO_FRAME_FORMAT_U8_420 = 0x03,

      SCHRO_FRAME_FORMAT_S16_444 = 0x04,
      SCHRO_FRAME_FORMAT_S16_422 = 0x05,
      SCHRO_FRAME_FORMAT_S16_420 = 0x07,

      SCHRO_FRAME_FORMAT_S32_444 = 0x08,
      SCHRO_FRAME_FORMAT_S32_422 = 0x09,
      SCHRO_FRAME_FORMAT_S32_420 = 0x0b,

      /* indirectly supported */
      SCHRO_FRAME_FORMAT_YUYV = 0x100, /* YUYV order */
      SCHRO_FRAME_FORMAT_UYVY = 0x101, /* UYVY order */
      SCHRO_FRAME_FORMAT_AYUV = 0x102,
      SCHRO_FRAME_FORMAT_ARGB = 0x103,
      SCHRO_FRAME_FORMAT_RGB = 0x104,
      SCHRO_FRAME_FORMAT_v216 = 0x105,
      SCHRO_FRAME_FORMAT_v210 = 0x106
    } SchroFrameFormat;

### SchroUpsampledFrame

    typedef struct {
      SchroFrame *frames[4];
      void *components[3];
    } SchroUpsampledFrame;

### SCHRO_FRAME_FORMAT_DEPTH()

    #define SCHRO_FRAME_FORMAT_DEPTH(format) ((format) & 0xc)

`format` : |

### SCHRO_FRAME_FORMAT_DEPTH_S16

    #define SCHRO_FRAME_FORMAT_DEPTH_S16 0x04

### SCHRO_FRAME_FORMAT_DEPTH_S32

    #define SCHRO_FRAME_FORMAT_DEPTH_S32 0x08

### SCHRO_FRAME_FORMAT_DEPTH_U8

    #define SCHRO_FRAME_FORMAT_DEPTH_U8 0x00

### SCHRO_FRAME_FORMAT_H_SHIFT()

    #define SCHRO_FRAME_FORMAT_H_SHIFT(format) ((format) & 0x1)

`format` : |

### SCHRO_FRAME_FORMAT_V_SHIFT()

    #define SCHRO_FRAME_FORMAT_V_SHIFT(format) (((format)>>1) & 0x1)

`format` : |

### SCHRO_FRAME_IS_PACKED()

    #define SCHRO_FRAME_IS_PACKED(format) (((format)>>8) & 0x1)

`format` : |

### SCHRO_FRAME_DATA_GET_LINE()

    #define SCHRO_FRAME_DATA_GET_LINE(fd,i) (SCHRO_OFFSET((fd)->data,(fd)->stride*(i)))

`fd` : |
`i` : |

### SCHRO_FRAME_DATA_GET_PIXEL_S16()

    #define SCHRO_FRAME_DATA_GET_PIXEL_S16(fd,i,j) ((int16_t *)SCHRO_OFFSET((fd)->data,(fd)->stride*(j)+(i)*sizeof(int16_t)))

`fd` : |
`i` : |
`j` : |

### SCHRO_FRAME_DATA_GET_PIXEL_U8()

    #define SCHRO_FRAME_DATA_GET_PIXEL_U8(fd,i,j) ((uint8_t *)SCHRO_OFFSET((fd)->data,(fd)->stride*(j)+(i)))

`fd` : |
`i` : |
`j` : |

### schro_frame_new ()

    SchroFrame *        schro_frame_new                     (void);

Creates a new SchroFrame object. The created frame is uninitialized and has no data storage associated with it. The caller must fill in the required information.

Returns : | a new SchroFrame object

### schro_frame_new_and_alloc ()

    SchroFrame *        schro_frame_new_and_alloc           (SchroMemoryDomain *domain,
                                                             SchroFrameFormat format,
                                                             int width,
                                                             int height);

Creates a new SchroFrame object with the requested size and format.

`domain` : |
`format` : |
`width` : |
`height` : |
Returns : | a new SchroFrame object

### schro_frame_new_from_data_AYUV ()

    SchroFrame *        schro_frame_new_from_data_AYUV      (void *data,
                                                             int width,
                                                             int height);

Creates a new SchroFrame object with the requested size using the data pointed to by `data`. The data must be in AYUV format. The data must remain for the lifetime of the SchroFrame object. It is recommended to use `schro_frame_set_free_callback()` for notification when the data is no longer needed.

`data` : |
`width` : |
`height` : |
Returns : | a new SchroFrame object

### schro_frame_new_from_data_I420 ()

    SchroFrame *        schro_frame_new_from_data_I420      (void *data,
                                                             int width,
                                                             int height);

Creates a new SchroFrame object with the requested size using the data pointed to by `data`. The data must be in I420 format. The data must remain for the lifetime of the SchroFrame object. It is recommended to use `schro_frame_set_free_callback()` for notification when the data is no longer needed.

`data` : |
`width` : |
`height` : |
Returns : | a new SchroFrame object

### schro_frame_new_from_data_YUY2 ()

    SchroFrame *        schro_frame_new_from_data_YUY2      (void *data,
                                                             int width,
                                                             int height);

Creates a new SchroFrame object with the requested size using the data pointed to by `data`. The data must be in UYVY format, although the row stride is allowed to be different than what would normally be calculated from `width`. The data must remain for the lifetime of the SchroFrame object. It is recommended to use `schro_frame_set_free_callback()` for notification when the data is no longer needed.

`data` : |
`width` : |
`height` : |
Returns : | a new SchroFrame object

### schro_frame_dup ()

    SchroFrame *        schro_frame_dup                     (SchroFrame *frame);

Creates a new SchroFrame object with the same dimensions and format as `frame`, and copies the data from the `frame` to the new object.

`frame` : |
Returns : | a new SchroFrame object

### schro_frame_ref ()

    SchroFrame *        schro_frame_ref                     (SchroFrame *frame);

Increases the reference count of `frame`.

`frame` : | a frame object
Returns : | the value of `frame`

### schro_frame_unref ()

    void                schro_frame_unref                   (SchroFrame *frame);

Decreases the reference count of `frame`. If the new reference count is 0, the frame is freed. If a frame free callback was set, this function is called.

`frame` : | a frame object

### schro_frame_set_free_callback ()

    void                schro_frame_set_free_callback       (SchroFrame *frame,
                                                             SchroFrameFreeFunc free_func,
                                                             void *priv);

Sets a function that will be called when the object reference count drops to zero and the object is freed.

`frame` : | a frame object
`free_func` : | the function to call when the frame is freed
`priv` : | callback key

### schro_frame_clone ()

    SchroFrame *        schro_frame_clone                   (SchroMemoryDomain *domain,
                                                             SchroFrame *frame);

Creates a new SchroFrame object with the same dimensions and format as `frame`. This function leaves the data in the new object uninitialized.

`domain` : |
`frame` : |
Returns : | a new SchroFrame object

### schro_frame_data_get_codeblock ()

    void                schro_frame_data_get_codeblock      (SchroFrameData *dest,
                                                             SchroFrameData *src,
                                                             int x,
                                                             int y,
                                                             int horiz_codeblocks,
                                                             int vert_codeblocks);

`dest` : |
`src` : |
`x` : |
`y` : |
`horiz_codeblocks` : |
`vert_codeblocks` : |

### schro_frame_get_metric ()

    int                 schro_frame_get_metric              (SchroFrame *frame1,
                                                             int x1,
                                                             int y1,
                                                             SchroFrame *frame2,
                                                             int x2,
                                                             int y2);

`frame1` : |
`x1` : |
`y1` : |
`frame2` : |
`x2` : |
`y2` : |
Returns : |

### schro_frame_get_subdata ()

    void                schro_frame_get_subdata             (SchroFrame *frame,
                                                             SchroFrameData *fd,
                                                             int comp,
                                                             int x,
                                                             int y);

`frame` : |
`fd` : |
`comp` : |
`x` : |
`y` : |

### schro_frame_inverse_iwt_transform_cuda ()

    void                schro_frame_inverse_iwt_transform_cuda
                                                            (SchroFrame *frame,
                                                             SchroFrame *transform_frame,
                                                             SchroParams *params);

`frame` : |
`transform_frame` : |
`params` : |

### schro_frame_new_from_data_UYVY ()

    SchroFrame *        schro_frame_new_from_data_UYVY      (void *data,
                                                             int width,
                                                             int height);

`data` : |
`width` : |
`height` : |
Returns : |

### schro_frame_new_from_data_YV12 ()

    SchroFrame *        schro_frame_new_from_data_YV12      (void *data,
                                                             int width,
                                                             int height);

Creates a new SchroFrame object with the requested size using the data pointed to by `data`. The data must be in YV12 format. The data must remain for the lifetime of the SchroFrame object. It is recommended to use `schro_frame_set_free_callback()` for notification when the data is no longer needed.

`data` : |
`width` : |
`height` : |
Returns : | a new SchroFrame object

### schro_frame_convert ()

    void                schro_frame_convert                 (SchroFrame *dest,
                                                             SchroFrame *src);

Copies data from the source frame to the destination frame, converting formats if necessary. Only a few conversions are supported.

`dest` : | destination frame
`src` : | source frame

### schro_frame_convert_to_444 ()

    SchroFrame *        schro_frame_convert_to_444          (SchroFrame *frame);

`frame` : |
Returns : |

### schro_frame_add ()

    void                schro_frame_add                     (SchroFrame *dest,
                                                             SchroFrame *src);

Adds data from the source frame to the destination frame. The frames must have the same chroma subsampling, and only a few combinations of bit depths are supported.

`dest` : | destination frame
`src` : | source frame

### schro_frame_subtract ()

    void                schro_frame_subtract                (SchroFrame *dest,
                                                             SchroFrame *src);

Subtracts data from the source frame to the destination frame. The frames must have the same chroma subsampling, and only a few combinations of bit depths are supported.

`dest` : | destination frame
`src` : | source frame

### schro_frame_shift_left ()

    void                schro_frame_shift_left              (SchroFrame *frame,
                                                             int shift);

Shifts each value in `frame` to the left by `shift` bits. This operation happens in-place.

`frame` : | frame
`shift` : | number of bits to shift

### schro_frame_shift_right ()

    void                schro_frame_shift_right             (SchroFrame *frame,
                                                             int shift);

Shifts each value in `frame` to the right by `shift` bits. This operation happens in-place.

`frame` : | frame
`shift` : | number of bits to shift

### schro_frame_edge_extend ()

    void                schro_frame_edge_extend             (SchroFrame *frame,
                                                             int width,
                                                             int height);

Extends the edges of the subpicture defined from 0,0 to `width`,`height` to the size of `frame`.

`frame` : | frame
`width` : | width of subpicture
`height` : | height of subpicture

### schro_frame_zero_extend ()

    void                schro_frame_zero_extend             (SchroFrame *frame,
                                                             int width,
                                                             int height);

`frame` : |
`width` : |
`height` : |

### schro_frame_iwt_transform ()

    void                schro_frame_iwt_transform           (SchroFrame *frame,
                                                             SchroParams *params);

Performs an in-place integer wavelet transform on `frame`. The frame must have a bit depth of 16.

`frame` : | frame
`params` : | transform parameters

### schro_frame_inverse_iwt_transform ()

    void                schro_frame_inverse_iwt_transform   (SchroFrame *frame,
                                                             SchroParams *params);

Performs an in-place inverse integer wavelet transform on `frame`. The frame must have a bit depth of 16.

`frame` : | frame
`params` : | transform parameters

### schro_frame_downsample ()

    void                schro_frame_downsample              (SchroFrame *dest,
                                                             SchroFrame *src);

`dest` : |
`src` : |

### schro_frame_mark ()

    void                schro_frame_mark                    (SchroFrame *frame,
                                                             int value);

`frame` : |
`value` : |

### schro_frame_upsample_horiz ()

    void                schro_frame_upsample_horiz          (SchroFrame *dest,
                                                             SchroFrame *src);

`dest` : |
`src` : |

### schro_frame_upsample_vert ()

    void                schro_frame_upsample_vert           (SchroFrame *dest,
                                                             SchroFrame *src);

`dest` : |
`src` : |

### schro_frame_ssim ()

    double              schro_frame_ssim                    (SchroFrame *a,
                                                             SchroFrame *b);

`a` : |
`b` : |
Returns : |

### schro_frame_mean_squared_error ()

    void                schro_frame_mean_squared_error      (SchroFrame *a,
                                                             SchroFrame *b,
                                                             double *mse);

`a` : |
`b` : |
`mse` : |

### schro_frame_md5 ()

    void                schro_frame_md5                     (SchroFrame *frame,
                                                             uint32_t *state);

`frame` : |
`state` : |

### schro_frame_calculate_average_luma ()

    double              schro_frame_calculate_average_luma  (SchroFrame *frame);

`frame` : |
Returns : |

### schro_upsampled_frame_free ()

    void                schro_upsampled_frame_free          (SchroUpsampledFrame *df);

`df` : |

### schro_upsampled_frame_new ()

    SchroUpsampledFrame * schro_upsampled_frame_new         (SchroFrame *frame);

`frame` : |
Returns : |

### schro_upsampled_frame_upsample ()

    void                schro_upsampled_frame_upsample      (SchroUpsampledFrame *df);

`df` : |

### schro_upsampled_frame_get_block_fast_precN ()

    void                schro_upsampled_frame_get_block_fast_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int prec,
                                                             SchroFrameData *dest,
                                                             SchroFrameData *fd);

`upframe` : |
`k` : |
`x` : |
`y` : |
`prec` : |
`dest` : |
`fd` : |

### schro_upsampled_frame_get_block_precN ()

    void                schro_upsampled_frame_get_block_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int prec,
                                                             SchroFrameData *dest);

`upframe` : |
`k` : |
`x` : |
`y` : |
`prec` : |
`dest` : |

### schro_upsampled_frame_get_pixel_prec0 ()

    int                 schro_upsampled_frame_get_pixel_prec0
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);

`upframe` : |
`k` : |
`x` : |
`y` : |
Returns : |

### schro_upsampled_frame_get_pixel_prec1 ()

    int                 schro_upsampled_frame_get_pixel_prec1
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);

`upframe` : |
`k` : |
`x` : |
`y` : |
Returns : |

### schro_upsampled_frame_get_pixel_prec3 ()

    int                 schro_upsampled_frame_get_pixel_prec3
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y);

`upframe` : |
`k` : |
`x` : |
`y` : |
Returns : |

### schro_upsampled_frame_get_pixel_precN ()

    int                 schro_upsampled_frame_get_pixel_precN
                                                            (SchroUpsampledFrame *upframe,
                                                             int k,
                                                             int x,
                                                             int y,
                                                             int mv_precision);

`upframe` : |
`k` : |
`x` : |
`y` : |
`mv_precision` : |
Returns : |