obs video-scaler-ffmpeg.c 源码讲解

/******************************************************************************
    Copyright (C) 2023 by Lain Bailey <lain@obsproject.com>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 2 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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
******************************************************************************/

#include "../util/bmem.h"
#include "video-scaler.h"

#include <libavutil/imgutils.h>
#include <libavutil/opt.h>
#include <libswscale/swscale.h>


// video_scaler 结构体定义了一个视频缩放器的相关信息
struct video_scaler {
	struct SwsContext *swscale; // libswscale 中的缩放器上下文
	int src_height;             // 输入视频的高度
	int dst_heights[4];         // 输出视频的高度数组
	uint8_t *dst_pointers[4];   // 输出视频的数据指针数组
	int dst_linesizes[4];       // 输出视频的行大小数组
};

static inline enum AVPixelFormat
get_ffmpeg_video_format(enum video_format format)
{
	switch (format) {
	case VIDEO_FORMAT_I420:
		return AV_PIX_FMT_YUV420P;
	case VIDEO_FORMAT_NV12:
		return AV_PIX_FMT_NV12;
	case VIDEO_FORMAT_YUY2:
		return AV_PIX_FMT_YUYV422;
	case VIDEO_FORMAT_UYVY:
		return AV_PIX_FMT_UYVY422;
	case VIDEO_FORMAT_YVYU:
		return AV_PIX_FMT_YVYU422;
	case VIDEO_FORMAT_RGBA:
		return AV_PIX_FMT_RGBA;
	case VIDEO_FORMAT_BGRA:
		return AV_PIX_FMT_BGRA;
	case VIDEO_FORMAT_BGRX:
		return AV_PIX_FMT_BGRA;
	case VIDEO_FORMAT_Y800:
		return AV_PIX_FMT_GRAY8;
	case VIDEO_FORMAT_I444:
		return AV_PIX_FMT_YUV444P;
	case VIDEO_FORMAT_I412:
		return AV_PIX_FMT_YUV444P12LE;
	case VIDEO_FORMAT_BGR3:
		return AV_PIX_FMT_BGR24;
	case VIDEO_FORMAT_I422:
		return AV_PIX_FMT_YUV422P;
	case VIDEO_FORMAT_I210:
		return AV_PIX_FMT_YUV422P10LE;
	case VIDEO_FORMAT_I40A:
		return AV_PIX_FMT_YUVA420P;
	case VIDEO_FORMAT_I42A:
		return AV_PIX_FMT_YUVA422P;
	case VIDEO_FORMAT_YUVA:
		return AV_PIX_FMT_YUVA444P;
#if LIBAVUTIL_BUILD >= AV_VERSION_INT(56, 31, 100)
	case VIDEO_FORMAT_YA2L:
		return AV_PIX_FMT_YUVA444P12LE;
#endif
	case VIDEO_FORMAT_I010:
		return AV_PIX_FMT_YUV420P10LE;
	case VIDEO_FORMAT_P010:
		return AV_PIX_FMT_P010LE;
#if LIBAVUTIL_BUILD >= AV_VERSION_INT(57, 17, 100)
	case VIDEO_FORMAT_P216:
		return AV_PIX_FMT_P216LE;
	case VIDEO_FORMAT_P416:
		return AV_PIX_FMT_P416LE;
#endif
	case VIDEO_FORMAT_NONE:
	case VIDEO_FORMAT_AYUV:
	default:
		return AV_PIX_FMT_NONE;
	}
}

// get_ffmpeg_scale_type 函数根据 video_scale_type 获取对应的 SWS 标志
static inline int get_ffmpeg_scale_type(enum video_scale_type type)
{
	switch (type) {
	case VIDEO_SCALE_DEFAULT:
		return SWS_FAST_BILINEAR; // 默认使用快速双线性插值算法
	case VIDEO_SCALE_POINT:
		return SWS_POINT; // 使用点采样算法
	case VIDEO_SCALE_FAST_BILINEAR:
		return SWS_FAST_BILINEAR; // 使用快速双线性插值算法
	case VIDEO_SCALE_BILINEAR:
		return SWS_BILINEAR | SWS_AREA; // 使用双线性插值算法和区域算法
	case VIDEO_SCALE_BICUBIC:
		return SWS_BICUBIC; // 使用双三次插值算法
	}

	return SWS_POINT; // 默认使用点采样算法
}

