SYCL Backend¶

The SYCL backend runs libvmaf's feature extractors on Intel GPUs (Arc, Xe integrated graphics) through oneAPI DPC++ and Level Zero. Build it with -Denable_sycl=true, select it with --backend sycl, and expect scores that equal the CPU's bit for bit for 24 of the 25 gated features.

This page covers what you need to build and run it, how closely it agrees with the CPU, and what is still open. The details live on five further pages:

Platform guides: bundling a self-contained binary and SYCL on Windows.

Hardware¶

The backend targets any SYCL device that Level Zero exposes.

• Intel Arc discrete GPUs: A-series (DG2 / ACM) and B-series (Battlemage).
• Intel integrated GPUs: Tiger Lake and later (Xe-LP, Xe-LPG, Xe2).
• Other devices: AMD through the HIP plugin and NVIDIA through the CUDA plugin work only when the DPC++ compiler is built with them. The shipped oneAPI binaries do not include the HIP plugin.

A device that is not in the ahead-of-time list, such as a Data Center GPU Flex or Max card, still works: the binary also carries portable SPIR-V, which the Level Zero runtime compiles on first use.

Requirements¶

build-config.env is the single source for these versions; the release image and CI install exactly what it names. Older oneAPI releases may work, but only the pinned set is tested.

ocloc is needed only for ahead-of-time builds (the default); see AOT targets. AdaptiveCpp is an alternative compiler, chosen with -Dsycl_compiler=acpp (see the table below).

Build¶

1. Configure from the repository root. The Meson source directory is core/:

   meson setup build core -Denable_sycl=true
   

2. Build:

   ninja -C build
   

The options that shape a SYCL build:

Run¶

./build/tools/vmaf ...                   # SYCL used automatically if it initialises
./build/tools/vmaf --backend sycl ...    # exit 100 if SYCL cannot initialise
./build/tools/vmaf --no_sycl ...         # force the CPU path
./build/tools/vmaf --sycl_device 1 ...   # pick device index 1

Index 0 is whichever device SYCL's default selector picks, usually the first discrete GPU. Pin an integrated GPU or a specific Arc card with --sycl_device, or with the oneAPI runtime variable ONEAPI_DEVICE_SELECTOR=level_zero:N.

Automatic selection falls back to the CPU when SYCL cannot initialise, for example when a Level Zero or Unified Runtime library fails to load or a container has no render node. The run still prints a score and exits 0; only a stderr line such as problem during vmaf_sycl_state_init, using CPU shows it. --backend sycl makes the failure explicit instead. See how selection works.

Choosing a twin from --feature¶

With --backend sycl, a --feature that names a CPU extractor runs on that extractor's SYCL twin (ADR-1359):

vmaf ... --backend sycl --feature cambi          # runs cambi_sycl
vmaf ... --backend sycl --feature psnr=enable_mse=true
vmaf ... --backend sycl --feature float_motion_sycl=motion_max_val=4

The twin runs only when it can honour the options and the frame size and bit depth you gave. Otherwise the CPU extractor runs and vmaf prints one warning that names the reason; the feature_backends receipt in the JSON output lists which extractor ran where. The rules and the warning texts are in CLI: feature extractors on a GPU backend. Naming the twin (adm_sycl) always selects it, and it fails when it cannot run.

A model's feature list resolves the same way, so the default model vmaf_v1.0.16_3d0h runs its VIF, ADM, motion and CAMBI features on the device.

Environment variables¶

VMAF_SYCL_DISPATCH is also listed in the env-var reference.

Dispatch strategy¶

VMAF_SYCL_DISPATCH chooses how kernels reach the device:

When nothing is set, an area threshold decides: graph from 1280 x 720 pixels upward, direct below. The zero-copy VA-import path of the libvmaf_sycl FFmpeg filter is the exception and defaults to direct at every resolution: there the graph's output is byte-identical, but the per-frame de-tile import plus the graph's compute barrier serialise decode and compute, which costs 15 to 25 % at 4K (ADR-1121). Set VMAF_SYCL_USE_GRAPH=1 or VMAF_SYCL_DISPATCH=<feature>:graph to force the graph there anyway.

VMAF_SYCL_NO_GRAPH is deprecated (ADR-0841): it still works, prints a one-shot warning, and the warning names v4.0 as the removal release. VMAF_SYCL_IMPORT_DEBUG is read once at init, so changing it mid-run has no effect.

Numerical agreement with the CPU¶

The SYCL twins return the CPU extractors' bits. The cross-backend gate compares 25 features; 24 have an exact-twin declaration in scripts/ci/exact_twins.d/*.sycl and are held to tolerance 0. Only ciede is bounded, at 1e-9 (measured 1.4e-11). The generated list is the exact-twin table and the procedure is in the gate guide.

Measured on an Intel Arc A380 (2026-10-02) with the default model, the VMAF score of every frame equals --backend cpu on the Netflix src01 pair (48 frames) and on 50 frames of BBB 3840x2160.

float_ansnr has no twin; it was removed (ADR-0865). The extractor-by-extractor coverage across all backends is in metrics/features.md.

Four rules about device code make the table possible. Each is enforced by a test, and Twin notes explains how the twins meet them:

The Netflix golden-data gate is CPU-only (principles). The SYCL backend's numerics are pinned by fork-added tests such as test_sycl_exact_twins, not by the Netflix goldens.

