On 08/21/2013 11:58 PM, Laurent Pinchart wrote: > Hi Hans, > > Thank you for the patch. > > On Monday 12 August 2013 12:58:32 Hans Verkuil wrote: >> From: Hans Verkuil <hans.verkuil@xxxxxxxxx> >> >> Signed-off-by: Hans Verkuil <hans.verkuil@xxxxxxxxx> >> --- >> 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 >> @@ -0,0 +1,178 @@ >> +<refentry id="vidioc-query-matrix"> >> + <refmeta> >> + <refentrytitle>ioctl VIDIOC_QUERY_MATRIX</refentrytitle> >> + &manvol; >> + </refmeta> >> + >> + <refnamediv> >> + <refname>VIDIOC_QUERY_MATRIX</refname> >> + <refpurpose>Query the attributes of a matrix</refpurpose> >> + </refnamediv> >> + >> + <refsynopsisdiv> >> + <funcsynopsis> >> + <funcprototype> >> + <funcdef>int <function>ioctl</function></funcdef> >> + <paramdef>int <parameter>fd</parameter></paramdef> >> + <paramdef>int <parameter>request</parameter></paramdef> >> + <paramdef>struct v4l2_query_matrix >> +*<parameter>argp</parameter></paramdef> >> + </funcprototype> >> + </funcsynopsis> >> + </refsynopsisdiv> >> + >> + <refsect1> >> + <title>Arguments</title> >> + >> + <variablelist> >> + <varlistentry> >> + <term><parameter>fd</parameter></term> >> + <listitem> >> + <para>&fd;</para> >> + </listitem> >> + </varlistentry> >> + <varlistentry> >> + <term><parameter>request</parameter></term> >> + <listitem> >> + <para>VIDIOC_QUERY_MATRIX</para> >> + </listitem> >> + </varlistentry> >> + <varlistentry> >> + <term><parameter>argp</parameter></term> >> + <listitem> >> + <para></para> >> + </listitem> >> + </varlistentry> >> + </variablelist> >> + </refsect1> >> + >> + <refsect1> >> + <title>Description</title> >> + >> + <para>Query the attributes of a matrix. The application fills in the >> + <structfield>type</structfield> and optionally the >> <structfield>ref</structfield> >> + fields of &v4l2-query-matrix;. All other fields will be returned by the >> driver. >> + </para> >> + >> + <table frame="none" pgwide="1" id="v4l2-query-matrix"> >> + <title>struct <structname>v4l2_query_matrix</structname></title> >> + <tgroup cols="4"> >> + &cs-str; >> + <tbody valign="top"> >> + <row> >> + <entry>__u32</entry> >> + <entry><structfield>type</structfield></entry> >> + <entry></entry> >> + <entry>Type of the matrix, see <xref linkend="v4l2-matrix-type" >> />.</entry> + </row> >> + <row> >> + <entry>union</entry> >> + <entry><structfield>ref</structfield></entry> >> + <entry></entry> >> + <entry>This union makes it possible to identify the object owning the >> + matrix. Currently the only defined matrix types are identified >> through >> + the filehandle used to call the ioctl, so this union isn't used >> (yet).</entry> >> + </row> >> + <row> >> + <entry>__u32</entry> >> + <entry><structfield>columns</structfield></entry> >> + <entry></entry> >> + <entry>Number of columns in the matrix.</entry> >> + </row> >> + <row> >> + <entry>__u32</entry> >> + <entry><structfield>rows</structfield></entry> >> + <entry></entry> >> + <entry>Number of rows in the matrix.</entry> >> + </row> >> + <row> >> + <entry>union</entry> >> + <entry><structfield>elem_min</structfield></entry> >> + <entry></entry> >> + <entry></entry> >> + </row> >> + <row> >> + <entry></entry> >> + <entry>__s64</entry> >> + <entry><structfield>val</structfield></entry> >> + <entry>The minimal signed value of each matrix element.</entry> >> + </row> >> + <row> >> + <entry></entry> >> + <entry>__u64</entry> >> + <entry><structfield>uval</structfield></entry> >> + <entry>The minimal unsigned value of each matrix >> element.</entry> >> + </row> >> + <row> >> + <entry>union</entry> >> + <entry><structfield>elem_max</structfield></entry> >> + <entry></entry> >> + <entry></entry> >> + </row> >> + <row> >> + <entry></entry> >> + <entry>__s64</entry> >> + <entry><structfield>val</structfield></entry> >> + <entry>The maximal signed value of each matrix element.</entry> >> + </row> >> + <row> >> + <entry></entry> >> + <entry>__u64</entry> >> + <entry><structfield>uval</structfield></entry> >> + <entry>The maximal unsigned value of each matrix >> element.</entry> >> + </row> >> + <row> >> + <entry>__u32</entry> >> + <entry><structfield>elem_size</structfield></entry> >> + <entry></entry> >> + <entry>The size in bytes of a single matrix element. >> + The full matrix size will be <structfield>columns</structfield> * >> + <structfield>rows</structfield> * >> <structfield>elem_size</structfield>.</entry> >> + </row> >> + <row> >> + <entry>__u32</entry> >> + <entry><structfield>reserved</structfield>[12]</entry> >> + <entry></entry> >> + <entry>Reserved for future extensions. Drivers must set >> + the array to zero.</entry> >> + </row> >> + </tbody> >> + </tgroup> >> + </table> >> + >> + <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. > > + </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, Hans -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