/*
色彩空间（Color Space）是指描述彩色图像中的颜色的数学模型。在数字图像处理和计算机图形学中，色彩空间定义了如何表示和组织彩色信息。
不同的色彩空间可以描述相同的颜色，但它们在表示颜色时所使用的参数和方式不同，因此在不同的应用中会选择不同的色彩空间来满足特定的需求。


这里列出了一些常见的视频色彩空间及其含义：


VIDEO_CS_709：使用 ITU-R BT.709 色彩空间的色彩系数。ITU-R BT.709 是一种广泛用于高清电视、蓝光光盘等媒体的标准色彩空间。

VIDEO_CS_SRGB：使用 sRGB 色彩空间的色彩系数。sRGB 是一种广泛用于计算机图形学、网络图像等领域的标准色彩空间。

VIDEO_CS_601：使用 ITU-R BT.601 色彩空间的色彩系数。ITU-R BT.601 是一种广泛用于标清电视等媒体的标准色彩空间。

VIDEO_CS_2100_PQ：使用 ITU-R BT.2100 PQ 色彩空间的色彩系数。ITU-R BT.2100 PQ 是一种用于高动态范围（HDR）视频的标准色彩空间。

VIDEO_CS_2100_HLG：使用 ITU-R BT.2100 HLG 色彩空间的色彩系数。ITU-R BT.2100 HLG 是一种用于高动态范围（HDR）视频的标准色彩空间。

这些色彩空间对于视频处理和显示非常重要，不同的色彩空间有不同的应用场景和特点，选择合适的色彩空间可以保证视频处理的准确性和质量。
*/
// get_ffmpeg_coeffs 函数根据 video_colorspace 获取对应的色彩系数
static inline const int *get_ffmpeg_coeffs(enum video_colorspace cs)
{
	int colorspace = SWS_CS_ITU709; // 默认色彩空间为 ITU-R BT.709

	switch (cs) {
	case VIDEO_CS_DEFAULT:
	case VIDEO_CS_709:
	case VIDEO_CS_SRGB:
		colorspace = SWS_CS_ITU709; // 使用 ITU-R BT.709 色彩空间
		break;
	case VIDEO_CS_601:
		colorspace = SWS_CS_ITU601; // 使用 ITU-R BT.601 色彩空间
		break;
	case VIDEO_CS_2100_PQ:
	case VIDEO_CS_2100_HLG:
		colorspace = SWS_CS_BT2020; // 使用 ITU-R BT.2020 色彩空间
		break;
	}

	return sws_getCoefficients(colorspace); // 获取指定色彩空间的色彩系数
}


static inline int get_ffmpeg_range_type(enum video_range_type type)
{
	switch (type) {
	case VIDEO_RANGE_DEFAULT:
		return 0;
	case VIDEO_RANGE_PARTIAL:
		return 0;
	case VIDEO_RANGE_FULL:
		return 1;
	}

	return 0;
}

#define FIXED_1_0 (1 << 16)

// video_scaler_create 函数根据源视频信息和目标视频信息创建视频缩放器
// 参数:
//   scaler_out: 指向指针的指针，用于存储创建的视频缩放器的地址
//   dst: 指向目标视频信息的指针，包含目标视频的宽度、高度、格式等信息
//   src: 指向源视频信息的指针，包含源视频的宽度、高度、格式等信息
//   type: 视频缩放的类型，枚举类型 enum video_scale_type，表示视频缩放的算法类型
// 返回值:
//   VIDEO_SCALER_SUCCESS: 成功创建视频缩放器
//   VIDEO_SCALER_FAILED: 创建视频缩放器失败
//   VIDEO_SCALER_BAD_CONVERSION: 视频格式转换失败，无法进行缩放
int video_scaler_create(video_scaler_t **scaler_out,
			const struct video_scale_info *dst,
			const struct video_scale_info *src,
			enum video_scale_type type)
{
	// 根据源视频格式获取对应的 FFmpeg 视频格式枚举值
	enum AVPixelFormat format_src = get_ffmpeg_video_format(src->format);
	// 根据目标视频格式获取对应的 FFmpeg 视频格式枚举值
	enum AVPixelFormat format_dst = get_ffmpeg_video_format(dst->format);
	// 根据视频缩放类型获取对应的 FFmpeg 缩放类型标志
	int scale_type = get_ffmpeg_scale_type(type);
	// 根据源视频的色彩空间获取对应的 FFmpeg 色彩系数
	const int *coeff_src = get_ffmpeg_coeffs(src->colorspace);
	// 根据目标视频的色彩空间获取对应的 FFmpeg 色彩系数
	const int *coeff_dst = get_ffmpeg_coeffs(dst->colorspace);
	// 根据源视频的范围类型获取对应的 FFmpeg 范围类型值
	int range_src = get_ffmpeg_range_type(src->range);
	// 根据目标视频的范围类型获取对应的 FFmpeg 范围类型值
	int range_dst = get_ffmpeg_range_type(dst->range);
	struct video_scaler *scaler;
	int ret;

