libplacebo

libplacebo 简而言之，是将 mpv 的核心渲染算法和理念重写为一个独立的库。如今，libplacebo 包含了大量的视频处理着色器，注重质量和性能。这些功能包括：

• 高质量、优化的放大和缩小，支持极坐标滤波器（"Jinc"）、抗锯齿、抗振铃和伽马校正缩放。
• 动态HDR 色调映射，包括实时场景直方图测量、场景变化检测、动态曝光控制、感知色域拉伸、对比度恢复等。
• 原生支持 Dolby Vision HDR，包括 Profile 5 转换为 HDR/PQ 或 SDR、读取 DV 侧数据和重塑。（目前仅限基础层）
• 色度准确的色彩管理引擎，支持软色域映射、ICC 配置文件、精确的 ITU-R BT.1886 仿真、黑点补偿和自定义 3DLUT（.cube）。
• 可插拔、可扩展的自定义着色器系统。这可用于任意扩展自定义着色器范围，包括流行的用户着色器如 RAVU、FSRCNNX 或 Anime4K。更多信息请参见 mpv wiki 上的用户脚本。
• 高性能 胶片颗粒合成，适用于 AV1 和 H.274，允许媒体播放器将解码的这部分工作从 CPU 卸载到 GPU。
• 可调节、快速的去色带和去隔行着色器。
• 高质量伽马校正抖动，包括误差扩散模式。

我们尽力提供这些功能时保持高度抽象，消除 GPU 编程、色彩空间、晦涩的二次采样模式、图像元数据操作等所有繁琐细节。专家级功能被打包成易用的函数，如 pl_frame_from_avframe 和 pl_render_image。

硬件要求

libplacebo 目前支持 Vulkan（包括 MoltenVK）、OpenGL 和 Direct3D 11。当前最低硬件要求如下：

• Vulkan：核心版本 1.2
• OpenGL：GLSL 版本 >= 130（GL >= 3.0，GL ES >= 3.0）
• Direct3D：特性级别 >= 9_1

更多文档，包括 API 介绍，请参见项目网站。

示例

这张来自包含的 plplay 演示程序 的截图突出展示了 libplacebo 渲染代码支持的部分功能，所有这些功能都可以在视频播放过程中动态调整。

历史

这个项目源于实现以下目标的兴趣：

• 清理 mpv 内部的 RA API，使其可重用于其他项目，作为一个通用的高级后端无关的图形 API 包装器。
• 提供基于 GLSL 的实用 GPU 加速图像处理原语标准库，使媒体播放器或浏览器等项目可以使用它们，而无需承担对 libmpv 的重度依赖。
• 在重新设计的抽象基础上重写 mpv 的 GPU 加速视频渲染器的核心部分，以实现现代化并支持更多功能。

它此后被 VLC 采用作为其可选的基于 Vulkan 的视频输出路径，并在 FFmpeg 项目中作为基于 Vulkan 的视频滤镜提供。

API 概述

libplacebo的公共API目前分为以下几个组件，其头文件(和文档)可在src/include/libplacebo目录中找到。API分为不同的"层级"，代表libplacebo内部的抽象级别。较高层级的API依赖于较低层级的API。用户使用哪个层级取决于他们想要对实际渲染有多大的控制权。较低层级更适合需要对整个渲染管道有强控制的大型项目；而较高层级更适合希望libplacebo处理一切的小型或简单项目。

层级0(日志记录、原始数学基元)

• cache.h：缓存子系统。用于缓存大型或计算密集型的二进制blob，如编译后的着色器、3DLUT等。
• colorspace.h：描述色彩空间的枚举和结构体集合，以及计算各种色彩空间转换矩阵的辅助函数集。
• common.h：多个子系统共享的杂项实用类型和宏的集合。通常不需要直接包含。
• log.h：日志子系统。
• config.h：定义libplacebo构建方式信息的宏，包括版本字符串和编译时的功能/依赖项。通常不需要直接包含。可能对功能测试有用。
• dither.h：生成各种噪声和抖动矩阵的辅助函数。可能对其他人有用。
• filters.h：可重用的重建滤波器核集合，可用于缩放。生成的权重数组半定制于libplacebo的需求，但可能对其他人也有用。还包含为libplacebo的上采样例程定义滤波器核所需的结构体。
• tone_mapping.h：色调映射函数集合，用于HDR和SDR内容之间的转换。
• gamut_mapping.h：色域映射函数集合，用于宽色域和标准色域内容之间的转换，以及色调映射后的色域重压缩。

