/src/vlc/include/vlc_chroma_probe.h

Source (jump to first uncovered line)
/*****************************************************************************
 * vlc_chroma_probe.h: chroma conversion probing
 *****************************************************************************
 * Copyright (C) 2025 VLC authors and VideoLAN
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef VLC_CHROMA_PROBE_H
#define VLC_CHROMA_PROBE_H 1

#include <vlc_common.h>
#include <vlc_vector.h>

/**
 * \defgroup chroma_probe Chroma conversion probing
 * \ingroup filter
 * @{
 * \file
 * Chroma conversion probing
 *
 * \defgroup chroma_probe_api Chroma probing API
 * \ingroup chroma_probe
 *
 * @{
 */

#define VLC_CHROMA_CONV_MAX_INDIRECT_STEPS 1
#define VLC_CHROMA_CONV_CHAIN_COUNT_MAX (2 /* in + out */ + VLC_CHROMA_CONV_MAX_INDIRECT_STEPS)

/**
 * Chroma conversion result structure
 */
struct vlc_chroma_conv_result
{
    /**
     * Array of chromas used to achieve the conversion
     *
     * 'chain[0]' is always equals to the 'in' argument of the
     * vlc_chroma_conv_Probe() function.
     *
     * if the out argument of the vlc_chroma_conv_Probe() is valid,
     * chain[chain_count - 1] is equals to 'out'
     */
    vlc_fourcc_t chain[VLC_CHROMA_CONV_CHAIN_COUNT_MAX];

    /** Number of chromas in the chain */
    size_t chain_count;

    /**
     * Cost of the full conversion, lower is better.
     */
    unsigned cost;

    /**
     * Quality of the conversion, higher is better.
     *
     * A quality of 100 means there are no quality loss: same color size and
     * same vlc_chroma_subtype (or same YUV subsampling for video).
     */
    unsigned quality;
};

/** Only accept YUV output chromas (the input chroma can be RGB) */
#define VLC_CHROMA_CONV_FLAG_ONLY_YUV 0x1
/** Only accept RGB output chromas (the input chroma can be YUV) */
#define VLC_CHROMA_CONV_FLAG_ONLY_RGB 0x2
/** Sort results by cost instead of quality */
#define VLC_CHROMA_CONV_FLAG_SORT_COST  0x4

/**
 * Probe possible chroma conversions

 * Results are sorted by quality, unless VLC_CHROMA_CONV_FLAG_SORT_COST is
 * specified in flags.

 * @param in the input chroma to convert from, must be valid
 * @param out the output chroma to convert to, if 0, the function will find all
 * possible conversion from in to x
 * @param width video width, used for finer cost calculation, can be 0
 * @param height video height, used for finer cost calculation, can be 0
 * @param max_indirect_steps maximum number of indirect conversion steps, must
 * be lower or equal to @ref VLC_CHROMA_CONV_MAX_INDIRECT_STEPS, if in and out
 * chromas are CPU chromas, the steps will be automatically lowered to 0
 * @param flags bitwise flags, cf. VLC_CHROMA_CONV_FLAG_*
 * @param count pointer to the number of results, must be valid
 * @return a pointer to an array of results, must be released with free(), can
 * be NULL
 */
VLC_API struct vlc_chroma_conv_result *
vlc_chroma_conv_Probe(vlc_fourcc_t in, vlc_fourcc_t out,
                      unsigned width, unsigned height,
                      unsigned max_indirect_steps, int flags, size_t *count);

/**
 * Get a string representing the result
 *
 * @param res pointer to a valid result
 * @return a string or NULL, must be released with free()
 */
VLC_API char *
vlc_chroma_conv_result_ToString(const struct vlc_chroma_conv_result *res);

/**
 * @}
 *
 * \defgroup chroma_probe_module Chroma probing module implementation
 * \ingroup chroma_probe
 *
 * @{
 */

/**
 * Chroma conversion entry structure
 */
struct vlc_chroma_conv_entry
{
    /** Cost factor, 0.25 for GPU<->GPU conversions, 0.75 for SIMD, 1 for CPU */
    float cost_factor;
    /** input chroma */
    vlc_fourcc_t in;
    /** output chroma */
    vlc_fourcc_t out;
};
typedef struct VLC_VECTOR(struct vlc_chroma_conv_entry) vlc_chroma_conv_vec;

/**
 * Module probe function signature
 *
 * @param vec pointer to an allocated vector
 * @return a VLC error code
 */
typedef void (*vlc_chroma_conv_probe)(vlc_chroma_conv_vec *vec);

