비디오 Overlay 인터페이스

Overlay 개요와 동시 스트림 모델

Video Overlay 인터페이스는 Framebuffer Overlay 또는 previewing이라고도 부릅니다. 일부 비디오 캡처 장치는 TV 영상 신호를 VGA 신호와 genlock 방식으로 합성하거나, 캡처한 영상을 그래픽 카드의 video memory에 직접 저장합니다. 보통 화면의 일부 영역만 갱신하도록 clipping하며, 예전에는 CPU와 bus 자원을 적게 쓰는 효율적인 미리보기 방식이었습니다.

Overlay는 video capture와 같은 character special file로 접근합니다. `/dev/video` 장치의 기본 기능은 capture이고, 애플리케이션이 `VIDIOC_S_FMT`로 overlay 형식을 설정한 뒤에만 overlay 기능을 사용할 수 있습니다.

드라이버가 허용하면 overlay와 read/write 또는 streaming capture를 동시에 실행할 수 있습니다. 다만 명목상 frame rate가 보장되는 것은 아닙니다. 장치가 일부 frame을 capture 쪽으로 전환하거나, 두 요청의 매개변수가 맞을 때 한 field씩 번갈아 처리할 수 있기 때문입니다.

동시 overlay와 capture를 사용하는 애플리케이션은 서로 다른 file descriptor를 사용해야 합니다. 이 기능을 제공하는 모든 드라이버는 두 descriptor 방식을 지원해야 하고, 하나의 descriptor에서 두 logical stream을 다루는 구형 V4L/초기 V4L2 호환 방식은 선택 사항입니다.

대표적인 구성은 X11의 Xv/V4L 드라이버가 한 descriptor로 overlay를 소유하고, 별도의 V4L2 애플리케이션이 다른 descriptor에서 memory mapping 또는 DMA capture를 수행하는 형태입니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _overlay:

***********************
Video Overlay Interface
***********************

**Also known as Framebuffer Overlay or Previewing.**

Video overlay devices have the ability to genlock (TV-)video into the
(VGA-)video signal of a graphics card, or to store captured images
directly in video memory of a graphics card, typically with clipping.
This can be considerable more efficient than capturing images and
displaying them by other means. In the old days when only nuclear power
plants needed cooling towers this used to be the only way to put live
video into a window.

Video overlay devices are accessed through the same character special
files as :ref:`video capture <capture>` devices.

.. note::

   The default function of a ``/dev/video`` device is video
   capturing. The overlay function is only available after calling
   the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.

The driver may support simultaneous overlay and capturing using the
read/write and streaming I/O methods. If so, operation at the nominal
frame rate of the video standard is not guaranteed. Frames may be
directed away from overlay to capture, or one field may be used for
overlay and the other for capture if the capture parameters permit this.

