From 680a513968b691d4ae013b7d6e2df0da3632b51f Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 5 May 2014 10:16:49 -0300 Subject: [PATCH] [media] DocBook media: update control section Document the support for compound types in controls. Signed-off-by: Hans Verkuil Reviewed-by: Sylwester Nawrocki Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/controls.xml | 27 +++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 73bae134a3a1..e7b8b72651bf 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -660,16 +660,29 @@ supported. &v4l2-control;, except for the fact that it also allows for 64-bit values and pointers to be passed. + Since the &v4l2-ext-control; supports pointers it is now +also possible to have controls with compound types such as N-dimensional arrays +and/or structures. You need to specify the V4L2_CTRL_FLAG_NEXT_COMPOUND +when enumerating controls to actually be able to see such compound controls. +In other words, these controls with compound types should only be used +programmatically. + + Since such compound controls need to expose more information +about themselves than is possible with &VIDIOC-QUERYCTRL; the +&VIDIOC-QUERY-EXT-CTRL; ioctl was added. In particular, this ioctl gives +the dimensions of the N-dimensional array if this control consists of more than +one element. + It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set actually is supported in the driver and what the valid range of values -is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to -check this. Also note that it is possible that some of the menu -indices in a control of type V4L2_CTRL_TYPE_MENU -may not be supported (VIDIOC_QUERYMENU will -return an error). A good example is the list of supported MPEG audio -bitrates. Some drivers only support one or two bitrates, others -support a wider range. +is. So use the &VIDIOC-QUERYCTRL; (or &VIDIOC-QUERY-EXT-CTRL;) and +&VIDIOC-QUERYMENU; ioctls to check this. Also note that it is possible +that some of the menu indices in a control of type +V4L2_CTRL_TYPE_MENU may not be supported +(VIDIOC_QUERYMENU will return an error). A good +example is the list of supported MPEG audio bitrates. Some drivers only +support one or two bitrates, others support a wider range. All controls use machine endianness. -- 2.20.1