AOT targets (default, ADR-0568)¶

The default build compiles device code ahead of time for 19 Intel targets, so the first launch does not pay a JIT compile. A device outside the list falls back to SPIR-V JIT.

Override the list with -Dsycl_icpx_aot_targets=dg2-g11,mtl-h, or disable AOT with -Dsycl_icpx_aot_targets=''. AOT targets has the silicon behind each name, the build and image checks, the target-list recipes and the sub-group-size table.

Scratch memory on Intel GPUs (ADR-1395)¶

A kernel uses scratch memory when the Intel graphics compiler puts a private array in memory or spills registers there. On an Arc A-series GPU under the Linux xe kernel driver, such kernels return wrong values with no error. This was measured on an Arc A380 with compute runtime 26.35.39758.10 and IGC 2.41.5, where the same kernels were correct under i915.

The fork's rule is that SYCL kernels use no scratch memory (ADR-1395). Since 2026-10-01 none does: the list of kernels that still did, core/src/sycl/scratch_ratchet.txt, is empty. float_adm_sycl was the last extractor on it; until then it returned NaN on an Arc A380 under xe and the run stopped with problem reading pictures.

What you see¶

At the first SYCL initialisation on each device, libvmaf runs two small probe kernels, one with a private array and one that spills. When either returns wrong values it logs a warning like this:

libvmaf WARNING SYCL: Intel(R) Arc(TM) A380 Graphics returns wrong values from kernels that use
scratch memory (private-array probe: 256 of 256 work-items wrong; register-spill probe: 256 of 256).
Seen on Arc A-series GPUs under the Linux xe kernel driver, not under i915. No libvmaf SYCL
extractor uses scratch memory, so its scores are not affected. See
docs/backends/sycl/overview.md (ADR-1395).

The device is still used and every libvmaf extractor gives correct scores on it. The warning stays because it describes the device: a kernel from outside libvmaf, or one added without the audit in the developer notes, would be affected.

The probes cost 3 to 5 ms with a warm compute-runtime kernel cache and about 0.4 s on the first run. VMAF_SYCL_SCRATCH_SELFTEST=0 skips them.

Checking a device¶

test_sycl_kernel_scratch (in --suite sycl) builds every kernel libvmaf registers for the default GPU and fails on each one that uses scratch memory:

ONEAPI_DEVICE_SELECTOR=level_zero:0 \
  python3 scripts/ci/run_meson_test.py -- -C build -v test_sycl_kernel_scratch

The ratchet list that used to exempt known kernels is empty and stays empty; test_sycl_kernel_source_contract.py rejects a new entry without a device. The test skips without a GPU, so CI, which has none, does not run it.

It audited 128 kernels on an Arc A380 at the revision of ADR-1488 (2026-10-02) and found none. On an Arc B580 and an Arc Pro B60 (Xe2, xe driver) it audited 127 kernels and found none (2026-10-03). Both Xe2 cards return correct values from the two probes, so they log no warning. Until 2026-10-03 the term kernel of float_adm_sycl used 128 bytes of scratch memory there (ADR-1501).

VIF kernels run at SIMD-16¶

vif_sycl runs its kernels at sub-group size 16 on every device (ADR-1830); a SYCL device without SIMD-16 sub-groups (no Intel GPU) gets -ENOTSUP from it. The SIMD-32 kernels and the VMAF_SYCL_VIF_SUBGROUP_SIZE variable that forced them were removed on 2026-10-05: they needed a 256-entry register file that Xe-LP integrated GPUs (UHD 770 and similar) do not have, spilled to scratch memory there, and were never faster than SIMD-16 on an Arc A380 (21.19 against 21.20 ms per frame at 3840x2160, 33.85 against 23.50 ms with vif_fused=true). Setting the variable now has no effect.

Profiling¶

• Intel VTune (vtune-gui) with the GPU Compute analysis type for kernel occupancy and EU utilization.
• onetrace from the pti-gpu project for Level Zero API-level tracing.
• VMAF_SYCL_PROFILE=1 gives the queues enable_profiling; with VMAF_SYCL_NO_GRAPH=1 graph extractors submit directly, so every kernel has its own event (Research-1369 describes the event-timing build).
• For end-to-end wall-time comparisons against the CUDA and CPU paths, use make test-netflix-golden, which records per-backend scores and timings.
• Programmatic profiling through VmafSyclState.enable_profiling; see api/gpu.md for the queue-event query API.

Known gaps¶

Only open items are listed. A closed gap is recorded in History and in docs/state.md, which is the authority on status.

See metrics/features.md for the per-extractor coverage matrix and api/gpu.md for the programmatic surface.

References¶

• SYCL 2020 Specification
• Intel oneAPI DPC++ Compiler
• Level Zero Specification
• Intel oneAPI Programming Guide

Licensing of the SYCL kernels (ADR-1250)¶

As with the other backends, a SYCL kernel implementing an upstream Netflix metric keeps that code's terms and copyright notice, while fork-original SYCL code is EUPL-1.2. Four files in core/src/sycl/ additionally carry an outside contributor's work and stay on their current terms until that contributor agrees to a change. See ADR-1250.

Former section names¶

ADRs and research digests link to these headings; each points to the section that now holds its content.

Numerical tolerance vs the CPU scalar path¶

Now under numerical agreement with the CPU.