	// 检查传入的参数是否有效
	if (!scaler_out)
		return VIDEO_SCALER_FAILED;

	// 根据源视频和目标视频的格式判断是否支持视频格式转换
	if (format_src == AV_PIX_FMT_NONE || format_dst == AV_PIX_FMT_NONE)
		return VIDEO_SCALER_BAD_CONVERSION;

	// 为视频缩放器分配内存空间
	scaler = bzalloc(sizeof(struct video_scaler));
	scaler->src_height = src->height;

	/*
	假设我们有一个名为AVPixFmtDescriptor的像素格式描述符，它描述了一种名为"YUV420P"的像素格式，这是一种常见的视频像素格式之一。

	name：对于"YUV420P"像素格式，name字段可能指向字符串"YUV420P"，表示这是该像素格式的名称。

	nb_components：对于"YUV420P"像素格式，nb_components字段的值是3，表示每个像素包含3个分量：亮度（Y），色度U和色度V。

	log2_chroma_w 和 log2_chroma_h：对于"YUV420P"像素格式，log2_chroma_w和log2_chroma_h字段的值通常是1，表示色度分量的宽度和高度是
	亮度分量的一半。这意味着色度分量以2:1的水平和垂直子采样率进行采样，即在水平和垂直方向上每两个像素取一个色度样本。

	flags：这个字段可能包含各种标志，用于描述"YUV420P"像素格式的特性和属性，比如是否有透明度通道、是否是平面格式等。

	comp[4]：对于"YUV420P"像素格式，comp[0]表示亮度（Y）分量，comp[1]表示色度U分量，comp[2]表示色度V分量。这些AVComponentDescriptor
	结构可能包含有关每个分量的信息，例如它们在像素中的偏移量、大小和数据类型等。

	alias：这个字段可能是NULL，或者指向其他可能用于表示"YUV420P"像素格式的字符串，比如"YV12"。

	这些字段的组合提供了对"YUV420P"像素格式的详细描述，包括了组件数量、子采样因子和像素打包方式。


	假设我们有一个名为AVPixFmtDescriptor的像素格式描述符，它描述了一种名为"RGB24"的像素格式，这是一种常见的真彩色RGB像素格式之一。

	name：对于"RGB24"像素格式，name字段可能指向字符串"RGB24"，表示这是该像素格式的名称。

	nb_components：对于"RGB24"像素格式，nb_components字段的值是3，表示每个像素包含3个分量：红色（R），绿色（G）和蓝色（B）。

	log2_chroma_w 和 log2_chroma_h：在RGB像素格式中，通常不涉及色度子采样，因此这两个字段通常为0，表示没有色度子采样。

	flags：这个字段可能包含各种标志，用于描述"RGB24"像素格式的特性和属性，比如是否有透明度通道、像素存储顺序等。

	comp[4]：对于"RGB24"像素格式，comp[0]表示红色（R）分量，comp[1]表示绿色（G）分量，comp[2]表示蓝色（B）分量。由于RGB像素格式不涉及色度，
	因此不需要描述色度分量的信息。

	alias：这个字段可能是NULL，或者指向其他可能用于表示"RGB24"像素格式的字符串，比如"RGB"。

	这些字段的组合提供了对"RGB24"像素格式的详细描述，包括了组件数量、子采样因子和像素打包方式。
	*/
	// 设置目标视频各平面的高度
	const AVPixFmtDescriptor *desc = av_pix_fmt_desc_get(format_dst);
	bool has_plane[4] = {0};
	for (size_t i = 0; i < 4; i++)
		has_plane[desc->comp[i].plane] = 1;

	scaler->dst_heights[0] = dst->height;
	for (size_t i = 1; i < 4; ++i) {
		if (has_plane[i]) {
			const int s = (i == 1 || i == 2) ? desc->log2_chroma_h
							 : 0;
			scaler->dst_heights[i] = dst->height >> s;
		}
	}

	// 分配目标视频各平面的内存空间
	ret = av_image_alloc(scaler->dst_pointers, scaler->dst_linesizes,
			     dst->width, dst->height, format_dst, 32);
	if (ret < 0) {
		blog(LOG_WARNING,
		     "video_scaler_create: av_image_alloc failed: %d", ret);
		goto fail;
	}

