{"id":13640729,"url":"https://github.com/haasn/libplacebo","last_synced_at":"2025-05-15T00:06:43.568Z","repository":{"id":38983637,"uuid":"106075151","full_name":"haasn/libplacebo","owner":"haasn","description":"Official mirror of libplacebo","archived":false,"fork":false,"pushed_at":"2025-05-08T11:53:15.000Z","size":7164,"stargazers_count":618,"open_issues_count":54,"forks_count":79,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-05-11T01:26:22.263Z","etag":null,"topics":["d3d11","ffmpeg","glsl","gpu","mirror","mpv","multimedia","opengl","shaders","video","video-player","video-processing","videolan","vlc","vulkan"],"latest_commit_sha":null,"homepage":"http://libplacebo.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/haasn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"haasn","patreon":"haasn","open_collective":"haasn"}},"created_at":"2017-10-07T06:00:38.000Z","updated_at":"2025-05-08T11:53:00.000Z","dependencies_parsed_at":"2023-02-16T21:55:34.741Z","dependency_job_id":"4ec75c4f-6475-41ec-bcce-0e38dbacdad9","html_url":"https://github.com/haasn/libplacebo","commit_stats":{"total_commits":3588,"total_committers":52,"mean_commits":69.0,"dds":0.5206243032329989,"last_synced_commit":"9e16c86f9a37af7fb207241150c2fe7ba50e3471"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasn%2Flibplacebo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasn%2Flibplacebo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasn%2Flibplacebo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haasn%2Flibplacebo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haasn","download_url":"https://codeload.github.com/haasn/libplacebo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249198,"owners_count":22039029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["d3d11","ffmpeg","glsl","gpu","mirror","mpv","multimedia","opengl","shaders","video","video-player","video-processing","videolan","vlc","vulkan"],"created_at":"2024-08-02T01:01:13.900Z","updated_at":"2025-05-15T00:06:43.517Z","avatar_url":"https://github.com/haasn.png","language":"C","funding_links":["https://github.com/sponsors/haasn","https://patreon.com/haasn","https://opencollective.com/haasn","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=SFJUTMPSZEAHC","https://www.patreon.com/haasn"],"categories":["C"],"sub_categories":[],"readme":"# libplacebo\n\n[![gitlab-ci badge](https://code.videolan.org/videolan/libplacebo/badges/master/pipeline.svg)](https://code.videolan.org/videolan/libplacebo/pipelines)\n[![gitlab-ci coverage](https://code.videolan.org/videolan/libplacebo/badges/master/coverage.svg)](https://code.videolan.org/videolan/libplacebo/-/jobs/artifacts/master/file/coverage/index.html?job=test-gpu)\n[![GitHub](https://img.shields.io/github/sponsors/haasn?logo=github)](https://github.com/sponsors/haasn)\n[![PayPal](https://img.shields.io/badge/donate-PayPal-blue.svg?logo=paypal)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=SFJUTMPSZEAHC)\n[![Patreon](https://img.shields.io/badge/pledge-Patreon-red.svg?logo=patreon)](https://www.patreon.com/haasn)\n\n**libplacebo** is, in a nutshell, the core rendering algorithms and ideas of\n[mpv](https://mpv.io) rewritten as an independent library. As of today,\nlibplacebo contains a large assortment of video processing shaders, focusing\non both quality and performance. These include features such as the following:\n\n- High-quality, optimized **upscaling and downscaling** including support for\n  polar filters (\"Jinc\"), anti-aliasing, anti-ringing and gamma correct\n  scaling.\n- Dynamic **HDR tone mapping**, including real-time measurement of scene\n  histogram, scene change detection, dynamic exposure control, perceptual gamut\n  stretching, contrast recovery and more.\n- Native support for **Dolby Vision HDR**, including Profile 5 conversion to\n  HDR/PQ or SDR, reading DV side data, and reshaping. (BL only, currently)\n- A colorimetrically accurate **color management** engine with support for\n  soft gamut mapping, ICC profiles, accurate ITU-R BT.1886 emulation, black\n  point compensation, and custom 3DLUTs (.cube).\n- A pluggable, extensible [**custom shader\n  system**](http://libplacebo.org/custom-shaders/). This can be used to\n  arbitrarily extend the range of custom shaders to include popular user\n  shaders like RAVU, FSRCNNX, or Anime4K. See the [mpv wiki on user\n  scripts](https://github.com/mpv-player/mpv/wiki/User-Scripts#user-shaders)\n  for more information.\n- High performance **film grain synthesis** for AV1 and H.274, allowing media\n  players to offload this part of decoding from the CPU to the GPU.\n- Tunable, fast **debanding** and **deinterlacing** shaders.\n- High quality gamma-correct **dithering**, including error diffusion modes.\n\nEvery attempt was made to provide these features at a **high level of\nabstraction**, taking away all the messy details of GPU programming, color\nspaces, obscure subsampling modes, image metadata manipulation, and so on.\nExpert-level functionality is packed into easy-to-use functions like\n`pl_frame_from_avframe` and `pl_render_image`.\n\n### Hardware requirements\n\nlibplacebo currently supports Vulkan (including MoltenVK), OpenGL, and\nDirect3D 11. It currently has the following minimum hardware requirements:\n\n- **Vulkan**: Core version 1.2\n- **OpenGL**: GLSL version \u003e= 130 (GL \u003e= 3.0, GL ES \u003e= 3.0)\n- **Direct3D**: Feature level \u003e= 9_1\n\nFor more documentation, including an introduction to the API, see [the project\nwebsite](https://libplacebo.org).\n\n### Examples\n\nThis screenshot from the included [plplay demo program](./demos/plplay.c)\nhighlights just some of the features supported by the libplacebo rendering\ncode, all of which are adjustable dynamically during video playback.\n\n[\u003cimg src=\"./demos/screenshots/plplay1.png\" width=\"200\" alt=\"plplay settings 1\" /\u003e](./demos/screenshots/plplay1.png)\n[\u003cimg src=\"./demos/screenshots/plplay2.png\" width=\"200\" alt=\"plplay settings 2\" /\u003e](./demos/screenshots/plplay2.png)\n[\u003cimg src=\"./demos/screenshots/plplay3.png\" width=\"200\" alt=\"plplay settings 3\" /\u003e](./demos/screenshots/plplay3.png)\n\n[\u003cimg src=\"./demos/screenshots/plplay4.png\" width=\"200\" alt=\"plplay settings 4\" /\u003e](./demos/screenshots/plplay4.png)\n[\u003cimg src=\"./demos/screenshots/plplay5.png\" width=\"200\" alt=\"plplay settings 5\" /\u003e](./demos/screenshots/plplay5.png)\n[\u003cimg src=\"./demos/screenshots/plplay6.png\" width=\"200\" alt=\"plplay settings 6\" /\u003e](./demos/screenshots/plplay6.png)\n\n### History\n\nThis project grew out of an interest to accomplish the following goals:\n\n- Clean up mpv's internal [RA](#tier-1-rendering-abstraction) API and make it\n  reusable for other projects, as a general high-level backend-agnostic\n  graphics API wrapper.\n- Provide a standard library of useful GPU-accelerated image processing\n  primitives based on GLSL, so projects like media players or browsers can use\n  them without incurring a heavy dependency on `libmpv`.\n- Rewrite core parts of mpv's GPU-accelerated video renderer on top of\n  redesigned abstractions, in order to modernize it and allow supporting more\n  features.\n\nIt has since been adopted by [VLC](https://www.videolan.org/vlc/) as their\noptional Vulkan-based video output path, and is provided as a Vulkan-based\nvideo filter in the FFmpeg project.\n\n## API Overview\n\nThe public API of libplacebo is currently split up into the following\ncomponents, the header files (and documentation) for which are available\ninside the [`src/include/libplacebo`](src/include/libplacebo) directory. The\nAPI is available in different \"tiers\", representing levels of abstraction\ninside libplacebo. The APIs in higher tiers depend on those in lower tiers.\nWhich tier is used by a user depends on how much power/control they want over\nthe actual rendering. The low-level tiers are more suitable for big projects\nthat need strong control over the entire rendering pipeline; whereas the\nhigh-level tiers are more suitable for smaller or simpler projects that want\nlibplacebo to take care of everything.\n\n### Tier 0 (logging, raw math primitives)\n\n- `cache.h`: Caching subsystem. Used to cache large or computationally heavy\n  binary blobs, such as compiled shaders, 3DLUTs, and so on.\n- `colorspace.h`: A collection of enums and structs for describing color\n  spaces, as well as a collection of helper functions for computing various\n  color space transformation matrices.\n- `common.h`: A collection of miscellaneous utility types and macros that are\n  shared among multiple subsystems. Usually does not need to be included\n  directly.\n- `log.h`: Logging subsystem.\n- `config.h`: Macros defining information about the way libplacebo was built,\n  including the version strings and compiled-in features/dependencies. Usually\n  does not need to be included directly. May be useful for feature tests.\n- `dither.h`: Some helper functions for generating various noise and dithering\n  matrices. Might be useful for somebody else.\n- `filters.h`: A collection of reusable reconstruction filter kernels, which\n  can be used for scaling. The generated weights arrays are semi-tailored to\n  the needs of libplacebo, but may be useful to somebody else regardless. Also\n  contains the structs needed to define a filter kernel for the purposes of\n  libplacebo's upscaling routines.\n- `tone_mapping.h`: A collection of tone mapping functions, used for\n  conversions between HDR and SDR content.\n- `gamut_mapping.h`: A collection of gamut mapping functions, used for\n  conversions between wide gamut and standard gamut content, as well as\n  for gamut recompression after tone-mapping.\n\nThe API functions in this tier are either used throughout the program\n(context, common etc.) or are low-level implementations of filter kernels,\ncolor space conversion logic etc.; which are entirely independent of GLSL\nand even the GPU in general.\n\n### Tier 1 (rendering abstraction)\n\n- `gpu.h`: Exports the GPU abstraction API used by libplacebo internally.\n- `swapchain.h`: Exports an API for wrapping platform-specific swapchains and\n  other display APIs. This is the API used to actually queue up rendered\n  frames for presentation (e.g. to a window or display device).\n- `vulkan.h`: GPU API implementation based on Vulkan.\n- `opengl.h`: GPU API implementation based on OpenGL.\n- `d3d11.h`: GPU API implementation based on Direct3D 11.\n- `dummy.h`: Dummy GPI API (interfaces with CPU only, no shader support)\n\nAs part of the public API, libplacebo exports a middle-level abstraction for\ndealing with GPU objects and state. Basically, this is the API libplacebo uses\ninternally to wrap OpenGL, Vulkan, Direct3D etc. into a single unifying API\nsubset that abstracts away state, messy details, synchronization etc. into a\nfairly high-level API suitable for libplacebo's image processing tasks.\n\nIt's made public both because it constitutes part of the public API of various\nimage processing functions, but also in the hopes that it will be useful for\nother developers of GPU-accelerated image processing software.\n\n### Tier 2 (GLSL generating primitives)\n\n- `shaders.h`: The low-level interface to shader generation. This can be used\n  to generate GLSL stubs suitable for inclusion in other programs, as part of\n  larger shaders. For example, a program might use this interface to generate\n  a specialized tone-mapping function for performing color space conversions,\n  then call that from their own fragment shader code. This abstraction has an\n  optional dependency on `gpu.h`, but can also be used independently from it.\n\nIn addition to this low-level interface, there are several available shader\nroutines which libplacebo exports:\n\n- `shaders/colorspace.h`: Shader routines for decoding and transforming\n  colors, tone mapping, and so forth.\n- `shaders/custom.h`: Allows directly ingesting custom GLSL logic into the\n  `pl_shader` abstraction, either as bare GLSL or in [mpv .hook\n  format](https://mpv.io/manual/master/#options-glsl-shaders).\n- `shaders/deinterlacing.h`: GPU deinterlacing shader based on yadif.\n- `shaders/dithering.h`: Shader routine for various GPU dithering methods.\n- `shaders/film_grain.h`: Film grain synthesis shaders for AV1 and H.274.\n- `shaders/icc.h`: Shader for ICC profile based color management.\n- `shaders/lut.h`: Code for applying arbitrary 1D/3D LUTs.\n- `shaders/sampling.h`: Shader routines for various algorithms that sample\n  from images, such as debanding and scaling.\n\n### Tier 3 (shader dispatch)\n\n- `dispatch.h`: A higher-level interface to the `pl_shader` system, based on\n  `gpu.h`. This dispatch mechanism generates+executes complete GLSL shaders,\n  subject to the constraints and limitations of the underlying GPU.\n\nThis shader dispatch mechanism is designed to be combined with the shader\nprocessing routines exported by `shaders/*.h`, but takes care of the low-level\ntranslation of the resulting `pl_shader_res` objects into legal GLSL. It also\ntakes care of resource binding, shader input placement, as well as shader\ncaching and resource pooling; and makes sure all generated shaders have unique\nidentifiers (so they can be freely merged together).\n\n### Tier 4 (high level renderer)\n\n- `options.h`: A high-level options framework which wraps all of the options\n  comprising `pl_render_params` into a memory-managed, serializable struct that\n  can also be treated as a key/value dictionary. Also includes an options\n  parser to load options provided by the API user in string format.\n- `renderer.h`: A high-level renderer which combines the shader primitives\n  and dispatch mechanism into a fully-fledged rendering pipeline that takes\n  raw texture data and transforms it into the desired output image.\n- `utils/frame_queue.h`: A high-level frame queuing abstraction. This API\n  can be used to interface with a decoder (or other source of frames), and\n  takes care of translating timestamped frames into a virtual stream of\n  presentation events suitable for use with `renderer.h`, including any extra\n  context required for frame interpolation (`pl_frame_mix`).\n- `utils/upload.h`: A high-level helper for uploading generic data in some\n  user-described format to a plane texture suitable for use with `renderer.h`.\n  These helpers essentially take care of picking/mapping a good image format\n  supported by the GPU. (Note: Eventually, this function will also support\n  on-CPU conversions to a different format where necessary, but for now, it\n  will just fail)\n- `utils/dav1d.h`: High level helper for translating between Dav1dPicture\n  and libplacebo's `pl_frame`. (Single header library)\n- `utils/libav.h`: High-level helpers for interoperation between\n  libplacebo and FFmpeg's libav* abstractions. (Single header library)\n\nThis is the \"primary\" interface to libplacebo, and the one most users will be\ninterested in. It takes care of internal details such as degrading to simpler\nalgorithms depending on the hardware's capabilities, combining the correct\nsequence of colorspace transformations and shader passes in order to get the\nbest overall image quality, and so forth.\n\n## Authors\n\nlibplacebo was founded and primarily developed by Niklas Haas\n([@haasn](https://github.com/haasn)), but it would not be possible without the\ncontributions of others, especially support for windows.\n\n[![contributor list](https://opencollective.com/libplacebo/contributors.svg?width=890\u0026button=false)](https://github.com/haasn/libplacebo/graphs/contributors)\n\n### License\n\nlibplacebo is currently available under the terms of the LGPLv2.1 (or later)\nlicense. However, it's possible to release it under a more permissive license\n(e.g. BSD2) if a use case emerges.\n\nPlease open an issue if you have a use case for a BSD2-licensed libplacebo.\n\n## Installing\n\n### Obtaining\n\nWhen cloning libplacebo, make sure to provide the `--recursive` flag:\n\n```bash\n$ git clone --recursive https://code.videolan.org/videolan/libplacebo\n```\n\nAlternatively (on an existing clone):\n\n```bash\n$ git submodule update --init\n```\n\nDoing either of these pulls in a handful of bundled 3rdparty dependencies.\nAlternatively, they can be provided via the system.\n\n### Building from source\n\nlibplacebo is built using the [meson build system](http://mesonbuild.com/).\nYou can build the project using the following steps:\n\n```bash\n$ DIR=./build\n$ meson $DIR\n$ ninja -C$DIR\n```\n\nTo rebuild the project on changes, re-run `ninja -Cbuild`. If you wish to\ninstall the build products to the configured prefix (typically `/usr/local/`),\nyou can run `ninja -Cbuild install`. Note that this is normally ill-advised\nexcept for developers who know what they're doing. Regular users should rely\non distro packages.\n\n### Dependencies\n\nIn principle, libplacebo has no mandatory dependencies - only optional ones.\nHowever, to get a useful version of libplacebo. you most likely want to build\nwith support for either `opengl`, `vulkan` or `d3d11`. libplacebo built without\nthese can still be used (e.g. to generate GLSL shaders such as the ones used in\nVLC), but the usefulness is severely impacted since most components will be\nmissing, impaired or otherwise not functional.\n\nA full list of optional dependencies each feature requires:\n\n- **glslang**: `glslang` + its related libraries (e.g. `libSPIRV.so`)\n- **lcms**: `liblcms2`\n- **libdovi**: `libdovi`\n- **opengl**: `glad2` (*)\n- **shaderc**: `libshaderc`\n- **vulkan**: `libvulkan`, `python3-jinja2` (*)\n- **xxhash**: `libxxhash`\n\n(*) This dependency is bundled automatically when doing a recursive clone.\n\n#### Vulkan support\n\nBecause the vulkan backend requires on code generation at compile time,\n`python3-Jinja2` is a hard dependency of the build system. In addition to this,\nthe path to the Vulkan registry (`vk.xml`) must be locatable, ideally by\nexplicitly providing it via the `-Dvulkan-registry=/path/to/vk.xml` option,\nunless it can be found in one of the built-in hard-coded locations.\n\n### Configuring\n\nTo get a list of configuration options supported by libplacebo, after running\n`meson $DIR` you can run `meson configure $DIR`, e.g.:\n\n```bash\n$ meson $DIR\n$ meson configure $DIR\n```\n\nIf you want to disable a component, for example Vulkan support, you can\nexplicitly set it to `false`, i.e.:\n\n```bash\n$ meson configure $DIR -Dvulkan=disabled -Dshaderc=disabled\n$ ninja -C$DIR\n```\n\n### Testing\n\nTo enable building and executing the tests, you need to build with\n`tests` enabled, i.e.:\n\n```bash\n$ meson configure $DIR -Dtests=true\n$ ninja -C$DIR test\n```\n\n### Benchmarking\n\nA naive benchmark suite is provided as an extra test case, disabled by default\n(due to the high execution time required). To enable it, use the `bench`\noption:\n\n```bash\n$ meson configure $DIR -Dbench=true\n$ meson test -C$DIR benchmark --verbose\n```\n\n## Using\n\nFor a full documentation of the API, refer to the above [API\nOverview](#api-overview) as well as the [public header\nfiles](src/include/libplacebo). You can find additional examples of how to use\nthe various components in the [demo programs](demos) as well as in the [unit\ntests](src/tests).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasn%2Flibplacebo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaasn%2Flibplacebo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaasn%2Flibplacebo/lists"}