这一层级的API函数要么在整个程序中使用(上下文、通用等)，要么是滤波器核、色彩空间转换逻辑等的低级实现；它们完全独立于GLSL甚至GPU。

层级1(渲染抽象)

• gpu.h：导出libplacebo内部使用的GPU抽象API。
• swapchain.h：导出用于包装平台特定交换链和其他显示API的API。这是用于将渲染帧排队呈现(例如到窗口或显示设备)的API。
• vulkan.h：基于Vulkan的GPU API实现。
• opengl.h：基于OpenGL的GPU API实现。
• d3d11.h：基于Direct3D 11的GPU API实现。
• dummy.h：虚拟GPU API(仅与CPU交互，不支持着色器)

作为公共API的一部分，libplacebo导出了一个中级抽象来处理GPU对象和状态。基本上，这是libplacebo内部用来将OpenGL、Vulkan、Direct3D等包装成单一统一API子集的API，它抽象了状态、繁琐细节、同步等，成为一个相当高级的API，适用于libplacebo的图像处理任务。

它之所以公开，一是因为它构成了各种图像处理函数的公共API的一部分，二是希望它对其他GPU加速图像处理软件的开发者有用。

层级2(GLSL生成基元)

• shaders.h：着色器生成的低级接口。这可以用来生成适合包含在其他程序中的GLSL存根，作为更大着色器的一部分。例如，程序可能使用这个接口生成专门的色调映射函数来执行色彩空间转换，然后从自己的片段着色器代码中调用它。这个抽象可选地依赖于gpu.h，但也可以独立使用。

除了这个低级接口，libplacebo还导出了几个可用的着色器例程：

• shaders/colorspace.h：用于解码和转换颜色、色调映射等的着色器例程。
• shaders/custom.h：允许直接将自定义GLSL逻辑注入pl_shader抽象，可以是裸GLSL或mpv .hook格式。
• shaders/deinterlacing.h：基于yadif的GPU去隔行着色器。
• shaders/dithering.h：各种GPU抖动方法的着色器例程。
• shaders/film_grain.h：AV1和H.274的胶片颗粒合成着色器。
• shaders/icc.h：基于ICC配置文件的色彩管理着色器。
• shaders/lut.h：用于应用任意1D/3D LUT的代码。
• shaders/sampling.h：各种从图像采样的算法的着色器例程，如去色带和缩放。

层级3(着色器调度)

• dispatch.h：基于gpu.h的pl_shader系统的高级接口。这个调度机制生成并执行完整的GLSL着色器，受底层GPU的约束和限制。

