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
16 extern "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(_WIN32) && defined(WEBP_DLL)
26 #define SHARPYUV_EXTERN __declspec(dllexport)
27 #elif defined(__GNUC__) && __GNUC__ >= 4
28 #define SHARPYUV_EXTERN extern __attribute__((visibility("default")))
29 #else
30 #define SHARPYUV_EXTERN extern
31 #endif /* defined(_WIN32) && defined(WEBP_DLL) */
32 #endif /* WEBP_EXTERN */
33 #endif /* SHARPYUV_EXTERN */
34
35 #ifndef SHARPYUV_INLINE
36 #ifdef WEBP_INLINE
37 #define SHARPYUV_INLINE WEBP_INLINE
38 #else
39 #ifndef _MSC_VER
40 #if defined(__cplusplus) || !defined(__STRICT_ANSI__) || \
41 (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L)
42 #define SHARPYUV_INLINE inline
43 #else
44 #define SHARPYUV_INLINE
45 #endif
46 #else
47 #define SHARPYUV_INLINE __forceinline
48 #endif /* _MSC_VER */
49 #endif /* WEBP_INLINE */
50 #endif /* SHARPYUV_INLINE */
51
52 // SharpYUV API version following the convention from semver.org
53 #define SHARPYUV_VERSION_MAJOR 0
54 #define SHARPYUV_VERSION_MINOR 4
55 #define SHARPYUV_VERSION_PATCH 0
56 // Version as a uint32_t. The major number is the high 8 bits.
57 // The minor number is the middle 8 bits. The patch number is the low 16 bits.
58 #define SHARPYUV_MAKE_VERSION(MAJOR, MINOR, PATCH) \
59 (((MAJOR) << 24) | ((MINOR) << 16) | (PATCH))
60 #define SHARPYUV_VERSION \
61 SHARPYUV_MAKE_VERSION(SHARPYUV_VERSION_MAJOR, SHARPYUV_VERSION_MINOR, \
62 SHARPYUV_VERSION_PATCH)
63
64 // Returns the library's version number, packed in hexadecimal. See
65 // SHARPYUV_VERSION.
66 SHARPYUV_EXTERN int SharpYuvGetVersion(void);
67
68 // RGB to YUV conversion matrix, in 16 bit fixed point.
69 // y = rgb_to_y[0] * r + rgb_to_y[1] * g + rgb_to_y[2] * b + rgb_to_y[3]
70 // u = rgb_to_u[0] * r + rgb_to_u[1] * g + rgb_to_u[2] * b + rgb_to_u[3]
71 // v = rgb_to_v[0] * r + rgb_to_v[1] * g + rgb_to_v[2] * b + rgb_to_v[3]
72 // Then y, u and v values are divided by 1<<16 and rounded.
73 typedef struct {
74 int rgb_to_y[4];
75 int rgb_to_u[4];
76 int rgb_to_v[4];
77 } SharpYuvConversionMatrix;
78
79 typedef struct SharpYuvOptions SharpYuvOptions;
80
81 // Enums for transfer functions, as defined in H.273,
82 // https://www.itu.int/rec/T-REC-H.273-202107-I/en
83 typedef enum SharpYuvTransferFunctionType {
84 // 0 is reserved
85 kSharpYuvTransferFunctionBt709 = 1,
86 // 2 is unspecified
87 // 3 is reserved
88 kSharpYuvTransferFunctionBt470M = 4,
89 kSharpYuvTransferFunctionBt470Bg = 5,
90 kSharpYuvTransferFunctionBt601 = 6,
91 kSharpYuvTransferFunctionSmpte240 = 7,
92 kSharpYuvTransferFunctionLinear = 8,
93 kSharpYuvTransferFunctionLog100 = 9,
94 kSharpYuvTransferFunctionLog100_Sqrt10 = 10,
95 kSharpYuvTransferFunctionIec61966 = 11,
96 kSharpYuvTransferFunctionBt1361 = 12,
97 kSharpYuvTransferFunctionSrgb = 13,
98 kSharpYuvTransferFunctionBt2020_10Bit = 14,
99 kSharpYuvTransferFunctionBt2020_12Bit = 15,
100 kSharpYuvTransferFunctionSmpte2084 = 16, // PQ
101 kSharpYuvTransferFunctionSmpte428 = 17,
102 kSharpYuvTransferFunctionHlg = 18,
103 kSharpYuvTransferFunctionNum
104 } SharpYuvTransferFunctionType;
105
106 // Converts RGB to YUV420 using a downsampling algorithm that minimizes
107 // artefacts caused by chroma subsampling.
108 // This is slower than standard downsampling (averaging of 4 UV values).
109 // Assumes that the image will be upsampled using a bilinear filter. If nearest
110 // neighbor is used instead, the upsampled image might look worse than with
111 // standard downsampling.
112 // r_ptr, g_ptr, b_ptr: pointers to the source r, g and b channels. Should point
113 // to uint8_t buffers if rgb_bit_depth is 8, or uint16_t buffers otherwise.
114 // rgb_step: distance in bytes between two horizontally adjacent pixels on the
115 // r, g and b channels. If rgb_bit_depth is > 8, it should be a
116 // multiple of 2.
117 // rgb_stride: distance in bytes between two vertically adjacent pixels on the
118 // r, g, and b channels. If rgb_bit_depth is > 8, it should be a
119 // multiple of 2.
120 // rgb_bit_depth: number of bits for each r/g/b value. One of: 8, 10, 12, 16.
121 // Note: 16 bit input is truncated to 14 bits before conversion to yuv.
122 // yuv_bit_depth: number of bits for each y/u/v value. One of: 8, 10, 12.
123 // y_ptr, u_ptr, v_ptr: pointers to the destination y, u and v channels. Should
124 // point to uint8_t buffers if yuv_bit_depth is 8, or uint16_t buffers
125 // otherwise.
126 // y_stride, u_stride, v_stride: distance in bytes between two vertically
127 // adjacent pixels on the y, u and v channels. If yuv_bit_depth > 8, they
128 // should be multiples of 2.
129 // width, height: width and height of the image in pixels
130 // This function calls SharpYuvConvertWithOptions with a default transfer
131 // function of kSharpYuvTransferFunctionSrgb.
132 SHARPYUV_EXTERN int SharpYuvConvert(const void* r_ptr, const void* g_ptr,
133 const void* b_ptr, int rgb_step,
134 int rgb_stride, int rgb_bit_depth,
135 void* y_ptr, int y_stride, void* u_ptr,
136 int u_stride, void* v_ptr, int v_stride,
137 int yuv_bit_depth, int width, int height,
138 const SharpYuvConversionMatrix* yuv_matrix);
139
140 struct SharpYuvOptions {
141 // This matrix cannot be NULL and can be initialized by
142 // SharpYuvComputeConversionMatrix.
143 const SharpYuvConversionMatrix* yuv_matrix;
144 SharpYuvTransferFunctionType transfer_type;
145 };
146
147 // Internal, version-checked, entry point
148 SHARPYUV_EXTERN int SharpYuvOptionsInitInternal(const SharpYuvConversionMatrix*,
149 SharpYuvOptions*, int);
150
151 // Should always be called, to initialize a fresh SharpYuvOptions
152 // structure before modification. SharpYuvOptionsInit() must have succeeded
153 // before using the 'options' object.
SharpYuvOptionsInit(const SharpYuvConversionMatrix * yuv_matrix,SharpYuvOptions * options)154 static SHARPYUV_INLINE int SharpYuvOptionsInit(
155 const SharpYuvConversionMatrix* yuv_matrix, SharpYuvOptions* options) {
156 return SharpYuvOptionsInitInternal(yuv_matrix, options, SHARPYUV_VERSION);
157 }
158
159 SHARPYUV_EXTERN int SharpYuvConvertWithOptions(
160 const void* r_ptr, const void* g_ptr, const void* b_ptr, int rgb_step,
161 int rgb_stride, int rgb_bit_depth, void* y_ptr, int y_stride, void* u_ptr,
162 int u_stride, void* v_ptr, int v_stride, int yuv_bit_depth, int width,
163 int height, const SharpYuvOptions* options);
164
165 // TODO(b/194336375): Add YUV444 to YUV420 conversion. Maybe also add 422
166 // support (it's rarely used in practice, especially for images).
167
168 #ifdef __cplusplus
169 } // extern "C"
170 #endif
171
172 #endif // WEBP_SHARPYUV_SHARPYUV_H_
173