## liboilfuncs-doc

liboilfuncs-doc

## Synopsis

    void                oil_clip_f32                        (float *dest,
                                                             int dstr,
                                                             const float *src,
                                                             int sstr,
                                                             int n,
                                                             const float *s2_1,
                                                             const float *s3_1);
    void                oil_clip_f64                        (double *dest,
                                                             int dstr,
                                                             const double *src,
                                                             int sstr,
                                                             int n,
                                                             const double *s2_1,
                                                             const double *s3_1);
    void                oil_clip_s16                        (int16_t *dest,
                                                             int dstr,
                                                             const int16_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int16_t *s2_1,
                                                             const int16_t *s3_1);
    void                oil_clip_s32                        (int32_t *dest,
                                                             int dstr,
                                                             const int32_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int32_t *s2_1,
                                                             const int32_t *s3_1);
    void                oil_clip_s8                         (int8_t *dest,
                                                             int dstr,
                                                             const int8_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int8_t *s2_1,
                                                             const int8_t *s3_1);
    void                oil_clip_u16                        (uint16_t *dest,
                                                             int dstr,
                                                             const uint16_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint16_t *s2_1,
                                                             const uint16_t *s3_1);
    void                oil_clip_u32                        (uint32_t *dest,
                                                             int dstr,
                                                             const uint32_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint32_t *s2_1,
                                                             const uint32_t *s3_1);
    void                oil_clip_u8                         (uint8_t *dest,
                                                             int dstr,
                                                             const uint8_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint8_t *s2_1,
                                                             const uint8_t *s3_1);
    void                oil_dequantize8x8_s16               (int16_t *d_8x8,
                                                             int dstr,
                                                             const int16_t *s1_8x8,
                                                             int sstr1,
                                                             const int16_t *s2_8x8,
                                                             int sstr2);
    void                oil_diffsquaresum_f64               (double *d_1,
                                                             const double *src1,
                                                             int sstr1,
                                                             const double *src2,
                                                             int sstr2,
                                                             int n);
    void                oil_md5                             (uint32_t *i_4,
                                                             const uint32_t *s_16);
    void                oil_mix_u8                          (uint8_t *dest,
                                                             const uint8_t *src1,
                                                             const uint8_t *src2,
                                                             const uint8_t *src3,
                                                             int n);
    void                oil_null                            (void);
    void                oil_scanlinescale2_u8               (uint8_t *d,
                                                             const uint8_t *s,
                                                             int n);
    void                oil_sincos_f64                      (double *dest1,
                                                             double *dest2,
                                                             int n,
                                                             const double *s1_1,
                                                             const double *s2_1);
    void                oil_utf8_validate                   (int32_t *d_1,
                                                             const uint8_t *s,
                                                             int n);
    void                oil_diff8x8_s16_u8                  (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);
    void                oil_diff8x8_average_s16_u8          (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2,
                                                             const uint8_t *s3_8x8,
                                                             int ss3);
    void                oil_err_inter8x8_u8_avg             (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             const uint8_t *s3_8x8,
                                                             int ss2);
    void                oil_recon8x8_inter                  (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const int16_t *s2_8x8);
    void                oil_err_intra8x8_u8                 (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1);
    void                oil_recon8x8_intra                  (uint8_t *d_8x8,
                                                             int ds,
                                                             const int16_t *s_8x8);
    void                oil_colsad8x8_u8                    (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);
    void                oil_composite_over_u8               (uint8_t *i_n,
                                                             const uint8_t *s1_n,
                                                             int n);
    void                oil_diff8x8_const128_s16_u8         (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1);
    void                oil_copy8x8_u8                      (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s_8x8,
                                                             int ss);
    void                oil_err_inter8x8_u8                 (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);
    void                oil_fdct8x8theora                   (const int16_t *s_8x8,
                                                             int16_t *d_8x8);
    void                oil_rowsad8x8_u8                    (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             const uint8_t *s2_8x8);
    void                oil_recon8x8_inter2                 (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2,
                                                             const int16_t *s3_8x8);
    void                oil_composite_add_u8                (uint8_t *i_n,
                                                             const uint8_t *s1_n,
                                                             int n);
    void                oil_sad8x8_u8_avg                   (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             const uint8_t *s3_8x8,
                                                             int ss2);

