{"id":50688832,"url":"https://github.com/vicondoa/virgl-vaapi-compat","last_synced_at":"2026-06-09T01:07:45.273Z","repository":{"id":363003016,"uuid":"1261589701","full_name":"vicondoa/virgl-vaapi-compat","owner":"vicondoa","description":"VA-API compatibility shim for virgl/virtio-gpu I420 DRM PRIME exports","archived":false,"fork":false,"pushed_at":"2026-06-07T00:06:20.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T01:09:03.485Z","etag":null,"topics":["dmabuf","firefox","libva","linux","nix","vaapi","virgl","virtio-gpu"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vicondoa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-06T22:31:06.000Z","updated_at":"2026-06-07T00:06:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vicondoa/virgl-vaapi-compat","commit_stats":null,"previous_names":["vicondoa/virgl-vaapi-compat"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vicondoa/virgl-vaapi-compat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicondoa%2Fvirgl-vaapi-compat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicondoa%2Fvirgl-vaapi-compat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicondoa%2Fvirgl-vaapi-compat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicondoa%2Fvirgl-vaapi-compat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vicondoa","download_url":"https://codeload.github.com/vicondoa/virgl-vaapi-compat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vicondoa%2Fvirgl-vaapi-compat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34086716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["dmabuf","firefox","libva","linux","nix","vaapi","virgl","virtio-gpu"],"created_at":"2026-06-09T01:07:42.545Z","updated_at":"2026-06-09T01:07:45.269Z","avatar_url":"https://github.com/vicondoa.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# virgl-vaapi-compat\n\n`virgl-vaapi-compat` is a small VA-API driver compatibility shim for\nvirgl/virtio-gpu video decode guests. It exists for one narrow interop gap:\nsome stacks export decoded YUV surfaces through `vaExportSurfaceHandle()` as\n`DRM_PRIME_2` three-plane `VA_FOURCC_I420`, while some VA-API clients only\naccept the equivalent U/V ordering when it is described as `VA_FOURCC_YV12`.\n\nThe shim is not a decoder, a color converter, a compositor, or a replacement\nfor Mesa, virglrenderer, libva, or the guest graphics stack. It delegates to the\nreal `virtio_gpu_drv_video.so` VA driver and adjusts only the exported metadata\nfor the known-compatible descriptor shape.\n\n## What it does\n\n```text\nVA-API client\n    -\u003e virgl-vaapi-compat virtio_gpu_drv_video.so\n        -\u003e real virtio_gpu_drv_video.so\n            -\u003e virgl / virtio-gpu video stack\n```\n\nAt driver initialization, the shim loads the real virtio-gpu VA driver, calls\nits matching `__vaDriverInit_*` symbol, and replaces only the driver's\n`vaExportSurfaceHandle` vtable entry. On a successful\n`VA_SURFACE_ATTRIB_MEM_TYPE_DRM_PRIME_2` export of an I420 descriptor with the\nexpected three-plane layout, it reports `VA_FOURCC_YV12` and swaps the U/V layer\nentries. All other calls, formats, memory types, errors, and descriptors pass\nthrough unchanged.\n\nThe original motivating client is Firefox hardware H.264 decode in a\nvirgl/rutabaga/crosvm guest, but the C shim itself is not Firefox-specific and\nis not Nix-specific.\n\n## Quickstart\n\nRequirements:\n\n- C compiler\n- `make`\n- `pkg-config`\n- libva headers and library\n- the real virtio-gpu VA driver available at a stable absolute path\n\nBuild and run the test harness:\n\n```bash\nmake\nmake test\n```\n\nIf the real driver is not at the default NixOS path\n`/run/opengl-driver/lib/dri/virtio_gpu_drv_video.so`, point the build at it:\n\n```bash\nmake REAL_DRIVER=/usr/lib/dri/virtio_gpu_drv_video.so\n```\n\nInstall the shim into a separate driver directory and put that directory first\nwhen launching a client:\n\n```bash\nmake install PREFIX=/usr/local\n\nLIBVA_DRIVER_NAME=virtio_gpu \\\nLIBVA_DRIVERS_PATH=/usr/local/lib/dri${LIBVA_DRIVERS_PATH:+:$LIBVA_DRIVERS_PATH} \\\nVIRGL_VAAPI_COMPAT_DEBUG=1 \\\nvainfo\n```\n\nDo not overwrite the only copy of the real driver with the shim. The shim must\nbe able to `dlopen()` the real `virtio_gpu_drv_video.so`, preferably through an\nabsolute path compiled with `REAL_DRIVER=...`.\n\n## Nix\n\nNix/NixOS users can package the shim by setting `REAL_DRIVER` to the real Mesa\nvirtio-gpu VA driver path in the target graphics closure and exposing the shim\nthrough a higher-priority `LIBVA_DRIVERS_PATH`. The public generic flake\ndocuments the shim package, checks, compatibility report, and overlay:\n\n```bash\nnix build github:vicondoa/virgl-vaapi-compat#virgl-vaapi-compat\nnix build github:vicondoa/virgl-vaapi-compat#compatibility-report\n```\n\nSee [`docs/nix.md`](docs/nix.md).\n\nClient-specific packaging, browser policies, wrapper packages, and application\nlogging recipes belong in downstream client repositories. This generic repo only\ndocuments the libva shim boundary.\n\n## Safety and scope\n\n`virgl-vaapi-compat` intentionally has a small blast radius:\n\n- hooks only `vaExportSurfaceHandle`\n- rewrites only successful `DRM_PRIME_2` I420 surface exports with at least the\n  U and V layer entries needed for the swap\n- changes descriptor metadata only; it does not touch pixel data or file\n  descriptors\n- leaves unsupported formats and failure paths untouched\n- can be enabled per-process with `LIBVA_DRIVERS_PATH`\n\nBecause it shadows a system VA driver name, deploy it conservatively: keep the\nreal driver available, test with `vainfo` and a known VA-API client, and remove\nit once the underlying stack no longer needs descriptor translation.\n\n## Status\n\nThis project is a focused compatibility adapter for a currently observed\nvirgl/virtio-gpu VA-API interop issue. It should become unnecessary when either\nvirgl/Mesa exports a client-accepted DRM PRIME descriptor directly, or affected\nclients accept the existing virgl I420 descriptor path. See\n[`docs/removal-criteria.md`](docs/removal-criteria.md).\n\n## Documentation\n\n- [`docs/how-it-works.md`](docs/how-it-works.md) - operational walkthrough of\n  the shim\n- [`docs/design.md`](docs/design.md) - design goals, non-goals, and constraints\n- [`docs/debugging.md`](docs/debugging.md) - reproducing and diagnosing the\n  motivating failure mode\n- [`docs/nix.md`](docs/nix.md) - Nix/NixOS integration notes\n- [`docs/troubleshooting.md`](docs/troubleshooting.md) - common symptoms and\n  fixes\n- [`docs/removal-criteria.md`](docs/removal-criteria.md) - how to know when the\n  shim can be retired\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicondoa%2Fvirgl-vaapi-compat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicondoa%2Fvirgl-vaapi-compat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicondoa%2Fvirgl-vaapi-compat/lists"}