From 282f02cb863594d9f39b7b89a92eeb7fc989a883 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 10 Jul 2016 08:22:19 -0300 Subject: [PATCH] [media] doc-rst: Don't use captions for examples Unfortunately, captions are new on Sphinx for c blocks: it was added only on version 1.3. Also, it were already bad enough not being able to auto-numerate them. So, let's give up and use, instead, titles before the examples. Not much is lost, and, as a side track, we don't need to numerate them anymore. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/uapi/dvb/dvbproperty.rst | 7 ++++++- Documentation/media/uapi/dvb/examples.rst | 8 ++++---- Documentation/media/uapi/v4l/audio.rst | 8 ++++++-- Documentation/media/uapi/v4l/control.rst | 11 ++++++++--- Documentation/media/uapi/v4l/crop.rst | 17 +++++++++++++---- Documentation/media/uapi/v4l/dev-osd.rst | 3 ++- Documentation/media/uapi/v4l/dmabuf.rst | 10 +++++++--- Documentation/media/uapi/v4l/mmap.rst | 7 +++++-- .../media/uapi/v4l/selection-api-006.rst | 9 ++++++--- Documentation/media/uapi/v4l/standard.rst | 9 ++++++--- Documentation/media/uapi/v4l/userp.rst | 3 ++- Documentation/media/uapi/v4l/video.rst | 8 ++++++-- 12 files changed, 71 insertions(+), 29 deletions(-) diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst index 9b3782c5bb44..3c348e585729 100644 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ b/Documentation/media/uapi/dvb/dvbproperty.rst @@ -48,8 +48,13 @@ symbol rate of 5.217 Mbauds, those properties should be sent to - :ref:`DTV_TUNE ` -The code that would do the above is: +The code that would that would do the above is show in +:ref:`dtv-prop-example`. +.. _dtv-prop-example: + +Example: Setting digital TV frontend properties +=============================================== .. code-block:: c diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst index 64e029ecd047..ead3ddf764c0 100644 --- a/Documentation/media/uapi/dvb/examples.rst +++ b/Documentation/media/uapi/dvb/examples.rst @@ -17,8 +17,8 @@ updated/recommended examples. .. _tuning: -Tuning -====== +Example: Tuning +=============== We will start with a generic tuning subroutine that uses the frontend and SEC, as well as the demux devices. The example is given for QPSK @@ -238,8 +238,8 @@ switch, and weather conditions this may be necessary. .. _the_dvr_device: -The DVR device -============== +Example: The DVR device +======================== The following program code shows how to use the DVR device for recording. diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst index 71502f0bf8bd..47f8334f071e 100644 --- a/Documentation/media/uapi/v4l/audio.rst +++ b/Documentation/media/uapi/v4l/audio.rst @@ -54,8 +54,10 @@ in the struct :ref:`v4l2_capability ` returned by the :ref:`VIDIOC_QUERYCAP` ioctl. +Example: Information about the current audio input +================================================== + .. code-block:: c - :caption: Example 1.3. Information about the current audio input struct v4l2_audio audio; @@ -69,8 +71,10 @@ the :ref:`VIDIOC_QUERYCAP` ioctl. printf("Current input: %s\\n", audio.name); +Example: Switching to the first audio input +=========================================== + .. code-block:: c - :caption: Example 1.4. Switching to the first audio input struct v4l2_audio audio; diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst index 6cf218ab36fb..feb55ac14377 100644 --- a/Documentation/media/uapi/v4l/control.rst +++ b/Documentation/media/uapi/v4l/control.rst @@ -373,8 +373,10 @@ more menu type controls. .. _enum_all_controls: +Example: Enumerating all user controls +====================================== + .. code-block:: c - :caption: Example 1.8. Enumerating all user controls struct v4l2_queryctrl queryctrl; @@ -438,8 +440,10 @@ more menu type controls. } +Example: Enumerating all user controls (alternative) +==================================================== + .. code-block:: c - :caption: Example 1.9. Enumerating all user controls (alternative) memset(&queryctrl, 0, sizeof(queryctrl)); @@ -462,9 +466,10 @@ more menu type controls. exit(EXIT_FAILURE); } +Example: Changing controls +========================== .. code-block:: c - :caption: Example 1.10. Changing controls struct v4l2_queryctrl queryctrl; struct v4l2_control control; diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst index ed43b36c51d8..51b19491c302 100644 --- a/Documentation/media/uapi/v4l/crop.rst +++ b/Documentation/media/uapi/v4l/crop.rst @@ -147,8 +147,10 @@ ensure the parameters are suitable before starting I/O. **NOTE:** on the next two examples, a video capture device is assumed; change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. +Example: Resetting the cropping parameters +========================================== + .. code-block:: c - :caption: Example 1.11. Resetting the cropping parameters struct v4l2_cropcap cropcap; struct v4l2_crop crop; @@ -173,8 +175,11 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. exit (EXIT_FAILURE); } + +Example: Simple downscaling +=========================== + .. code-block:: c - :caption: Example 1.12. Simple downscaling struct v4l2_cropcap cropcap; struct v4l2_format format; @@ -199,10 +204,12 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. /* We could check the actual image size now, the actual scaling factor or if the driver can scale at all. */ +Example: Selecting an output area +================================= + **NOTE:** This example assumes an output device. .. code-block:: c - :caption: Example 1.13. Selecting an output area struct v4l2_cropcap cropcap; struct v4l2_crop crop; @@ -236,10 +243,12 @@ change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. exit (EXIT_FAILURE); } +Example: Current scaling factor and pixel aspect +================================================ + **NOTE:** This example assumes a video capture device. .. code-block:: c - :caption: Example 1.14. Current scaling factor and pixel aspect struct v4l2_cropcap cropcap; struct v4l2_crop crop; diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst index b9b53fd7eb5d..98570cea63a5 100644 --- a/Documentation/media/uapi/v4l/dev-osd.rst +++ b/Documentation/media/uapi/v4l/dev-osd.rst @@ -50,9 +50,10 @@ standard. A V4L2 driver may reject attempts to change the video standard (or any other ioctl which would imply a framebuffer size change) with an ``EBUSY`` error code until all applications closed the framebuffer device. +Example: Finding a framebuffer device for OSD +--------------------------------------------- .. code-block:: c - :caption: Example 4.1. Finding a framebuffer device for OSD #include diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst index 474d8c021507..57917fb98c7a 100644 --- a/Documentation/media/uapi/v4l/dmabuf.rst +++ b/Documentation/media/uapi/v4l/dmabuf.rst @@ -37,8 +37,10 @@ driver must be switched into DMABUF I/O mode by calling the :ref:`VIDIOC_REQBUFS ` with the desired buffer type. +Example: Initiating streaming I/O with DMABUF file descriptors +============================================================== + .. code-block:: c - :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors struct v4l2_requestbuffers reqbuf; @@ -62,9 +64,10 @@ buffers, every plane can be associated with a different DMABUF descriptor. Although buffers are commonly cycled, applications can pass a different DMABUF descriptor at each :ref:`VIDIOC_QBUF ` call. +Example: Queueing DMABUF using single plane API +=============================================== .. code-block:: c - :caption: Example 3.5. Queueing DMABUF using single plane API int buffer_queue(int v4lfd, int index, int dmafd) { @@ -84,9 +87,10 @@ a different DMABUF descriptor at each :ref:`VIDIOC_QBUF ` call. return 0; } +Example 3.6. Queueing DMABUF using multi plane API +================================================== .. code-block:: c - :caption: Example 3.6. Queueing DMABUF using multi plane API int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) { diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst index f7fe26e7ca43..b01f4486499a 100644 --- a/Documentation/media/uapi/v4l/mmap.rst +++ b/Documentation/media/uapi/v4l/mmap.rst @@ -52,9 +52,10 @@ allocated in physical memory, as opposed to virtual memory, which can be swapped out to disk. Applications should free the buffers as soon as possible with the :ref:`munmap() ` function. +Example: Mapping buffers in the single-planar API +================================================= .. code-block:: c - :caption: Example 3.1. Mapping buffers in the single-planar API struct v4l2_requestbuffers reqbuf; struct { @@ -122,8 +123,10 @@ possible with the :ref:`munmap() ` function. munmap(buffers[i].start, buffers[i].length); +Example: Mapping buffers in the multi-planar API +================================================ + .. code-block:: c - :caption: Example 3.2. Mapping buffers in the multi-planar API struct v4l2_requestbuffers reqbuf; /* Our current format uses 3 planes per buffer */ diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-006.rst index b2ac12f2e3d4..67e0e9aed9e8 100644 --- a/Documentation/media/uapi/v4l/selection-api-006.rst +++ b/Documentation/media/uapi/v4l/selection-api-006.rst @@ -8,9 +8,10 @@ Examples ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to ``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area) +Example: Resetting the cropping parameters +========================================== .. code-block:: c - :caption: Example 1.15. Resetting the cropping parameters struct v4l2_selection sel = { .type = V4L2_BUF_TYPE_VIDEO_CAPTURE, @@ -27,9 +28,10 @@ Examples Setting a composing area on output of size of *at most* half of limit placed at a center of a display. +Example: Simple downscaling +=========================== .. code-block:: c - :caption: Example 1.16. Simple downscaling struct v4l2_selection sel = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, @@ -55,9 +57,10 @@ placed at a center of a display. A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` for other devices +Example: Querying for scaling factors +===================================== .. code-block:: c - :caption: Example 1.17. Querying for scaling factors struct v4l2_selection compose = { .type = V4L2_BUF_TYPE_VIDEO_OUTPUT, diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst index 538588eef317..529891cf3af2 100644 --- a/Documentation/media/uapi/v4l/standard.rst +++ b/Documentation/media/uapi/v4l/standard.rst @@ -64,9 +64,10 @@ Applications can make use of the :ref:`input-capabilities` and :ref:`output-capabilities` flags to determine whether the video standard ioctls can be used with the given input or output. +Example: Information about the current video standard +===================================================== .. code-block:: c - :caption: Example 1.5. Information about the current video standard v4l2_std_id std_id; struct v4l2_standard standard; @@ -100,9 +101,10 @@ standard ioctls can be used with the given input or output. exit(EXIT_FAILURE); } +Example: Listing the video standards supported by the current input +=================================================================== .. code-block:: c - :caption: Example 1.6. Listing the video standards supported by the current input struct v4l2_input input; struct v4l2_standard standard; @@ -139,9 +141,10 @@ standard ioctls can be used with the given input or output. exit(EXIT_FAILURE); } +Example: Selecting a new video standard +======================================= .. code-block:: c - :caption: Example 1.7. Selecting a new video standard struct v4l2_input input; v4l2_std_id std_id; diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst index 2f0002bfbc3f..0871c204dc6c 100644 --- a/Documentation/media/uapi/v4l/userp.rst +++ b/Documentation/media/uapi/v4l/userp.rst @@ -26,9 +26,10 @@ No buffers (planes) are allocated beforehand, consequently they are not indexed and cannot be queried like mapped buffers with the :ref:`VIDIOC_QUERYBUF ` ioctl. +Example: Initiating streaming I/O with user pointers +==================================================== .. code-block:: c - :caption: Example 3.3. Initiating streaming I/O with user pointers struct v4l2_requestbuffers reqbuf; diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst index e38ebe192614..d3f00715fbc1 100644 --- a/Documentation/media/uapi/v4l/video.rst +++ b/Documentation/media/uapi/v4l/video.rst @@ -28,8 +28,10 @@ applications call the :ref:`VIDIOC_S_INPUT ` and implement all the input ioctls when the device has one or more inputs, all the output ioctls when the device has one or more outputs. +Example: Information about the current video input +================================================== + .. code-block:: c - :caption: Example 1.1. Information about the current video input struct v4l2_input input; int index; @@ -50,8 +52,10 @@ all the output ioctls when the device has one or more outputs. printf("Current input: %s\\n", input.name); +Example: Switching to the first video input +=========================================== + .. code-block:: c - :caption: Example 1.2. Switching to the first video input int index; -- 2.39.5