## Description

## Details

### oil_clip_f32 ()

    void                oil_clip_f32                        (float *dest,
                                                             int dstr,
                                                             const float *src,
                                                             int sstr,
                                                             int n,
                                                             const float *s2_1,
                                                             const float *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_f64 ()

    void                oil_clip_f64                        (double *dest,
                                                             int dstr,
                                                             const double *src,
                                                             int sstr,
                                                             int n,
                                                             const double *s2_1,
                                                             const double *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_s16 ()

    void                oil_clip_s16                        (int16_t *dest,
                                                             int dstr,
                                                             const int16_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int16_t *s2_1,
                                                             const int16_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_s32 ()

    void                oil_clip_s32                        (int32_t *dest,
                                                             int dstr,
                                                             const int32_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int32_t *s2_1,
                                                             const int32_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_s8 ()

    void                oil_clip_s8                         (int8_t *dest,
                                                             int dstr,
                                                             const int8_t *src,
                                                             int sstr,
                                                             int n,
                                                             const int8_t *s2_1,
                                                             const int8_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_u16 ()

    void                oil_clip_u16                        (uint16_t *dest,
                                                             int dstr,
                                                             const uint16_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint16_t *s2_1,
                                                             const uint16_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_u32 ()

    void                oil_clip_u32                        (uint32_t *dest,
                                                             int dstr,
                                                             const uint32_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint32_t *s2_1,
                                                             const uint32_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_clip_u8 ()

    void                oil_clip_u8                         (uint8_t *dest,
                                                             int dstr,
                                                             const uint8_t *src,
                                                             int sstr,
                                                             int n,
                                                             const uint8_t *s2_1,
                                                             const uint8_t *s3_1);

Clips each value in `src` to the range [`s2_1`,`s3_1`] and places the result in `dest`.

`dest` : |
`dstr` : |
`src` : |
`sstr` : |
`n` : |
`s2_1` : |
`s3_1` : |

### oil_dequantize8x8_s16 ()

    void                oil_dequantize8x8_s16               (int16_t *d_8x8,
                                                             int dstr,
                                                             const int16_t *s1_8x8,
                                                             int sstr1,
                                                             const int16_t *s2_8x8,
                                                             int sstr2);

Multiplies each element in `s1_8x8` by the corresponding element in `s2_8x8` and places the result in `d_8x8`.

`d_8x8` : |
`dstr` : |
`s1_8x8` : |
`sstr1` : |
`s2_8x8` : |
`sstr2` : |

### oil_diffsquaresum_f64 ()

    void                oil_diffsquaresum_f64               (double *d_1,
                                                             const double *src1,
                                                             int sstr1,
                                                             const double *src2,
                                                             int sstr2,
                                                             int n);

Calculates the sum of squared differences between `src1` and `src2` and places the result in `d_1`.

`d_1` : |
`src1` : |
`sstr1` : |
`src2` : |
`sstr2` : |
`n` : |

### oil_md5 ()

    void                oil_md5                             (uint32_t *i_4,
                                                             const uint32_t *s_16);

Performs an MD5 checksum iteration. The iteration operates on the 64 bytes contained in `s_16`, and changes the hash contained in `i_4`. This only implements a portion of the MD5 algorithm. The full MD5 algorithm requires initializing the hash with a specific value and additional handling of bytes at the end of the stream.

See also the md5 example in the Liboil source code.

FIXME: need a reference here

`i_4` : |
`s_16` : |

### oil_mix_u8 ()

    void                oil_mix_u8                          (uint8_t *dest,
                                                             const uint8_t *src1,
                                                             const uint8_t *src2,
                                                             const uint8_t *src3,
                                                             int n);

Performs the compisiting operation DEST = (SRC2 IN MASK) OVER SRC1, except it is done incorrectly, so this function should not be used.

FIXME: This function is broken.

`dest` : | DEST
`src1` : | SRC1
`src2` : | SRC2
`src3` : | MASK
`n` : |

### oil_null ()

    void                oil_null                            (void);

Does nothing, and does it fast.

This function is useful for testing the overhead of calling a Liboil function.

### oil_scanlinescale2_u8 ()

    void                oil_scanlinescale2_u8               (uint8_t *d,
                                                             const uint8_t *s,
                                                             int n);

Upsamples the source array by a factor of two. That is, if the values in `s` are A,B,C,D,E, the values written to `d` are A,A,B,B,C,C,D,D,E,E. Note that `n` is the number of elements written to `d`, and that half of `s` is not used.

`d` : | destination array
`s` : | source array
`n` : | number of elements

### oil_sincos_f64 ()

    void                oil_sincos_f64                      (double *dest1,
                                                             double *dest2,
                                                             int n,
                                                             const double *s1_1,
                                                             const double *s2_1);

Calculates sin(x) and cos(x) and places the results in `dest1` and `dest2` respectively. Values for x start at `s1_1` and are incremented by `s2_1` for each destination element.

`dest1` : |
`dest2` : |
`n` : |
`s1_1` : |
`s2_1` : |

### oil_utf8_validate ()

    void                oil_utf8_validate                   (int32_t *d_1,
                                                             const uint8_t *s,
                                                             int n);

Checks `s` for valid UTF-8 characters. If the entire `s` array represents valid UTF-8 characters, `n` is written to `d_1`. Otherwise, the index in the array of the beginning of the first invalid UTF-8 character is written to `d_1`.

`d_1` : |
`s` : |
`n` : |

### oil_diff8x8_s16_u8 ()

    void                oil_diff8x8_s16_u8                  (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);

Calculates the difference of each value in `s1_8x8` and `s2_8x8` and places the result in `d_8x8`. Note that the destination type is larger than the source type.

`d_8x8` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`ss2` : |

### oil_diff8x8_average_s16_u8 ()

    void                oil_diff8x8_average_s16_u8          (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2,
                                                             const uint8_t *s3_8x8,
                                                             int ss3);

Calculates the difference of each value in `s1_8x8` and the average of `s2_8x8` and `s3_8x8`, and places the result in `d_8x8`. Note that the destination type is larger than the source type.

`d_8x8` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`ss2` : |
`s3_8x8` : |
`ss3` : |

### oil_err_inter8x8_u8_avg ()

    void                oil_err_inter8x8_u8_avg             (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             const uint8_t *s3_8x8,
                                                             int ss2);

Calculates an intermediate 8x8 block where each element is the difference between `s1_8x8` and the average of `s2_8x8` and `s3_8x8`. The sum of squares of the difference of each element in the intermediate block and the mean of the intermediate block is placed into `d_1`. This result is 64 times the variance of the mean of the intermediate block.

FIXME: This function is broken, since the reference function uses `ss2` as the stride for both `s2_8x8` and `s3_8x8`.

`d_1` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`s3_8x8` : |
`ss2` : |

### oil_recon8x8_inter ()

    void                oil_recon8x8_inter                  (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const int16_t *s2_8x8);

Adds each element in `s1_8x8` and `s2_8x8`, clamps to the range [0,255], and places the result in the destination array.

`d_8x8` : |
`ds` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |

### oil_err_intra8x8_u8 ()

    void                oil_err_intra8x8_u8                 (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1);

Calculates the sum of squared differences from the mean over `s1_8x8` and places the result in `d_1`. This result is 64 times the variance of the mean of `s1_8x8`.

`d_1` : |
`s1_8x8` : |
`ss1` : |

### oil_recon8x8_intra ()

    void                oil_recon8x8_intra                  (uint8_t *d_8x8,
                                                             int ds,
                                                             const int16_t *s_8x8);

Adds 128 to each value in the source array, clamps to the range [0,255], and places the result in the destination array.

`d_8x8` : |
`ds` : |
`s_8x8` : |

### oil_colsad8x8_u8 ()

    void                oil_colsad8x8_u8                    (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);

Divides the 8x8 block into 16 1x4 regions, and calculates the sum of absolute differences between `s1_8x8` and `s2_8x8` for each region. The maximum of the results in each region is placed in `d_1`.

`d_1` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`ss2` : |

### oil_composite_over_u8 ()

    void                oil_composite_over_u8               (uint8_t *i_n,
                                                             const uint8_t *s1_n,
                                                             int n);

Performs the compositing operation DEST = SRC OVER DEST.

`i_n` : | DEST
`s1_n` : | SRC
`n` : | number of elements

### oil_diff8x8_const128_s16_u8 ()

    void                oil_diff8x8_const128_s16_u8         (int16_t *d_8x8,
                                                             const uint8_t *s1_8x8,
                                                             int ss1);

Subtracts 128 from each value in `s1_8x8` and places the result in `d_8x8`. Note that the destination type is larger than the source type.

`d_8x8` : |
`s1_8x8` : |
`ss1` : |

### oil_copy8x8_u8 ()

    void                oil_copy8x8_u8                      (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s_8x8,
                                                             int ss);

Copies an 8x8 block.

`d_8x8` : |
`ds` : |
`s_8x8` : |
`ss` : |

### oil_err_inter8x8_u8 ()

    void                oil_err_inter8x8_u8                 (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2);

Calculates an intermediate 8x8 block where each element is the difference between `s1_8x8` and `s2_8x8`. The sum of squares of the difference of each element in the intermediate block and the mean of the intermediate block is placed into `d_1`. This result is equal to 64 times the variance of the mean of the intermediate block.

`d_1` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`ss2` : |

### oil_fdct8x8theora ()

    void                oil_fdct8x8theora                   (const int16_t *s_8x8,
                                                             int16_t *d_8x8);

Calculates the FDCT transformation of `s_8x8` according to the Theora specification and places the result in `d_8x8`.

Note that the source and destination arrays are reversed compared to normal Liboil order.

`s_8x8` : |
`d_8x8` : |

### oil_rowsad8x8_u8 ()

    void                oil_rowsad8x8_u8                    (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             const uint8_t *s2_8x8);

Calculates the sum of absolute differences between `s1_8x8` and `s1_8s8` for the first 4 elements of the first row, and the sum of absolute differences for the last 4 elements of the first row, and places the maximum of those values in `dest`.

FIXME: This function is declared incorrectly.

`d_1` : |
`s1_8x8` : |
`s2_8x8` : |

### oil_recon8x8_inter2 ()

    void                oil_recon8x8_inter2                 (uint8_t *d_8x8,
                                                             int ds,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             int ss2,
                                                             const int16_t *s3_8x8);

Adds each element in `s1_8x8` and `s2_8x8`, divides by 2, and adds to `s3_8x8`, clamps to the range [0,255], and places the result in the destination array.

`d_8x8` : |
`ds` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`ss2` : |
`s3_8x8` : |

### oil_composite_add_u8 ()

    void                oil_composite_add_u8                (uint8_t *i_n,
                                                             const uint8_t *s1_n,
                                                             int n);

Performs the compositing operation DEST = SRC ADD DEST.

`i_n` : | DEST
`s1_n` : | SRC
`n` : | number of elements

### oil_sad8x8_u8_avg ()

    void                oil_sad8x8_u8_avg                   (uint32_t *d_1,
                                                             const uint8_t *s1_8x8,
                                                             int ss1,
                                                             const uint8_t *s2_8x8,
                                                             const uint8_t *s3_8x8,
                                                             int ss2);

Calculates the sum of absolute differences between `s1_8x8` and the average of `s2_8x8` and `s3_8x8`.

FIXME: This function is broken because the reference function assumes the stride for `s3_8x8` is `ss2`.

`d_1` : |
`s1_8x8` : |
`ss1` : |
`s2_8x8` : |
`s3_8x8` : |
`ss2` : |