diff mbox series

[v10,09/11,RESEND] media: v4l2: document the usage of min/max for V4L2_CTRL_TYPE_RECT

Message ID 20221201023204.2177458-10-yunkec@google.com (mailing list archive)
State Superseded
Delegated to: Laurent Pinchart
Headers
Series media: Implement UVC v1.5 ROI |

Commit Message

Yunke Cao Dec. 1, 2022, 2:32 a.m. UTC 
  Document the default implementation of min/max for rectangle controls.

Signed-off-by: Yunke Cao <yunkec@google.com>
---
Changelog since v9:
- No change.
Changelog since v8:
- New patch.

 Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

Comments

Sergey Senozhatsky Dec. 1, 2022, 3:59 a.m. UTC | #1 
On (22/12/01 11:32), Yunke Cao wrote:
> +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
> @@ -447,7 +447,11 @@ See also the examples in :ref:`control`.
>        - n/a
>        - A struct :c:type:`v4l2_rect`, containing a rectangle described by
>  	the position of its top-left corner, the width and the height. Units
> -	depend on the use case.
> +	depend on the use case. Use ``V4L2_CTRL_WHICH_MIN_VAL`` and
> +	``V4L2_CTRL_WHICH_MAX_VAL`` to query the range of rectangle sizes. The
> +	top-left corner of the minimum and maximum rectangles should be the
> +	same. For example, a control can have a minimum rectangle of 1x1@0x0 and
> +	a maximum of 640x480@0x0.

I assume that examples use width-height@top-left convention. Is this common
or should it be 0x0@1x1 and 0x0@640x480?
Yunke Cao Dec. 6, 2022, 8:45 a.m. UTC | #2 
Thanks for the review!

On Thu, Dec 1, 2022 at 12:59 PM Sergey Senozhatsky
<senozhatsky@chromium.org> wrote:
>
> On (22/12/01 11:32), Yunke Cao wrote:
> > +++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
> > @@ -447,7 +447,11 @@ See also the examples in :ref:`control`.
> >        - n/a
> >        - A struct :c:type:`v4l2_rect`, containing a rectangle described by
> >       the position of its top-left corner, the width and the height. Units
> > -     depend on the use case.
> > +     depend on the use case. Use ``V4L2_CTRL_WHICH_MIN_VAL`` and
> > +     ``V4L2_CTRL_WHICH_MAX_VAL`` to query the range of rectangle sizes. The
> > +     top-left corner of the minimum and maximum rectangles should be the
> > +     same. For example, a control can have a minimum rectangle of 1x1@0x0 and
> > +     a maximum of 640x480@0x0.
>
> I assume that examples use width-height@top-left convention. Is this common
> or should it be 0x0@1x1 and 0x0@640x480?

It is width-height@left-top. I'm not sure how common it is.
I used the same format in code in patch 01/10, which was suggested by
Hans in a previous version.

case V4L2_CTRL_TYPE_RECT:
        pr_cont("%ux%u@%dx%d",
                     ptr.p_rect->width, ptr.p_rect->height,
                     ptr.p_rect->left, ptr.p_rect->top);
       break;

Let me know if you have any suggestions :) .

Best,
Yunke
diff mbox series

Patch

diff --git a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
index 58982cd382e3..efa07428ba7a 100644
--- a/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
+++ b/Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst
@@ -447,7 +447,11 @@  See also the examples in :ref:`control`.
       - n/a
       - A struct :c:type:`v4l2_rect`, containing a rectangle described by
 	the position of its top-left corner, the width and the height. Units
-	depend on the use case.
+	depend on the use case. Use ``V4L2_CTRL_WHICH_MIN_VAL`` and
+	``V4L2_CTRL_WHICH_MAX_VAL`` to query the range of rectangle sizes. The
+	top-left corner of the minimum and maximum rectangles should be the
+	same. For example, a control can have a minimum rectangle of 1x1@0x0 and
+	a maximum of 640x480@0x0.
     * - ``V4L2_CTRL_TYPE_H264_SPS``
       - n/a
       - n/a