From 53b5d5749b6fcca37c7ad60cd40feafadd390b70 Mon Sep 17 00:00:00 2001 From: Pawel Osciak Date: Fri, 7 Jan 2011 01:41:33 -0300 Subject: [media] Add multi-planar API documentation Add DocBook documentation for the new multi-planar API extensions to the Video for Linux 2 API DocBook. Signed-off-by: Pawel Osciak Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media-entities.tmpl | 4 + Documentation/DocBook/v4l/common.xml | 2 + Documentation/DocBook/v4l/compat.xml | 11 ++ Documentation/DocBook/v4l/dev-capture.xml | 13 +- Documentation/DocBook/v4l/dev-output.xml | 13 +- Documentation/DocBook/v4l/func-mmap.xml | 10 +- Documentation/DocBook/v4l/func-munmap.xml | 3 +- Documentation/DocBook/v4l/io.xml | 247 ++++++++++++++++++++++---- Documentation/DocBook/v4l/pixfmt.xml | 116 +++++++++++- Documentation/DocBook/v4l/planar-apis.xml | 81 +++++++++ Documentation/DocBook/v4l/v4l2.xml | 21 ++- Documentation/DocBook/v4l/vidioc-enum-fmt.xml | 2 + Documentation/DocBook/v4l/vidioc-g-fmt.xml | 15 +- Documentation/DocBook/v4l/vidioc-qbuf.xml | 24 ++- Documentation/DocBook/v4l/vidioc-querybuf.xml | 14 +- Documentation/DocBook/v4l/vidioc-querycap.xml | 24 ++- 16 files changed, 530 insertions(+), 70 deletions(-) create mode 100644 Documentation/DocBook/v4l/planar-apis.xml diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index be34dcbe0d90..74923d745535 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -129,6 +129,7 @@ v4l2_audioout"> v4l2_bt_timings"> v4l2_buffer"> +v4l2_plane"> v4l2_capability"> v4l2_captureparm"> v4l2_clip"> @@ -167,6 +168,8 @@ v4l2_output"> v4l2_outputparm"> v4l2_pix_format"> +v4l2_pix_format_mplane"> +v4l2_plane_pix_format"> v4l2_queryctrl"> v4l2_querymenu"> v4l2_rect"> @@ -202,6 +205,7 @@ + diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml index cea23e1c4fc6..dbab79c215c1 100644 --- a/Documentation/DocBook/v4l/common.xml +++ b/Documentation/DocBook/v4l/common.xml @@ -846,6 +846,8 @@ conversion routine or library for integration into applications. + &sub-planar-apis; +
Image Cropping, Insertion and Scaling diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml index c9ce61d981f5..223c24c536b7 100644 --- a/Documentation/DocBook/v4l/compat.xml +++ b/Documentation/DocBook/v4l/compat.xml @@ -2353,6 +2353,17 @@ that used it. It was originally scheduled for removal in 2.6.35.
+
+ V4L2 in Linux 2.6.38 + + + Multi-planar API added. Does not affect the compatibility of + current drivers and applications. See + multi-planar API + for details. + + +
Relation of V4L2 to other Linux multimedia APIs diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml index 32807e43f170..2237c661f26a 100644 --- a/Documentation/DocBook/v4l/dev-capture.xml +++ b/Documentation/DocBook/v4l/dev-capture.xml @@ -18,7 +18,8 @@ files are used for video output devices. Querying Capabilities Devices supporting the video capture interface set the -V4L2_CAP_VIDEO_CAPTURE flag in the +V4L2_CAP_VIDEO_CAPTURE or +V4L2_CAP_VIDEO_CAPTURE_MPLANE flag in the capabilities field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions they may also support the video overlay @@ -64,9 +65,11 @@ linkend="crop" />. To query the current image format applications set the type field of a &v4l2-format; to -V4L2_BUF_TYPE_VIDEO_CAPTURE and call the +V4L2_BUF_TYPE_VIDEO_CAPTURE or +V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE and call the &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; pix member of the +the &v4l2-pix-format; pix or the +&v4l2-pix-format-mplane; pix_mp member of the fmt union. To request different parameters applications set the @@ -84,8 +87,8 @@ adjust the parameters and finally return the actual parameters as without disabling I/O or possibly time consuming hardware preparations. - The contents of &v4l2-pix-format; are discussed in . See also the specification of the + The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in . See also the specification of the VIDIOC_G_FMT, VIDIOC_S_FMT and VIDIOC_TRY_FMT ioctls for details. Video capture devices must implement both the diff --git a/Documentation/DocBook/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml index 63c3c20e5a72..919e22c53854 100644 --- a/Documentation/DocBook/v4l/dev-output.xml +++ b/Documentation/DocBook/v4l/dev-output.xml @@ -17,7 +17,8 @@ files are used for video capture devices. Querying Capabilities Devices supporting the video output interface set the -V4L2_CAP_VIDEO_OUTPUT flag in the +V4L2_CAP_VIDEO_OUTPUT or +V4L2_CAP_VIDEO_OUTPUT_MPLANE flag in the capabilities field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions they may also support the raw VBI @@ -60,9 +61,11 @@ linkend="crop" />. To query the current image format applications set the type field of a &v4l2-format; to -V4L2_BUF_TYPE_VIDEO_OUTPUT and call the +V4L2_BUF_TYPE_VIDEO_OUTPUT or +V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE and call the &VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill -the &v4l2-pix-format; pix member of the +the &v4l2-pix-format; pix or the +&v4l2-pix-format-mplane; pix_mp member of the fmt union. To request different parameters applications set the @@ -80,8 +83,8 @@ adjust the parameters and finally return the actual parameters as without disabling I/O or possibly time consuming hardware preparations. - The contents of &v4l2-pix-format; are discussed in . See also the specification of the + The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane; +are discussed in . See also the specification of the VIDIOC_G_FMT, VIDIOC_S_FMT and VIDIOC_TRY_FMT ioctls for details. Video output devices must implement both the diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml index 2e2fc3933aea..786732b64bbd 100644 --- a/Documentation/DocBook/v4l/func-mmap.xml +++ b/Documentation/DocBook/v4l/func-mmap.xml @@ -45,7 +45,10 @@ just specify a NULL pointer here. Length of the memory area to map. This must be the same value as returned by the driver in the &v4l2-buffer; -length field. +length field for the +single-planar API, and the same value as returned by the driver +in the &v4l2-plane; length field for the +multi-planar API. @@ -106,7 +109,10 @@ flag. Offset of the buffer in device memory. This must be the same value as returned by the driver in the &v4l2-buffer; -m union offset field. +m union offset field for +the single-planar API, and the same value as returned by the driver +in the &v4l2-plane; m union +mem_offset field for the multi-planar API. diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml index 502ed49323b0..e2c4190f9bb6 100644 --- a/Documentation/DocBook/v4l/func-munmap.xml +++ b/Documentation/DocBook/v4l/func-munmap.xml @@ -37,7 +37,8 @@ Length of the mapped buffer. This must be the same value as given to mmap() and returned by the driver in the &v4l2-buffer; length -field. +field for the single-planar API and in the &v4l2-plane; +length field for the multi-planar API. diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index a9750437000c..227e7ac45a06 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -121,18 +121,22 @@ mapped. Before applications can access the buffers they must map them into their address space with the &func-mmap; function. The location of the buffers in device memory can be determined with the -&VIDIOC-QUERYBUF; ioctl. The m.offset and -length returned in a &v4l2-buffer; are -passed as sixth and second parameter to the -mmap() function. The offset and length values -must not be modified. Remember the buffers are 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 -&func-munmap; function. +&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the +m.offset and length +returned in a &v4l2-buffer; are passed as sixth and second parameter to the +mmap() function. When using the multi-planar API, +struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each +containing its own m.offset and +length. When using the multi-planar API, every +plane of every buffer has to be mapped separately, so the number of +calls to &func-mmap; should be equal to number of buffers times number of +planes in each buffer. The offset and length values must not be modified. +Remember, the buffers are 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 &func-munmap; function. - Mapping buffers - + Mapping buffers in the single-planar API &v4l2-requestbuffers; reqbuf; struct { @@ -201,6 +205,88 @@ for (i = 0; i < reqbuf.count; i++) + + Mapping buffers in the multi-planar API + +&v4l2-requestbuffers; reqbuf; +/* Our current format uses 3 planes per buffer */ +#define FMT_NUM_PLANES = 3; + +struct { + void *start[FMT_NUM_PLANES]; + size_t length[FMT_NUM_PLANES]; +} *buffers; +unsigned int i, j; + +memset(&reqbuf, 0, sizeof(reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; +reqbuf.memory = V4L2_MEMORY_MMAP; +reqbuf.count = 20; + +if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { + if (errno == EINVAL) + printf("Video capturing or mmap-streaming is not supported\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); +} + +/* We want at least five buffers. */ + +if (reqbuf.count < 5) { + /* You may need to free the buffers here. */ + printf("Not enough buffer memory\n"); + exit(EXIT_FAILURE); +} + +buffers = calloc(reqbuf.count, sizeof(*buffers)); +assert(buffers != NULL); + +for (i = 0; i < reqbuf.count; i++) { + &v4l2-buffer; buffer; + &v4l2-plane; planes[FMT_NUM_PLANES]; + + memset(&buffer, 0, sizeof(buffer)); + buffer.type = reqbuf.type; + buffer.memory = V4L2_MEMORY_MMAP; + buffer.index = i; + /* length in struct v4l2_buffer in multi-planar API stores the size + * of planes array. */ + buffer.length = FMT_NUM_PLANES; + buffer.m.planes = planes; + + if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { + perror("VIDIOC_QUERYBUF"); + exit(EXIT_FAILURE); + } + + /* Every plane has to be mapped separately */ + for (j = 0; j < FMT_NUM_PLANES; j++) { + buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ + + buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, + PROT_READ | PROT_WRITE, /* recommended */ + MAP_SHARED, /* recommended */ + fd, buffer.m.planes[j].m.offset); + + if (MAP_FAILED == buffers[i].start[j]) { + /* If you do not exit here you should unmap() and free() + the buffers and planes mapped so far. */ + perror("mmap"); + exit(EXIT_FAILURE); + } + } +} + +/* Cleanup. */ + +for (i = 0; i < reqbuf.count; i++) + for (j = 0; j < FMT_NUM_PLANES; j++) + munmap(buffers[i].start[j], buffers[i].length[j]); + + + Conceptually streaming drivers maintain two buffer queues, an incoming and an outgoing queue. They separate the synchronous capture or output operation locked to a video clock from the application which is @@ -286,13 +372,13 @@ pointer method (not only memory mapping) is supported must be determined by calling the &VIDIOC-REQBUFS; ioctl. This I/O method combines advantages of the read/write and -memory mapping methods. Buffers are allocated by the application +memory mapping methods. Buffers (planes) are allocated by the application itself, and can reside for example in virtual or shared memory. Only pointers to data are exchanged, these pointers and meta-information -are passed in &v4l2-buffer;. The driver must be switched -into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the -desired buffer type. No buffers are allocated beforehands, -consequently they are not indexed and cannot be queried like mapped +are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). +The driver must be switched into user pointer I/O mode by calling the +&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated +beforehand, consequently they are not indexed and cannot be queried like mapped buffers with the VIDIOC_QUERYBUF ioctl. @@ -316,7 +402,7 @@ if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { - Buffer addresses and sizes are passed on the fly with the + Buffer (plane) addresses and sizes are passed on the fly with the &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, applications can pass different addresses and sizes at each VIDIOC_QBUF call. If required by the hardware the @@ -396,11 +482,18 @@ rest should be evident. Buffers A buffer contains data exchanged by application and -driver using one of the Streaming I/O methods. Only pointers to -buffers are exchanged, the data itself is not copied. These pointers, -together with meta-information like timestamps or field parity, are -stored in a struct v4l2_buffer, argument to -the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. +driver using one of the Streaming I/O methods. In the multi-planar API, the +data is held in planes, while the buffer structure acts as a container +for the planes. Only pointers to buffers (planes) are exchanged, the data +itself is not copied. These pointers, together with meta-information like +timestamps or field parity, are stored in a struct +v4l2_buffer, argument to +the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. +In the multi-planar API, some plane-specific members of struct +v4l2_buffer, such as pointers and sizes for each +plane, are stored in struct v4l2_plane instead. +In that case, struct v4l2_buffer contains an array of +plane structures. Nominally timestamps refer to the first data byte transmitted. In practice however the wide range of hardware covered by the V4L2 API @@ -551,26 +644,40 @@ in accordance with the selected I/O method. __u32 offset - When memory is -V4L2_MEMORY_MMAP this is the offset of the buffer -from the start of the device memory. The value is returned by the -driver and apart of serving as parameter to the &func-mmap; function -not useful for applications. See for details. + For the single-planar API and when +memory is V4L2_MEMORY_MMAP this +is the offset of the buffer from the start of the device memory. The value is +returned by the driver and apart of serving as parameter to the &func-mmap; +function not useful for applications. See for details + unsigned long userptr - When memory is -V4L2_MEMORY_USERPTR this is a pointer to the -buffer (casted to unsigned long type) in virtual memory, set by the -application. See for details. + For the single-planar API and when +memory is V4L2_MEMORY_USERPTR +this is a pointer to the buffer (casted to unsigned long type) in virtual +memory, set by the application. See for details. + + + + + struct v4l2_plane + *planes + When using the multi-planar API, contains a userspace pointer + to an array of &v4l2-plane;. The size of the array should be put + in the length field of this + v4l2_buffer structure. __u32 length - Size of the buffer (not the payload) in bytes. + Size of the buffer (not the payload) in bytes for the + single-planar API. For the multi-planar API should contain the + number of elements in the planes array. + __u32 @@ -596,6 +703,66 @@ should set this to 0. + + struct <structname>v4l2_plane</structname> + + &cs-ustr; + + + __u32 + bytesused + + The number of bytes occupied by data in the plane + (its payload). + + + __u32 + length + + Size in bytes of the plane (not its payload). + + + union + m + + + + + + __u32 + mem_offset + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_MMAP, this is the value that + should be passed to &func-mmap;, similar to the + offset field in &v4l2-buffer;. + + + + __unsigned long + userptr + When the memory type in the containing &v4l2-buffer; is + V4L2_MEMORY_USERPTR, this is a userspace + pointer to the memory allocated for this plane by an application. + + + + __u32 + data_offset + + Offset in bytes to video data in the plane, if applicable. + + + + __u32 + reserved[11] + + Reserved for future use. Should be zeroed by an + application. + + + +
+ enum v4l2_buf_type @@ -604,13 +771,27 @@ should set this to 0. V4L2_BUF_TYPE_VIDEO_CAPTURE 1 - Buffer of a video capture stream, see Buffer of a single-planar video capture stream, see . + + + V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE + + 9 + Buffer of a multi-planar video capture stream, see . V4L2_BUF_TYPE_VIDEO_OUTPUT 2 - Buffer of a video output stream, see Buffer of a single-planar video output stream, see . + + + V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE + + 10 + Buffer of a multi-planar video output stream, see . diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml index cfffc88d7383..28f9c700f752 100644 --- a/Documentation/DocBook/v4l/pixfmt.xml +++ b/Documentation/DocBook/v4l/pixfmt.xml @@ -2,12 +2,16 @@ The V4L2 API was primarily designed for devices exchanging image data with applications. The -v4l2_pix_format structure defines the format -and layout of an image in memory. Image formats are negotiated with -the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video +v4l2_pix_format and v4l2_pix_format_mplane + structures define the format and layout of an image in memory. +The former is used with the single-planar API, while the latter is used with the +multi-planar version (see ). Image formats are +negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video capturing and output, for overlay frame buffer formats see also &VIDIOC-G-FBUF;.) +
+ Single-planar format structure
struct <structname>v4l2_pix_format</structname> @@ -106,6 +110,98 @@ set this field to zero.
+
+ +
+ Multi-planar format structures + The v4l2_plane_pix_format structures define + size and layout for each of the planes in a multi-planar format. + The v4l2_pix_format_mplane structure contains + information common to all planes (such as image width and height) and + an array of v4l2_plane_pix_format structures, + describing all planes of that format. + + struct <structname>vl42_plane_pix_format</structname> + + &cs-str; + + + __u32 + sizeimage + Maximum size in bytes required for image data in this plane. + + + + __u16 + bytesperline + Distance in bytes between the leftmost pixels in two adjacent + lines. + + + __u16 + reserved[7] + Reserved for future extensions. Should be zeroed by the + application. + + + +
+ + struct <structname>v4l2_pix_format_mplane</structname> + + &cs-str; + + + __u32 + width + Image width in pixels. + + + __u32 + height + Image height in pixels. + + + __u32 + pixelformat + The pixel format. Both single- and multi-planar four character +codes can be used. + + + &v4l2-field; + field + See &v4l2-pix-format;. + + + &v4l2-colorspace; + colorspace + See &v4l2-pix-format;. + + + &v4l2-plane-pix-format; + plane_fmt[VIDEO_MAX_PLANES] + An array of structures describing format of each plane this + pixel format consists of. The number of valid entries in this array + has to be put in the num_planes + field. + + + __u8 + num_planes + Number of planes (i.e. separate memory buffers) for this format + and the number of valid entries in the + plane_fmt array. + + + __u8 + reserved[11] + Reserved for future extensions. Should be zeroed by the + application. + + + +
+
Standard Image Formats @@ -142,11 +238,19 @@ leftmost pixel of the second row from the top, and so on. The last row has just as many pad bytes after it as the other rows. In V4L2 each format has an identifier which looks like -PIX_FMT_XXX, defined in the videodev2.h -header file. These identifiers -represent four character codes +PIX_FMT_XXX, defined in the videodev.h header file. These identifiers +represent four character (FourCC) codes which are also listed below, however they are not the same as those used in the Windows world. + + For some formats, data is stored in separate, discontiguous +memory buffers. Those formats are identified by a separate set of FourCC codes +and are referred to as "multi-planar formats". For example, a YUV422 frame is +normally stored in one memory buffer, but it can also be placed in two or three +separate buffers, with Y component in one buffer and CbCr components in another +in the 2-planar version or with each component in its own buffer in the +3-planar case. Those sub-buffers are referred to as "planes".
diff --git a/Documentation/DocBook/v4l/planar-apis.xml b/Documentation/DocBook/v4l/planar-apis.xml new file mode 100644 index 000000000000..8be7552b37de --- /dev/null +++ b/Documentation/DocBook/v4l/planar-apis.xml @@ -0,0 +1,81 @@ +
+ Single- and multi-planar APIs + + Some devices require data for each input or output video frame + to be placed in discontiguous memory buffers. In such cases one + video frame has to be addressed using more than one memory address, i.e. one + pointer per "plane". A plane is a sub-buffer of current frame. For examples + of such formats see . + + Initially, V4L2 API did not support multi-planar buffers and a set of + extensions has been introduced to handle them. Those extensions constitute + what is being referred to as the "multi-planar API". + + Some of the V4L2 API calls and structures are interpreted differently, + depending on whether single- or multi-planar API is being used. An application + can choose whether to use one or the other by passing a corresponding buffer + type to its ioctl calls. Multi-planar versions of buffer types are suffixed with + an `_MPLANE' string. For a list of available multi-planar buffer types + see &v4l2-buf-type;. + + +
+ Multi-planar formats + Multi-planar API introduces new multi-planar formats. Those formats + use a separate set of FourCC codes. It is important to distinguish between + the multi-planar API and a multi-planar format. Multi-planar API calls can + handle all single-planar formats as well, while the single-planar API cannot + handle multi-planar formats. Applications do not have to switch between APIs + when handling both single- and multi-planar devices and should use the + multi-planar API version for both single- and multi-planar formats. + Drivers that do not support multi-planar API can still be handled with it, + utilizing a compatibility layer built into standard V4L2 ioctl handling. + +
+ +
+ Single and multi-planar API compatibility layer + In most casesThe compatibility layer does not cover + drivers that do not use video_ioctl2() call., applications + can use the multi-planar API with older drivers that support + only its single-planar version and vice versa. Appropriate conversion is + done seamlessly for both applications and drivers in the V4L2 core. The + general rule of thumb is: as long as an application uses formats that + a driver supports, it can use either API (although use of multi-planar + formats is only possible with the multi-planar API). The list of formats + supported by a driver can be obtained using the &VIDIOC-ENUM-FMT; call. + It is possible, but discouraged, for a driver or an application to support + and use both versions of the API. +
+ +
+ Calls that distinguish between single and multi-planar APIs + + + &VIDIOC-QUERYCAP; + Two additional multi-planar capabilities are added. They can + be set together with non-multi-planar ones for devices that handle + both single- and multi-planar formats. + + + &VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT; + New structures for describing multi-planar formats are added: + &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may + define new multi-planar formats, which have distinct FourCC codes from + the existing single-planar ones. + + + + &VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF; + A new &v4l2-plane; structure for describing planes is added. + Arrays of this structure are passed in the new + m.planes field of &v4l2-buffer;. + + + + &VIDIOC-REQBUFS; + Will allocate multi-planar buffers as requested. + + +
+
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 9288af96de34..9c7a1751ba1e 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -85,6 +85,17 @@ Remote Controller chapter. + + + Pawel + Osciak + Designed and documented the multi-planar API. + +
+ pawel AT osciak.com +
+ + @@ -102,7 +113,8 @@ Remote Controller chapter. 2010 2011 Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin -Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab +Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, + Pawel Osciak Except when explicitly stated as GPL, programming examples within @@ -115,6 +127,13 @@ structs, ioctls) must be noted in more detail in the history chapter (compat.xml), along with the possible impact on existing drivers and applications. --> + + 2.6.38 + po + Added the multi-planar API. + + + 2.6.37 2010-08-06 diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml index 960d44615ca6..71d373b6d36a 100644 --- a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml @@ -76,7 +76,9 @@ pixelformat field. Type of the data stream, set by the application. Only these types are valid here: V4L2_BUF_TYPE_VIDEO_CAPTURE, +V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE, V4L2_BUF_TYPE_VIDEO_OUTPUT, +V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE, V4L2_BUF_TYPE_VIDEO_OVERLAY, and custom (driver defined) types with code V4L2_BUF_TYPE_PRIVATE and higher. diff --git a/Documentation/DocBook/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml index 7c7d1b72c40d..a4ae59b664eb 100644 --- a/Documentation/DocBook/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml @@ -60,11 +60,13 @@ application. type field of a struct v4l2_format to the respective buffer (stream) type. For example video capture devices use -V4L2_BUF_TYPE_VIDEO_CAPTURE. When the application +V4L2_BUF_TYPE_VIDEO_CAPTURE or +V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE. When the application calls the VIDIOC_G_FMT ioctl with a pointer to this structure the driver fills the respective member of the fmt union. In case of video capture devices -that is the &v4l2-pix-format; pix member. +that is either the &v4l2-pix-format; pix or +the &v4l2-pix-format-mplane; pix_mp member. When the requested buffer type is not supported drivers return an &EINVAL;. @@ -131,6 +133,15 @@ this ioctl. Definition of an image format, see , used by video capture and output devices. + + + + &v4l2-pix-format-mplane; + pix_mp + Definition of an image format, see , used by video capture and output +devices that support the multi-planar +version of the API. diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index ab691ebf3b93..f2b11f8a4031 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -64,7 +64,8 @@ zero to the number of buffers allocated with &VIDIOC-REQBUFS; contents of the struct v4l2_buffer returned by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is intended for output (type is -V4L2_BUF_TYPE_VIDEO_OUTPUT or +V4L2_BUF_TYPE_VIDEO_OUTPUT, +V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE, or V4L2_BUF_TYPE_VBI_OUTPUT) applications must also initialize the bytesused, field and @@ -75,7 +76,11 @@ supports capturing from specific video inputs and you want to specify a video input, then flags should be set to V4L2_BUF_FLAG_INPUT and the field input must be initialized to the desired input. -The reserved field must be set to 0. +The reserved field must be set to 0. When using +the multi-planar API, the +m.planes field must contain a userspace pointer +to a filled-in array of &v4l2-plane; and the length +field must be set to the number of elements in that array. To enqueue a memory mapped @@ -93,10 +98,13 @@ structure the driver sets the buffer applications set the memory field to V4L2_MEMORY_USERPTR, the m.userptr field to the address of the -buffer and length to its size. -When VIDIOC_QBUF is called with a pointer to this -structure the driver sets the V4L2_BUF_FLAG_QUEUED -flag and clears the V4L2_BUF_FLAG_MAPPED and +buffer and length to its size. When the multi-planar +API is used, m.userptr and +length members of the passed array of &v4l2-plane; +have to be used instead. When VIDIOC_QBUF is called with +a pointer to this structure the driver sets the +V4L2_BUF_FLAG_QUEUED flag and clears the +V4L2_BUF_FLAG_MAPPED and V4L2_BUF_FLAG_DONE flags in the flags field, or it returns an error code. This ioctl locks the memory pages of the buffer in physical memory, @@ -115,7 +123,9 @@ remaining fields or returns an error code. The driver may also set V4L2_BUF_FLAG_ERROR in the flags field. It indicates a non-critical (recoverable) streaming error. In such case the application may continue as normal, but should be aware that data in the -dequeued buffer might be corrupted. +dequeued buffer might be corrupted. When using the multi-planar API, the +planes array does not have to be passed; the m.planes +member must be set to NULL in that case. By default VIDIOC_DQBUF blocks when no buffer is in the outgoing queue. When the diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml index e649805a4908..5c104d42d31c 100644 --- a/Documentation/DocBook/v4l/vidioc-querybuf.xml +++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml @@ -61,6 +61,10 @@ buffer at any time after buffers have been allocated with the to the number of buffers allocated with &VIDIOC-REQBUFS; (&v4l2-requestbuffers; count) minus one. The reserved field should to set to 0. +When using the multi-planar API, the +m.planes field must contain a userspace pointer to an +array of &v4l2-plane; and the length field has +to be set to the number of elements in that array. After calling VIDIOC_QUERYBUF with a pointer to this structure drivers return an error code or fill the rest of the structure. @@ -70,11 +74,13 @@ the structure. V4L2_BUF_FLAG_QUEUED and V4L2_BUF_FLAG_DONE flags will be valid. The memory field will be set to the current -I/O method, the m.offset +I/O method. For the single-planar API, the m.offset contains the offset of the buffer from the start of the device memory, -the length field its size. The driver may -or may not set the remaining fields and flags, they are meaningless in -this context. +the length field its size. For the multi-planar API, +fields m.mem_offset and +length in the m.planes +array elements will be used instead. The driver may or may not set the remaining +fields and flags, they are meaningless in this context. The v4l2_buffer structure is specified in . diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml index d499da93a450..93699769cd07 100644 --- a/Documentation/DocBook/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/v4l/vidioc-querycap.xml @@ -142,14 +142,30 @@ this array to zero. V4L2_CAP_VIDEO_CAPTURE 0x00000001 - The device supports the Video Capture interface. + The device supports single-planar formats through the Video Capture interface. An application can use either +the single or the multi-planar API. + + + V4L2_CAP_VIDEO_CAPTURE_MPLANE + 0x00001000 + The device supports multi-planar formats through the Video Capture interface. An application has to use the +multi-planar API. V4L2_CAP_VIDEO_OUTPUT 0x00000002 - The device supports the Video Output interface. + The device supports single-planar formats through the Video Output interface. An application can use either +the single or the multi-planar API. + + + V4L2_CAP_VIDEO_OUTPUT_MPLANE + 0x00002000 + The device supports multi-planar formats through the Video Output interface. An application has to use the +multi-planar API. V4L2_CAP_VIDEO_OVERLAY -- cgit v1.2.3