Home

Awesome

libplacebo

gitlab-ci badge gitlab-ci coverage GitHub PayPal Patreon

libplacebo is, in a nutshell, the core rendering algorithms and ideas of mpv rewritten as an independent library. As of today, libplacebo contains a large assortment of video processing shaders, focusing on both quality and performance. These include features such as the following:

Every attempt was made to provide these features at a high level of abstraction, taking away all the messy details of GPU programming, color spaces, obscure subsampling modes, image metadata manipulation, and so on. Expert-level functionality is packed into easy-to-use functions like pl_frame_from_avframe and pl_render_image.

Hardware requirements

libplacebo currently supports Vulkan (including MoltenVK), OpenGL, and Direct3D 11. It currently has the following minimum hardware requirements:

For more documentation, including an introduction to the API, see the project website.

Examples

This screenshot from the included plplay demo program highlights just some of the features supported by the libplacebo rendering code, all of which are adjustable dynamically during video playback.

<img src="./demos/screenshots/plplay1.png" width="200" alt="plplay settings 1" /> <img src="./demos/screenshots/plplay2.png" width="200" alt="plplay settings 2" /> <img src="./demos/screenshots/plplay3.png" width="200" alt="plplay settings 3" />

<img src="./demos/screenshots/plplay4.png" width="200" alt="plplay settings 4" /> <img src="./demos/screenshots/plplay5.png" width="200" alt="plplay settings 5" /> <img src="./demos/screenshots/plplay6.png" width="200" alt="plplay settings 6" />

History

This project grew out of an interest to accomplish the following goals:

It has since been adopted by VLC as their optional Vulkan-based video output path, and is provided as a Vulkan-based video filter in the FFmpeg project.

API Overview

The public API of libplacebo is currently split up into the following components, the header files (and documentation) for which are available inside the src/include/libplacebo directory. The API is available in different "tiers", representing levels of abstraction inside libplacebo. The APIs in higher tiers depend on those in lower tiers. Which tier is used by a user depends on how much power/control they want over the actual rendering. The low-level tiers are more suitable for big projects that need strong control over the entire rendering pipeline; whereas the high-level tiers are more suitable for smaller or simpler projects that want libplacebo to take care of everything.

Tier 0 (logging, raw math primitives)

The API functions in this tier are either used throughout the program (context, common etc.) or are low-level implementations of filter kernels, color space conversion logic etc.; which are entirely independent of GLSL and even the GPU in general.

Tier 1 (rendering abstraction)

As part of the public API, libplacebo exports a middle-level abstraction for dealing with GPU objects and state. Basically, this is the API libplacebo uses internally to wrap OpenGL, Vulkan, Direct3D etc. into a single unifying API subset that abstracts away state, messy details, synchronization etc. into a fairly high-level API suitable for libplacebo's image processing tasks.

It's made public both because it constitutes part of the public API of various image processing functions, but also in the hopes that it will be useful for other developers of GPU-accelerated image processing software.

Tier 2 (GLSL generating primitives)

In addition to this low-level interface, there are several available shader routines which libplacebo exports:

Tier 3 (shader dispatch)

This shader dispatch mechanism is designed to be combined with the shader processing routines exported by shaders/*.h, but takes care of the low-level translation of the resulting pl_shader_res objects into legal GLSL. It also takes care of resource binding, shader input placement, as well as shader caching and resource pooling; and makes sure all generated shaders have unique identifiers (so they can be freely merged together).

Tier 4 (high level renderer)

This is the "primary" interface to libplacebo, and the one most users will be interested in. It takes care of internal details such as degrading to simpler algorithms depending on the hardware's capabilities, combining the correct sequence of colorspace transformations and shader passes in order to get the best overall image quality, and so forth.

Authors

libplacebo was founded and primarily developed by Niklas Haas (@haasn), but it would not be possible without the contributions of others, especially support for windows.

contributor list

License

libplacebo is currently available under the terms of the LGPLv2.1 (or later) license. However, it's possible to release it under a more permissive license (e.g. BSD2) if a use case emerges.

Please open an issue if you have a use case for a BSD2-licensed libplacebo.

Installing

Obtaining

When cloning libplacebo, make sure to provide the --recursive flag:

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

Alternatively (on an existing clone):

$ git submodule update --init

Doing either of these pulls in a handful of bundled 3rdparty dependencies. Alternatively, they can be provided via the system.

Building from source

libplacebo is built using the meson build system. You can build the project using the following steps:

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

To rebuild the project on changes, re-run ninja -Cbuild. If you wish to install the build products to the configured prefix (typically /usr/local/), you can run ninja -Cbuild install. Note that this is normally ill-advised except for developers who know what they're doing. Regular users should rely on distro packages.

Dependencies

In principle, libplacebo has no mandatory dependencies - only optional ones. However, to get a useful version of libplacebo. you most likely want to build with support for either opengl, vulkan or d3d11. libplacebo built without these can still be used (e.g. to generate GLSL shaders such as the ones used in VLC), but the usefulness is severely impacted since most components will be missing, impaired or otherwise not functional.

A full list of optional dependencies each feature requires:

(*) This dependency is bundled automatically when doing a recursive clone.

Vulkan support

Because the vulkan backend requires on code generation at compile time, python3-Jinja2 is a hard dependency of the build system. In addition to this, the path to the Vulkan registry (vk.xml) must be locatable, ideally by explicitly providing it via the -Dvulkan-registry=/path/to/vk.xml option, unless it can be found in one of the built-in hard-coded locations.

Configuring

To get a list of configuration options supported by libplacebo, after running meson $DIR you can run meson configure $DIR, e.g.:

$ meson $DIR
$ meson configure $DIR

If you want to disable a component, for example Vulkan support, you can explicitly set it to false, i.e.:

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

Testing

To enable building and executing the tests, you need to build with tests enabled, i.e.:

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

Benchmarking

A naive benchmark suite is provided as an extra test case, disabled by default (due to the high execution time required). To enable it, use the bench option:

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

Using

For a full documentation of the API, refer to the above API Overview as well as the public header files. You can find additional examples of how to use the various components in the demo programs as well as in the unit tests.