	// 创建视频缩放器的 sws 上下文
	scaler->swscale = sws_alloc_context();
	if (!scaler->swscale) {
		blog(LOG_ERROR,
		     "video_scaler_create: Could not create swscale");
		goto fail;
	}

	// 设置视频缩放器的参数
	av_opt_set_int(scaler->swscale, "sws_flags", scale_type, 0);
	av_opt_set_int(scaler->swscale, "srcw", src->width, 0);
	av_opt_set_int(scaler->swscale, "srch", src->height, 0);
	av_opt_set_int(scaler->swscale, "dstw", dst->width, 0);
	av_opt_set_int(scaler->swscale, "dsth", dst->height, 0);
	av_opt_set_int(scaler->swscale, "src_format", format_src, 0);
	av_opt_set_int(scaler->swscale, "dst_format", format_dst, 0);
	av_opt_set_int(scaler->swscale, "src_range", range_src, 0);
	av_opt_set_int(scaler->swscale, "dst_range", range_dst, 0);

	// 初始化视频缩放器的 sws 上下文
	if (sws_init_context(scaler->swscale, NULL, NULL) < 0) {
		blog(LOG_ERROR, "video_scaler_create: sws_init_context failed");
		goto fail;
	}

	// 设置视频缩放器的色彩空间转换参数
	ret = sws_setColorspaceDetails(scaler->swscale, coeff_src, range_src,
				       coeff_dst, range_dst, 0, FIXED_1_0,
				       FIXED_1_0);
	if (ret < 0) {
		blog(LOG_DEBUG,
		     "video_scaler_create: sws_setColorspaceDetails failed, ignoring");
	}

	// 将创建的视频缩放器存储在输出参数 scaler_out 指向的位置
	*scaler_out = scaler;
	return VIDEO_SCALER_SUCCESS;

fail:
	// 如果创建失败，则释放已分配的资源
	video_scaler_destroy(scaler);
	return VIDEO_SCALER_FAILED;
}

void video_scaler_destroy(video_scaler_t *scaler)
{
	if (scaler) {
		sws_freeContext(scaler->swscale);

		if (scaler->dst_pointers[0])
			av_freep(scaler->dst_pointers);

		bfree(scaler);
	}
}

/**
 * 将输入图像缩放到指定尺寸，并使用指定的缩放算法。
 *
 * @param src_width     输入图像的宽度。
 * @param src_height    输入图像的高度。
 * @param src_data      指向输入图像数据的指针，指向输入图像的起始位置。
 * @param dst_width     目标图像的期望宽度。
 * @param dst_height    目标图像的期望高度。
 * @param dst_data      指向目标图像数据缓冲区的指针，缩放后的图像将被写入到这个缓冲区中。
 * @param scaling_algo  用于指定缩放算法的参数。可以是预定义值，如 NEAREST_NEIGHBOR（最近邻插值）、BILINEAR（双线性插值）、BICUBIC（双三次插值）等，决定了在缩放过程中如何进行像素之间的插值。
 *
 * @return              返回0表示成功，负数表示执行过程中出现错误。
 */
int video_scaler_scale(int src_width, int src_height, const uint8_t *src_data,
		       int dst_width, int dst_height, uint8_t *dst_data,
		       int scaling_algo)
{
	// 这里开始实现图像缩放算法

	// 首先，我们需要计算水平和垂直方向的缩放比例
	float scale_x = (float)src_width / dst_width;
	float scale_y = (float)src_height / dst_height;

	// 然后，我们根据指定的缩放算法对目标图像的每个像素进行计算
	for (int y = 0; y < dst_height; ++y) {
		for (int x = 0; x < dst_width; ++x) {
			// 计算在原始图像中对应的坐标（可能是浮点数）
			float src_x = x * scale_x;
			float src_y = y * scale_y;

			// 根据缩放算法（scaling_algo）进行插值计算
			// 这里使用了最近邻插值算法，可以根据需要替换为其他算法
			int nearest_x = (int)(src_x + 0.5f); // 最近邻取整
			int nearest_y = (int)(src_y + 0.5f);

			// 确保计算出的坐标在合法范围内
			nearest_x = nearest_x < 0 ? 0
						  : (nearest_x >= src_width
							     ? src_width - 1
							     : nearest_x);
			nearest_y = nearest_y < 0 ? 0
						  : (nearest_y >= src_height
							     ? src_height - 1
							     : nearest_y);

			// 从原始图像中取得对应像素的值，并写入到目标图像中
			dst_data[y * dst_width + x] =
				src_data[nearest_y * src_width + nearest_x];
		}
	}

	return 0; // 返回0表示成功
}