Re: [RFCv2 PATCH 09/10] DocBook: document the new v4l2 matrix ioctls.

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

Hi Hans,

On Thursday 22 August 2013 08:56:00 Hans Verkuil wrote:
> On 08/21/2013 11:58 PM, Laurent Pinchart wrote:
> > On Monday 12 August 2013 12:58:32 Hans Verkuil wrote:
> >> From: Hans Verkuil <hans.verkuil@cisco.com>
> >> 
> >> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> >> ---
> >> 
> >>  Documentation/DocBook/media/v4l/v4l2.xml           |   2 +
> >>  .../DocBook/media/v4l/vidioc-g-matrix.xml          | 115 +++++++++++++
> >>  .../DocBook/media/v4l/vidioc-query-matrix.xml      | 178 +++++++++++++++
> >>  3 files changed, 295 insertions(+)
> >>  create mode 100644 Documentation/DocBook/media/v4l/vidioc-g-matrix.xml
> >>  create mode 100644
> >>  Documentation/DocBook/media/v4l/vidioc-query-matrix.xml
> > 
> > [snip]
> > 
> >> diff --git a/Documentation/DocBook/media/v4l/vidioc-query-matrix.xml
> >> b/Documentation/DocBook/media/v4l/vidioc-query-matrix.xml new file mode
> >> 100644
> >> index 0000000..c2845c7
> >> --- /dev/null
> >> +++ b/Documentation/DocBook/media/v4l/vidioc-query-matrix.xml

[snip]

> >> +    <table pgwide="1" frame="none" id="v4l2-matrix-type">
> >> +      <title>Matrix Types</title>
> >> +      <tgroup cols="2" align="left">
> >> +	<colspec colwidth="30*" />
> >> +	<colspec colwidth="55*" />
> >> +	<thead>
> >> +	  <row>
> >> +	    <entry>Type</entry>
> >> +	    <entry>Description</entry>
> >> +	  </row>
> >> +	</thead>
> >> +	<tbody valign="top">
> >> +	  <row>
> >> +	    <entry><constant>V4L2_MATRIX_T_MD_REGION</constant></entry>
> >> +	    <entry>Hardware motion detection often divides the image into
> >> several
> >> +	    regions, and each region can have its own motion detection
> >> thresholds.
> >> +	    This matrix assigns a region number to each element. Each element
> >> is
> >> a __u8.
> >> +	    Generally each element refers to a block of pixels in the image.
> > 
> > From the description I have trouble understanding what the matrix type is
> > for. Do you think we could make the explanation more detailed ?
> 
> How about this:
> 
> Hardware motion detection divides the image up into cells. If the image
> resolution is WxH and the matrix size is COLSxROWS, then each cell is a
> rectangle of (W/COLS)x(H/ROWS) pixels (approximately as there may be some
> rounding involved). Depending on the hardware each cell can have its own
> properties. This matrix type sets the 'region' property which is a __u8.
> Each region will typically have its own set of motion detection parameters
> such as a threshold that determines the motion detection sensitivity. By
> assigning each cell a region you can create regions with lower and regions
> with higher motion sensitivity.

That sounds good to me. One more question, however: if the hardware divides 
the sub-sampled image into regions, how do you configure per-region thresholds 
? The V4L2_MATRIX_T_MD_THRESHOLD matrix only configures per-cell thresholds.

> > > +	    </entry>
> > > +	  </row>
> > > +	  <row>
> > > +	    <entry><constant>V4L2_MATRIX_T_MD_THRESHOLD</constant></entry>
> > > +	    <entry>Hardware motion detection can assign motion detection
> > > threshold +	    values to each element of an image. Each element is a
> > > __u16. +       Generally each element refers to a block of pixels in
> > > the image.
> This would be improved as well along the same lines:
> 
> Hardware motion detection divides the image up into cells. If the image
> resolution is WxH and the matrix size is COLSxROWS, then each cell is a
> rectangle of (W/COLS)x(H/ROWS) pixels (approximately as there may be some
> rounding involved). Depending on the hardware each cell can have its own
> motion detection sensitivity threshold. This matrix type sets the motion
> detection threshold property which is a __u16.
> > > +	    </entry>
> > > +	  </row>
> > > +	</tbody>
> > > +      </tgroup>
> > > +    </table>
> > > +
> > > +  </refsect1>
> > > +  <refsect1>
> > > +    &return-value;
> > > +  </refsect1>
> > > +</refentry>

-- 
Regards,

Laurent Pinchart