How to Use the FFmpeg scale_opencl Filter

This article provides a straightforward guide on how to hardware-accelerate video scaling in FFmpeg using the scale_opencl filter. You will learn the required prerequisites, the syntax for initializing OpenCL devices, how to move frames between system memory and GPU memory, and a complete command-line example for practical use.

Prerequisites

To use scale_opencl, ensure your system meets the following requirements:

  1. FFmpeg with OpenCL Support: Your FFmpeg build must be compiled with the --enable-opencl flag. Verify this by running ffmpeg -buildconf and checking for --enable-opencl.
  2. OpenCL Drivers: Your GPU (Intel, AMD, or NVIDIA) must have functional OpenCL runtime drivers installed.

Understanding the Pipeline

Because OpenCL operates on GPU memory, standard video frames stored in CPU system RAM cannot be processed directly by scale_opencl. The processing chain requires:

  1. Initializing an OpenCL device context.
  2. Uploading the input frames from system RAM to GPU memory using hwupload.
  3. Applying the scale_opencl filter.
  4. Downloading the processed frames back to system RAM using hwdownload and restoring a compatible pixel format with the format filter before encoding.

The Basic Command

Here is the standard command to scale a video to 1920x1080 using OpenCL:

ffmpeg -init_hw_device opencl=ocl:0.0 -filter_hw_device ocl -i input.mp4 -vf "format=yuv420p,hwupload,scale_opencl=1920:1080,hwdownload,format=yuv420p" -c:v libx264 -c:a copy output.mp4

Breakdown of Parameters

  • -init_hw_device opencl=ocl:0.0: Initializes an OpenCL hardware device named ocl. The 0.0 specifies platform index 0 and device index 0.
  • -filter_hw_device ocl: Instructs the filter graph to use the OpenCL device named ocl.
  • format=yuv420p (first instance): Ensures the input pixel format is standardized before being sent to the GPU.
  • hwupload: Transfers raw frames from CPU memory to the GPU OpenCL surface.
  • scale_opencl=1920:1080: Performs the resize operation directly on the GPU. You can also use expressions like scale_opencl=1280:-1 to maintain aspect ratio.
  • hwdownload: Transfers the scaled frames from the GPU back to system memory.
  • format=yuv420p (second instance): Restores the pixel format required by standard software encoders like libx264.

Selecting the Correct Device

If your system has multiple GPUs or OpenCL platforms, you may need to adjust the 0.0 value. You can find available platforms and devices by running:

ffmpeg -init_hw_device opencl -v verbose

Review the output to locate the correct platform index and device index (e.g., 1.0 or 0.1), then update the -init_hw_device opencl=ocl:X.Y argument accordingly.