#define set_callback_chroma_conv_probe(activate) \
    { \
        vlc_chroma_conv_probe activate__ = activate; \
        (void) activate__; \
        set_callback(activate) \
    } \
    set_capability("chroma probe", 100)

/**
 * Helper that add a chroma conversion
 *
 * Must be called inside vlc_chroma_conv_probe()
 *
 * @param vec pointer to the vector of chromas
 * @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
 * @param in cf. vlc_chroma_conv_entry.in
 * @param out cf. vlc_chroma_conv_entry.out
 * @param twoway if true, 'out' can also be converted to 'in'
 */
static inline void
vlc_chroma_conv_add(vlc_chroma_conv_vec *vec, float cost_factor,
                    vlc_fourcc_t in, vlc_fourcc_t out, bool twoway)
{
    {
        const struct vlc_chroma_conv_entry entry = {
            cost_factor, in, out
        };
        vlc_vector_push(vec, entry);
    }

    if (twoway)
    {
        const struct vlc_chroma_conv_entry entry = {
            cost_factor, out, in
        };
        vlc_vector_push(vec, entry);
    }
}

/**
 * Helper that add an array of out chroma conversions
 *
 * Must be called inside vlc_chroma_conv_probe()
 *
 * @param vec pointer to the vector of chromas
 * @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
 * @param in cf. vlc_chroma_conv_entry.in
 * @param out_array a list of out chromas
 * @param out_count number of elements in the out_array
 */
static inline void
vlc_chroma_conv_add_in_outarray(vlc_chroma_conv_vec *vec, float cost_factor,
                                vlc_fourcc_t in,
                                const vlc_fourcc_t *out_array, size_t out_count)
{
    for (size_t i = 0; i < out_count; i++)
    {
        const struct vlc_chroma_conv_entry entry = {
            cost_factor, in, out_array[i],
        };
        vlc_vector_push(vec, entry);
    }
}

/**
 * Helper that add a list of out chroma conversions
 */
#define vlc_chroma_conv_add_in_outlist(vec, cost_factor, in, ...) do { \
    static const vlc_fourcc_t out_array[] = { __VA_ARGS__ }; \
    size_t count = ARRAY_SIZE(out_array); \
    vlc_chroma_conv_add_in_outarray(vec, cost_factor, in, out_array, count); \
} while(0)

/**
 * Helper that add an array of in chroma conversions
 *
 * Must be called inside vlc_chroma_conv_probe()
 *
 * @param vec pointer to the vector of chromas
 * @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
 * @param out cf. vlc_chroma_conv_entry.out
 * @param in_array a list of out chromas
 * @param in_count number of elements in the in_array
 */
static inline void
vlc_chroma_conv_add_out_inarray(vlc_chroma_conv_vec *vec, float cost_factor,
                                vlc_fourcc_t out,
                                const vlc_fourcc_t *in_array, size_t in_count)
{
    for (size_t i = 0; i < in_count; i++)
    {
        const struct vlc_chroma_conv_entry entry = {
            cost_factor, in_array[i], out,
        };
        vlc_vector_push(vec, entry);
    }
}

/**
 * Helper that add a list of in chroma conversions
 */
#define vlc_chroma_conv_add_out_inlist(vec, cost_factor, out, ...) do { \
    static const vlc_fourcc_t in_array[] = { __VA_ARGS__ }; \
    size_t count = ARRAY_SIZE(in_array); \
    vlc_chroma_conv_add_out_inarray(vec, cost_factor, out, in_array, count); \
} while(0)

/**
 * @}
 * @}
 */

#endif /* VLC_CHROMA_PROBE_H */

Coverage Report

Created: 2025-07-11 06:16

