sh_eth: fix EESIPR values for SH77{34|63}
[linux/fpc-iii.git] / Documentation / media / uapi / v4l / vidioc-g-fbuf.rst
blob4a6a03d158cad61c71e9c398cd117f4ca5148758
1 .. -*- coding: utf-8; mode: rst -*-
3 .. _VIDIOC_G_FBUF:
5 **********************************
6 ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
7 **********************************
9 Name
10 ====
12 VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
15 Synopsis
16 ========
18 .. c:function:: int ioctl( int fd, VIDIOC_G_FBUF, struct v4l2_framebuffer *argp )
19     :name: VIDIOC_G_FBUF
21 .. c:function:: int ioctl( int fd, VIDIOC_S_FBUF, const struct v4l2_framebuffer *argp )
22     :name: VIDIOC_S_FBUF
25 Arguments
26 =========
28 ``fd``
29     File descriptor returned by :ref:`open() <func-open>`.
31 ``argp``
34 Description
35 ===========
37 Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
38 to get and set the framebuffer parameters for a
39 :ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
40 (OSD). The type of overlay is implied by the device type (capture or
41 output device) and can be determined with the
42 :ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
43 device must not support both kinds of overlay.
45 The V4L2 API distinguishes destructive and non-destructive overlays. A
46 destructive overlay copies captured video images into the video memory
47 of a graphics card. A non-destructive overlay blends video images into a
48 VGA signal or graphics into a video signal. *Video Output Overlays* are
49 always non-destructive.
51 To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
52 ioctl with a pointer to a struct :c:type:`v4l2_framebuffer`
53 structure. The driver fills all fields of the structure or returns an
54 EINVAL error code when overlays are not supported.
56 To set the parameters for a *Video Output Overlay*, applications must
57 initialize the ``flags`` field of a struct
58 struct :c:type:`v4l2_framebuffer`. Since the framebuffer is
59 implemented on the TV card all other parameters are determined by the
60 driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
61 this structure, the driver prepares for the overlay and returns the
62 framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
63 code.
65 To set the parameters for a *non-destructive Video Overlay*,
66 applications must initialize the ``flags`` field, the ``fmt``
67 substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
68 the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
69 does, or it returns an error code.
71 For a *destructive Video Overlay* applications must additionally provide
72 a ``base`` address. Setting up a DMA to a random memory location can
73 jeopardize the system security, its stability or even damage the
74 hardware, therefore only the superuser can set the parameters for a
75 destructive video overlay.
78 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
80 .. c:type:: v4l2_framebuffer
82 .. cssclass:: longtable
84 .. flat-table:: struct v4l2_framebuffer
85     :header-rows:  0
86     :stub-columns: 0
87     :widths:       1 1 1 2
89     * - __u32
90       - ``capability``
91       -
92       - Overlay capability flags set by the driver, see
93         :ref:`framebuffer-cap`.
94     * - __u32
95       - ``flags``
96       -
97       - Overlay control flags set by application and driver, see
98         :ref:`framebuffer-flags`
99     * - void *
100       - ``base``
101       -
102       - Physical base address of the framebuffer, that is the address of
103         the pixel in the top left corner of the framebuffer. [#f1]_
104     * -
105       -
106       -
107       - This field is irrelevant to *non-destructive Video Overlays*. For
108         *destructive Video Overlays* applications must provide a base
109         address. The driver may accept only base addresses which are a
110         multiple of two, four or eight bytes. For *Video Output Overlays*
111         the driver must return a valid base address, so applications can
112         find the corresponding Linux framebuffer device (see
113         :ref:`osd`).
114     * - struct
115       - ``fmt``
116       -
117       - Layout of the frame buffer.
118     * -
119       - __u32
120       - ``width``
121       - Width of the frame buffer in pixels.
122     * -
123       - __u32
124       - ``height``
125       - Height of the frame buffer in pixels.
126     * -
127       - __u32
128       - ``pixelformat``
129       - The pixel format of the framebuffer.
130     * -
131       -
132       -
133       - For *non-destructive Video Overlays* this field only defines a
134         format for the struct :c:type:`v4l2_window`
135         ``chromakey`` field.
136     * -
137       -
138       -
139       - For *destructive Video Overlays* applications must initialize this
140         field. For *Video Output Overlays* the driver must return a valid
141         format.
142     * -
143       -
144       -
145       - Usually this is an RGB format (for example
146         :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
147         formats (only packed YUV formats when chroma keying is used, not
148         including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
149         ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
150         the driver when an application requests a compressed format is
151         undefined. See :ref:`pixfmt` for information on pixel formats.
152     * -
153       - enum :c:type:`v4l2_field`
154       - ``field``
155       - Drivers and applications shall ignore this field. If applicable,
156         the field order is selected with the
157         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
158         field of struct :c:type:`v4l2_window`.
159     * -
160       - __u32
161       - ``bytesperline``
162       - Distance in bytes between the leftmost pixels in two adjacent
163         lines.
164     * - :cspan:`3`
166         This field is irrelevant to *non-destructive Video Overlays*.
168         For *destructive Video Overlays* both applications and drivers can
169         set this field to request padding bytes at the end of each line.
170         Drivers however may ignore the requested value, returning
171         ``width`` times bytes-per-pixel or a larger value required by the
172         hardware. That implies applications can just set this field to
173         zero to get a reasonable default.
175         For *Video Output Overlays* the driver must return a valid value.
177         Video hardware may access padding bytes, therefore they must
178         reside in accessible memory. Consider for example the case where
179         padding bytes after the last line of an image cross a system page
180         boundary. Capture devices may write padding bytes, the value is
181         undefined. Output devices ignore the contents of padding bytes.
183         When the image format is planar the ``bytesperline`` value applies
184         to the first plane and is divided by the same factor as the
185         ``width`` field for the other planes. For example the Cb and Cr
186         planes of a YUV 4:2:0 image have half as many padding bytes
187         following each line as the Y plane. To avoid ambiguities drivers
188         must return a ``bytesperline`` value rounded up to a multiple of
189         the scale factor.
190     * -
191       - __u32
192       - ``sizeimage``
193       - This field is irrelevant to *non-destructive Video Overlays*. For
194         *destructive Video Overlays* applications must initialize this
195         field. For *Video Output Overlays* the driver must return a valid
196         format.
198         Together with ``base`` it defines the framebuffer memory
199         accessible by the driver.
200     * -
201       - enum :c:type:`v4l2_colorspace`
202       - ``colorspace``
203       - This information supplements the ``pixelformat`` and must be set
204         by the driver, see :ref:`colorspaces`.
205     * -
206       - __u32
207       - ``priv``
208       - Reserved. Drivers and applications must set this field to zero.
211 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
213 .. _framebuffer-cap:
215 .. flat-table:: Frame Buffer Capability Flags
216     :header-rows:  0
217     :stub-columns: 0
218     :widths:       3 1 4
220     * - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
221       - 0x0001
222       - The device is capable of non-destructive overlays. When the driver
223         clears this flag, only destructive overlays are supported. There
224         are no drivers yet which support both destructive and
225         non-destructive overlays. Video Output Overlays are in practice
226         always non-destructive.
227     * - ``V4L2_FBUF_CAP_CHROMAKEY``
228       - 0x0002
229       - The device supports clipping by chroma-keying the images. That is,
230         image pixels replace pixels in the VGA or video signal only where
231         the latter assume a certain color. Chroma-keying makes no sense
232         for destructive overlays.
233     * - ``V4L2_FBUF_CAP_LIST_CLIPPING``
234       - 0x0004
235       - The device supports clipping using a list of clip rectangles.
236     * - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
237       - 0x0008
238       - The device supports clipping using a bit mask.
239     * - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
240       - 0x0010
241       - The device supports clipping/blending using the alpha channel of
242         the framebuffer or VGA signal. Alpha blending makes no sense for
243         destructive overlays.
244     * - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
245       - 0x0020
246       - The device supports alpha blending using a global alpha value.
247         Alpha blending makes no sense for destructive overlays.
248     * - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
249       - 0x0040
250       - The device supports clipping/blending using the inverted alpha
251         channel of the framebuffer or VGA signal. Alpha blending makes no
252         sense for destructive overlays.
253     * - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
254       - 0x0080
255       - The device supports Source Chroma-keying. Video pixels with the
256         chroma-key colors are replaced by framebuffer pixels, which is
257         exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
260 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
262 .. _framebuffer-flags:
264 .. cssclass:: longtable
266 .. flat-table:: Frame Buffer Flags
267     :header-rows:  0
268     :stub-columns: 0
269     :widths:       3 1 4
271     * - ``V4L2_FBUF_FLAG_PRIMARY``
272       - 0x0001
273       - The framebuffer is the primary graphics surface. In other words,
274         the overlay is destructive. This flag is typically set by any
275         driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
276         capability and it is cleared otherwise.
277     * - ``V4L2_FBUF_FLAG_OVERLAY``
278       - 0x0002
279       - If this flag is set for a video capture device, then the driver
280         will set the initial overlay size to cover the full framebuffer
281         size, otherwise the existing overlay size (as set by
282         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
283         video capture driver (bttv) supports this flag. The use of this
284         flag for capture devices is deprecated. There is no way to detect
285         which drivers support this flag, so the only reliable method of
286         setting the overlay size is through
287         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
288         video output device, then the video output overlay window is
289         relative to the top-left corner of the framebuffer and restricted
290         to the size of the framebuffer. If it is cleared, then the video
291         output overlay window is relative to the video output display.
292     * - ``V4L2_FBUF_FLAG_CHROMAKEY``
293       - 0x0004
294       - Use chroma-keying. The chroma-key color is determined by the
295         ``chromakey`` field of struct :c:type:`v4l2_window`
296         and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
297         ioctl, see :ref:`overlay` and :ref:`osd`.
298     * - :cspan:`2` There are no flags to enable clipping using a list of
299         clip rectangles or a bitmap. These methods are negotiated with the
300         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
301         and :ref:`osd`.
302     * - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
303       - 0x0008
304       - Use the alpha channel of the framebuffer to clip or blend
305         framebuffer pixels with video images. The blend function is:
306         output = framebuffer pixel * alpha + video pixel * (1 - alpha).
307         The actual alpha depth depends on the framebuffer pixel format.
308     * - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
309       - 0x0010
310       - Use a global alpha value to blend the framebuffer with video
311         images. The blend function is: output = (framebuffer pixel * alpha
312         + video pixel * (255 - alpha)) / 255. The alpha value is
313         determined by the ``global_alpha`` field of struct
314         :c:type:`v4l2_window` and negotiated with the
315         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
316         and :ref:`osd`.
317     * - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
318       - 0x0020
319       - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
320         framebuffer to clip or blend framebuffer pixels with video images,
321         but with an inverted alpha value. The blend function is: output =
322         framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
323         alpha depth depends on the framebuffer pixel format.
324     * - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
325       - 0x0040
326       - Use source chroma-keying. The source chroma-key color is
327         determined by the ``chromakey`` field of struct
328         :c:type:`v4l2_window` and negotiated with the
329         :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
330         and :ref:`osd`. Both chroma-keying are mutual exclusive to each
331         other, so same ``chromakey`` field of struct
332         :c:type:`v4l2_window` is being used.
335 Return Value
336 ============
338 On success 0 is returned, on error -1 and the ``errno`` variable is set
339 appropriately. The generic error codes are described at the
340 :ref:`Generic Error Codes <gen-errors>` chapter.
342 EPERM
343     :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
344     negotiate the parameters for a destructive overlay.
346 EINVAL
347     The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
349 .. [#f1]
350    A physical base address may not suit all platforms. GK notes in
351    theory we should pass something like PCI device + memory region +
352    offset instead. If you encounter problems please discuss on the
353    linux-media mailing list:
354    `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.