* [PATCH] vidioc-enumin/output.rst: improve documentation
@ 2017-03-31 8:58 Hans Verkuil
2017-03-31 10:05 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 3+ messages in thread
From: Hans Verkuil @ 2017-03-31 8:58 UTC (permalink / raw)
To: Linux Media Mailing List, Helen Koike, Sakari Ailus,
Laurent Pinchart, Mauro Carvalho Chehab
The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
hopelessly out of date. Fix this, and also fix a few style issues in these
documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
(only used by the zoran driver).
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
Question: should we perhaps add _TYPE_VIDEO aliases?
---
diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
index 17aaaf939757..266e48ab237f 100644
--- a/Documentation/media/uapi/v4l/vidioc-enuminput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -33,7 +33,7 @@ Description
To query the attributes of a video input applications initialize the
``index`` field of struct :c:type:`v4l2_input` and call the
-:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
+:ref:`VIDIOC_ENUMINPUT` with a pointer to this structure. Drivers
fill the rest of the structure or return an ``EINVAL`` error code when the
index is out of bounds. To enumerate all inputs applications shall begin
at index zero, incrementing by one until the driver returns ``EINVAL``.
@@ -117,8 +117,9 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
- This input uses a tuner (RF demodulator).
* - ``V4L2_INPUT_TYPE_CAMERA``
- 2
- - Analog baseband input, for example CVBS / Composite Video,
- S-Video, RGB.
+ - Any non-tuner video input, for example Composite Video,
+ S-Video, HDMI, camera sensor. The naming as ``_TYPE_CAMERA`` is historical,
+ today we would have called it ``_TYPE_VIDEO``.
* - ``V4L2_INPUT_TYPE_TOUCH``
- 3
- This input is a touch device for capturing raw touch data.
@@ -209,11 +210,11 @@ at index zero, incrementing by one until the driver returns ``EINVAL``.
* - ``V4L2_IN_CAP_DV_TIMINGS``
- 0x00000002
- This input supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
+ ``VIDIOC_S_DV_TIMINGS``.
* - ``V4L2_IN_CAP_STD``
- 0x00000004
- This input supports setting the TV standard by using
- VIDIOC_S_STD.
+ ``VIDIOC_S_STD``.
* - ``V4L2_IN_CAP_NATIVE_SIZE``
- 0x00000008
- This input supports setting the native size using the
diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
index d7dd2742475a..93a2cf3b310c 100644
--- a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
+++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
@@ -33,11 +33,11 @@ Description
To query the attributes of a video outputs applications initialize the
``index`` field of struct :c:type:`v4l2_output` and call
-the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
+the :ref:`VIDIOC_ENUMOUTPUT` with a pointer to this structure.
Drivers fill the rest of the structure or return an ``EINVAL`` error code
when the index is out of bounds. To enumerate all outputs applications
shall begin at index zero, incrementing by one until the driver returns
-EINVAL.
+``EINVAL``.
.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
@@ -112,11 +112,12 @@ EINVAL.
- This output is an analog TV modulator.
* - ``V4L2_OUTPUT_TYPE_ANALOG``
- 2
- - Analog baseband output, for example Composite / CVBS, S-Video,
- RGB.
+ - Any non-modulator video output, for example Composite Video,
+ S-Video, HDMI. The naming as ``_TYPE_ANALOG`` is historical,
+ today we would have called it ``_TYPE_VIDEO``.
* - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
- 3
- - [?]
+ - The video output will be copied to a :ref:`video overlay <overlay>`.
@@ -132,11 +133,11 @@ EINVAL.
* - ``V4L2_OUT_CAP_DV_TIMINGS``
- 0x00000002
- This output supports setting video timings by using
- VIDIOC_S_DV_TIMINGS.
+ ``VIDIOC_S_DV_TIMINGS``.
* - ``V4L2_OUT_CAP_STD``
- 0x00000004
- This output supports setting the TV standard by using
- VIDIOC_S_STD.
+ ``VIDIOC_S_STD``.
* - ``V4L2_OUT_CAP_NATIVE_SIZE``
- 0x00000008
- This output supports setting the native size using the
^ permalink raw reply related [flat|nested] 3+ messages in thread* Re: [PATCH] vidioc-enumin/output.rst: improve documentation
2017-03-31 8:58 [PATCH] vidioc-enumin/output.rst: improve documentation Hans Verkuil
@ 2017-03-31 10:05 ` Mauro Carvalho Chehab
2017-03-31 12:12 ` Hans Verkuil
0 siblings, 1 reply; 3+ messages in thread
From: Mauro Carvalho Chehab @ 2017-03-31 10:05 UTC (permalink / raw)
To: Hans Verkuil
Cc: Linux Media Mailing List, Helen Koike, Sakari Ailus,
Laurent Pinchart, Mauro Carvalho Chehab
Em Fri, 31 Mar 2017 10:58:39 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
> hopelessly out of date. Fix this, and also fix a few style issues in these
> documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
> (only used by the zoran driver).
>
> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> ---
Patch looks OK to me, but see below.
> Question: should we perhaps add _TYPE_VIDEO aliases?
IMHO, let's rename it to _TYPE_VIDEO (or STREAM, or V_STREAM), and make
_TYPE_CAMERA an alias, e. g.:
#define V4L2_INPUT_TYPE_VIDEO 2
#define V4L2_INPUT_TYPE_CAMERA V4L2_INPUT_TYPE_VIDEO
This way, we'll let clearer what's currently preferred. We should also
change it at the documentation, mentioning that V4L2_INPUT_TYPE_CAMERA
is an alias, due to historical reasons.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] vidioc-enumin/output.rst: improve documentation
2017-03-31 10:05 ` Mauro Carvalho Chehab
@ 2017-03-31 12:12 ` Hans Verkuil
0 siblings, 0 replies; 3+ messages in thread
From: Hans Verkuil @ 2017-03-31 12:12 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Media Mailing List, Helen Koike, Sakari Ailus,
Laurent Pinchart, Mauro Carvalho Chehab
On 31/03/17 12:05, Mauro Carvalho Chehab wrote:
> Em Fri, 31 Mar 2017 10:58:39 +0200
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
>
>> The V4L2_INPUT_TYPE_CAMERA and V4L2_OUTPUT_TYPE_ANALOG descriptions were
>> hopelessly out of date. Fix this, and also fix a few style issues in these
>> documents. Finally add the missing documentation for V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY
>> (only used by the zoran driver).
>>
>> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
>> ---
>
> Patch looks OK to me, but see below.
>
>> Question: should we perhaps add _TYPE_VIDEO aliases?
>
> IMHO, let's rename it to _TYPE_VIDEO (or STREAM, or V_STREAM), and make
> _TYPE_CAMERA an alias, e. g.:
>
> #define V4L2_INPUT_TYPE_VIDEO 2
>
> #define V4L2_INPUT_TYPE_CAMERA V4L2_INPUT_TYPE_VIDEO
>
> This way, we'll let clearer what's currently preferred. We should also
> change it at the documentation, mentioning that V4L2_INPUT_TYPE_CAMERA
> is an alias, due to historical reasons.
Does this really make sense to do this now? Everyone is used to the old defines,
wouldn't changing this just increase confusion?
Sorry, playing devil's advocate here.
I'm a bit hesitant of doing this. We've done this in the past for APIs that
were very new or rarely used, but this is everywhere.
I feel fixing the spec is sufficient.
If more people think that adding this aliases is a good idea, then I can do that.
Regards,
Hans
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2017-03-31 12:12 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-03-31 8:58 [PATCH] vidioc-enumin/output.rst: improve documentation Hans Verkuil
2017-03-31 10:05 ` Mauro Carvalho Chehab
2017-03-31 12:12 ` Hans Verkuil
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.