Line	Count	Source (jump to first uncovered line)
1		/*****************************************************************************
2		* vlc_chroma_probe.h: chroma conversion probing
3		*****************************************************************************
4		* Copyright (C) 2025 VLC authors and VideoLAN
5		*
6		* This program is free software; you can redistribute it and/or modify it
7		* under the terms of the GNU Lesser General Public License as published by
8		* the Free Software Foundation; either version 2.1 of the License, or
9		* (at your option) any later version.
10		*
11		* This program is distributed in the hope that it will be useful,
12		* but WITHOUT ANY WARRANTY; without even the implied warranty of
13		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14		* GNU Lesser General Public License for more details.
15		*
16		* You should have received a copy of the GNU Lesser General Public License
17		* along with this program; if not, write to the Free Software Foundation,
18		* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19		*****************************************************************************/
20
21		#ifndef VLC_CHROMA_PROBE_H
22		#define VLC_CHROMA_PROBE_H 1
23
24		#include <vlc_common.h>
25		#include <vlc_vector.h>
26
27		/**
28		* \defgroup chroma_probe Chroma conversion probing
29		* \ingroup filter
30		* @{
31		* \file
32		* Chroma conversion probing
33		*
34		* \defgroup chroma_probe_api Chroma probing API
35		* \ingroup chroma_probe
36		*
37		* @{
38		*/
39
40		#define VLC_CHROMA_CONV_MAX_INDIRECT_STEPS 1
41		#define VLC_CHROMA_CONV_CHAIN_COUNT_MAX (2 /* in + out */ + VLC_CHROMA_CONV_MAX_INDIRECT_STEPS)
42
43		/**
44		* Chroma conversion result structure
45		*/
46		struct vlc_chroma_conv_result
47		{
48		/**
49		* Array of chromas used to achieve the conversion
50		*
51		* 'chain[0]' is always equals to the 'in' argument of the
52		* vlc_chroma_conv_Probe() function.
53		*
54		* if the out argument of the vlc_chroma_conv_Probe() is valid,
55		* chain[chain_count - 1] is equals to 'out'
56		*/
57		vlc_fourcc_t chain[VLC_CHROMA_CONV_CHAIN_COUNT_MAX];
58
59		/** Number of chromas in the chain */
60		size_t chain_count;
61
62		/**
63		* Cost of the full conversion, lower is better.
64		*/
65		unsigned cost;
66
67		/**
68		* Quality of the conversion, higher is better.
69		*
70		* A quality of 100 means there are no quality loss: same color size and
71		* same vlc_chroma_subtype (or same YUV subsampling for video).
72		*/
73		unsigned quality;
74		};
75
76		/** Only accept YUV output chromas (the input chroma can be RGB) */
77	0	#define VLC_CHROMA_CONV_FLAG_ONLY_YUV 0x1
78		/** Only accept RGB output chromas (the input chroma can be YUV) */
79	0	#define VLC_CHROMA_CONV_FLAG_ONLY_RGB 0x2
80		/** Sort results by cost instead of quality */
81	0	#define VLC_CHROMA_CONV_FLAG_SORT_COST 0x4
82
83		/**
84		* Probe possible chroma conversions
85
86		* Results are sorted by quality, unless VLC_CHROMA_CONV_FLAG_SORT_COST is
87		* specified in flags.
88
89		* @param in the input chroma to convert from, must be valid
90		* @param out the output chroma to convert to, if 0, the function will find all
91		* possible conversion from in to x
92		* @param width video width, used for finer cost calculation, can be 0
93		* @param height video height, used for finer cost calculation, can be 0
94		* @param max_indirect_steps maximum number of indirect conversion steps, must
95		* be lower or equal to @ref VLC_CHROMA_CONV_MAX_INDIRECT_STEPS, if in and out
96		* chromas are CPU chromas, the steps will be automatically lowered to 0
97		* @param flags bitwise flags, cf. VLC_CHROMA_CONV_FLAG_*
98		* @param count pointer to the number of results, must be valid
99		* @return a pointer to an array of results, must be released with free(), can
100		* be NULL
101		*/
102		VLC_API struct vlc_chroma_conv_result *
103		vlc_chroma_conv_Probe(vlc_fourcc_t in, vlc_fourcc_t out,
104		unsigned width, unsigned height,
105		unsigned max_indirect_steps, int flags, size_t *count);
106
107		/**
108		* Get a string representing the result
109		*
110		* @param res pointer to a valid result
111		* @return a string or NULL, must be released with free()
112		*/
113		VLC_API char *
114		vlc_chroma_conv_result_ToString(const struct vlc_chroma_conv_result *res);
115
116		/**
117		* @}
118		*
119		* \defgroup chroma_probe_module Chroma probing module implementation
120		* \ingroup chroma_probe
121		*
122		* @{
123		*/
124
125		/**
126		* Chroma conversion entry structure
127		*/
128		struct vlc_chroma_conv_entry
129		{
130		/** Cost factor, 0.25 for GPU<->GPU conversions, 0.75 for SIMD, 1 for CPU */
131		float cost_factor;
132		/** input chroma */
133		vlc_fourcc_t in;
134		/** output chroma */
135		vlc_fourcc_t out;
136		};
137		typedef struct VLC_VECTOR(struct vlc_chroma_conv_entry) vlc_chroma_conv_vec;
138
139		/**
140		* Module probe function signature
141		*
142		* @param vec pointer to an allocated vector
143		* @return a VLC error code
144		*/
145		typedef void (vlc_chroma_conv_probe)(vlc_chroma_conv_vec vec);
146
147		#define set_callback_chroma_conv_probe(activate) \
148		{ \
149		vlc_chroma_conv_probe activate__ = activate; \
150		(void) activate__; \
151		set_callback(activate) \
152		} \
153		set_capability("chroma probe", 100)
154
155		/**
156		* Helper that add a chroma conversion
157		*
158		* Must be called inside vlc_chroma_conv_probe()
159		*
160		* @param vec pointer to the vector of chromas
161		* @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
162		* @param in cf. vlc_chroma_conv_entry.in
163		* @param out cf. vlc_chroma_conv_entry.out
164		* @param twoway if true, 'out' can also be converted to 'in'
165		*/
166		static inline void
167		vlc_chroma_conv_add(vlc_chroma_conv_vec *vec, float cost_factor,
168		vlc_fourcc_t in, vlc_fourcc_t out, bool twoway)
169	0	{
170	0	{
171	0	const struct vlc_chroma_conv_entry entry = {
172	0	cost_factor, in, out
173	0	};
174	0	vlc_vector_push(vec, entry);
175	0	}
176	0
177	0	if (twoway)
178	0	{
179	0	const struct vlc_chroma_conv_entry entry = {
180	0	cost_factor, out, in
181	0	};
182	0	vlc_vector_push(vec, entry);
183	0	}
184	0	} Unexecuted instantiation: fourcc.c:vlc_chroma_conv_add Unexecuted instantiation: chroma_probe.c:vlc_chroma_conv_add
185
186		/**
187		* Helper that add an array of out chroma conversions
188		*
189		* Must be called inside vlc_chroma_conv_probe()
190		*
191		* @param vec pointer to the vector of chromas
192		* @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
193		* @param in cf. vlc_chroma_conv_entry.in
194		* @param out_array a list of out chromas
195		* @param out_count number of elements in the out_array
196		*/
197		static inline void
198		vlc_chroma_conv_add_in_outarray(vlc_chroma_conv_vec *vec, float cost_factor,
199		vlc_fourcc_t in,
200		const vlc_fourcc_t *out_array, size_t out_count)
201	0	{
202	0	for (size_t i = 0; i < out_count; i++)
203	0	{
204	0	const struct vlc_chroma_conv_entry entry = {
205	0	cost_factor, in, out_array[i],
206	0	};
207	0	vlc_vector_push(vec, entry);
208	0	}
209	0	} Unexecuted instantiation: fourcc.c:vlc_chroma_conv_add_in_outarray Unexecuted instantiation: chroma_probe.c:vlc_chroma_conv_add_in_outarray
210
211		/**
212		* Helper that add a list of out chroma conversions
213		*/
214		#define vlc_chroma_conv_add_in_outlist(vec, cost_factor, in, ...) do { \
215		static const vlc_fourcc_t out_array[] = { __VA_ARGS__ }; \
216		size_t count = ARRAY_SIZE(out_array); \
217		vlc_chroma_conv_add_in_outarray(vec, cost_factor, in, out_array, count); \
218		} while(0)
219
220		/**
221		* Helper that add an array of in chroma conversions
222		*
223		* Must be called inside vlc_chroma_conv_probe()
224		*
225		* @param vec pointer to the vector of chromas
226		* @param cost_factor cf. vlc_chroma_conv_entry.cost_factor
227		* @param out cf. vlc_chroma_conv_entry.out
228		* @param in_array a list of out chromas
229		* @param in_count number of elements in the in_array
230		*/
231		static inline void
232		vlc_chroma_conv_add_out_inarray(vlc_chroma_conv_vec *vec, float cost_factor,
233		vlc_fourcc_t out,
234		const vlc_fourcc_t *in_array, size_t in_count)
235	0	{
236	0	for (size_t i = 0; i < in_count; i++)
237	0	{
238	0	const struct vlc_chroma_conv_entry entry = {
239	0	cost_factor, in_array[i], out,
240	0	};
241	0	vlc_vector_push(vec, entry);
242	0	}
243	0	} Unexecuted instantiation: fourcc.c:vlc_chroma_conv_add_out_inarray Unexecuted instantiation: chroma_probe.c:vlc_chroma_conv_add_out_inarray
244
245		/**
246		* Helper that add a list of in chroma conversions
247		*/
248		#define vlc_chroma_conv_add_out_inlist(vec, cost_factor, out, ...) do { \
249		static const vlc_fourcc_t in_array[] = { __VA_ARGS__ }; \
250		size_t count = ARRAY_SIZE(in_array); \
251		vlc_chroma_conv_add_out_inarray(vec, cost_factor, out, in_array, count); \
252		} while(0)
253
254		/**
255		* @}
256		* @}
257		*/
258
259		#endif /* VLC_CHROMA_PROBE_H */