1// Copyright 2022 Google Inc. All Rights Reserved.
2//
3// Use of this source code is governed by a BSD-style license
4// that can be found in the COPYING file in the root of the source
5// tree. An additional intellectual property rights grant can be found
6// in the file PATENTS. All contributing project authors may
7// be found in the AUTHORS file in the root of the source tree.
8// -----------------------------------------------------------------------------
9//
10// Sharp RGB to YUV conversion.
11
12#ifndef WEBP_SHARPYUV_SHARPYUV_H_
13#define WEBP_SHARPYUV_SHARPYUV_H_
14
15#ifdef __cplusplus
16extern "C" {
17#endif
18
19#ifndef SHARPYUV_EXTERN
20#ifdef WEBP_EXTERN
21#define SHARPYUV_EXTERN WEBP_EXTERN
22#else
23// This explicitly marks library functions and allows for changing the
24// signature for e.g., Windows DLL builds.
25#if defined(__GNUC__) && __GNUC__ >= 4
26#define SHARPYUV_EXTERN extern __attribute__((visibility("default")))
27#else
28#if defined(_MSC_VER) && defined(WEBP_DLL)
29#define SHARPYUV_EXTERN __declspec(dllexport)
30#else
31#define SHARPYUV_EXTERN extern
32#endif /* _MSC_VER && WEBP_DLL */
33#endif /* __GNUC__ >= 4 */
34#endif /* WEBP_EXTERN */
35#endif /* SHARPYUV_EXTERN */
36
37// SharpYUV API version following the convention from semver.org
38#define SHARPYUV_VERSION_MAJOR 0
39#define SHARPYUV_VERSION_MINOR 2
40#define SHARPYUV_VERSION_PATCH 1
41// Version as a uint32_t. The major number is the high 8 bits.
42// The minor number is the middle 8 bits. The patch number is the low 16 bits.
43#define SHARPYUV_MAKE_VERSION(MAJOR, MINOR, PATCH) \
44 (((MAJOR) << 24) | ((MINOR) << 16) | (PATCH))
45#define SHARPYUV_VERSION \
46 SHARPYUV_MAKE_VERSION(SHARPYUV_VERSION_MAJOR, SHARPYUV_VERSION_MINOR, \
47 SHARPYUV_VERSION_PATCH)
48
49// Returns the library's version number, packed in hexadecimal. See
50// SHARPYUV_VERSION.
51SHARPYUV_EXTERN int SharpYuvGetVersion(void);
52
53// RGB to YUV conversion matrix, in 16 bit fixed point.
54// y = rgb_to_y[0] * r + rgb_to_y[1] * g + rgb_to_y[2] * b + rgb_to_y[3]
55// u = rgb_to_u[0] * r + rgb_to_u[1] * g + rgb_to_u[2] * b + rgb_to_u[3]
56// v = rgb_to_v[0] * r + rgb_to_v[1] * g + rgb_to_v[2] * b + rgb_to_v[3]
57// Then y, u and v values are divided by 1<<16 and rounded.
58typedef struct {
59 int rgb_to_y[4];
60 int rgb_to_u[4];
61 int rgb_to_v[4];
62} SharpYuvConversionMatrix;
63
64// Converts RGB to YUV420 using a downsampling algorithm that minimizes
65// artefacts caused by chroma subsampling.
66// This is slower than standard downsampling (averaging of 4 UV values).
67// Assumes that the image will be upsampled using a bilinear filter. If nearest
68// neighbor is used instead, the upsampled image might look worse than with
69// standard downsampling.
70// r_ptr, g_ptr, b_ptr: pointers to the source r, g and b channels. Should point
71// to uint8_t buffers if rgb_bit_depth is 8, or uint16_t buffers otherwise.
72// rgb_step: distance in bytes between two horizontally adjacent pixels on the
73// r, g and b channels. If rgb_bit_depth is > 8, it should be a
74// multiple of 2.
75// rgb_stride: distance in bytes between two vertically adjacent pixels on the
76// r, g, and b channels. If rgb_bit_depth is > 8, it should be a
77// multiple of 2.
78// rgb_bit_depth: number of bits for each r/g/b value. One of: 8, 10, 12, 16.
79// Note: 16 bit input is truncated to 14 bits before conversion to yuv.
80// yuv_bit_depth: number of bits for each y/u/v value. One of: 8, 10, 12.
81// y_ptr, u_ptr, v_ptr: pointers to the destination y, u and v channels. Should
82// point to uint8_t buffers if yuv_bit_depth is 8, or uint16_t buffers
83// otherwise.
84// y_stride, u_stride, v_stride: distance in bytes between two vertically
85// adjacent pixels on the y, u and v channels. If yuv_bit_depth > 8, they
86// should be multiples of 2.
87// width, height: width and height of the image in pixels
88SHARPYUV_EXTERN int SharpYuvConvert(const void* r_ptr, const void* g_ptr,
89 const void* b_ptr, int rgb_step,
90 int rgb_stride, int rgb_bit_depth,
91 void* y_ptr, int y_stride, void* u_ptr,
92 int u_stride, void* v_ptr, int v_stride,
93 int yuv_bit_depth, int width, int height,
94 const SharpYuvConversionMatrix* yuv_matrix);
95
96// TODO(b/194336375): Add YUV444 to YUV420 conversion. Maybe also add 422
97// support (it's rarely used in practice, especially for images).
98
99#ifdef __cplusplus
100} // extern "C"
101#endif
102
103#endif // WEBP_SHARPYUV_SHARPYUV_H_
104