这个着色器调度机制设计用于与shaders/*.h导出的着色器处理例程结合使用，但负责将结果pl_shader_res对象低级转换为合法的GLSL。它还负责资源绑定、着色器输入放置，以及着色器缓存和资源池化；并确保所有生成的着色器都有唯一的标识符(因此可以自由合并)。

层级4(高级渲染器)

• options.h：高级选项框架，将pl_render_params中的所有选项包装成内存管理的、可序列化的结构体，也可以作为键值字典处理。还包括一个选项解析器，用于加载API用户以字符串格式提供的选项。
• renderer.h：高级渲染器，将着色器基元和调度机制组合成一个完整的渲染管道，将原始纹理数据转换为所需的输出图像。
• utils/frame_queue.h：高级帧队列抽象。这个API可用于与解码器(或其他帧源)接口，并负责将带时间戳的帧转换为适合与renderer.h一起使用的虚拟呈现事件流，包括帧插值(pl_frame_mix)所需的任何额外上下文。
• utils/upload.h：高级辅助工具，用于将用户描述格式的通用数据上传到适合与renderer.h一起使用的平面纹理。这些辅助工具基本上负责选择/映射GPU支持的好的图像格式。(注：最终，这个函数也将支持在必要时进行CPU上的格式转换，但目前，它只会失败)
• utils/dav1d.h：在Dav1dPicture和libplacebo的pl_frame之间转换的高级辅助工具。(单头文件库)
• utils/libav.h：libplacebo和FFmpeg的libav*抽象之间互操作的高级辅助工具。(单头文件库)

这是libplacebo的"主要"接口，也是大多数用户最感兴趣的接口。它处理内部细节，如根据硬件能力降级到更简单的算法，组合正确的色彩空间转换和着色器通道序列以获得最佳整体图像质量，等等。

作者

libplacebo由Niklas Haas (@haasn)创立并主要开发，但没有其他人的贡献it将无法实现，尤其是对Windows的支持。

许可证

libplacebo 目前根据 LGPLv2.1（或更高版本）许可证提供。但是，如果出现需求，也可以考虑以更宽松的许可证（如 BSD2）发布。

如果您有使用 BSD2 许可的 libplacebo 的需求，请提出一个问题。

安装

获取

克隆 libplacebo 时，请确保使用 --recursive 标志：

$ git clone --recursive https://code.videolan.org/videolan/libplacebo

或者（在现有克隆上）：

$ git submodule update --init

执行以上任一操作都会拉取一些捆绑的第三方依赖项。另外，也可以通过系统提供这些依赖项。

从源码构建

libplacebo 使用 meson 构建系统进行构建。 您可以按照以下步骤构建项目：

$ DIR=./build
$ meson $DIR
$ ninja -C$DIR

要在更改后重新构建项目，重新运行 ninja -Cbuild。如果您想将构建产物安装到配置的前缀（通常是 /usr/local/），可以运行 ninja -Cbuild install。请注意，除非您是了解自己在做什么的开发人员，否则通常不建议这样做。普通用户应该依赖发行版包。

依赖项

原则上，libplacebo 没有强制性依赖项 - 只有可选的依赖项。 然而，要获得有用的 libplacebo 版本，您很可能希望构建时支持 opengl、vulkan 或 d3d11 中的至少一个。没有这些构建的 libplacebo 仍然可以使用（例如生成 VLC 中使用的 GLSL 着色器），但其实用性会受到严重影响，因为大多数组件将缺失、受损或无法正常工作。

每个功能所需的可选依赖项完整列表：

• glslang: glslang 及其相关库（如 libSPIRV.so）
• lcms: liblcms2
• libdovi: libdovi
• opengl: glad2 (*)
• shaderc: libshaderc
• vulkan: libvulkan, python3-jinja2 (*)
• xxhash: libxxhash

(*) 这些依赖项在递归克隆时会自动捆绑。

Vulkan 支持

由于 Vulkan 后端需要在编译时进行代码生成，python3-Jinja2 是构建系统的硬性依赖。此外，必须能够找到 Vulkan 注册表（vk.xml）的路径，最好通过 -Dvulkan-registry=/path/to/vk.xml 选项明确提供，除非可以在内置的硬编码位置之一找到它。

配置

要获取 libplacebo 支持的配置选项列表，在运行 meson $DIR 后，您可以运行 meson configure $DIR，例如：

$ meson $DIR
$ meson configure $DIR

如果您想禁用某个组件，例如 Vulkan 支持，可以明确将其设置为 false，即：

$ meson configure $DIR -Dvulkan=disabled -Dshaderc=disabled
$ ninja -C$DIR

测试

要启用构建和执行测试，您需要启用 tests 选项进行构建，即：

$ meson configure $DIR -Dtests=true
$ ninja -C$DIR test

基准测试

提供了一个简单的基准测试套件作为额外的测试用例，默认情况下禁用（由于所需的执行时间较长）。要启用它，请使用 bench 选项：

$ meson configure $DIR -Dbench=true
$ meson test -C$DIR benchmark --verbose

使用

有关 API 的完整文档，请参阅上面的 API 概述 以及 公共头文件。您可以在 演示程序 以及 单元测试 中找到如何使用各种组件的其他示例。