1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10********
11Examples
12********
13
14(A video capture device is assumed; change
15``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
16``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
17
18Example: Resetting the cropping parameters
19==========================================
20
21.. code-block:: c
22
23	struct v4l2_selection sel = {
24	    .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
25	    .target = V4L2_SEL_TGT_CROP_DEFAULT,
26	};
27	ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
28	if (ret)
29	    exit(-1);
30	sel.target = V4L2_SEL_TGT_CROP;
31	ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
32	if (ret)
33	    exit(-1);
34
35Setting a composing area on output of size of *at most* half of limit
36placed at a center of a display.
37
38Example: Simple downscaling
39===========================
40
41.. code-block:: c
42
43	struct v4l2_selection sel = {
44	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
45	    .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
46	};
47	struct v4l2_rect r;
48
49	ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
50	if (ret)
51	    exit(-1);
52	/* setting smaller compose rectangle */
53	r.width = sel.r.width / 2;
54	r.height = sel.r.height / 2;
55	r.left = sel.r.width / 4;
56	r.top = sel.r.height / 4;
57	sel.r = r;
58	sel.target = V4L2_SEL_TGT_COMPOSE;
59	sel.flags = V4L2_SEL_FLAG_LE;
60	ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
61	if (ret)
62	    exit(-1);
63
64A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
65for other devices
66
67Example: Querying for scaling factors
68=====================================
69
70.. code-block:: c
71
72	struct v4l2_selection compose = {
73	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
74	    .target = V4L2_SEL_TGT_COMPOSE,
75	};
76	struct v4l2_selection crop = {
77	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
78	    .target = V4L2_SEL_TGT_CROP,
79	};
80	double hscale, vscale;
81
82	ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
83	if (ret)
84	    exit(-1);
85	ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
86	if (ret)
87	    exit(-1);
88
89	/* computing scaling factors */
90	hscale = (double)compose.r.width / crop.r.width;
91	vscale = (double)compose.r.height / crop.r.height;
92