Applications should use different file descriptors for capturing and
overlay. This must be supported by all drivers capable of simultaneous
capturing and overlay. Optionally these drivers may also permit
capturing and overlay with a single file descriptor for compatibility
with V4L and earlier versions of V4L2. [#f1]_

A common application of two file descriptors is the X11
:ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
While the X server controls video overlay, the application can take
advantage of memory mapping and DMA.

Capability와 보조 기능

Video Overlay를 지원하는 장치는 `VIDIOC_QUERYCAP`가 반환하는 `struct v4l2_capability.capabilities`에 `V4L2_CAP_VIDEO_OVERLAY`를 설정합니다. 이 장치에는 overlay I/O가 필수이고 tuner와 audio input은 선택 사항입니다.

장치가 실제로 제공하는 기능에 따라 audio input, tuner, control, cropping/scaling, streaming parameter 관련 ioctl도 지원해야 합니다. 반면 video input과 video standard ioctl은 모든 Video Overlay 장치가 반드시 구현해야 합니다.

Querying Capabilities
=====================

Devices supporting the video overlay interface set the
``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
method specified below must be supported. Tuners and audio inputs are
optional.


Supplemental Functions
======================

Video overlay devices shall support :ref:`audio input <audio>`,
:ref:`tuner`, :ref:`controls <control>`,
:ref:`cropping and scaling <crop>` and
:ref:`streaming parameter <streaming-par>` ioctls as needed. The
:ref:`video input <video>` and :ref:`video standard <standard>`
ioctls must be supported by all video overlay devices.

Framebuffer 설정과 clipping 방식

현재 API에서 framebuffer setup 지원은 제거되었습니다. 다음 설명은 제거된 인터페이스의 동작과 기존 애플리케이션이 알아야 할 의미를 기록합니다.

과거 인터페이스에서는 overlay를 시작하기 전에 `VIDIOC_G_FBUF`와 `VIDIOC_S_FBUF`로 framebuffer의 physical address, 크기, pixel format을 설정했습니다. 예를 들어 RGB 5:6:5처럼 그래픽 메모리에 실제로 쓰이는 형식을 지정했습니다.

Framebuffer physical memory로 DMA하면 커널의 메모리 보호를 우회할 수 있으므로 `VIDIOC_S_FBUF`는 일반적으로 권한이 필요한 작업이었습니다. address와 크기를 바꾸는 권한은 superuser에게만 주어야 하며, TV 애플리케이션 전체를 root 또는 SUID로 실행해서는 안 됩니다. 필요한 설정만 작은 privileged helper로 분리하는 방식이 권장됩니다.

일부 장치는 framebuffer 내용을 수정하지 않고 그래픽 출력 단계에서 video를 합성합니다. 이런 장치는 address나 pixel format 설정이 필요하지 않고 `VIDIOC_S_FBUF`도 특권 작업이 아닙니다. 애플리케이션은 `VIDIOC_G_FBUF` 결과로 이 방식을 구별할 수 있습니다.

Overlay 영역을 제한하거나 배경과 합성하는 방법은 다섯 가지입니다. chroma key, 제거된 bitmap, 제거된 clipping rectangle list, framebuffer alpha channel, global alpha가 그것입니다. 실제 지원 방식은 framebuffer capability와 flag를 통해 협상합니다.

Capture와 overlay를 동시에 요청했는데 capture image format과 framebuffer format을 하드웨어가 함께 처리할 수 없다면 먼저 설정된 요청이 우선합니다. 나중의 `VIDIOC_S_FMT` 또는 `VIDIOC_S_FBUF`는 `EBUSY`로 실패하거나 하드웨어가 지원하는 매개변수로 조정해 반환할 수 있습니다.

Setup
=====

*Note: support for this has been removed.*
Before overlay can commence applications must program the driver with
frame buffer parameters, namely the address and size of the frame buffer
and the image format, for example RGB 5:6:5. The
:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
privileged because it allows to set up DMA into physical memory,
bypassing the memory protection mechanisms of the kernel. Only the
superuser can change the frame buffer address and size. Users are not
supposed to run TV applications as root or with SUID bit set. A small
helper application with suitable privileges should query the graphics
system and program the V4L2 driver at the appropriate time.

Some devices add the video overlay to the output signal of the graphics
card. In this case the frame buffer is not modified by the video device,
and the frame buffer address and pixel format are not needed by the
driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
ioctl.

A driver may support any (or none) of five clipping/blending methods:

1. Chroma-keying displays the overlaid image only where pixels in the
   primary graphics surface assume a certain color.

2. *Note: support for this has been removed.*
   A bitmap can be specified where each bit corresponds to a pixel in
   the overlaid image. When the bit is set, the corresponding video
   pixel is displayed, otherwise a pixel of the graphics surface.

3. *Note: support for this has been removed.*
   A list of clipping rectangles can be specified. In these regions *no*
   video is displayed, so the graphics surface can be seen here.

4. The framebuffer has an alpha channel that can be used to clip or
   blend the framebuffer with the video.

5. A global alpha value can be specified to blend the framebuffer
   contents with video images.

When simultaneous capturing and overlay is supported and the hardware
prohibits different image and frame buffer formats, the format requested
first takes precedence. The attempt to capture
(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
code or return accordingly modified parameters..

Overlay window와 scaling

Cropping은 incoming video에서 사용할 영역을 고르고, overlay window는 framebuffer에서 영상을 놓을 위치와 clipping 정보를 정의합니다. 설정을 시작할 때 crop을 기본값으로 되돌리면 두 좌표계의 관계를 예측하기 쉽습니다.

현재 window를 읽으려면 `struct v4l2_format.type`을 `V4L2_BUF_TYPE_VIDEO_OVERLAY`로 설정하고 `VIDIOC_G_FMT`를 호출합니다. 드라이버는 `fmt.win`의 `struct v4l2_window`를 채웁니다. 과거에 설정한 clipping list나 bitmap은 다시 가져올 수 없습니다.

Window를 설정할 때는 같은 type으로 `win`을 채워 `VIDIOC_S_FMT`를 호출합니다. 드라이버는 하드웨어 제약에 맞게 값을 조정하고 실제 값을 반환합니다. `VIDIOC_TRY_FMT`는 상태를 바꾸지 않고 같은 제약을 시험하며, overlay를 이미 enabled한 뒤에도 사용할 수 있습니다.

Scaling 비율은 `v4l2_window`의 width와 height를 crop rectangle의 크기와 비교해 정해집니다. 하나가 framebuffer의 destination 크기이고 다른 하나가 incoming video의 source 크기입니다.

동시 capture와 overlay에서 image 크기와 window 크기를 서로 다르게 설정할 수 없는 하드웨어도 있습니다. 이때 역시 첫 요청이 우선하고 나중의 `VIDIOC_S_FMT`는 `EBUSY`로 실패하거나 조정된 값을 반환할 수 있습니다.

Overlay Window
==============

The overlaid image is determined by cropping and overlay window
parameters. The former select an area of the video picture to capture,
the latter how images are overlaid and clipped. Cropping initialization
at minimum requires to reset the parameters to defaults. An example is
given in :ref:`crop`.

The overlay window is described by a struct
:c:type:`v4l2_window`. It defines the size of the image,
its position over the graphics surface and the clipping to be applied.
To get the current parameters applications set the ``type`` field of a
struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
struct :c:type:`v4l2_window` substructure named ``win``. It is not
possible to retrieve a previously programmed clipping list or bitmap.

To program the overlay window applications set the ``type`` field of a
struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
adjusts the parameters against hardware limits and returns the actual
parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
about driver capabilities without actually changing driver state. Unlike
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.

The scaling factor of the overlaid image is implied by the width and
height given in struct :c:type:`v4l2_window` and the size
of the cropping rectangle. For more information see :ref:`crop`.

When simultaneous capturing and overlay is supported and the hardware
prohibits different image and window sizes, the size requested first
takes precedence. The attempt to capture or overlay as well
(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
code or return accordingly modified parameters.

v4l2_window의 위치, field, chromakey

`struct v4l2_window.w`는 framebuffer 왼쪽 위를 기준으로 한 `struct v4l2_rect`입니다. x와 y는 음수일 수 있고 width와 height 때문에 오른쪽이나 아래쪽 경계를 넘어갈 수도 있으며, window 전체가 framebuffer 밖에 놓일 수도 있습니다. 드라이버는 가능한 부분을 clip하거나 지원 가능한 값으로 조정합니다.

`field`는 `V4L2_FIELD_ANY`, `V4L2_FIELD_TOP`, `V4L2_FIELD_BOTTOM`, `V4L2_FIELD_INTERLACED` 중 하나입니다. 애플리케이션이 `V4L2_FIELD_ANY`를 요청하면 드라이버가 실제 field order를 선택해 반환할 수 있습니다.

`chromakey`는 `VIDIOC_S_FBUF`로 협상한 framebuffer pixel format의 값이며 host byte order를 따릅니다. BGR24에서 같은 RGB 성분은 little-endian host에서는 `0xRRGGBB`, big-endian host에서는 `0xBBGGRR`로 표현됩니다.

.. c:type:: v4l2_window

struct v4l2_window
------------------

``struct v4l2_rect w``
    Size and position of the window relative to the top, left corner of
    the frame buffer defined with
    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
    frame buffer width and height, the ``x`` and ``y`` coordinates can
    be negative, and it can lie completely outside the frame buffer. The
    driver clips the window accordingly, or if that is not possible,
    modifies its size and/or position.

``enum v4l2_field field``
    Applications set this field to determine which video field shall be
    overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
    ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
    ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
    field order and return the actual setting here.

``__u32 chromakey``
    When chroma-keying has been negotiated with
    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
    to the desired pixel value for the chroma key. The format is the
    same as the pixel format of the framebuffer (struct
    :c:type:`v4l2_framebuffer` ``fmt.pixelformat``
    field), with bytes in host order. E. g. for
    :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
    be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.

Clips, bitmap과 global alpha

`clips`와 `clipcount`로 clipping rectangle list를 넘기는 지원은 제거되었습니다. 과거에는 chroma key를 쓰지 않고 `VIDIOC_G_FBUF`가 기능을 알렸을 때 `clips`가 `struct v4l2_clip` 배열을 가리켰습니다. 각 rectangle은 window 왼쪽 위에 상대적이고 framebuffer 경계를 벗어나거나 서로 겹치면 안 되며, 가능한 경우 인접 rectangle을 합쳐야 했습니다. Banding이나 목록 순서에는 의미가 없었습니다.

지원되지 않는 장치에서는 `clips`와 `clipcount`가 무시되고 `VIDIOC_S_FMT` 뒤 내용도 정의되지 않습니다. 지원 장치에서 `clipcount`가 0이면 clipping하지 않는다는 뜻이었습니다. 애플리케이션은 예전 clipping list를 다시 읽을 수 없습니다.

`bitmap` 지원도 제거되었습니다. 과거에는 chroma key가 없고 framebuffer가 bitmap clipping을 지원할 때 window와 같은 크기의 bit mask를 전달했습니다. 좌표 `(x, y)`의 bit는 `((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))` 식으로 검사하며 범위는 `0 <= x < w.width`, `0 <= y < w.height`입니다.

지원하지 않는 장치는 bitmap을 무시하고 호출 뒤 내용을 정의하지 않습니다. 지원 장치에서 `bitmap == NULL`이면 clipping이 없습니다. Clipping list와 bitmap을 동시에 넘기거나 chroma key와 함께 넘기는 동작은 정의되지 않으며, 하드웨어 한계를 넘는 목록이나 mask를 제공한 결과도 정의되지 않습니다.

`global_alpha`는 `V4L2_FBUF_FLAG_GLOBAL_ALPHA`가 설정된 경우 framebuffer와 video를 혼합하는 전체 alpha 값입니다. 이 필드는 Linux 2.6.23에 추가되었지만 부모 `struct v4l2_format`의 padding 덕분에 기존 `VIDIOC_G_FMT`, `VIDIOC_S_FMT`, `VIDIOC_TRY_FMT` 호출의 binary layout에는 영향을 주지 않았습니다.

``struct v4l2_clip * clips``
    *Note: support for this has been removed.*
    When chroma-keying has *not* been negotiated and
    :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
    applications can set this field to point to an array of clipping
    rectangles.

    Like the window coordinates w, clipping rectangles are defined
    relative to the top, left corner of the frame buffer. However
    clipping rectangles must not extend the frame buffer width and
    height, and they must not overlap. If possible applications
    should merge adjacent rectangles. Whether this must create
    x-y or y-x bands, or the order of rectangles, is not defined. When
    clip lists are not supported the driver ignores this field. Its
    contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
    are undefined.

``__u32 clipcount``
    *Note: support for this has been removed.*
    When the application set the ``clips`` field, this field must
    contain the number of clipping rectangles in the list. When clip
    lists are not supported the driver ignores this field, its contents
    after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
    supported but no clipping is desired this field must be set to zero.

``void * bitmap``
    *Note: support for this has been removed.*
    When chroma-keying has *not* been negotiated and
    :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
    applications can set this field to point to a clipping bit mask.

It must be of the same size as the window, ``w.width`` and ``w.height``.
Each bit corresponds to a pixel in the overlaid image, which is
displayed only when the bit is *set*. Pixel coordinates translate to
bits like:


.. code-block:: c

    ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))

where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_

When a clipping bit mask is not supported the driver ignores this field,
its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
undefined. When a bit mask is supported but no clipping is desired this
field must be set to ``NULL``.

Applications need not create a clip list or bit mask. When they pass
both, or despite negotiating chroma-keying, the results are undefined.
Regardless of the chosen method, the clipping abilities of the hardware
may be limited in quantity or quality. The results when these limits are
exceeded are undefined. [#f3]_

``__u8 global_alpha``
    The global alpha value used to blend the framebuffer with video
    images, if global alpha blending has been negotiated
    (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
    :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
    :ref:`framebuffer-flags`).

.. note::

   This field was added in Linux 2.6.23, extending the
   structure. However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
   ioctls, which take a pointer to a :c:type:`v4l2_format`
   parent structure with padding bytes at the end, are not affected.

v4l2_clip과 v4l2_rect

`struct v4l2_clip.c`는 window 왼쪽 위를 기준으로 한 clipping rectangle입니다. 목록에 들어 있는 모든 clipping rectangle의 바깥쪽 pixel만 화면에 표시됩니다. 즉 rectangle은 표시 영역이 아니라 가릴 영역을 뜻합니다.

`struct v4l2_clip.next`는 다음 원소를 가리키고 마지막 원소에서 `NULL`인 pointer로 정의되어 있지만 드라이버는 이 값을 무시합니다. 따라서 linked list를 넘길 수 없고, 실제 ABI는 `clipcount`로 길이를 지정한 연속 배열을 전제로 했습니다.

`struct v4l2_rect`의 `left`와 `top`은 왼쪽 위 꼭짓점의 수평·수직 offset입니다. Offset은 오른쪽과 아래쪽으로 증가하며 `width`와 `height`는 pixel 단위입니다.

.. c:type:: v4l2_clip

struct v4l2_clip [#f4]_
-----------------------

``struct v4l2_rect c``
    Coordinates of the clipping rectangle, relative to the top, left
    corner of the frame buffer. Only window pixels *outside* all
    clipping rectangles are displayed.

``struct v4l2_clip * next``
    Pointer to the next clipping rectangle, ``NULL`` when this is the last
    rectangle. Drivers ignore this field, it cannot be used to pass a
    linked list of clipping rectangles.


.. c:type:: v4l2_rect

struct v4l2_rect
----------------

``__s32 left``
    Horizontal offset of the top, left corner of the rectangle, in
    pixels.

``__s32 top``
    Vertical offset of the top, left corner of the rectangle, in pixels.
    Offsets increase to the right and down.

``__u32 width``
    Width of the rectangle, in pixels.

``__u32 height``
    Height of the rectangle, in pixels.

Overlay 시작·중지와 설계 주석

설정이 끝나면 `VIDIOC_OVERLAY` ioctl로 overlay를 시작하거나 중지합니다. Format과 window 협상을 마친 뒤 표시 상태만 전환하는 단계입니다.

API 설계자는 동시 capture와 overlay에 두 file descriptor 방식을 반드시 지원하고 한 descriptor 방식은 선택 사항으로 두었습니다. 하나의 descriptor에서 두 stream의 상태와 명령을 섞으면 인터페이스가 복잡해지므로, descriptor 하나를 logical stream 하나에 대응시키는 모델이 기본입니다.

원문의 주석은 bitmap에서 `w.width`가 8의 배수여야 하는지 질문을 남깁니다. 명세가 확정하지 않은 부분이므로 애플리케이션은 임의로 가정하지 말고 드라이버가 반환한 제약과 실제 format을 따라야 합니다.

Framebuffer에 직접 쓰는 장치에서는 under-clipping이 특히 바람직하지 않습니다. 애플리케이션이나 그래픽 시스템이 손상된 영역을 다시 그려야 한다는 사실을 알지 못하기 때문입니다. 정확한 경계를 지원할 수 없다면 드라이버는 더 넓게 clip하거나 아예 쓰지 않는 쪽을 선택해야 합니다.

X11 region의 rectangle은 `BoxRec`의 `x1`, `y1`, `x2`, `y2`로 표현되고 width는 `x2 - x1`, height는 `y2 - y1`입니다. V4L2 clipping rectangle과 표현 및 의미가 다르므로 X11 clip list를 그대로 전달할 수 없습니다.

Enabling Overlay
================

To start or stop the frame buffer overlay applications call the
:ref:`VIDIOC_OVERLAY` ioctl.

.. [#f1]
   In the opinion of the designers of this API, no driver writer taking
   the efforts to support simultaneous capturing and overlay will
   restrict this ability by requiring a single file descriptor, as in
   V4L and earlier versions of V4L2. Making this optional means
   applications depending on two file descriptors need backup routines
   to be compatible with all drivers, which is considerable more work
   than using two fds in applications which do not. Also two fd's fit
   the general concept of one file descriptor for each logical stream.
   Hence as a complexity trade-off drivers *must* support two file
   descriptors and *may* support single fd operation.

.. [#f2]
   Should we require ``w.width`` to be a multiple of eight?

.. [#f3]
   When the image is written into frame buffer memory it will be
   undesirable if the driver clips out less pixels than expected,
   because the application and graphics system are not aware these
   regions need to be refreshed. The driver should clip out more pixels
   or not write the image at all.

.. [#f4]
   The X Window system defines "regions" which are vectors of ``struct
   BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
   ``height = y2 - y1``, so one cannot pass X11 clip lists directly.