| Message ID | 20180925101434.20327-4-sakari.ailus@linux.intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Add units to controls | expand |
On Tue, Sep 25, 2018 at 12:14:32PM +0200, Sakari Ailus wrote: > + * - ``V4L2_CTRL_UNIT_PIXEL`` > + - 5 > + - A pixel in sensor's pixel matrix. This is a unit of time commonly used > + by camera sensors in e.g. exposure control, i.e. the time it takes for > + a sensor to read a pixel from the sensor's pixel matrix. > + > + * - ``V4L2_CTRL_UNIT_PIXEL`` > + - 6 The latter V4L2_CTRL_UNIT_PIXEL looks like a typo that should say V4L2_CTRL_UNIT_PIXELS_PER_SEC. Helmut
On Tue, Sep 25, 2018 at 12:39:56PM +0200, Helmut Grohne wrote: > On Tue, Sep 25, 2018 at 12:14:32PM +0200, Sakari Ailus wrote: > > + * - ``V4L2_CTRL_UNIT_PIXEL`` > > + - 5 > > + - A pixel in sensor's pixel matrix. This is a unit of time commonly used > > + by camera sensors in e.g. exposure control, i.e. the time it takes for > > + a sensor to read a pixel from the sensor's pixel matrix. > > + > > + * - ``V4L2_CTRL_UNIT_PIXEL`` > > + - 6 > > The latter V4L2_CTRL_UNIT_PIXEL looks like a typo that should say > V4L2_CTRL_UNIT_PIXELS_PER_SEC. Correct. I'll fix this for v2. Thanks!
On 09/25/2018 12:14 PM, Sakari Ailus wrote: > Document V4L2 control exponential bases, units and prefixes, as well as > the control flag telling a control value is an exponent. > > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> > --- > Documentation/media/uapi/v4l/extended-controls.rst | 2 + > Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 152 ++++++++++++++++++++- > Documentation/media/videodev2.h.rst.exceptions | 22 +++ > 3 files changed, 175 insertions(+), 1 deletion(-) > > diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst > index 9f7312bf33651..8461fd92d1b9e 100644 > --- a/Documentation/media/uapi/v4l/extended-controls.rst > +++ b/Documentation/media/uapi/v4l/extended-controls.rst > @@ -3460,6 +3460,8 @@ Image Process Control IDs > by selecting the desired horizontal and vertical blanking. The unit > of this control is Hz. > > +.. _v4l2_cid_pixel_rate: > + > ``V4L2_CID_PIXEL_RATE (64-bit integer)`` > Pixel rate in the source pads of the subdev. This control is > read-only and its unit is pixels / second. > diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst > index ff2d131223b84..472378f5d7566 100644 > --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst > +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst > @@ -269,8 +269,22 @@ See also the examples in :ref:`control`. > - ``dims[V4L2_CTRL_MAX_DIMS]`` > - The size of each dimension. The first ``nr_of_dims`` elements of > this array must be non-zero, all remaining elements must be zero. > + * - __u8 > + - ``base`` > + - The exponential base of the control value. Valid only if the > + :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` control flag is > + set. This is an enumeration. > + * - __u8 > + - ``prefix`` > + - Prefix of the unit. This is an enumeration. > + * - __u16 > + - ``unit`` > + - Unit of the value. Together with the ``prefix`` as well as the ``base`` > + field (if :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` is set), > + defines the relation between the control value and the property of the > + hardware being controlled. This is an enumeration. > * - __u32 > - - ``reserved``\ [32] > + - ``reserved``\ [31] > - Reserved for future extensions. Applications and drivers must set > the array to zero. > > @@ -523,6 +537,142 @@ See also the examples in :ref:`control`. > streaming is in progress since most drivers do not support changing > the format in that case. > > + * .. _FLAG_EXPONENTIAL: > + > + - ``V4L2_CTRL_FLAG_EXPONENTIAL`` > + - 0x00000800 > + > + - The value of the control has an exponential relation to the feature > + being controled instead of a linear relation. In other words, the value controled -> controlled > + of the control is an exponent of the base specified in the > + base field in &struct v4l2_query_ext_ctrl. It would be nice if you can add some math here. See colorspaces-details.rst for examples of that. > + > + > +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| > + > +.. _control-bases: > + > +.. cssclass:: longtable > + > +.. flat-table:: Control Exponential Bases > + :header-rows: 1 > + :stub-columns: 0 > + :widths: 3 1 4 > + > + * - Base Name > + - Value > + - Description > + > + * - ``V4L2_CTRL_BASE_UNDEFINED`` > + - 0 > + - The control exponential base is not defined. > + > + * - ``V4L2_CTRL_BASE_LINEAR`` > + - 1 > + - The control is linear. > + > + * - ``V4L2_CTRL_BASE_2`` > + - 2 > + - The base of the control is 2. > + > + * - ``V4L2_CTRL_BASE_10`` > + - 10 > + - The base of the control is 10. > + > +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| > + > +.. _control-prefixes: > + > +.. cssclass:: longtable > + > +.. flat-table:: Control Prefixes > + :header-rows: 1 > + :stub-columns: 0 > + :widths: 3 1 4 > + > + * - Prefix Name > + - Value > + - Description > + > + * - ``V4L2_CTRL_PREFIX_NANO`` > + - -9 > + - Nano > + > + * - ``V4L2_CTRL_PREFIX_MICRO`` > + - -6 > + - Micro > + > + * - ``V4L2_CTRL_PREFIX_MILLI`` > + - -3 > + - Milli > + > + * - ``V4L2_CTRL_PREFIX_1`` > + - 0 > + - \- > + > + * - ``V4L2_CTRL_PREFIX_KILO`` > + - 3 > + - Kilo > + > + * - ``V4L2_CTRL_PREFIX_MEGA`` > + - 6 > + - Mega > + > + * - ``V4L2_CTRL_PREFIX_GIGA`` > + - 9 > + - Giga > + > +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| > + > +.. _control-units: > + > +.. cssclass:: longtable > + > +.. flat-table:: Control Units > + :header-rows: 1 > + :stub-columns: 0 > + :widths: 3 1 4 > + > + * - Unit Name > + - Value > + - Description > + > + * - ``V4L2_CTRL_UNIT_UNDEFINED`` > + - 0 > + - The unit of the control is not defined. > + > + * - ``V4L2_CTRL_UNIT_NONE`` > + - 1 > + - The control has no unit. > + > + * - ``V4L2_CTRL_UNIT_SECOND`` > + - 2 > + - Second > + > + * - ``V4L2_CTRL_UNIT_AMPERE`` > + - 3 > + - Ampère > + > + * - ``V4L2_CTRL_UNIT_LINE`` > + - 4 > + - A line of pixels in sensor's pixel matrix. This is a unit of time > + commonly used by camera sensors in e.g. exposure control, i.e. the time > + it takes for a sensor to read a line of pixels from the sensor's pixel > + matrix. See :ref:`V4L2_CID_PIXEL_RATE <V4L2_CID_PIXEL_RATE>`. That's a bad name. I'd call it a PIXEL_LINE or FRAME_LINE or something like that. When I first saw the define I thought it applied to a gpio line or a bus line or something like that. > + > + * - ``V4L2_CTRL_UNIT_PIXEL`` > + - 5 > + - A pixel in sensor's pixel matrix. This is a unit of time commonly used > + by camera sensors in e.g. exposure control, i.e. the time it takes for > + a sensor to read a pixel from the sensor's pixel matrix. > + > + * - ``V4L2_CTRL_UNIT_PIXEL`` Duplicate name as above. You meant PIXELS_PER_SECOND. I use this technique these days to avoid having to add defines to the videodev2.h.rst.exceptions file: * .. _`V4L2-CTRL-UNIT-PIXEL`: - ``V4L2_CTRL_UNIT_PIXEL`` - 5 - A pixel in sensor's pixel matrix. This is a unit of time commonly used by camera sensors in e.g. exposure control, i.e. the time it takes for a sensor to read a pixel from the sensor's pixel matrix. > + - 6 > + - Pixels per second > + > + * - ``V4L2_CTRL_UNIT_HZ > + - 7 > + - Hertz > > Return Value > ============ > diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions > index 63fa131729c09..8183a4f3554b0 100644 > --- a/Documentation/media/videodev2.h.rst.exceptions > +++ b/Documentation/media/videodev2.h.rst.exceptions > @@ -343,11 +343,33 @@ replace define V4L2_CTRL_FLAG_VOLATILE control-flags > replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags > replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags > replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags > +replace define V4L2_CTRL_FLAG_EXPONENTIAL control-flags > > replace define V4L2_CTRL_FLAG_NEXT_CTRL control > replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control > replace define V4L2_CID_PRIVATE_BASE control > > +# V4L2 control bases, prefixes and units > +replace define V4L2_CTRL_BASE_UNDEFINED control-bases > +replace define V4L2_CTRL_BASE_LINEAR control-bases > +replace define V4L2_CTRL_BASE_2 control-bases > +replace define V4L2_CTRL_BASE_10 control-bases > + > +replace define V4L2_CTRL_PREFIX_NANO control-prefixes > +replace define V4L2_CTRL_PREFIX_MICRO control-prefixes > +replace define V4L2_CTRL_PREFIX_MILLI control-prefixes > +replace define V4L2_CTRL_PREFIX_1 control-prefixes > +replace define V4L2_CTRL_PREFIX_KILO control-prefixes > +replace define V4L2_CTRL_PREFIX_MEGA control-prefixes > +replace define V4L2_CTRL_PREFIX_GIGA control-prefixes > + > +replace define V4L2_CTRL_UNIT_UNDEFINED control-units > +replace define V4L2_CTRL_UNIT_NONE control-units > +replace define V4L2_CTRL_UNIT_SECOND control-units > +replace define V4L2_CTRL_UNIT_AMPERE control-units > +replace define V4L2_CTRL_UNIT_LINE control-units > +replace define V4L2_CTRL_UNIT_PIXEL control-units You need to add PIXELS_PER_SECOND here as well. > + > # V4L2 tuner > > replace define V4L2_TUNER_CAP_LOW tuner-capability > Regards, Hans
diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst index 9f7312bf33651..8461fd92d1b9e 100644 --- a/Documentation/media/uapi/v4l/extended-controls.rst +++ b/Documentation/media/uapi/v4l/extended-controls.rst @@ -3460,6 +3460,8 @@ Image Process Control IDs by selecting the desired horizontal and vertical blanking. The unit of this control is Hz. +.. _v4l2_cid_pixel_rate: + ``V4L2_CID_PIXEL_RATE (64-bit integer)`` Pixel rate in the source pads of the subdev. This control is read-only and its unit is pixels / second. diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst index ff2d131223b84..472378f5d7566 100644 --- a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst +++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst @@ -269,8 +269,22 @@ See also the examples in :ref:`control`. - ``dims[V4L2_CTRL_MAX_DIMS]`` - The size of each dimension. The first ``nr_of_dims`` elements of this array must be non-zero, all remaining elements must be zero. + * - __u8 + - ``base`` + - The exponential base of the control value. Valid only if the + :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` control flag is + set. This is an enumeration. + * - __u8 + - ``prefix`` + - Prefix of the unit. This is an enumeration. + * - __u16 + - ``unit`` + - Unit of the value. Together with the ``prefix`` as well as the ``base`` + field (if :ref:`V4L2_CTRL_FLAG_EXPONENTIAL <FLAG_EXPONENTIAL>` is set), + defines the relation between the control value and the property of the + hardware being controlled. This is an enumeration. * - __u32 - - ``reserved``\ [32] + - ``reserved``\ [31] - Reserved for future extensions. Applications and drivers must set the array to zero. @@ -523,6 +537,142 @@ See also the examples in :ref:`control`. streaming is in progress since most drivers do not support changing the format in that case. + * .. _FLAG_EXPONENTIAL: + + - ``V4L2_CTRL_FLAG_EXPONENTIAL`` + - 0x00000800 + + - The value of the control has an exponential relation to the feature + being controled instead of a linear relation. In other words, the value + of the control is an exponent of the base specified in the + base field in &struct v4l2_query_ext_ctrl. + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _control-bases: + +.. cssclass:: longtable + +.. flat-table:: Control Exponential Bases + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + * - Base Name + - Value + - Description + + * - ``V4L2_CTRL_BASE_UNDEFINED`` + - 0 + - The control exponential base is not defined. + + * - ``V4L2_CTRL_BASE_LINEAR`` + - 1 + - The control is linear. + + * - ``V4L2_CTRL_BASE_2`` + - 2 + - The base of the control is 2. + + * - ``V4L2_CTRL_BASE_10`` + - 10 + - The base of the control is 10. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _control-prefixes: + +.. cssclass:: longtable + +.. flat-table:: Control Prefixes + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + * - Prefix Name + - Value + - Description + + * - ``V4L2_CTRL_PREFIX_NANO`` + - -9 + - Nano + + * - ``V4L2_CTRL_PREFIX_MICRO`` + - -6 + - Micro + + * - ``V4L2_CTRL_PREFIX_MILLI`` + - -3 + - Milli + + * - ``V4L2_CTRL_PREFIX_1`` + - 0 + - \- + + * - ``V4L2_CTRL_PREFIX_KILO`` + - 3 + - Kilo + + * - ``V4L2_CTRL_PREFIX_MEGA`` + - 6 + - Mega + + * - ``V4L2_CTRL_PREFIX_GIGA`` + - 9 + - Giga + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. _control-units: + +.. cssclass:: longtable + +.. flat-table:: Control Units + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + * - Unit Name + - Value + - Description + + * - ``V4L2_CTRL_UNIT_UNDEFINED`` + - 0 + - The unit of the control is not defined. + + * - ``V4L2_CTRL_UNIT_NONE`` + - 1 + - The control has no unit. + + * - ``V4L2_CTRL_UNIT_SECOND`` + - 2 + - Second + + * - ``V4L2_CTRL_UNIT_AMPERE`` + - 3 + - Ampère + + * - ``V4L2_CTRL_UNIT_LINE`` + - 4 + - A line of pixels in sensor's pixel matrix. This is a unit of time + commonly used by camera sensors in e.g. exposure control, i.e. the time + it takes for a sensor to read a line of pixels from the sensor's pixel + matrix. See :ref:`V4L2_CID_PIXEL_RATE <V4L2_CID_PIXEL_RATE>`. + + * - ``V4L2_CTRL_UNIT_PIXEL`` + - 5 + - A pixel in sensor's pixel matrix. This is a unit of time commonly used + by camera sensors in e.g. exposure control, i.e. the time it takes for + a sensor to read a pixel from the sensor's pixel matrix. + + * - ``V4L2_CTRL_UNIT_PIXEL`` + - 6 + - Pixels per second + + * - ``V4L2_CTRL_UNIT_HZ + - 7 + - Hertz Return Value ============ diff --git a/Documentation/media/videodev2.h.rst.exceptions b/Documentation/media/videodev2.h.rst.exceptions index 63fa131729c09..8183a4f3554b0 100644 --- a/Documentation/media/videodev2.h.rst.exceptions +++ b/Documentation/media/videodev2.h.rst.exceptions @@ -343,11 +343,33 @@ replace define V4L2_CTRL_FLAG_VOLATILE control-flags replace define V4L2_CTRL_FLAG_HAS_PAYLOAD control-flags replace define V4L2_CTRL_FLAG_EXECUTE_ON_WRITE control-flags replace define V4L2_CTRL_FLAG_MODIFY_LAYOUT control-flags +replace define V4L2_CTRL_FLAG_EXPONENTIAL control-flags replace define V4L2_CTRL_FLAG_NEXT_CTRL control replace define V4L2_CTRL_FLAG_NEXT_COMPOUND control replace define V4L2_CID_PRIVATE_BASE control +# V4L2 control bases, prefixes and units +replace define V4L2_CTRL_BASE_UNDEFINED control-bases +replace define V4L2_CTRL_BASE_LINEAR control-bases +replace define V4L2_CTRL_BASE_2 control-bases +replace define V4L2_CTRL_BASE_10 control-bases + +replace define V4L2_CTRL_PREFIX_NANO control-prefixes +replace define V4L2_CTRL_PREFIX_MICRO control-prefixes +replace define V4L2_CTRL_PREFIX_MILLI control-prefixes +replace define V4L2_CTRL_PREFIX_1 control-prefixes +replace define V4L2_CTRL_PREFIX_KILO control-prefixes +replace define V4L2_CTRL_PREFIX_MEGA control-prefixes +replace define V4L2_CTRL_PREFIX_GIGA control-prefixes + +replace define V4L2_CTRL_UNIT_UNDEFINED control-units +replace define V4L2_CTRL_UNIT_NONE control-units +replace define V4L2_CTRL_UNIT_SECOND control-units +replace define V4L2_CTRL_UNIT_AMPERE control-units +replace define V4L2_CTRL_UNIT_LINE control-units +replace define V4L2_CTRL_UNIT_PIXEL control-units + # V4L2 tuner replace define V4L2_TUNER_CAP_LOW tuner-capability
Document V4L2 control exponential bases, units and prefixes, as well as the control flag telling a control value is an exponent. Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com> --- Documentation/media/uapi/v4l/extended-controls.rst | 2 + Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 152 ++++++++++++++++++++- Documentation/media/videodev2.h.rst.exceptions | 22 +++ 3 files changed, 175 insertions(+), 1 deletion(-)